i2chelper.h

Asynchronous, interrupt-driven I2C (aka TWI) helper module.  Master mode only, for the time being.

Summary
i2chelper.hAsynchronous, interrupt-driven I2C (aka TWI) helper module.
Enumerations
I2C Module State/Result CodesNOTE: The error codes are those with names starting with “I2C_E_”.
Variables
i2c_slave_addrThe type of I2C slave addresses.
i2c_stateThe type of state and result codes for the I2C module.
i2c_task_catsTasks 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_stateContains a state code representing the current state of the I2C module.
Macros
I2C_IS_READYEvaluates to a true value if and only if the I2C module is initialized and ready to begin a new operation.
I2C_IS_ACTIVEEvaluates to a true value if and only if the I2C module is busy with an ongoing operation.
Functions
i2chelper_mstr_initConfigures the I2C module for master mode (the only one currently implemented).
i2chelper_requestInitiates an I2C request operation consisting of a transmit phase followed by a receive phase.
i2chelper_shutdownShuts down the I2C module.

Enumerations

I2C Module State/Result Codes

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.

I2C_DISABLEDmodule is disabled
I2C_READYmodule is idle and ready to begin a new operation
I2C_ACTIVEmodule is currently performing an operation
I2C_E_UNSPECIFIEDunspecified error
I2C_E_LENGTHI2C length error (bytes to transmit and receive both zero)
I2C_E_STATEattempted operation not allowed in current module state
I2C_E_NOT_ACKreceived unexpected negative acknowledgement
I2C_E_ARB_LOSTlost I2C master arbitration
I2C_E_FSMhardware generated unexpected status code

Variables

i2c_slave_addr

typedef uint8_t i2c_slave_addr

The type of I2C slave addresses.

i2c_state

typedef uint8_t i2c_state

The type of state and result codes for the I2C module.

i2c_task_cats

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).

i2c_request_state

extern volatile i2c_state i2c_request_state

Contains a state code representing the current state of the I2C module.

CAUTION: Do not update this variable in external code, unless you know what you’re doing.

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.  Expression macro.

I2C_IS_ACTIVE

Evaluates to a true value if and only if the I2C module is busy with an ongoing operation.  Expression macro.

Functions

i2chelper_mstr_init

void i2chelper_mstr_init(uint8_t twbr,
sched_catflags task_cats)

Configures the I2C module for master mode (the only one currently implemented).

Parameters

twbrA clock divisor value that is used to control the I2C bit rate.
task_catsA set of bit flags specifying task categories whose members should be notified in response to certain events in the I2C module.  Used to initialize i2c_task_cats.

i2chelper_request

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.

Parameters

addrThe 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_outNumber of 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_outPointer to the data bytes to transmit.  If n_out is zero, this MAY be a null pointer.
n_inNumber of 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_inPointer to memory to copy received data bytes into.  If n_in is zero, this MAY be a null pointer.

Returns

I2C_ACTIVE if and only if the request operation was successfully started, otherwise an error code.

i2chelper_shutdown

void i2chelper_shutdown(void)

Shuts down the I2C module.

CAUTION: Do not call this function while an I2C operation is ongoing.

typedef uint8_t i2c_slave_addr
The type of I2C slave addresses.
typedef uint8_t i2c_state
The type of state and result codes for the I2C module.
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).
typedef uint16_t sched_catflags
The type of fields containing sets of bit flags that correspond to task categories.
extern volatile i2c_state i2c_request_state
Contains a state code representing the current state of the I2C module.
void i2chelper_mstr_init(uint8_t twbr,
sched_catflags task_cats)
Configures the I2C module for master mode (the only one currently implemented).
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.
void i2chelper_shutdown(void)
Shuts down the I2C module.
Evaluates to a true value if and only if the I2C module is busy with an ongoing operation.
module is currently performing an operation
Close