Synergy Software Package User's Manual
I2C Master Driver

Table of Contents

I2C Master HAL Module Introduction

The I2C Master on RIIC HAL module provides a high-level API for industry standard I2C serial communications applications and uses the IIC peripheral on a Synergy MCU. Callbacks are provided for transmit complete and receive complete events notification.

I2C Master HAL Module Features

  • Support for I2C RIIC operations
    • Standard (up to 100 kHz)
    • I2C fast-mode (up to 400 kHz)
    • I2C fast-mode plus (up to 1 MHz on channel 0 (SCL0-A, SDA0-A) of S7G2 and S5D9 MCU families)
  • Initialization of the RIIC module
  • Read from a slave device
  • Write to a slave device
  • Reset the MCUs I2C peripheral
  • Set the address of the slave device
  • Callback support
    • Transfer aborted (along with exact IIC hardware-generated error event)
    • Transmit complete (number of bytes transmitted provided)
    • Receive complete (number of bytes received provided)
riic_master_BD.png
I2C Master HAL Module Block Diagram

RIIC Master Hardware support details

The following hardware features are, or are not, supported by SSP for the RIIC Master Driver:

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group I2C Format SMBus Format Master Mode Slave Mode Fast Mode
Plus 		Selectable
duty cycle
S124 ✓ ⌧ ✓ ✓ N/A ⌧
S128 ✓ ⌧ ✓ ✓ N/A ⌧
S1JA ✓ ⌧ ✓ ✓ N/A ⌧
S3A1 ✓ ⌧ ✓ ✓ N/A ⌧
S3A3 ✓ ⌧ ✓ ✓ N/A ⌧
S3A6 ✓ ⌧ ✓ ✓ N/A ⌧
S3A7 ✓ ⌧ ✓ ✓ N/A ⌧
S5D3 ✓ ⌧ ✓ ✓ ✓ ⌧
S5D5 ✓ ⌧ ✓ ✓ ✓ ⌧
S5D9 ✓ ⌧ ✓ ✓ ✓ ⌧
S7G2 ✓ ⌧ ✓ ✓ ✓ ⌧
MCU Group Configurable
to up to three
different slave
addresses 		7- and 10-
bit address
formats 		General call
address,
Device ID
address and
SMBus host
address
detectable 		Automatic
loading of the
acknowledge
bit 		SDA
output
delay
function 		Selectable
Wait
functions
(8/9 or 9/1)
S124 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S128 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S1JA ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S3A1 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S3A3 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S3A6 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S3A7 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S5D3 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S5D5 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S5D9 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
S7G2 ⌧ 7 and 10-bit ⌧ ✓ ✓ ⌧
MCU Group Full Arbitration Support Internal Detect Time-Out Programmable
Digital Noise Filters 		Support all Interrupt
Sources
S124 Master, NACK arbitrations ✓ ⌧ ✓
S128 Master, NACK arbitrations ✓ ⌧ ✓
S1JA Master, NACK arbitrations ✓ ⌧ ✓
S3A1 Master, NACK arbitrations ✓ ⌧ ✓
S3A3 Master, NACK arbitrations ✓ ⌧ ✓
S3A6 Master, NACK arbitrations ✓ ⌧ ✓
S3A7 Master, NACK arbitrations ✓ ⌧ ✓
S5D3 Master, NACK arbitrations ✓ ⌧ ✓
S5D5 Master, NACK arbitrations ✓ ⌧ ✓
S5D9 Master, NACK arbitrations ✓ ⌧ ✓
S7G2 Master, NACK arbitrations ✓ ⌧ ✓

I2C Master HAL Module APIs Overview

The I2C Master on RIIC (I2C RIIC) HAL module defines API functions including reading and writing using a master I2C device.  A complete list of the available API functions, an example API function call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

I2C Master HAL Module API Summary

Function Name Example API Call and Description
open g_i2c.p_api->open(g_i2c.p_ctrl, g_i2c.p_cfg);
Open the instance and initialize the hardware.
close g_i2c.p_api->close(g_i2c.p_ctrl);
Closes the driver and releases the I2C device.
read g_i2c.p_api->read(g_i2c.p_ctrl, &destination, bytes, restart);
Performs a read operation on an I2C device.
write g_i2c.p_api->write(g_i2c.p_ctrl, &destination, bytes, restart);
Performs a write operation on an I2C device.
reset g_i2c.p_api->reset(g_i2c.p_ctrl);
Reset the peripheral.
versionGet g_i2c.p_api->versionGet(&version);
Retrieve the API version with the version pointer.
slaveAddressSet g_i2c.p_api->slaveAddressSet(g_i2c.p_ctrl, slave_addr, addr_mode);
Reconfigures the slave address.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS API Call Successful.
SSP_ERR_INVALID_POINTER Pointer is NULL.
SSP_ERR_IN_USE I2C bus busy state detected during I2C transaction operation or attempted to open an already open device instance only during open API call.
SSP_ERR_ABORTED Device was closed while a transfer was in progress.
SSP_ERR_INVALID_ARGUMENT Parameter has invalid value.
SSP_ERR_INVALID_RATE The requested rate cannot be set.
SSP_ERR_HW_LOCKED Driver busy doing riic operation.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

