aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorbrickbots <rich@brickbots.com>2020-03-15 00:17:48 -0700
committerGitHub <noreply@github.com>2020-03-15 00:17:48 -0700
commit499d7c8ce610a3c150c64eaacbca3038f7796cc5 (patch)
tree729e82225170a337d9007b46e7d7708f480f8da8 /docs
parent60b020acabf5f78976203213bfd0097eed7656a4 (diff)
downloadqmk_firmware-499d7c8ce610a3c150c64eaacbca3038f7796cc5.tar.gz
qmk_firmware-499d7c8ce610a3c150c64eaacbca3038f7796cc5.zip
[Docs] Update to I2C docs: Clarify address expectation and return values (#8413)
* Clarifying docs for i2c * Fix typo * Fix up punctuation * Implementing great suggestions * Update docs/i2c_driver.md * Update docs/i2c_driver.md
Diffstat (limited to 'docs')
-rw-r--r--docs/i2c_driver.md35
1 files changed, 24 insertions, 11 deletions
diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md
index d5c340edc..c9f53ef0d 100644
--- a/docs/i2c_driver.md
+++ b/docs/i2c_driver.md
@@ -2,27 +2,40 @@
2 2
3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. 3The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.
4 4
5## An important note on I2C Addresses
6
7All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting
8the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed
9on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be
10shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`.
11
12You 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`:
13
14`#define MY_I2C_ADDRESS (0x18 << 1)`
15
16See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details.
17
5## Available functions 18## Available functions
6 19
7|Function |Description | 20|Function |Description |
8|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 21|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
9|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. | 22|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. |
10|`uint8_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. | 23|`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. |
11|`uint8_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. | 24|`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. |
12|`uint8_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. | 25|`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. |
13|`uint8_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. | 26|`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. |
14|`uint8_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. | 27|`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. |
15|`uint8_t i2c_stop(void);` |Ends an I2C transaction. | 28|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. |
16 29
17### Function Return 30### Function Return
18 31
19All the above functions, except `void i2c_init(void);` return the following truth table: 32All the above functions, except `void i2c_init(void);` return the following truth table:
20 33
21|Return Value |Description | 34|Return Constant |Value|Description |
22|---------------|---------------------------------------------------| 35|--------------------|-----|--------------------------------|
23|0 |Operation executed successfully. | 36|`I2C_STATUS_SUCCESS`|0 |Operation executed successfully.|
24|-1 |Operation failed. | 37|`I2C_STATUS_ERROR` |-1 |Operation failed. |
25|-2 |Operation timed out. | 38|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. |
26 39
27 40
28## AVR 41## AVR
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-04 07:58:35 +0000