Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update to I2C docs: Clarify address expectation and return values #8413

Merged
merged 8 commits into from
Mar 15, 2020
Merged

Update to I2C docs: Clarify address expectation and return values #8413

Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7de0784
Clarifying docs for i2c
brickbots Mar 14, 2020
07c9ad8
Fix typo
brickbots Mar 14, 2020
82eb1d8
Fix up punctuation
brickbots Mar 14, 2020
533c55e
Implementing great suggestions
brickbots Mar 14, 2020
2b66f83
Merge branch 'master' of https://github.com/qmk/qmk_firmware into i2c…
brickbots Mar 14, 2020
a459c50
All merged together now
brickbots Mar 14, 2020
408c29f
Update docs/i2c_driver.md
brickbots Mar 14, 2020
effc191
Update docs/i2c_driver.md
brickbots Mar 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 32 additions & 6 deletions docs/i2c_driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,34 @@

The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs.

## An important 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
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
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`:

`#define MY_I2C_ADDRESS 0x18 << 1`

See:

https://www.robot-electronics.co.uk/i2c-tutorial

For more information about I2C addressing and other technial details.

## Available functions

|Function |Description |
|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. |
|`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. |
|`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. |
|`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. |
|`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. |
|`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. |
|`uint8_t i2c_stop(void);` |Ends an I2C transaction. |
|`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

Expand All @@ -24,6 +41,15 @@ All the above functions, except `void i2c_init(void);` return the following trut
|-1 |Operation failed. |
|-2 |Operation timed out. |

These are defined in `i2c_master.h` and it is suggested you use this definitions for future compatibility if
they change.

```
#define I2C_STATUS_SUCCESS (0)
#define I2C_STATUS_ERROR (-1)
#define I2C_STATUS_TIMEOUT (-2)
```


## AVR

Expand Down