I2C Interface

I2C Platform interface

I2C Overview

I2C (Inter-Integrated Circuit) is a synchronous, multi-master, multi-slave, packet-switched, single-ended, serial communication protocol used for connecting low-speed peripherals in embedded systems. It is widely used in microcontroller-based systems to interface with sensors, EEPROMs, displays, and other devices.

I2C allows multiple devices to communicate over a two-wire bus: one for the clock signal (SCL) and one for data (SDA). The simplicity of I2C makes it an excellent choice for devices that require low to moderate data transfer rates and minimal hardware resources.

Supported Communication Modes

The following modes of I2C communication are supported:

  • Blocking - Here the read/write register function waits(blocked) till the operation is performed or time out

  • Non-Blocking - The read/write register function returns immediately and the registered callback is invoked after the completion of operation or time out

I2C Role Operation

The role operation for I2C determines whether a device operates as the Master or Slave in the I2C communication setup. The role defines how the device interacts with the bus, including controlling data transmission, generating the clock signal, and addressing other devices.

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions

Function

Description

rs_i2c_open

To open the I2C interface.

rs_i2c_set_config

To configure the I2C interface.

rs_i2c_master_write_reg16

To transfer a 16 bit register address followed by given number of bytes

rs_i2c_master_write_reg8

To transfer a 8 bit register address followed by given number of bytes

rs_i2c_master_read_reg16

To read a 16 bit register address followed by receiving given number of bytes

rs_i2c_master_read_reg8

To read a 8 bit register address followed by receiving given number of bytes

rs_i2c_register_completion_callback

To registers the given callback function for completion of I2C transfer operation

rs_i2c_close

To close the I2C interface.

Implementation Guide

This section explains how to implement the I2C interface using the RAPIDSEA stack, the steps to be followed are

  • Configure the preferred method of RX or TX communication(Blocking / Non-Blocking).

  • Configure the I2C interface(port, role, slave addr width, bitrate).

  • Then call the open call of the I2C interface.

  • Register the callback function.

  • Perform the read and write register register functions as required and handle the error codes.

  • Close the I2C interface.

Error Code

  • Every API’s for the I2C returns some success or failure values. Please refer below section,

Documentation from the relevant header as follows:

I2C Specific APIs.

Defines macros and functions specific to I2C functionality

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_I2C_SLAVE_ADDR_WIDTH_7_BITS

Slave address width control Slave address is 7 bits wide

RS_I2C_SLAVE_ADDR_WIDTH_10_BITS

