I2C Communication Device (rm_comms_i2c)

Functions
fsp_err_t	RM_COMMS_I2C_Open (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_cfg_t const *const p_cfg)
	Opens and configures the Communications Middle module. Implements rm_comms_api_t::open. More...
fsp_err_t	RM_COMMS_I2C_Close (rm_comms_ctrl_t *const p_api_ctrl)
	Disables specified Communications Middle module. Implements rm_comms_api_t::close. More...
fsp_err_t	RM_COMMS_I2C_Read (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
	Performs a read from the I2C device. Implements rm_comms_api_t::read. More...
fsp_err_t	RM_COMMS_I2C_Write (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes)
	Performs a write from the I2C device. Implements rm_comms_api_t::write. More...
fsp_err_t	RM_COMMS_I2C_WriteRead (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_write_read_params_t const write_read_params)
	Performs a write to, then a read from the I2C device. Implements rm_comms_api_t::writeRead. More...

Detailed Description

Middleware to implement the I2C communications interface. This module implements the Communications Middleware Interface.

Overview

Features

The implementation of the I2C communications interface has the following key features:

• Reading data from, writing data to I2C bus
• Writes to I2C bus, then reads with restart
• A single I2C bus used by multiple I2C devices

Configuration

Build Time Configurations for rm_comms_i2c

The following build time configurations are defined in fsp_cfg/rm_comms_i2c_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Connectivity > I2C Shared Bus (rm_comms_i2c)

This module can be added to the Stacks tab via New Stack > Connectivity > I2C Shared Bus (rm_comms_i2c).

Configuration	Options	Default	Description
Name	Manual Entry	g_comms_i2c_bus0	Module name.
Bus Timeout	Value must be a non-negative integer	0xFFFFFFFF	Set timeout for locking bus in using RTOS.
Semaphore for Blocking (RTOS only)	Unuse Use	Unuse	Set Semaphore for blocking in using RTOS.
Recursive Mutex for Bus (RTOS only)	Unuse Use	Unuse	Set Mutex for locking bus in using RTOS.

Configurations for Connectivity > I2C Communication Device (rm_comms_i2c)

This module can be added to the Stacks tab via New Stack > Connectivity > I2C Communication Device (rm_comms_i2c).

Configuration	Options	Default	Description
Name	Manual Entry	g_comms_i2c_device0	Module name.
Semaphore Timeout (RTOS only)	Value must be a non-negative integer	0xFFFFFFFF	Set timeout for blocking in using RTOS.
Slave Address	Value must be non-negative	0x00	Specify the slave address.
Address Mode	7-Bit 10-Bit	7-Bit	Select the I2C address mode.
Callback	Name must be a valid C symbol	comms_i2c_callback	A user callback function can be provided.

Pin Configuration

This module uses SDA and SCL pins of I2C function.

Usage Notes

If an RTOS is used, blocking and bus lock is available.

• If blocking of an I2C bus is required, it is necessary to create a semaphore for blocking.
• If bus lock is required, it is necessary to create a mutex for bus lock. Bus lock is only available when a semaphore for blocking is used.
  If an RTOS is used and blocking and bus lock is enabled, RM_COMMS_I2C_Write(), RM_COMMS_I2C_Read() and RM_COMMS_I2C_WriteRead() cannot be called in callback.

Bus Initialization

The I2C communications interface expects a bus instance to be opened before opening any specific I2C comms device. The communications interface will handle switching between devices on the bus but will not open or close the bus instance. The user should open the bus with the appropriate I2C Master Interface open call.

Examples

Basic Example

This is a basic example of minimal use of I2C communications implementation in an application.

void rm_comms_i2c_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the I2C bus if it is not already open. */
    rm_comms_i2c_bus_extended_cfg_t * p_extend          = (rm_comms_i2c_bus_extended_cfg_t *) g_comms_i2c_cfg.p_extend;
    i2c_master_instance_t           * p_driver_instance = (i2c_master_instance_t *) p_extend->p_driver_instance;
    p_driver_instance->p_api->open(p_driver_instance->p_ctrl, p_driver_instance->p_cfg);

#if BSP_CFG_RTOS

    /* Create a semaphore for blocking if a semaphore is not NULL */
    if (NULL != p_extend->p_blocking_semaphore)
    {
 #if BSP_CFG_RTOS == 1                 // AzureOS
        tx_semaphore_create(p_extend->p_blocking_semaphore->p_semaphore_handle,
                            p_extend->p_blocking_semaphore->p_semaphore_name,
                            (ULONG) 0);
 #elif BSP_CFG_RTOS == 2               // FreeRTOS
        *(p_extend->p_blocking_semaphore->p_semaphore_handle) =
            xSemaphoreCreateCountingStatic((UBaseType_t) 1,
                                           (UBaseType_t) 0,
                                           p_extend->p_blocking_semaphore->p_semaphore_memory);
 #endif
    }

    /* Create a recursive mutex for bus lock if a recursive mutex is not NULL */
    if (NULL != p_extend->p_bus_recursive_mutex)
    {
 #if BSP_CFG_RTOS == 1                 // AzureOS
        tx_mutex_create(p_extend->p_bus_recursive_mutex->p_mutex_handle,
                        p_extend->p_bus_recursive_mutex->p_mutex_name,
                        TX_INHERIT);
 #elif BSP_CFG_RTOS == 2               // FreeRTOS
        *(p_extend->p_bus_recursive_mutex->p_mutex_handle) =
            xSemaphoreCreateRecursiveMutexStatic(p_extend->p_bus_recursive_mutex->p_mutex_memory);
 #endif
    }
#endif


    err = RM_COMMS_I2C_Open(&g_comms_i2c_ctrl, &g_comms_i2c_cfg);


    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);

    while (true)
    {
        g_flag = 0;

        /* Send data to an I2C device. */
        RM_COMMS_I2C_Write(&g_comms_i2c_ctrl, &write_data, 1);
        while (0 == g_flag)
        {
            /* Wait callback */
        }

        g_flag = 0;

        /* Receive data from an I2C device. */
        RM_COMMS_I2C_Read(&g_comms_i2c_ctrl, &read_data, 1);
        while (0 == g_flag)
        {
            /* Wait callback */
        }
    }
}