I2C Master HAL Module Operational Overview

The I2C master on RIIC HAL module supports transactions with an I2C Slave device. Callbacks are provided to interrupt the CPU when a transmission or receive has been completed. The RIIC HAL module invokes the callback with the argument i2c_callback_args_t, indicating the number of received or transmitted bytes in buffer, pointer to user provided context, and the event i2c_event_t.

I2C Master HAL Module Important Operational Notes and Limitations

I2C Master HAL Module Operational Notes

Interrupts

  • The RIIC error (EEI), receive buffer full (RXI), transmit buffer empty (TXI) and transmit end (TEI) interrupts for the selected channel used must be enabled in the properties of the selected device irrespective of whether the user wants to use callbacks.
  • Set equal priority levels for all the interrupts mentioned above. Setting the interrupts to different priority levels could result in improper operation.

IIC Rate Calculation

  • The I2C Master module calculates the internal baud-rate setting based on the configured transfer rate and passed to open. 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.

Triggering DMAC/DTC with the IIC

  • DTC transfer support added by default in the configurator. This can be removed for CPU transfer cases. The DTC is configured in the module. No user configuration is required for this.
  • DMA transfer is not supported.

Triggering ELC Events with the IIC

  • The I2C Master module can trigger the start of other peripherals. See events and peripheral definitions in the ELC User Guide for further information.

Multiple Devices on the Bus

  • If multiple devices are connected on the same bus, only one device can be opened at a time.
  • If multiple slave devices are on the same bus, and they have different configurations, the application program should use multiple I2C master modules- one for each configuration.
  • If the application wants to switch the device without opening and closing the bus, use the i2c_api_master_t::slaveAddressSet API where g_i2c.p_ctrl is the same control instance that was used in the last opened device. The module will use the same bus configuration to communicate with the new device when the application program subsequently calls the i2c_api_master_t::read or i2c_api_master_t::write API functions.

Usage of Restart Condition

  • Passing the value 'true' to the restart parameter of the write/read API will generate restart condition after specified number (length) of bytes.The master will continue to hold the bus busy (low) without timeout so that current master can trigger the next write/read 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.

SDA Delay Support

The SDA Delay function delays SDA output from the detection of a falling edge of SCL signal to ensure that

the SDA signal is output within the interval during which the SCL is low.

I2C Master HAL Module Limitations

  • Any of the supported IIC channel can be configured for either Master or Slave mode operation but not for both.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the I2C Master HAL Module in an Application

This section describes how to include the I2C Master HAL Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the I2C Master Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the I2C Master Driver is g_i2c0. This name can be changed in the associated Properties window.)

I2C Master HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_i2c0 I2C Master Driver on r_riic Threads New Stack> Driver> Communications> I2C Master Driver on r_riic

When the I2C Master HAL module on r_riic is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

riic_master_MS.png
I2C Master HAL Module Stack

Configuring the I2C Master HAL Module

The I2C Master HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the I2C Master HAL Module on r_riic

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable parameter error checking.
Name g_i2c0 Module name.
Channel 0 Specify the IIC channel to be used with this configuration.
Rate Standard, Fast-mode, Fast-mode Plus
Default: Standard 		Standard, Fast, and Fast-plus. (See IIC Rate Calculation.)
Slave Address 0x00 Set the address of the slave device the I2C master will be communicating with.
Address Mode 7-Bit, 10-Bit
Default: 7-Bit 		Only 7-bit addresses are currently supported.
SDA Output Delay(nanoseconds) Default: 300 SDA output delay in nanoseconds.
Callback NULL A user callback function can be registered in i2c_api_master_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) for each of the conditions defined in i2c_event_t*. 
*Exact hardware generated error event is also provided when i2c_event_t is I2C_EVENT_ABORTED.

Warning: Since the callback is called from an ISR, do not use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Receive Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Priority 2 		Receive interrupt priority selection.
Transmit Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Priority 2 		Transmit interrupt priority selection.
Transmit End Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Priority 2 		Transmit end interrupt priority selection.
Error Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Priority 2 		Error interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the I2C Master HAL Module Lower Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module:

