logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

i2c.md (12767B)

    

  1. # I2C Master Driver {#i2c-master-driver}
  3. The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
  5. ## Usage {#usage}
  7. In most cases, the I2C Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](../features/oled_driver).
  9. However, if you need to use the driver standalone, add the following to your `rules.mk`:
  11. ```make
  12. I2C_DRIVER_REQUIRED = yes
  13. ```
  15. You can then call the I2C API by including `i2c_master.h` in your code.
  17. ## I2C Addressing {#note-on-i2c-addresses}
  19. I2C addresses listed on datasheets and the internet are usually represented as a 7-bit value. The eighth bit (the least significant bit) controls whether the operation is a read or a write.
  21. All of the address parameters expected by the driver API should therefore be pushed to the upper 7 bits of the address byte; the driver will take care of setting the read/write bit as appropriate.
  23. This is easy to do via the bitwise left shift operator. For example, if your device has an address of `0x18` you might create a define for convenience:
  25. ```c
  26. #define MY_I2C_ADDRESS (0x18 << 1)
  27. ```
  29. Or, you can shift the address ahead of time:
  31. ```c
  32. #define MY_I2C_ADDRESS 0x30
  33. ```
  35. See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
  37. ## AVR Configuration {#avr-configuration}
  39. The following defines can be used to configure the I2C master driver:
  41. |`config.h` Override|Description          |Default |
  42. |-------------------|---------------------|--------|
  43. |`F_SCL`            |Clock frequency in Hz|`400000`|
  45. No further setup is required - just connect the `SDA` and `SCL` pins of your I2C devices to the matching pins on the MCU:
  47. |MCU          |`SCL`|`SDA`|
  48. |-------------|-----|-----|
  49. |ATmega16/32U4|`D0` |`D1` |
  50. |AT90USB64/128|`D0` |`D1` |
  51. |ATmega32A    |`C0` |`C1` |
  52. |ATmega328/P  |`C5` |`C4` |
  54. ::: tip
  55. The ATmega16/32U2 does not possess I2C functionality, and so cannot use this driver.
  56. :::
  58. ## ChibiOS/ARM Configuration {#arm-configuration}
  60. You'll need to determine which pins can be used for I2C -- as an example, STM32 parts generally have multiple I2C peripherals, labeled I2C1, I2C2, I2C3 etc.
  62. To enable I2C, modify your board's `halconf.h` to enable I2C, then modify your board's `mcuconf.h` to enable the peripheral you've chosen:
  64. ::: code-group
  65. ```c [halconf.h]
  66. #pragma once
  68. #define HAL_USE_I2C TRUE // [!code focus]
  70. #include_next <halconf.h>
  71. ```
  72. ```c [mcuconf.h]
  73. #pragma once
  75. #include_next <mcuconf.h>
  77. #undef STM32_I2C_USE_I2C2 // [!code focus]
  78. #define STM32_I2C_USE_I2C2 TRUE // [!code focus]
  79. ```
  80. :::
  82. |`mcuconf.h` Setting         |Description                                                                       |Default|
  83. |----------------------------|----------------------------------------------------------------------------------|-------|
  84. |`STM32_I2C_BUSY_TIMEOUT`    |Time in milliseconds until the I2C command is aborted if no response is received  |`50`   |
  85. |`STM32_I2C_XXX_IRQ_PRIORITY`|Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING)            |`10`   |
  86. |`STM32_I2C_USE_DMA`         |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit|`TRUE` |
  87. |`STM32_I2C_XXX_DMA_PRIORITY`|Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING)          |`1`    |
  89. 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.
  91. |`config.h` Override|Description                                                  |Default|
  92. |-------------------|-------------------------------------------------------------|-------|
  93. |`I2C_DRIVER`       |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc.|`I2CD1`|
  94. |`I2C1_SCL_PIN`     |The pin to use for SCL                                       |`B6`   |
  95. |`I2C1_SCL_PAL_MODE`|The alternate function mode for SCL                          |`4`    |
  96. |`I2C1_SDA_PIN`     |The pin to use for SDA                                       |`B7`   |
  97. |`I2C1_SDA_PAL_MODE`|The alternate function mode for SDA                          |`4`    |
  99. ::: tip
  100. Currently only a single I2C peripheral is supported, therefore the `I2C1_*` defines are used for configuration regardless of the selected peripheral.
  101. :::
  103. The following configuration values are dependent on the ChibiOS I2C LLD, which is dictated by the microcontroller.
  105. ### I2Cv1 {#arm-configuration-i2cv1}
  107. * STM32F1xx
  108. * STM32F2xx
  109. * STM32F4xx
  110. * STM32L0xx
  111. * STM32L1xx
  113. See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#7_I2Cv1_configuration_structure) for the I2Cv1 configuration structure.
  115. |`config.h` Override|Default         |
  116. |-------------------|----------------|
  117. |`I2C1_OPMODE`      |`OPMODE_I2C`    |
  118. |`I2C1_CLOCK_SPEED` |`100000`        |
  119. |`I2C1_DUTY_CYCLE`  |`STD_DUTY_CYCLE`|
  121. ### I2Cv2 {#arm-configuration-i2cv2}
  123. * STM32F0xx
  124. * STM32F3xx
  125. * STM32F7xx
  126. * STM32L4xx
  128. See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#8_I2Cv2_I2Cv3_configuration_structure) for the I2Cv2 configuration structure.
  130. |`config.h` Override  |Default|
  131. |---------------------|-------|
  132. |`I2C1_TIMINGR_PRESC` |`0U`   |
  133. |`I2C1_TIMINGR_SCLDEL`|`7U`   |
  134. |`I2C1_TIMINGR_SDADEL`|`0U`   |
  135. |`I2C1_TIMINGR_SCLH`  |`38U`  |
  136. |`I2C1_TIMINGR_SCLL`  |`129U` |
  138. ## API {#api}
  140. ### `void i2c_init(void)` {#api-i2c-init}
  142. Initialize the I2C driver. This function must be called only once, before any of the below functions can be called.
  144. This function is weakly defined, meaning it can be overridden if necessary for your particular use case:
  146. ```c
  147. void i2c_init(void) {
  148.     gpio_set_pin_input(B6); // Try releasing special pins for a short time
  149.     gpio_set_pin_input(B7);
  150.     wait_ms(10); // Wait for the release to happen
  152.     palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function
  153.     palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function
  154. }
  155. ```
  157. ---
  159. ### `i2c_status_t i2c_transmit(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-transmit}
  161. Send multiple bytes to the selected I2C device.
  163. #### Arguments {#api-i2c-transmit-arguments}
  165.  - `uint8_t address`  
  166.    The 7-bit I2C address of the device.
  167.  - `const uint8_t* data`  
  168.    A pointer to the data to transmit.
  169.  - `uint16_t length`  
  170.    The number of bytes to write. Take care not to overrun the length of `data`.
  171.  - `uint16_t timeout`  
  172.    The time in milliseconds to wait for a response from the target device.
  174. #### Return Value {#api-i2c-transmit-return}
  176. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  178. ---
  180. ### `i2c_status_t i2c_transmit_P(uint8_t address, const uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-transmit-p}
  182. Send multiple bytes from PROGMEM to the selected I2C device.
  184. On ARM devices, this function is simply an alias for `i2c_transmit(address, data, length, timeout)`.
  186. #### Arguments {#api-i2c-transmit-p-arguments}
  188.  - `uint8_t address`  
  189.    The 7-bit I2C address of the device.
  190.  - `const uint8_t* data`  
  191.    A pointer to the data to transmit.
  192.  - `uint16_t length`  
  193.    The number of bytes to write. Take care not to overrun the length of `data`.
  194.  - `uint16_t timeout`  
  195.    The time in milliseconds to wait for a response from the target device.
  197. #### Return Value {#api-i2c-transmit-p-return}
  199. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  201. ---
  203. ### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-receive}
  205. Receive multiple bytes from the selected I2C device.
  207. #### Arguments {#api-i2c-receive-arguments}
  209.  - `uint8_t address`  
  210.    The 7-bit I2C address of the device.
  211.  - `uint8_t* data`  
  212.    A pointer to a buffer to read into.
  213.  - `uint16_t length`  
  214.    The number of bytes to read. Take care not to overrun the length of `data`.
  215.  - `uint16_t timeout`  
  216.    The time in milliseconds to wait for a response from the target device.
  218. #### Return Value {#api-i2c-receive-return}
  220. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  222. ---
  224. ### `i2c_status_t i2c_write_register(uint8_t devaddr, uint8_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-write-register}
  226. Write to a register with an 8-bit address on the I2C device.
  228. #### Arguments {#api-i2c-write-register-arguments}
  230.  - `uint8_t devaddr`  
  231.    The 7-bit I2C address of the device.
  232.  - `uint8_t regaddr`  
  233.    The register address to write to.
  234.  - `const uint8_t* data`  
  235.    A pointer to the data to transmit.
  236.  - `uint16_t length`  
  237.    The number of bytes to write. Take care not to overrun the length of `data`.
  238.  - `uint16_t timeout`  
  239.    The time in milliseconds to wait for a response from the target device.
  241. #### Return Value {#api-i2c-write-register-return}
  243. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  245. ---
  247. ### `i2c_status_t i2c_write_register16(uint8_t devaddr, uint16_t regaddr, const uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-write-register16}
  249. Write to a register with a 16-bit address (big endian) on the I2C device.
  251. #### Arguments {#api-i2c-write-register16-arguments}
  253.  - `uint8_t devaddr`  
  254.    The 7-bit I2C address of the device.
  255.  - `uint16_t regaddr`  
  256.    The register address to write to.
  257.  - `const uint8_t* data`  
  258.    A pointer to the data to transmit.
  259.  - `uint16_t length`  
  260.    The number of bytes to write. Take care not to overrun the length of `data`.
  261.  - `uint16_t timeout`  
  262.    The time in milliseconds to wait for a response from the target device.
  264. #### Return Value {#api-i2c-write-register16-return}
  266. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  268. ---
  270. ### `i2c_status_t i2c_read_register(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-read-register}
  272. Read from a register with an 8-bit address on the I2C device.
  274. #### Arguments {#api-i2c-read-register-arguments}
  276.  - `uint8_t devaddr`  
  277.    The 7-bit I2C address of the device.
  278.  - `uint8_t regaddr`  
  279.    The register address to read from.
  280.  - `uint8_t data`  
  281.    A pointer to a buffer to read into.
  282.  - `uint16_t length`  
  283.    The number of bytes to read. Take care not to overrun the length of `data`.
  284.  - `uint16_t timeout`  
  285.    The time in milliseconds to wait for a response from the target device.
  287. #### Return Value {#api-i2c-read-register-return}
  289. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  291. ---
  293. ### `i2c_status_t i2c_read_register16(uint8_t devaddr, uint16_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` {#api-i2c-read-register16}
  295. Read from a register with a 16-bit address (big endian) on the I2C device.
  297. #### Arguments {#api-i2c-read-register16-arguments}
  299.  - `uint8_t devaddr`  
  300.    The 7-bit I2C address of the device.
  301.  - `uint16_t regaddr`  
  302.    The register address to read from.
  303.  - `uint8_t* data`  
  304.    A pointer to a buffer to read into.
  305.  - `uint16_t length`  
  306.    The number of bytes to read. Take care not to overrun the length of `data`.
  307.  - `uint16_t timeout`  
  308.    The time in milliseconds to wait for a response from the target device.
  310. #### Return Value {#api-i2c-read-register16-return}
  312. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.
  314. ---
  316. ### `i2c_status_t i2c_ping_address(uint8_t address, uint16_t timeout)` {#api-i2c-ping-address}
  318. Ping the I2C bus for a specific address.
  320. On ChibiOS a "best effort" attempt is made by reading a single byte from register 0 at the given address. This should generally work except for I2C devices that do not not respond to a register 0 read request, which will result in a false negative result (unsuccessful response to ping attempt).
  322. This function is weakly defined, meaning it can be overridden if necessary for your particular use case.
  324. #### Arguments {#api-i2c-ping-address-arguments}
  326.  - `uint8_t address`  
  327.    The 7-bit I2C address of the device.
  328.  - `uint16_t timeout`  
  329.    The time in milliseconds to wait for a response from the target device.
  331. #### Return Value {#api-i2c-ping-address-return}
  333. `I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`.