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 Description
MIRA_I2C_FREQUENCY_100_KHZ
MIRA_I2C_FREQUENCY_250_KHZ
MIRA_I2C_FREQUENCY_400_KHZ

mira_i2c_transfer_type_t

Name Description
MIRA_I2C_TRANSFER_TYPE_TX
MIRA_I2C_TRANSFER_TYPE_RX
MIRA_I2C_TRANSFER_TYPE_NONE

Structs

mira_i2c_config_t

Name Type Description
pin mira_gpio_pin_t GPIO pin to use for the SCL clock signal

GPIO pin to use for the SDA signal

pull mira_gpio_pull_t Pull resistor setting for SCL

Pull resistor setting for SDA

scl struct mira_i2c_config_t::@2
sda struct mira_i2c_config_t::@3
frequency mira_i2c_frequency_t The transfer frequency

mira_i2c_context_t

Struct containing the context of an i2c channel.

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

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

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 mira_i2c_config_init()

Parameters

Name 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 value

Name 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

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

Return value

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

Example to initialize i2c with config:

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

Name Description
context Configuration block for the I2C module.

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

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

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 value

Name 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

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

mira_i2c_set_slave_address

void mira_i2c_set_slave_address(mira_i2c_context_t *context, uint8_t slave_address);

Set slave address.

Parameters

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

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

Name Description
context Configuration block for the I2C module.

Return value

Name 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

Name Description
context Configuration block for the I2C module.

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

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