hailey
/
qmk_firmware
mirror of https://github.com/hailey/qmk_firmware.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rework I2C driver docs (#11658)

Browse Source
gc_switch
Ryan 4 years ago committed by GitHub
parent 0355cd0f72
commit 5d5cbb877d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 222 additions and 106 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 286
      docs/i2c_driver.md
  2. 42
      docs/spi_driver.md

286
docs/i2c_driver.md
Unescape View File

@ -2,132 +2,236 @@
The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
## An important note on I2C Addresses :id=note-on-i2c-addresses ## I2C Addressing :id=note-on-i2c-addresses
All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting
the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed
on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be
shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`. shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`.
You can either do this on each call to the functions below, or once in your definition of the address. For example if your device has an address of `0x18`: You can either do this on each call to the functions below, or once in your definition of the address. For example, if your device has an address of `0x18`:
`#define MY_I2C_ADDRESS (0x18 << 1)` ```c
#define MY_I2C_ADDRESS (0x18 << 1)
```
See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
## Available functions :id=available-functions ## AVR Configuration :id=avr-configuration
|Function |Description |
|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. |
|`i2c_status_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. |
|`i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction. |
|`i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. |
|`i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written. |
|`i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. |
|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. |
### Function Return :id=function-return The following defines can be used to configure the I2C master driver:
All the above functions, except `void i2c_init(void);` return the following truth table: |`config.h` Override|Description |Default |
|-------------------|---------------------|--------|
|`F_SCL` |Clock frequency in Hz|`400000`|
|Return Constant |Value|Description | No further setup is required - just connect the `SDA` and `SCL` pins of your I2C devices to the matching pins on the MCU:
|--------------------|-----|--------------------------------|
|`I2C_STATUS_SUCCESS`|0 |Operation executed successfully.|
|`I2C_STATUS_ERROR` |-1 |Operation failed. |
|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. |
|MCU |`SCL`|`SDA`|
|------------------|-----|-----|
|ATmega16/32U4 |`D0` |`D1` |
|AT90USB64/128 |`D0` |`D1` |
|ATmega32A |`C0` |`C1` |
|ATmega328/P |`C5` |`C4` |
## AVR :id=avr ?> The ATmega16/32U2 does not possess I2C functionality, and so cannot use this driver.
### Configuration :id=avr-configuration ## ChibiOS/ARM Configuration :id=arm-configuration
The following defines can be used to configure the I2C master driver. You'll need to determine which pins can be used for I2C -- a an example, STM32 parts generally have multiple I2C peripherals, labeled I2C1, I2C2, I2C3 etc.
|Variable |Description |Default| To enable I2C, modify your board's `halconf.h` to enable I2C:
|------------------|---------------------------------------------------|-------|
|`F_SCL` |Clock frequency in Hz |400KHz |
AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. ```c
#define HAL_USE_I2C TRUE
## ARM :id=arm ```
For ARM the Chibios I2C HAL driver is under the hood.
This section assumes an STM32 MCU.
### Configuration :id=arm-configuration Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports. ```c
#undef STM32_I2C_USE_I2C2
#define STM32_I2C_USE_I2C2 TRUE
```
Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers. |`mcuconf.h` Setting |Description |Default|
|----------------------------|----------------------------------------------------------------------------------|-------|
|`STM32_I2C_BUSY_TIMEOUT` |Time in milliseconds until the I2C command is aborted if no response is received |`50` |
|`STM32_I2C_XXX_IRQ_PRIORITY`|Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |`10` |
|`STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit|`TRUE` |
|`STM32_I2C_XXX_DMA_PRIORITY`|Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |`1` |
|Variable |Description |Default| Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303.
|------------------------------|------------------------------------------------------------------------------------|-------|
|`#STM32_I2C_USE_XXX` |Enable/Disable the hardware driver XXX (each driver should be explicitly listed) |FALSE |
|`#STM32_I2C_BUSY_TIMEOUT` |Time in ms until the I2C command is aborted if no response is received |50 |
|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |10 |
|`#STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit |TRUE |
|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |1 |
Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver. |`config.h` Overrride |Description |Default|
|------------------------|-------------------------------------------------------------------------------------------|-------|
|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`|
|`I2C1_BANK` (deprecated)|The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superseded by `I2C1_SCL_BANK`/`I2C1_SDA_BANK`|`GPIOB`|
|`I2C1_SCL_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL |`GPIOB`|
|`I2C1_SCL` |The pin number for SCL (0-15) |`6` |
|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` |
|`I2C1_SDA_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA |`GPIOB`|
|`I2C1_SDA` |The pin number for SDA (0-15) |`7` |
|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` |
Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use. The following configuration values depend on the specific MCU in use.
By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used, `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver. ### I2Cv1 :id=i2cv1
STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. You can use these defines to set your i2c pins: * STM32F1xx
* STM32F2xx
* STM32F4xx
* STM32L0xx
* STM32L1xx
| Variable | Description | Default | See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#7_I2Cv1_configuration_structure) for the I2Cv1 configuration structure.
|--------------------------|----------------------------------------------------------------------------------------------|---------|
| `I2C1_SCL_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL | `GPIOB` |
| `I2C1_SDA_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA | `GPIOB` |
| `I2C1_SCL` | The pin number for the SCL pin (0-15) | `6` |
| `I2C1_SDA` | The pin number for the SDA pin (0-15) | `7` |
| `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` |
The ChibiOS I2C driver configuration depends on STM32 MCU: |`config.h` Override|Default |
|-------------------|----------------|
|`I2C1_OPMODE` |`OPMODE_I2C` |
|`I2C1_CLOCK_SPEED` |`100000` |
|`I2C1_DUTY_CYCLE` |`STD_DUTY_CYCLE`|
STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1; ### I2Cv2 :id=i2cv2
STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2;
#### I2Cv1 :id=i2cv1 * STM32F0xx
STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using <https://www.playembedded.org/blog/stm32-i2c-chibios/#I2Cv1_configuration_structure> as a reference: * STM32F3xx
* STM32F7xx
* STM32L4xx
| Variable | Default | See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#8_I2Cv2_I2Cv3_configuration_structure) for the I2Cv2 configuration structure.
|--------------------|------------------|
| `I2C1_OPMODE` | `OPMODE_I2C` |
| `I2C1_CLOCK_SPEED` | `100000` |
| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` |
#### I2Cv2 :id=i2cv2 |`config.h` Override |Default|
STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using <https://www.st.com/en/embedded-software/stsw-stm32126.html> as a reference: |---------------------|-------|
|`I2C1_TIMINGR_PRESC` |`0U` |
|`I2C1_TIMINGR_SCLDEL`|`7U` |
|`I2C1_TIMINGR_SDADEL`|`0U` |
|`I2C1_TIMINGR_SCLH` |`38U` |
|`I2C1_TIMINGR_SCLL` |`129U` |
| Variable | Default | ## Functions :id=functions
|-----------------------|---------|
| `I2C1_TIMINGR_PRESC` | `15U` |
| `I2C1_TIMINGR_SCLDEL` | `4U` |
| `I2C1_TIMINGR_SDADEL` | `2U` |
| `I2C1_TIMINGR_SCLH` | `15U` |
| `I2C1_TIMINGR_SCLL` | `21U` |
STM32 MCUs allow for different "alternate function" modes when configuring GPIO pins. These are required to switch the pins used to I2Cv2 mode. See the respective datasheet for the appropriate values for your MCU. ### `void i2c_init(void)`
| Variable | Default | Initialize the I2C driver. This function must be called only once, before any of the below functions can be called.
|---------------------|---------|
| `I2C1_SCL_PAL_MODE` | `4` |
| `I2C1_SDA_PAL_MODE` | `4` |
#### Other :id=other This function is weakly defined, meaning it can be overridden if necessary for your particular use case:
You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function:
```c ```c
void i2c_init(void) void i2c_init(void) {
{ setPinInput(B6); // Try releasing special pins for a short time
setPinInput(B6); // Try releasing special pins for a short time setPinInput(B7);
setPinInput(B7); wait_ms(10); // Wait for the release to happen
wait_ms(10); // Wait for the release to happen
palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function
palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
} }
``` ```
---
### `i2c_status_t i2c_start(uint8_t address, uint16_t timeout)`
Start an I2C transaction.
#### Arguments
- `uint8_t address`
The 7-bit I2C address of the device (ie. without the read/write bit - this will be set automatically).
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)`
Send multiple bytes to the selected I2C device.
#### Arguments
- `uint8_t address`
The 7-bit I2C address of the device.
- `uint8_t *data`
A pointer to the data to transmit.
- `uint16_t length`
The number of bytes to write. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)`
Receive multiple bytes from the selected SPI device.
#### Arguments
- `uint8_t address`
The 7-bit I2C address of the device.
- `uint8_t *data`
A pointer to the buffer to read into.
- `uint16_t length`
The number of bytes to read. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Writes to a register on the I2C device.
#### Arguments
- `uint8_t devaddr`
The 7-bit I2C address of the device.
- `uint8_t regaddr`
The register address to write to.
- `uint8_t *data`
A pointer to the data to transmit.
- `uint16_t length`
The number of bytes to write. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)`
Reads from a register on the I2C device.
#### Arguments
- `uint8_t devaddr`
The 7-bit I2C address of the device.
- `uint8_t regaddr`
The register address to read from.
- `uint16_t length`
The number of bytes to read. Take care not to overrun the length of `data`.
- `uint16_t timeout`
The time in milliseconds to wait for a response from the target device.
#### Return Value
`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
---
### `i2c_status_t i2c_stop(void)`
Stop the current I2C transaction.

