Skip to content

I2C

I2C (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