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