FastArduino
v1.9
C++ library to build fast but small Arduino/AVR projects
|
Define API to define and manage I2C devices. More...
Namespaces | |
debug | |
Defines API to ease I2C devices debugging. | |
status | |
Defines API to ease I2C manager status tracing and debugging. | |
Classes | |
class | I2CDevice |
Base class for all I2C devices. More... | |
class | ReadRegisterFuture |
General Future that can be used to read an I2C device register. More... | |
class | TReadRegisterFuture |
Generic Future that can be used to read an I2C device register. More... | |
class | WriteRegisterFuture |
General Future that can be used to write to an I2C device register. More... | |
class | TWriteRegisterFuture |
Generic Future that can be used to write to an I2C device register. More... | |
class | TWriteMultiRegisterFuture |
Generic Future that can be used to write to several I2C device registers. More... | |
class | I2CFuturesGroup |
Abstract class to allow aggregation of several futures in relation to I2C transactions. More... | |
class | I2CSameFutureGroup |
Class to allow dynamic creation of futures from values stored in flash memory, leading to launch of I2C transactions. More... | |
class | AbstractI2CSyncATmegaManager |
Abstract synchronous I2C Manager for ATmega architecture. More... | |
class | AbstractI2CAsyncManager |
Abstract asynchronous I2C Manager. More... | |
class | I2CAsyncManager |
Asynchronous I2C Manager for ATmega architecture. More... | |
class | I2CAsyncDebugManager |
Asynchronous I2C Manager for ATmega architecture with debug facility. More... | |
class | I2CAsyncStatusManager |
Asynchronous I2C Manager for ATmega architecture with status notification facility. More... | |
class | I2CAsyncStatusDebugManager |
Asynchronous I2C Manager for ATmega architecture with debug and status notification facilities. More... | |
class | I2CAsyncLCManager |
Asynchronous I2C Manager for ATmega architecture with support for dynamic proxies. More... | |
class | I2CAsyncLCDebugManager |
Asynchronous I2C Manager for ATmega architecture with debug facility and support for dynamic proxies. More... | |
class | I2CAsyncLCStatusManager |
Asynchronous I2C Manager for ATmega architecture with status notification facility and support for dynamic proxies. More... | |
class | I2CAsyncLCStatusDebugManager |
Asynchronous I2C Manager for ATmega architecture with debug and status notification facilities and support for dynamic proxies. More... | |
class | I2CSyncManager |
Synchronous I2C Manager for ATmega architecture. More... | |
class | I2CSyncStatusManager |
Synchronous I2C Manager for ATmega architecture wit status notification facility. More... | |
class | I2CSyncDebugManager |
Synchronous I2C Manager for ATmega architecture with debug facility. More... | |
class | I2CSyncStatusDebugManager |
Synchronous I2C Manager for ATmega architecture with status notification and debug facility. More... | |
class | I2CSyncLCManager |
Synchronous I2C Manager for ATmega architecture with support for dynamic proxies. More... | |
class | I2CSyncLCStatusManager |
Synchronous I2C Manager for ATmega architecture with status notification facility and support for dynamic proxies. More... | |
class | I2CSyncLCDebugManager |
Synchronous I2C Manager for ATmega architecture with debug facility and support for dynamic proxies. More... | |
class | I2CSyncLCStatusDebugManager |
Synchronous I2C Manager for ATmega architecture with status notification and debug facilities and support for dynamic proxies. More... | |
class | AbstractI2CSyncATtinyManager |
Abstract synchronous I2C Manager for ATtiny architecture. More... | |
class | I2CLightCommand |
Light atomic I2C command as prepared by an I2C device. More... | |
class | I2CCommand |
Atomic I2C command as used internally by an asynchronous I2C Manager. More... | |
class | AbstractI2CSyncManager |
Abstract synchronous I2C Manager for all MCU architectures. More... | |
Typedefs | |
using | I2C_DEBUG_HOOK = void(*)(DebugStatus status, uint8_t data) |
The default debugging hook type. More... | |
using | I2C_STATUS_HOOK = void(*)(Status expected, Status actual) |
The default status observer hook type. More... | |
Enumerations | |
enum class | Status : uint8_t { OK = 0x00 , START_TRANSMITTED = 0x08 , REPEAT_START_TRANSMITTED = 0x10 , SLA_W_TRANSMITTED_ACK = 0x18 , SLA_W_TRANSMITTED_NACK = 0x20 , DATA_TRANSMITTED_ACK = 0x28 , DATA_TRANSMITTED_NACK = 0x30 , ARBITRATION_LOST = 0x38 , SLA_R_TRANSMITTED_ACK = 0x40 , SLA_R_TRANSMITTED_NACK = 0x48 , DATA_RECEIVED_ACK = 0x50 , DATA_RECEIVED_NACK = 0x58 } |
Transmission status codes. More... | |
enum class | I2CMode : uint8_t { STANDARD , FAST } |
I2C available transmission modes. More... | |
enum class | I2CErrorPolicy : uint8_t { DO_NOTHING , CLEAR_ALL_COMMANDS , CLEAR_TRANSACTION_COMMANDS } |
I2C Manager policy to use in case of an error during I2C transaction. More... | |
enum class | I2CCallback : uint8_t { NONE = 0 , END_COMMAND , END_TRANSACTION , ERROR } |
Type passed to I2C ISR registered callbacks (asynchronous I2C Manager only) when an asynchronous I2C transaction is executed. More... | |
enum class | DebugStatus : uint8_t { START = 0 , REPEAT_START , SLAW , SLAR , SEND , RECV , RECV_LAST , STOP , SEND_OK , SEND_ERROR , RECV_OK , RECV_ERROR } |
List of debug states that are reported by the I2C Manager in debug mode. More... | |
Functions | |
template<typename MANAGER > | |
bool | await_same_future_group (I2CDevice< MANAGER > &device, const uint8_t *buffer, uint8_t size) |
Helper function that creates a I2CSameFutureGroup instance for the provided flash array, launches its I2C transactions on the provided I2C device, and waits for the transaction to finish. More... | |
Variables | |
static constexpr Mode | I2C_STANDARD = Mode<I2CMode::STANDARD>{} |
Constant determining that best supported I2C mode for an I2CDevice is STANDARD (100kHz). | |
static constexpr Mode | I2C_FAST = Mode<I2CMode::FAST>{} |
Constant determining that best supported I2C mode for an I2CDevice is FAST (400kHz). | |
Define API to define and manage I2C devices.
This namespace defines everything related to I2C.
I2C is available to all MCU supported by FastArduino, even in ATtiny MCU, for which I2C is implemented with Universal Serial Interface (USI).
The following snippet shows how to use an I2C device, the DS1307 Real Time Clock:
In FastArduino, I2C communication is centralized by an I2C Manager; there are several flavors of I2C Manager defined in FastArduino, with distinct characteristics such as:
I2C devices to connect with must be managed by a dedicated subclass of i2c::I2CDevice, which provides a specific API for the interfaced device, and handles all communication with an I2C Manager.
For any I2C device subclass, the provided API comes in 2 flavours at a time (whatever I2C Manager is used):
FastArduino defines many specific I2C Manager classes among the following:
All these classes are template classes with various arguments (the actual list of arguments depends on each specific class):
All these different flavors of I2C Manager share the same API (except for their constructor that may need different arguments).
Lifecycle support enables programs to move futures around without losing track of the right location, thanks to the use of lifecycle::LightProxy. Although not often needed, it can prove useful in some situations.
All I2C Manager asynchronous flavors operate based on a queue of I2C commands. It is up to the end program to create the properly sized buffer for that command queue, before instantiating the relevant asynchronous I2C Manager; the buffer must be passed to the asynchronous I2C Manager constructor. Asynchronous I2C Manager classes will work fine only if the proper ISR function is registered, through one of the 3 provided registration macros. Some of these registration macros also allow registration of a callback hook that will be called for every single I2C step (as defined in ATmega datasheet).
The following snippet shows the minimal code to operate the I2C RTC device DS1307 in synchronous mode:
The next snippet demonstrates how to do the same but in an asynchronous way:
using i2c::I2C_DEBUG_HOOK = typedef void (*)(DebugStatus status, uint8_t data) |
The default debugging hook type.
i2c_debug.h
.Definition at line 83 of file i2c_handler_common.h.
using i2c::I2C_STATUS_HOOK = typedef void (*)(Status expected, Status actual) |
The default status observer hook type.
i2c_status.h
.Definition at line 96 of file i2c_handler_common.h.
|
strong |
Transmission status codes.
Transmission status is returned by all i2c::I2CDevice
read and write methods. This status is also transmitted to an optional hook function for debug purposes.
All codes are defined and directly mapped from ATmega328 datasheet (section 22. "2-wire Serial interface", tables 22-2 and 22-3).
You will probably never need to use these codes in your program.
|
strong |
I2C available transmission modes.
This defines the maximum bus transmission frequency.
Enumerator | |
---|---|
STANDARD | I2C Standard mode, less than 100KHz. |
FAST | I2C Fast mode, less than 400KHz. |
|
strong |
I2C Manager policy to use in case of an error during I2C transaction.
Enumerator | |
---|---|
DO_NOTHING | Do nothing at all in case of an error; useful only with a synchronous I2C Manager. |
CLEAR_ALL_COMMANDS | In case of an error during I2C transaction, then all I2CCommand currently in queue will be removed.
|
CLEAR_TRANSACTION_COMMANDS | In case of an error during I2C transaction, then all pending I2CCommand of the current transaction will be removed. |
Definition at line 119 of file i2c_handler_atmega.h.
|
strong |
Type passed to I2C ISR registered callbacks (asynchronous I2C Manager only) when an asynchronous I2C transaction is executed.
Definition at line 146 of file i2c_handler_atmega.h.
|
strong |
List of debug states that are reported by the I2C Manager in debug mode.
Definition at line 43 of file i2c_handler_common.h.
bool i2c::await_same_future_group | ( | I2CDevice< MANAGER > & | device, |
const uint8_t * | buffer, | ||
uint8_t | size | ||
) |
Helper function that creates a I2CSameFutureGroup
instance for the provided flash array, launches its I2C transactions on the provided I2C device, and waits for the transaction to finish.
MANAGER | the type of I2C Manager used to handle I2C communication |
device | the i2c::I2CDevice subclass instance that shall handle I2C commands to the I2C device |
buffer | pointer, in flash storage space, to the first byte to write to the I2C device |
size | size in bytes of the buffer array |
true | if the whole I2C transactions could be completely performed successfully |
Definition at line 815 of file i2c_device_utilities.h.