I2C¶

I²C (Inter-Integrated Circuit) is a synchronous, multi-master, multi-slave, packet switched, single-ended, serial bus

It is widely used for attaching lower-speed peripheral ICs to processors and microcontrollers in short-distance, intra-board communication.

MiraOS support a single I2C master interface to communicate with slaves.

Enums¶

mira_i2c_frequency_t¶

Name	Value	Description
`MIRA_I2C_FREQUENCY_100_KHZ`
`MIRA_I2C_FREQUENCY_250_KHZ`
`MIRA_I2C_FREQUENCY_400_KHZ`

mira_i2c_transfer_type_t¶

Name	Value	Description
`MIRA_I2C_TRANSFER_TYPE_TX`
`MIRA_I2C_TRANSFER_TYPE_RX`
`MIRA_I2C_TRANSFER_TYPE_NONE`

Structs¶

mira_i2c_config_t¶

Type	Name	Description
`mira_gpio_pin_t`	pin	GPIO pin to use for the SCL clock signal GPIO pin to use for the SDA signal
`mira_gpio_pull_t`	pull	Pull resistor setting for SCL Pull resistor setting for SDA
`struct mira_i2c_config_t::@2`	scl
`struct mira_i2c_config_t::@3`	sda
`mira_i2c_frequency_t`	frequency	The transfer frequency

Structs¶

mira_i2c_context_t¶

Type	Name	Description
`process`	transfer_process
`uint8_t *`	primary_buffer
`uint8_t *`	secondary_buffer
`uint16_t`	primary_buffer_size
`uint16_t`	secondary_buffer_size
`mira_i2c_transfer_type_t`	transfer_type
`mira_status_t`	transfer_status
`uint8_t`	slave_address
`mira_bool_t`	is_transfering

Struct containing the context of an i2c channel.

Do not change this struct directly, use the modifier methods mira_i2c_set_*().

Functions¶

mira_i2c_init¶

mira_status_t mira_i2c_init(
    mira_i2c_context_t*   context,
    mira_gpio_pin_t       pin_scl,
    mira_gpio_pin_t       pin_sda,
    mira_i2c_frequency_t  frequency);

Initialize the I2C module with default configuration Pull resistors default at pull-up. Use

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.
`pin_scl`	GPIO pin to use for the SCL clock signal.
`pin_sda`	GPIO pin to use for the SDA signal.
`frequency`	The transfer frequency.

Return

See enum definition.

Value	Description
`MIRA_SUCCESS`	I2C successfully initialized.
`MIRA_ERROR_UNKNOWN`	An unknown error occurred.
`MIRA_INVALID_VALUE`	Invalid input parameter.
`MIRA_I2C_ERROR_INVALID_PIN`	Chosen pins are not valid.
`MIRA_ERROR_NOT_IMPLEMENTED`	I2C not implemented.

mira_i2c_config_init¶

mira_status_t mira_i2c_config_init(
    mira_i2c_context_t*       context,
    const mira_i2c_config_t*  config);

Initialize the I2C module with the configuration passed as argument.

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.
`config`	See `mira_i2c_config_t`.

Return

See enum definition.

Value	Description
`MIRA_SUCCESS`	I2C successfully initialized.
`MIRA_ERROR_UNKNOWN`	An unknown error occurred.
`MIRA_INVALID_VALUE`	Invalid input parameter.
`MIRA_I2C_ERROR_INVALID_PIN`	Chosen pins are not valid.
`MIRA_ERROR_NOT_IMPLEMENTED`	I2C not implemented.

mira_i2c_context_t context;
mira_status_t status = mira_i2c_init(
    &context,
    &(mira_i2c_config_t) {
        .scl = {
            .pin = RTC_SCL,
            .pull = MIRA_GPIO_PULL_NONE
        },
        .sda = {
            .pin = RTC_SDA,
            .pull = MIRA_GPIO_PULL_NONE
        },
        .frequency = MIRA_I2C_FREQUENCY_400_KHZ
    });
// Check return value

mira_i2c_uninit¶

void mira_i2c_uninit(
    mira_i2c_context_t*  context);

Uninitialize the I2C module.

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.

Return

void

mira_i2c_set_transfer_type_write¶

void mira_i2c_set_transfer_type_write(
    mira_i2c_context_t*  context,
    uint8_t*             write_buffer,
    uint16_t             nb_bytes_to_write);

Set the type of transfer to write.

Write buffer can be constructed manually or by using mira_i2c_construct_write_buffer.

The write sequence is:

-----------------------------------------------------------
Master | SLAVE+W |   | CMD/RA |   | D |   |...| D |   | P |
-----------------------------------------------------------
Slave  |         | A |        | A |   | A |...|   | A |   |
-----------------------------------------------------------
SLAVE+W = slave address followed by 0 for write.
CMD/RA = command or register address to send to slave.
S = start condition
A = ACK
D = data byte
P = stop condition

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.
`write_buffer`	The data to be written to slave device. Command or register address followed by the data to write to register of slave.
`nb_bytes_to_write`	The number of bytes to write to slave.

