|
|
|
This page provides the description of the I2C protocol and his implementation in Boardcore.
|
|
|
|
This page provides the description of the I2C protocol and his low and high level implementation in Boardcore.
|
|
|
|
|
|
|
|
# I2C introduction
|
|
|
|
|
| ... | ... | @@ -31,7 +31,8 @@ After the data transfer a STOP condition is sent (consisting in driving the SDA |
|
|
|
|
|
|
|
# Electronic setup
|
|
|
|
|
|
|
|
In order to use properly the I2C bus a pull-up circuit should be implemented. The SCL and SDA GPIOs should be setted with the mode `ALTERNATE_OD` (alternate function with open-drain). This is because master and slaves should only be able to pull down the line and, when they release the line, the signal should be pulled up. If the `ALTERNATE_OD` mode is setted but no pull-up circuit is implemented the driver could hang forever. A lot of sensors implement on their own the pull-up circuit, so it could be enough; however, if no sensor is attached the hanging of the system could be caused anyway.
|
|
|
|
In order to use properly the I2C bus a pull-up circuit should be implemented and the _SCL_ and _SDA_ GPIOs should be setted with the mode `ALTERNATE_OD` (alternate function with open-drain). This is because master and slaves should only be able to pull down the line and, when they release the line, the signal should be pulled up. In order to avoid electrically damaging sensors, the driver sets internally the mode and the alternate functions of the _SCL_ and _SDA_ GPIOs so that we won't end up short circuiting master's VDD and slave's GND for a software error.
|
|
|
|
If the `ALTERNATE_OD` mode is setted but no pull-up circuit is implemented the driver could hang forever. A lot of sensors implement their own pull-up circuit, so it could be enough; however, if no sensor is attached the hanging of the system could be caused anyway.
|
|
|
|
|
|
|
|
# _Deadlocks are a feature, not a bug!_
|
|
|
|
|
| ... | ... | @@ -45,4 +46,25 @@ The locked state manifests as in the following image, so with the SCL line relea |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The recovery of the locked state is performed doing bit-banging of the clock from the master to the slave (literally is like doing CPR to the locked slave), so we force a set of clock cycles on the SCL line (changing the SCL pin to the OUTPUT mode and forcing high/low the line at the right frequency). This injects to the slave the necessary clock cycles in order to end the current transaction and restore to idle mode. |
|
|
\ No newline at end of file |
|
|
|
The recovery of the locked state is performed doing bit-banging of the clock from the master to the slave (literally is like doing CPR to the locked slave), so we force a set of clock cycles on the SCL line (changing the SCL pin to the OUTPUT mode and forcing high/low the line at the right frequency). This injects to the slave the necessary clock cycles in order to end the current transaction and restore to idle mode.
|
|
|
|
|
|
|
|
# Low-level driver: _I2CDriver_
|
|
|
|
In boardcore the most low level driver for the I2C peripherals is the _I2CDriver_, which implements only the basic communication with I2C devices. The principal features implemented are:
|
|
|
|
- Support for both Standard mode (100kHz) and Fast mode (400 kHz);
|
|
|
|
- Support of 7-bit and 10-bit addressing (not yet tested!);
|
|
|
|
- Raw `read` method, in order to read nBytes from a slave;
|
|
|
|
- Raw `write` method, in order to send nBytes to a slave with the possibility to not issue a STOP condition in order to keep the same transaction for the whole communication;
|
|
|
|
- A `flushBus` method in order to recover from a locked state on the bus;
|
|
|
|
|
|
|
|
Be aware that if used in the wrong way, the write method without the STOP condition could lead to deadlocks, so it is reccomanded to use it only through the high-level driver
|
|
|
|
|
|
|
|
# High-level driver: _I2C_ and _SyncedI2C_
|
|
|
|
An abstraction of the low-level driver is implemented in the _I2C_ driver, which collects maybe some useful features for driver developement, such as:
|
|
|
|
- For the raw read and write low-level methods implements an auto-recovery from locked state;
|
|
|
|
- `readRegister`: Implements the read of a register without issuing a STOP condition in the middle;
|
|
|
|
- `probe`: Permit a fast interrogation about the availability of a device on the bus;
|
|
|
|
|
|
|
|
It is also available a synchronized version of the high-level driver called _SyncedI2C_ in order to use this driver in a threadsafe way if for whatever reason this is necessary.
|
|
|
|
|
|
|
|
# Usage
|
|
|
|
The driver usage is as simple as instantiating an I2C object and using his methods. In Boardcore there are two showcases: `test-i2c-driver` (low-level driver) and `test-i2c` (high-level driver). |
|
|
\ No newline at end of file |
