Functions
fsp_err_t	R_IICA_MASTER_Open (i2c_master_ctrl_t const p_api_ctrl, i2c_master_cfg_t const const p_cfg)

fsp_err_t	R_IICA_MASTER_Read (i2c_master_ctrl_t const p_api_ctrl, uint8_t const p_dest, uint32_t const bytes, bool const restart)

fsp_err_t	R_IICA_MASTER_Write (i2c_master_ctrl_t const p_api_ctrl, uint8_t const p_src, uint32_t const bytes, bool const restart)

fsp_err_t	R_IICA_MASTER_Abort (i2c_master_ctrl_t *const p_api_ctrl)

fsp_err_t	R_IICA_MASTER_SlaveAddressSet (i2c_master_ctrl_t *const p_api_ctrl, uint32_t const slave, i2c_master_addr_mode_t const addr_mode)

fsp_err_t	R_IICA_MASTER_CallbackSet (i2c_master_ctrl_t const p_api_ctrl, void(p_callback)(i2c_master_callback_args_t ), void const const p_context, i2c_master_callback_args_t *const p_callback_memory)

fsp_err_t	R_IICA_MASTER_StatusGet (i2c_master_ctrl_t const p_api_ctrl, i2c_master_status_t p_status)

fsp_err_t	R_IICA_MASTER_Close (i2c_master_ctrl_t *const p_api_ctrl)

Detailed Description

Driver for the IICA peripheral on RA MCUs. This module implements the I2C Master Interface.

Overview

The IICA master on IICA HAL module supports transactions with an IICA slave device. Callbacks must be provided which are invoked when a transmit or receive operation has completed. The callback argument will contain information about the transaction status, bytes transferred and a pointer to the user defined context.

Features

Supports multiple transmission rates
- Standard Mode Support with up to 100-kHz transaction rate.
- Fast Mode Support with up to 400-kHz transaction rate.
- Fast Mode Plus Support with up to 1-MHz transaction rate.
IICA Master Read from a slave device.
IICA Master Write to a slave device.
Abort any in-progress transactions.
Set the address of the slave device.
Non-blocking behavior is achieved by the use of callbacks.

Configuration

Build Time Configurations for r_iica_master

The following build time configurations are defined in fsp_cfg/r_iica_master_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.
10-bit slave addressing	Enabled Disabled	Disabled	If enabled, the driver will support 10-bit slave addressing mode along with the default 7-bit slave addressing mode.
Enable Single Channel	MCU Specific Options		Enable single channel to reduce code size if only one channel is to be configured for IICA.

Configurations for Connectivity > IICA Master (r_iica_master)

This module can be added to the Stacks tab via New Stack > Connectivity > IICA Master (r_iica_master).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_iica_master0	Module name.
Channel	Value must be a non-negative integer	0	Specify the IICA channel.
Rate	Standard Fast-mode Fast-mode plus	Standard	Select the transfer rate. If the requested transfer rate cannot be achieved, the settings with the largest possible transfer rate that is less than or equal to the requested transfer rate are used. The theoretical calculated transfer rate is printed in a comment in the generated iica_master_extended_cfg_t structure.
Custom Rate (bps)	Value must be a non-negative integer	0	Set a custom bitrate (bps). Set to 0 to use the maximum bitrate for the selected mode. Standard-mode: up to 100000; Fast-mode: up to 400000; Fast-mode plus: up to 1000000
Signal Rising Time (us)	Must be a valid value	0	Set the SDA and SCL signal rising time in micro-seconds.
Signal Falling Time (us)	Must be a valid value	0	Set the SDA and SCL signal falling time in micro-seconds.
Duty Cycle (%)	Value must be an integer between 0 and 100	53	Set SCL high duty cycle.
Digital Filter	Enabled Disabled	Disabled	Configure digital filter.
Address Mode	7-Bit 10-Bit	7-Bit	Select the slave address mode. Ensure 10-bit slave addressing is enabled in the configuration to use 10-Bit setting here.
Slave Address	Value must be a non-negative integer	0x00	Specify the slave address.
Communication reservation	Enabled Disabled	Disabled	Configure Communication Reservation.
Callback	Name must be a valid C symbol	iica_master_callback	A user callback function must be provided. This will be called from the interrupt service routine (ISR) upon IICA transaction completion reporting the transaction status.
Interrupt Priority Level	MCU Specific Options		Select end of IICA communication interrupt priority.