Return

void

mira_i2c_get_transfer_status¶

mira_status_t mira_i2c_get_transfer_status(
    mira_i2c_context_t*  context);

Get the transfer status after transfer done.

Note: Only valid after mira_i2c_transfer_in_progress returns MIRA_FALSE.

Return

See enum definition.

Value	Description
`MIRA_SUCCESS`	I2C successfully transfered.
`MIRA_I2C_ERROR_NACK`	I2C transfer NACKed.
`MIRA_ERROR_UNKNOWN`	Unknown error.
`MIRA_I2C_ERROR_INVALID_SLAVE_ADDRESS`	Slave address is invalid.
`MIRA_I2C_ERROR_INVALID_TRANSFER_TYPE`	Transfer type is invalid.

mira_i2c_set_transfer_type_read¶

void mira_i2c_set_transfer_type_read(
    mira_i2c_context_t*  context,
    uint8_t*             write_buffer,
    uint16_t             nb_bytes_to_write,
    uint8_t*             read_buffer,
    uint16_t             nb_bytes_to_read);

Set the type of transfer to read.

The read sequence is:

-----------------------------------------------------------------------------
Master | SLAVE+W |   | CMD/RA |   | S | SLAVE+R |   |   | A |...|   | A | P |
-----------------------------------------------------------------------------
Slave  |         | A |        | A |   |         | A | D |   |...| D |   |   |
-----------------------------------------------------------------------------
SLAVE+W = slave address followed by 0 for write.
SLAVE+R = slave address followed by 1 for read.
CMD/RA = command or register address to send to slave.
S = start condition
A = ACK
D = data byte
P = stop condition

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.
`write_buffer`	The data to be written to slave device. Command or register address and any extra write data.
`nb_bytes_to_write`	The number of bytes to write to slave.
`read_buffer`	The buffer populated by the data that is read from slave.
`nb_bytes_to_read`	Number of bytes to read from slave.

Return

void

mira_i2c_set_slave_address¶

void mira_i2c_set_slave_address(
    mira_i2c_context_t*  context,
    uint8_t              slave_address);

Set slave address.

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.
`slave_address`	Address of the I2C unit to communicate with

Return

void

mira_i2c_transfer_start¶

mira_status_t mira_i2c_transfer_start(
    mira_i2c_context_t*  context);

Start an I2C transfer.

Example of I2C transfer from slave to master:

mira_i2c_context_t context;
uint8_t device_address;
uint8_t register_address;
uint16_t register_address_size;
uint8_t byte_array;
uint16_t byte_array_size;

mira_i2c_set_transfer_type_read(
    &context,
    &register_address,
    register_address_size,
    &byte_array[0],
    byte_array_size);
mira_i2c_set_slave_address(&context, device_address);
mira_i2c_transfer_start(&context);
PROCESS_WAIT_UNTIL(!mira_i2c _transfer_in_progress(&context));
status = mira_i2c_get_transfer_status(&context);
if(status == MIRA_SUCCESS) {
    ... I2C transfer is complete ...
} else {
    ... handle error ...
}

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.

Return

See enum definition.

Value	Description
`MIRA_SUCCESS`	i2c transfer started successfully.
`MIRA_ERROR_UNKNOWN`	An unknown error occurred.
`MIRA_I2C_ERROR_INVALID_SLAVE_ADDRESS`	Slave address is invalid.
`MIRA_I2C_ERROR_INVALID_TRANSFER_TYPE`	Transfer type is invalid.

mira_i2c_transfer_in_progress¶

mira_bool_t mira_i2c_transfer_in_progress(
    mira_i2c_context_t*  context);

Get if the transfer is in progress.

Parameters

Parameter	Description
`context`	Configuration block for the I2C module.

Return

Bool indicating if transfer is in progress or not.

mira_i2c_construct_write_buffer¶

void mira_i2c_construct_write_buffer(
    uint8_t*      dst,
    uint16_t*     nb_dst_bytes,
    uint8_t*      command_buffer,
    uint16_t      nb_command_bytes,
    uint8_t*      write_data_buffer,
    uint16_t      nb_write_data_bytes);

Construct a write buffer.

Construct the buffer from command/register address buffer and write data buffer.

Note: size of dst >= nb_command_bytes + nb_write_data_bytes.

Parameters

Parameter	Description
`dst`	The destination byte array.
`nb_dst_bytes`	The resulting size of the destination byte array.
`command_buffer`	Buffer containing the commands/register address to send to slave device.
`nb_command_bytes`	Number of command/register bytes to send to slave device.
`write_data_buffer`	Buffer containing the data to send to slave device.
`nb_write_data_bytes`	Number of data bytes in buffer to read or write to slave device.

Return

void