Slave address is 10` bits wide.

RS_I2C_ROLE_SLAVE

Operation role

Slave mode operation

RS_I2C_ROLE_MASTER

Master mode operation.

RS_I2C_BLOCKING

Operation mode Blocking Mode operation

RS_I2C_NON_BLOCKING

Non-Blocking Mode operation.

Typedefs

typedef void (*rs_i2c_callback)(rs_handle_t handle, rs_ret_val_t reason)

Serial callback function.

typedef struct tag_rs_i2c_config rs_i2c_config_t

Structure for configuring the I2C interface.

typedef struct tag_rs_i2c_transfer rs_i2c_transfer_t

Structure for I2C data transfer.

typedef struct tag_rs_i2c_instance rs_i2c_instance_t

Structure for I2C instance.

typedef void (*rs_i2c_callback_completion)(rs_handle_t handle, rs_ret_val_t result)

Callback function format.

This callback function is called on completion of given activity

Param handle:

[in] - Handle to the I2C interface

Param result:

[in] - Result of the last operation requested in non-blocking mode

Return:

None

Functions

rs_handle_t rs_i2c_open(rs_i2c_instance_t *ptr_instance, rs_i2c_config_t *ptr_config)

Configures the I2C port and parameters.

This function configures/re-configures the I2C port as per the given instance

Parameters:

  • ptr_instance – [in] - Pointer to the i2c instance

  • ptr_config – [in] - Pointer to the i2c configuration

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_set_config(rs_i2c_config_t *ptr_config, uint8_t u8_port, uint8_t u8_role, uint8_t u8_slave_addr_width, uint8_t u8_non_blocking, uint32_t u32_bit_rate)

Updates the I2C configuration structure.

This function configures the I2C with the given configuration settings

Parameters:

  • ptr_config – [out] - Pointer to the I2C configuration structure

  • u8_port – [in] - I2c port

  • u8_role – [in] - Role of I2C port

  • u8_slave_addr_width – [in] - Slave address width

  • u8_non_blocking – [in] - blocking or non blocking mode

  • u32_bit_rate – [in] - Bit rate

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_master_transfer(rs_handle_t handle, uint16_t u16_slave_addr, void *ptr_tx_data, uint32_t u32_tx_len, void *ptr_rx_data, uint32_t u32_rx_len)

Performs transfers over I2C master.

This function transfer the given data and receives the requested number of bytes

Parameters:

  • handle – [in] - Handle to the I2C interface

  • u16_slave_addr – [in] - Slave address

  • ptr_tx_data – [in] - Pointer to transmit buffer. Can be NULL if no transmission is needed.

  • u32_tx_len – [in] - Number of bytes to be transmitted

  • ptr_rx_data – [out] - Pointer to receive buffer. Can be NULL if no reception is needed.

  • u32_rx_len – [in] - Number of bytes to be received

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_master_write_reg16(rs_handle_t handle, uint16_t u16_slave_addr, uint16_t u16_reg_addr, void *ptr_tx_data, uint32_t u32_tx_len, uint32_t u32_time_out)

Convenience function to transfer a 8 bit register address followed by given number of bytes.

This function sends the register address followed by given number of bytes

Parameters:

  • handle – [in] - Handle to the I2C interface

  • u16_slave_addr – [in] - Slave address

  • u16_reg_addr – [in] - Register address to write

  • ptr_tx_data – [in] - Pointer to transmit buffer

  • u32_tx_len – [in] - Number of bytes to be transmitted

  • u32_time_out – [in] - Time out in ms to wait for write complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_master_read_reg16(rs_handle_t handle, uint16_t u16_slave_addr, uint16_t u16_reg_addr, void *ptr_rx_data, uint32_t u32_rx_len, uint32_t u32_time_out)

Convenience function to transfer a 8 bit register address followed by receiving given number of bytes.

This function sends the register address and then receives the given number of bytes

Parameters:

  • handle – [in] - Handle to the I2C interface

  • u16_slave_addr – [in] - Slave address

  • u16_reg_addr – [in] - Register address to read from

  • ptr_rx_data – [out] - Pointer to receive buffer

  • u32_rx_len – [in] - Number of bytes to be received

  • u32_time_out – [in] - Time out in ms to wait for read complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_master_write_reg8(rs_handle_t handle, uint16_t u16_slave_addr, uint8_t u8_reg_addr, void *ptr_tx_data, uint32_t u32_tx_len, uint32_t u32_time_out)

Convenience function to transfer a 8 bit register address followed by given number of bytes.

This function sends the register address followed by given number of bytes

Parameters:

  • handle – [in] - Handle to the I2C interface

  • u16_slave_addr – [in] - Slave address

  • u8_reg_addr – [in] - Register address to write

  • ptr_tx_data – [in] - Pointer to transmit buffer

  • u32_tx_len – [in] - Number of bytes to be transmitted

  • u32_time_out – [in] - Time out in ms to wait for write complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_master_read_reg8(rs_handle_t handle, uint16_t u16_slave_addr, uint8_t u8_reg_addr, void *ptr_rx_data, uint32_t u32_rx_len, uint32_t u32_time_out)

Convenience function to transfer a 8 bit register address followed by receiving given number of bytes.

This function sends the register address and then receives the given number of bytes

Parameters:

  • handle – [in] - Handle to the I2C interface

  • u16_slave_addr – [in] - Slave address

  • u8_reg_addr – [in] - Register address to read from

  • ptr_rx_data – [out] - Pointer to receive buffer

  • u32_rx_len – [in] - Number of bytes to be received

  • u32_time_out – [in] - Time out in ms to wait for read complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_register_completion_callback(rs_handle_t handle, rs_i2c_callback_completion ptr_func)

Registers the given callback function for completion of I2C transfer operation.

This function registers the given callback function for completion of transfer operation

Parameters:

  • handle – [in] - Handle to the I2C interface

  • ptr_func – [in] - Callback function to call to

Returns:

0 on success or error code on failure

rs_ret_val_t rs_i2c_close(rs_handle_t handle)

Un-initializes the I2C interface.

This function un-initializes the I2C interface and releases the handle

Parameters:

handle – [in] - Handle to the I2C interface

Returns:

0 on success or error code on failure

struct tag_rs_i2c_config
#include <rs_i2c.h>

Structure for configuring the I2C interface.

Public Members

uint8_t port

Index to I2C Port.

uint8_t role

Master or Slave operation.

uint8_t slave_addr_width

Width of the slave address.

uint8_t non_blocking

Blocking vs Non-blocking.

uint32_t bit_rate

Bit rate/Clock speed.

struct tag_rs_i2c_transfer
#include <rs_i2c.h>

Structure for I2C data transfer.

Public Members

uint8_t u8_i2c_direction

I2C direction - Write/Read.

uint16_t u16_sub_reg_addr

sub reg address

uint8_t u8_sub_reg_addr_size

sub reg address size

uint8_t *ptr_data_buf

Data buffer to transmit and receive.

uint32_t data_buf_len

Data buffer length.

uint32_t remaing_data_len

Remaining data length to transmit/receive.

uint32_t transfer_timeout_time

Transfer timeout.

struct tag_rs_i2c_instance
#include <rs_i2c.h>

Structure for I2C instance.

Public Members

rs_i2c_config_t *ptr_config

Pointer to the configuration structure.

uint32_t u32_i2c_handle

i2c handle

rs_i2c_transfer_t i2c_transfer

I2c transfer object to manage the Transmit/Receive process.

rs_fevent_t fevent_transfer_complete

Transfer Complete Event handler.

rs_fevent_t mutex_handle

Transfer Complete Event handler.

rs_i2c_callback ptr_cb

Pointer to the callback function.

void *ptr_arg

Pointer to the callback function argument.

To be added for Slave functionality.