diff options
| -rw-r--r-- | docs/i2c_driver.md | 35 |
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 | ||
| 3 | The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. | 3 | The 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 | |||
| 7 | All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting | ||
| 8 | the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed | ||
| 9 | on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be | ||
| 10 | shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`. | ||
| 11 | |||
| 12 | 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`: | ||
| 13 | |||
| 14 | `#define MY_I2C_ADDRESS (0x18 << 1)` | ||
| 15 | |||
| 16 | See 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 | ||
| 19 | All the above functions, except `void i2c_init(void);` return the following truth table: | 32 | All 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 |