42
docs/spi_driver.md
Unescape View File

@ -8,7 +8,7 @@ No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` p
|MCU |`SS`|`SCK`|`MOSI`|`MISO`| |MCU |`SS`|`SCK`|`MOSI`|`MISO`|
|---------------|----|-----|------|------| |---------------|----|-----|------|------|
|ATMega16/32U2/4|`B0`|`B1` |`B2` |`B3` | |ATmega16/32U2/4|`B0`|`B1` |`B2` |`B3` |
|AT90USB64/128 |`B0`|`B1` |`B2` |`B3` | |AT90USB64/128 |`B0`|`B1` |`B2` |`B3` |
|ATmega32A |`B4`|`B7` |`B5` |`B6` | |ATmega32A |`B4`|`B7` |`B5` |`B6` |
|ATmega328/P |`B2`|`B5` |`B3` |`B4` | |ATmega328/P |`B2`|`B5` |`B3` |`B4` |
@ -20,22 +20,34 @@ You may use more than one slave select pin, not just the `SS` pin. This is usefu
You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc. You'll need to determine which pins can be used for SPI -- as an example, STM32 parts generally have multiple SPI peripherals, labeled SPI1, SPI2, SPI3 etc.
To enable SPI, modify your board's `halconf.h` to enable SPI - both `HAL_USE_SPI` and `SPI_USE_WAIT` should be `TRUE`, and `SPI_SELECT_MODE` should be `SPI_SELECT_MODE_PAD`. To enable SPI, modify your board's `halconf.h` to enable SPI:
Then, modify your board's `mcuconf.h` to enable the SPI peripheral you've chosen -- in the case of using SPI2, modify `STM32_SPI_USE_SPI2` to be `TRUE`.
As per the AVR configuration, you may select any other standard GPIO as a slave select pin, and can be supplied to `spi_start()`. ```c
#define HAL_USE_SPI TRUE
#define SPI_USE_WAIT TRUE
#define SPI_SELECT_MODE SPI_SELECT_MODE_PAD
```
Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example:
```c
#undef STM32_SPI_USE_SPI2
#define STM32_SPI_USE_SPI2 TRUE
```
Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303.
`config.h` override | Description | Default Value |`config.h` Override|Description |Default|
----------------------------|---------------------------------------------------------------|-------------- |-------------------|-------------------------------------------------------------|-------|
`#define SPI_DRIVER` | SPI peripheral to use - SPI1 => `SPID1`, SPI2 => `SPID2` etc. | `SPID2` |`SPI_DRIVER` |SPI peripheral to use - SPI1 -> `SPID1`, SPI2 -> `SPID2` etc.|`SPID2`|
`#define SPI_SCK_PIN` | The pin to use for the SCK | `B13` |`SPI_SCK_PIN` |The pin to use for SCK |`B13` |
`#define SPI_SCK_PAL_MODE` | The alternate function mode for the SCK pin | `5` |`SPI_SCK_PAL_MODE` |The alternate function mode for SCK |`5` |
`#define SPI_MOSI_PIN` | The pin to use for the MOSI | `B15` |`SPI_MOSI_PIN` |The pin to use for MOSI |`B15` |
`#define SPI_MOSI_PAL_MODE` | The alternate function mode for the MOSI pin | `5` |`SPI_MOSI_PAL_MODE`|The alternate function mode for MOSI |`5` |
`#define SPI_MISO_PIN` | The pin to use for the MISO | `B14` |`SPI_MISO_PIN` |The pin to use for MISO |`B14` |
`#define SPI_MISO_PAL_MODE` | The alternate function mode for the MISO pin | `5` |`SPI_MISO_PAL_MODE`|The alternate function mode for MISO |`5` |
As per the AVR configuration, you may choose any other standard GPIO as a slave select pin, which should be supplied to `spi_start()`.
## Functions ## Functions
@ -112,7 +124,7 @@ Send multiple bytes to the selected SPI device.
#### Return Value #### Return Value
`SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise. `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`.
--- ---
@ -129,7 +141,7 @@ Receive multiple bytes from the selected SPI device.
#### Return Value #### Return Value
`SPI_STATUS_TIMEOUT` if the internal transmission timeout period elapses, `SPI_STATUS_SUCCESS` on success, or `SPI_STATUS_ERROR` otherwise. `SPI_STATUS_TIMEOUT` if the timeout period elapses, `SPI_STATUS_ERROR` if some other error occurs, otherwise `SPI_STATUS_SUCCESS`.
--- ---

Write Preview
Loading…
Cancel
Save