Helper module for I2C (aka TWI) communication. Provides an asynchronous, interrupt-driven request-response API. This API is master mode only, for the time being.
| i2chelper.h | Helper module for I2C (aka TWI) communication. |
| Enumerations | |
| I2C Module State/ | NOTE: The error codes are those with names starting with “I2C_E_”. |
| Variables | |
| i2c_slave_addr | The type of I2C slave addresses. |
| i2c_state | The type of state and result codes for the I2C module. |
| i2c_task_cats | Tasks in the categories indicated by this sched_catflags value will be notified by the I2C module’s ISR when a request operation finishes (either successfully or with an error). |
| i2c_request_state | Contains a state code representing the current state of the I2C module. |
| Macros | |
| I2C_IS_READY | Evaluates to a true value if and only if the I2C module is initialized and ready to begin a new operation. |
| I2C_IS_ACTIVE | Evaluates to a true value if and only if the I2C module is busy with an ongoing operation. |
| Functions | |
| i2chelper_mstr_init | Configures the I2C module for master mode (the only one currently implemented). |
| i2chelper_request | Initiates an I2C request operation consisting of a transmit phase followed by a receive phase. |
| i2chelper_shutdown | Shuts down the I2C module. |
NOTE: The error codes are those with names starting with “I2C_E_”. These all have numeric values greater than or equal to I2C_E_UNSPECIFIED.
extern volatile sched_catflags i2c_task_cats
Tasks in the categories indicated by this sched_catflags value will be notified by the I2C module’s ISR when a request operation finishes (either successfully or with an error).
void i2chelper_mstr_init( uint8_t twbr, sched_catflags task_cats )
Configures the I2C module for master mode (the only one currently implemented).
| twbr | A clock divisor value that is used to control the I2C bit rate. |
| task_cats | A set of bit flags specifying task categories whose members should be notified when this module has finished an I2C transaction. Used to initialize i2c_task_cats. |
i2c_state i2chelper_request( i2c_slave_addr addr, uint8_t n_out, volatile const uint8_t * bfr_out, uint8_t n_in, volatile uint8_t * bfr_in )
Initiates an I2C request operation consisting of a transmit phase followed by a receive phase. Either the transmit or the receive phase can be omitted, but not both.
Completion of an I2C request initiated by this function can be detected by polling i2c_request_state (e.g. via the I2C_IS_ACTIVE macro) and by specifying task categories to be notified via i2c_task_cats.
NOTE: The bfr_out and bfr_in arguments MAY point to the same buffer. This function ensures that all the bytes to transmit from bfr_out are transmitted before any received bytes are stored in bfr_in.
| addr | The 7-bit I2C slave address of the target device. The address MUST be stored in the 7 least significant bits of the argument and MUST NOT include an R/W control bit. |
| n_out | Number of data bytes to transmit. If this argument is zero, the transmit phase will be omitted and the I2C module will transmit an SLA+R address byte immediately after transmitting a START condition. |
| bfr_out | Pointer to the data bytes to transmit. If n_out is zero, this MAY be a null pointer. |
| n_in | Number of data bytes to receive. If this argument is zero, the receive phase will be omitted and the I2C module will transmit a STOP condition immediately after receiving (positive or negative) acknowledgement of the last transmitted data byte. |
| bfr_in | Pointer to memory to copy received data bytes into. If n_in is zero, this MAY be a null pointer. |
I2C_ACTIVE if and only if the request operation was successfully started, otherwise an error code.
The type of I2C slave addresses.
typedef uint8_t i2c_slave_addr
The type of state and result codes for the I2C module.
typedef uint8_t i2c_state
Tasks in the categories indicated by this sched_catflags value will be notified by the I2C module’s ISR when a request operation finishes (either successfully or with an error).
extern volatile sched_catflags i2c_task_cats
The type of fields containing sets of bit flags that correspond to task categories.
typedef uint16_t sched_catflags
Contains a state code representing the current state of the I2C module.
extern volatile i2c_state i2c_request_state
Configures the I2C module for master mode (the only one currently implemented).
void i2chelper_mstr_init( uint8_t twbr, sched_catflags task_cats )
Initiates an I2C request operation consisting of a transmit phase followed by a receive phase.
i2c_state i2chelper_request( i2c_slave_addr addr, uint8_t n_out, volatile const uint8_t * bfr_out, uint8_t n_in, volatile uint8_t * bfr_in )
Shuts down the I2C module.
void i2chelper_shutdown( void )