Clock Configuration

The IICA peripheral module uses the PCLKB as its clock source. The actual I2C transfer rate will be calculated and set by the tooling depending on the selected transfer rate. If the PCLKB is configured in such a manner that the selected internal rate cannot be achieved, an error will be returned.

Pin Configuration

The IICA peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. An IICA channel would consist of two pins - SDAA and SCLA for data/address and clock respectively.

Usage Notes

IICA Master Rate Calculation

The RA Configuration editor calculates the internal baud-rate setting based on the configured transfer rate.

When the Custom Rate setting is set to 0 the bitrate is fixed to the maximum values shown below. Otherwise, the supplied value is used to generate bitrate settings.
- Standard-mode (Sm) : up to 100 kbps
- Fast-mode (Fm) : up to 400 kbps
- Fast-mode Plus (Fm+) : up to 1 Mbps
The closest possible baud-rate that can be achieved (less than or equal to the requested rate) at the current PCLKB settings is calculated and used.
If a valid clock rate could not be calculated, an error is returned by the tool.

Multiple Devices on the Bus

A single IICA instance can be used to communicate with multiple slave devices on the same channel by using the SlaveAddressSet API.

Multi-Master Support

If multiple masters are connected on the same bus, the I2C Master is capable of detecting bus busy state before initiating the communication.

Restart

IICA master can hold the bus after an I2C transaction by issuing a repeated start condition.This will mimic a stop followed by start condition.

Limitations

DTC not supported.
Interrupt request is always generated on the falling edge of the 9th clock cycle.
Master operation in multi-master system is not supported
Custom bitrate is not yet supported for IICA.
Communication reservation function will be deprecated.

Examples

Basic Example

This is a basic example of minimal use of the r_iica_master in an application. This example shows how this driver can be used for basic read and write operations.