Configuration Settings for the Transfer Driver on r_dtc Event IIC0 TXI

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Selects if code for parameter checking is to be included in the build.
Software Start Enabled, Disabled
Default: Disabled 		Software start selection.
Linker section to keep DTC vector table .ssp_dtc_vector_table Linker section to keep DTC vector table.
Name g_transfer0 Module name.
Mode Normal Mode selection.
Transfer Size 1 Byte Transfer size selection.
Destination Address Mode Fixed Destination address mode selection.
Source Address Mode Incremented Source address mode selection.
Repeat Area (Unused in Normal Mode Source Repeat area selection.
Interrupt Frequency After all transfers have completed Interrupt frequency selection.
Destination Pointer NULL Destination pointer selection.
Source Pointer NULL Source pointer selection.
Number of Transfers 0 Number of transfers selection.
Number of Blocks (Valid only in Block Mode) 0 Number of blocks selection.
Activation Source (Must enable IRQ) Event IIC0 TXI Activation source selection.
Auto Enable FALSE Auto enable selection.
Callback (Only valid with Software start) NULL Callback selection.
ELC Software Event Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Disabled 		ELC software event interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Transfer Driver on r_dtc Event IIC0 RXI

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Selects if code for parameter checking is to be included in the build.
Software Start Enabled, Disabled
Default: Disabled 		Software start selection.
Linker section to keep DTC vector table .ssp_dtc_vector_table Linker section to keep DTC vector table.
Name g_transfer1 Module name.
Mode Normal Mode selection.
Transfer Size 1 Byte Transfer size selection.
Destination Address Mode Incremented Destination address mode selection.
Source Address Mode Fixed Source address mode selection.
Repeat Area (Unused in Normal Mode Destination Repeat area selection.
Interrupt Frequency After all transfers have completed Interrupt frequency selection.
Destination Pointer NULL Destination pointer selection.
Source Pointer NULL Source pointer selection.
Number of Transfers 0 Number of transfers selection.
Number of Blocks (Valid only in Block Mode) 0 Number of blocks selection.
Activation Source (Must enable IRQ) Event IIC0 RXI Activation source selection.
Auto Enable FALSE Auto enable selection.
Callback (Only valid with Software start) NULL Callback selection.
ELC Software Event Interrupt Priority Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX)
Default: Disabled 		ELC software event interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

I2C Master HAL Module Clock Configuration

The IIC peripheral module uses the PCLKB as its clock source. The actual I2C transfer rate will be calculated and set internally by the driver 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 when initializing the driver.

I2C Master HAL Module Pin Configuration

The IIC 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.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the pins:

Note
The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for I2C Master HAL Module on r_riic

Resource ISDE Tab Pin selection Sequence
IIC Pins Select Peripherals> Connectivity: IIC> IIC0
Note
The selection sequence assumes IIC0 is the desired hardware target for the driver.

Pin Configuration Settings for the I2C Master HAL Module on r_sci_uart

Pin Configuration Property Value Description
Pin Group Selection _A only, _B only, Mixed
Default: _A only 		Pin group selection.
Operation Mode Enabled, Disabled
Default: Disabled 		Enable or disable peripheral module.
SDA None, P401, P407
Default: None 		SDA Pin.
SCL None, P400, P204
Default: None 		SCL Pin.
SCK None, P412, P102
Default: P412 		SCK Pin.
CTS_RTS_SS None, P413, P103
Default: None 		CTS Pin.
SDA Disabled SDA Pin (when Simple I2C is used).
SCL Disabled SCL Pin (when Simple I2C is used).
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy Kits and other Synergy MCUs may have different available pin configuration settings.

Using the I2C Master HAL Module in an Application

The steps in using the I2C Master HAL module in a typical application are:

  1. Initialize and open the I2C RIIC HAL Module using the i2c_api_master_t::open API.
  2. Transfer data to the slave using the i2c_api_master_t::write API.
  3. Receive data from the slave using the i2c_api_master_t::read API.
  4. Reset the module using the i2c_api_master_t::reset API. (Optional)
  5. Change the slave address using i2c_api_master_t::slaveAddressSet API. (Optional)
  6. Transfer data to the slave using the i2c_api_master_t::write API. (Optional)
  7. Receive data from the slave using the i2c_api_master_t::read API. (Optional)
  8. Close the module using the i2c_api_master_t::close API. (Optional)

These common steps are illustrated in a typical operational flow diagram in the following figure:

riic_master_TA.png
Flow Diagram of a Typical I2C Master HAL Module Application