Classes
struct	st_rm_comms_i2c_bus_extended_cfg
struct	st_rm_comms_i2c_instance_ctrl

Typedefs
typedef struct st_rm_comms_i2c_bus_extended_cfg	rm_comms_i2c_bus_extended_cfg_t
typedef struct st_rm_comms_i2c_instance_ctrl	rm_comms_i2c_instance_ctrl_t

---

Class Documentation

RZA::st_rm_comms_i2c_bus_extended_cfg

struct RZA::st_rm_comms_i2c_bus_extended_cfg

I2C bus configuration

Class Members
rm_comms_i2c_mutex_t const *	p_bus_recursive_mutex	The mutex for the bus. If this is NULL then operations will not lock the bus while it is in use.
rm_comms_i2c_semaphore_t const *	p_blocking_semaphore	The semaphore for blocking operations. If this is NULL then operations will be non-blocking and require a callback.
uint32_t	bus_timeout	Possible in ticks.
rm_comms_ctrl_t *	p_current_ctrl	Current device using the bus (by switching the address)
void const *	p_driver_instance	Pointer to I2C HAL interface to be used in the framework.

RZA::st_rm_comms_i2c_instance_ctrl

struct RZA::st_rm_comms_i2c_instance_ctrl

Communications middleware control structure.

Public Attributes
rm_comms_cfg_t const *	p_cfg
	middleware configuration.
rm_comms_i2c_bus_extended_cfg_t *	p_bus
	Bus using this device;.
void *	p_lower_level_cfg
	Used to reconfigure I2C driver.
uint32_t	open
	Open flag.
uint32_t	transfer_data_bytes
	Size of transfer data.
uint8_t *	p_transfer_data
	Pointer to transfer data buffer.
void *	p_context
	Pointer to the user-provided context.

Typedef Documentation

rm_comms_i2c_bus_extended_cfg_t

typedef struct st_rm_comms_i2c_bus_extended_cfg rm_comms_i2c_bus_extended_cfg_t

I2C bus configuration Please refer to the struct st_rm_comms_i2c_bus_extended_cfg.

rm_comms_i2c_instance_ctrl_t

typedef struct st_rm_comms_i2c_instance_ctrl rm_comms_i2c_instance_ctrl_t

Communications middleware control structure. Please refer to the struct st_rm_comms_i2c_instance_ctrl.

Function Documentation

RM_COMMS_I2C_Open()

fsp_err_t RM_COMMS_I2C_Open	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_cfg_t const *const	p_cfg
	)

Opens and configures the Communications Middle module. Implements rm_comms_api_t::open.

Example:

    err = RM_COMMS_I2C_Open(&g_comms_i2c_ctrl, &g_comms_i2c_cfg);

Return values

FSP_SUCCESS	Communications Middle module successfully configured.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPEN	Module is already open. This module can only be opened once.

RM_COMMS_I2C_Close()

fsp_err_t RM_COMMS_I2C_Close

(

rm_comms_ctrl_t *const

p_api_ctrl

)

Disables specified Communications Middle module. Implements rm_comms_api_t::close.

Return values

FSP_SUCCESS	Successfully closed.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

RM_COMMS_I2C_Read()

fsp_err_t RM_COMMS_I2C_Read	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes
	)

Performs a read from the I2C device. Implements rm_comms_api_t::read.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

RM_COMMS_I2C_Write()

fsp_err_t RM_COMMS_I2C_Write	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes
	)

Performs a write from the I2C device. Implements rm_comms_api_t::write.

Return values

FSP_SUCCESS	Successfully writing data .
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

RM_COMMS_I2C_WriteRead()

fsp_err_t RM_COMMS_I2C_WriteRead	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_write_read_params_t const	write_read_params
	)

Performs a write to, then a read from the I2C device. Implements rm_comms_api_t::writeRead.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.