iica_master_instance_ctrl_t g_i2c_device_ctrl_1;
i2c_master_cfg_t            g_i2c_device_cfg_1 =
{
    .channel       = I2C_CHANNEL,
    .rate          = I2C_MASTER_RATE_FAST,
    .slave         = I2C_SLAVE_EEPROM,
    .p_callback    = iica_master_callback, // Callback
    .p_context     = &g_i2c_device_ctrl_1,
    .p_transfer_tx = NULL,
    .p_transfer_rx = NULL,
    .p_extend      = &g_iic_master_cfg_extend
};
void iica_master_callback (i2c_master_callback_args_t * p_args)
{
    g_i2c_callback_event = p_args->event;
}
void basic_example (void)
{
    fsp_err_t err;
    uint32_t  i;
    uint32_t  timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
    /* Initialize the IIC module */
    err = R_IICA_MASTER_Open(&g_i2c_device_ctrl_1, &g_i2c_device_cfg_1);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Write some data to the transmit buffer */
    for (i = 0; i < I2C_BUFFER_SIZE_BYTES; i++)
    {
        g_i2c_tx_buffer[i] = (uint8_t) i;
    }
    /* Send data to I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    err = R_IICA_MASTER_Write(&g_i2c_device_ctrl_1, &g_i2c_tx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    assert(FSP_SUCCESS == err);
    /* Since there is nothing else to do, block until Callback triggers*/
    while ((I2C_MASTER_EVENT_TX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Read data back from the I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    timeout_ms           = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IICA_MASTER_Read(&g_i2c_device_ctrl_1, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    assert(FSP_SUCCESS == err);
    /* Since there is nothing else to do, block until Callback triggers*/
    while ((I2C_MASTER_EVENT_RX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Verify the read data */
    if (0U != memcmp(g_i2c_tx_buffer, g_i2c_rx_buffer, I2C_BUFFER_SIZE_BYTES))
    {
        __BKPT(0);
    }
}

Multiple Slave devices on the same channel (bus)

This example demonstrates how a single IICA driver can be used to communicate with different slave devices which are on the same channel.

Note: The callback function from the first example applies to this example as well.

iica_master_instance_ctrl_t g_i2c_device_ctrl_2;
i2c_master_cfg_t            g_i2c_device_cfg_2 =
{
    .channel       = I2C_CHANNEL,
    .rate          = I2C_MASTER_RATE_STANDARD,
    .slave         = I2C_SLAVE_TEMP_SENSOR,
    .p_callback    = iica_master_callback, // Callback
    .p_context     = &g_i2c_device_ctrl_2,
    .p_transfer_tx = NULL,
    .p_transfer_rx = NULL,
    .p_extend      = &g_iic_master_cfg_extend
};
void single_channel_multi_slave (void)
{
    fsp_err_t err;
    uint32_t  timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IICA_MASTER_Open(&g_i2c_device_ctrl_2, &g_i2c_device_cfg_2);
    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);
    /* Clear the recieve buffer */
    memset(g_i2c_rx_buffer, '0', I2C_BUFFER_SIZE_BYTES);
    /* Read data from I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    err = R_IICA_MASTER_Read(&g_i2c_device_ctrl_2, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    assert(FSP_SUCCESS == err);
    while ((I2C_MASTER_EVENT_RX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Send data to I2C slave on the same channel */
    err = R_IICA_MASTER_SlaveAddressSet(&g_i2c_device_ctrl_2, I2C_SLAVE_DISPLAY_ADAPTER, I2C_MASTER_ADDR_MODE_7BIT);
    assert(FSP_SUCCESS == err);
    g_i2c_tx_buffer[0]   = 0xAA;       // NOLINT
    g_i2c_tx_buffer[1]   = 0xBB;       // NOLINT
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    timeout_ms           = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IICA_MASTER_Write(&g_i2c_device_ctrl_2, &g_i2c_tx_buffer[0], 2U, false);
    assert(FSP_SUCCESS == err);
    while ((I2C_MASTER_EVENT_TX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
}

Data Structures
struct	iica_master_clock_settings_t

struct	iica_master_pin_settings_t

struct	iica_master_instance_ctrl_t

struct	iica_master_extended_cfg_t

Enumerations
enum	iica_master_comm_rez_t

Data Structure Documentation

◆ iica_master_clock_settings_t

struct iica_master_clock_settings_t

IICA clock settings

◆ iica_master_pin_settings_t

struct iica_master_pin_settings_t

Configuration settings for IICA pins

Data Fields
bsp_io_port_pin_t	pin	The pin.
uint32_t	cfg	Configuration for the pin.

◆ iica_master_instance_ctrl_t

struct iica_master_instance_ctrl_t

IICA control structure. DO NOT INITIALIZE.

◆ iica_master_extended_cfg_t

struct iica_master_extended_cfg_t

R_IICA extended configuration

Data Fields
iica_master_clock_settings_t	clock_settings
iica_master_pin_settings_t	sda_pin_settings	SDAA pin setting.
iica_master_pin_settings_t	scl_pin_settings	SCLAA pin setting.

Enumeration Type Documentation

◆ iica_master_comm_rez_t

enum iica_master_comm_rez_t

IICA communication reservation parameter definition

Function Documentation

◆ R_IICA_MASTER_Open()

fsp_err_t R_IICA_MASTER_Open	(	i2c_master_ctrl_t *const	p_api_ctrl,
		i2c_master_cfg_t const *const	p_cfg
	)

Opens the IICA device.

Return values

FSP_SUCCESS	Requested clock rate was set exactly.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	Channel is not available on this MCU.
FSP_ERR_ASSERTION	Parameter check failure due to one or more reasons below: p_api_ctrl or p_cfg is NULL. extended parameter is NULL. Callback parameter is NULL. Invalid IRQ number assigned

◆ R_IICA_MASTER_Read()

fsp_err_t R_IICA_MASTER_Read	(	i2c_master_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes,
		bool const	restart
	)

Performs a read from the IICA device. The caller will be notified when the operation has completed (successfully) by an I2C_MASTER_EVENT_RX_COMPLETE in the callback.

Return values

FSP_SUCCESS	Function executed without issue.
FSP_ERR_ASSERTION	p_api_ctrl, p_dest or bytes is NULL.
FSP_ERR_INVALID_SIZE	Provided number of bytes more than uint16_t size (65535) for data transfer.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IICA_MASTER_Open to initialize the control block.

◆ R_IICA_MASTER_Write()

fsp_err_t R_IICA_MASTER_Write	(	i2c_master_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes,
		bool const	restart
	)

Performs a write to the IICA device. The caller will be notifieEd when the operation has completed (successfully) by an I2C_MASTER_EVENT_TX_COMPLET in the callback.

Return values

FSP_SUCCESS	Function executed without issue.
FSP_ERR_ASSERTION	p_api_ctrl or p_src is NULL.
FSP_ERR_INVALID_SIZE	Provided number of bytes more than uint16_t size (65535) for data transfer.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IICA_MASTER_Open to initialize the control block.

◆ R_IICA_MASTER_Abort()

fsp_err_t R_IICA_MASTER_Abort ( i2c_master_ctrl_t *const p_api_ctrl )

Safely aborts any in-progress transfer and forces the IICA peripheral into ready state.

Return values

FSP_SUCCESS	Channel was reset successfully.
FSP_ERR_ASSERTION	p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IICA_MASTER_Open to initialize the control block.

Note: A callback will not be invoked in case an in-progress transfer gets aborted by calling this API.

◆ R_IICA_MASTER_SlaveAddressSet()

fsp_err_t R_IICA_MASTER_SlaveAddressSet	(	i2c_master_ctrl_t *const	p_api_ctrl,
		uint32_t const	slave,
		i2c_master_addr_mode_t const	addr_mode
	)

Sets address and addressing mode of the slave device. This function is used to set the device address and addressing mode of the slave without reconfiguring the entire bus.

Return values

FSP_SUCCESS	Address of the slave is set correctly.
FSP_ERR_ASSERTION	Pointer to control structure is NULL.
FSP_ERR_IN_USE	Another transfer was in-progress.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IICA_MASTER_Open to initialize the control block.

◆ R_IICA_MASTER_CallbackSet()

fsp_err_t R_IICA_MASTER_CallbackSet	(	i2c_master_ctrl_t *const	p_api_ctrl,
		void()(i2c_master_callback_args_t )	p_callback,
		void const *const	p_context,
		i2c_master_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements i2c_master_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

◆ R_IICA_MASTER_StatusGet()

fsp_err_t R_IICA_MASTER_StatusGet	(	i2c_master_ctrl_t *const	p_api_ctrl,
		i2c_master_status_t *	p_status
	)

Provides driver status.

Return values

FSP_SUCCESS	Status stored in p_status.
FSP_ERR_ASSERTION	NULL pointer.

◆ R_IICA_MASTER_Close()

fsp_err_t R_IICA_MASTER_Close ( i2c_master_ctrl_t *const p_api_ctrl )

Closes the IICA device. May power down IICA peripheral. This function will safely terminate any in-progress IICA transfers.

Return values

FSP_SUCCESS	Device closed without issue.
FSP_ERR_ASSERTION	p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IICA_MASTER_Open to initialize the control block.

Note: A callback will not be invoked in case an in-progress transfer gets aborted by calling this API.

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for r_iica_master

Configurations for Connectivity > IICA Master (r_iica_master)

Clock Configuration

Pin Configuration

Usage Notes

IICA Master Rate Calculation

Multiple Devices on the Bus

Multi-Master Support

Restart

Limitations

Examples

Basic Example

Multiple Slave devices on the same channel (bus)

Data Structures

Enumerations

Data Structure Documentation

◆ iica_master_clock_settings_t

◆ iica_master_pin_settings_t

◆ iica_master_instance_ctrl_t

◆ iica_master_extended_cfg_t

Enumeration Type Documentation

◆ iica_master_comm_rez_t

Function Documentation

◆ R_IICA_MASTER_Open()

◆ R_IICA_MASTER_Read()

◆ R_IICA_MASTER_Write()

◆ R_IICA_MASTER_Abort()

◆ R_IICA_MASTER_SlaveAddressSet()

◆ R_IICA_MASTER_CallbackSet()

◆ R_IICA_MASTER_StatusGet()

◆ R_IICA_MASTER_Close()