I2C Framework

Table of Contents

• I2C Framework Introduction
  • I2C Framework Module Features
• I2C Framework Module APIs Overview
• I2C Framework Module Operational Overview
  • I2C Framework Module Important Operational Notes and Limitations
    • I2C Framework Module Operational Notes
    • I2C Framework Module Limitations
• Including the I2C Framework Module in an Application
• Configuring the I2C Framework Module
  • Configuring the I2C Framework Lower-Level Modules
  • I2C Framework Module Clock Configuration
  • I2C Framework Module Pin Configuration
  • I2C Framework Module Additional Settings
• Using the I2C Framework Module in an Application

I2C Framework Introduction

The I2C Framework module provides a ThreadX-aware high-level API for I2C industry standard serial device communications and configures the I2C peripheral in order to enable serial communication to be used by the framework. The I2C Framework module uses the I2C and SCI peripherals on the Synergy MCU.

I2C Framework Module Features

• ThreadX-aware framework
• Handles integration and synchronization of multiple I2C peripherals on the I2C bus
• Provides a single interface to access both SCI I2C and RIIC drivers
• The I2C framework module configures I2C communication in master mode
• The I2C framework module supports three data rates: 100 kHz, 400 kHz, and 1 MHz
• The I2C framework module supports both 7-bit addressing and 10-bit addressing
• The I2C framework module also provides support for callbacks internally. User defined callback is not used. The callback functions are called with the following events i2c_event_t
  • Transfer aborted
  • Transmit complete
  • Receive complete
• The callback structure i2c_callback_args_t also provides the number of bytes that were sent or received
• Implemented by:
  • Simple I2C on SCI
  • RIIC

I2C Framework Module Block Diagram

I2C Framework Module APIs Overview

The I2C Framework interface defines APIs for opening, closing, reading, writing, locking, unlocking and resetting the bus using the I2C Framework. A complete list of the available APIs, an example API 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 Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_i2c_device.p_api->open(g_sf_i2c_device.p_ctrl, g_sf_i2c_device.p_cfg); Opens a designated I2C device on the bus.
close	g_sf_i2c_device.p_api->close (g_sf_i2c_device.p_ctrl); Disables I2C device designated by control handle. Closes the RTOS services used by the bus if no devices are connected to the bus.
read	g_sf_i2c_device.p_api->read (g_sf_i2c_device.p_ctrl, &destination, no_of_bytes_to_read, restart,timeout); Receives data from I2C device.
write	g_sf_i2c_device.p_api->write (g_sf_i2c_device.p_ctrl, &source, no_of_bytes_to_write , restart, timeout); Transmits data to I2C device
lock	g_sf_i2c_device.p_api->lock (g_sf_i2c_device.p_ctrl); Locks the bus for a device. Locking reserves the bus until unlocking and allows several reads and writes without interrupt.
unlock	g_sf_i2c_device.p_api->unlock (g_sf_i2c_device.p_ctrl); Unlocks the bus from a particular device and makes it available for other devices.
reset	g_sf_i2c_device.p_api->reset (g_sf_i2c_device.p_ctrl, timeout); Aborts any in-progress transfer and forces the I2C peripheral into ready state.
version	g_sf_i2c_device.p_api->version(version); Retrieves the version information using the version pointer.
lockWait	g_sf_i2c_device.p_api->lockWait (g_sf_i2c_device.p_ctrl, timeout); Locks the bus for a device. Locking reserves the bus until unlocking and allows several reads and writes without intervention from other devices on the same I2C bus. Timeout value is user configurable.

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	I2C function performed successfully.
SSP_ERR_INVALID_MODE	Illegal I2C mode is specified.
SSP_ERR_IP_CHANNEL_NOT_PRESENT	Omitted I2C channel is specified.
SSP_ERR_IN_USE	I2C channel has already been opened.
SSP_ERR_INVALID_ARGUMENT	Argument is not one of the predefined values.
SSP_ERR_INTERNAL	Internal error has occurred.
SSP_ERR_ASSERTION	A critical assertion has failed or Null pointer(s) is (are) given.
SSP_ERR_NOT_OPEN	Device instance not opened.
SSP_ERR_TRANSFER_ABORTED	The data transfer was aborted.
SSP_ERR_INVALID_RATE	The requested rate cannot be set.
SSP_ERR_TIMEOUT	Timeout error occurs.

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 Framework Module Operational Overview

The I2C Framework module complies with the layered driver architecture of the SSP. It uses the lower-level I2C HAL modules to communicate with I2C peripherals and controls the I2C-capable peripherals on a Synergy microcontroller (as configured by a user). With the I2C Framework module, one or more I2C buses can be created and multiple I2C peripherals can be connected to each I2C bus. The I2C Framework module APIs use a ThreadX-Mutex to acquire and release the shared bus for I2C Slave devices. Acquire and release are implemented by sf_i2c_api_t::lock or sf_i2c_api_t::lockWait and sf_i2c_api_t::unlock APIs respectively in the I2C Framework module.

As I2C framework module configures I2C communication in master mode, this allows the user to:

• Initialize the driver
• Read from a slave device
• Write to a slave device
• Reset the MCU I2C peripheral
• Lock the I2C bus
• Unlock the I2C bus

The I2C Framework module works with the Synergy MCU I2C hardware modules; the RIIC and SCI HAL modules. Both I2C modules support the I2C fast-mode with bit rates of up to 400 kHz. The IIC peripheral and the RIIC HAL module support fast-mode plus with 1-MHz bit-rates. The module supports only master mode for both implementations.

Multiple Slave Devices on the Same Bus

The I2C Framework module uses a bus and device on bus architecture. If multiple slaves are connected to the I2C bus, each slave communicates with an associated and separate SF_I2C module instance. Each SF_I2C instance is created in a separate thread. Every slave device is linked to the bus to which it will be connected and shares the bus with all other slave devices. The user must configure the framework shared-bus and the lower-level I2C HAL layer for each framework device connecting to the bus. The user can add the existing framework shared-bus when configuring multiple devices on the same bus. A common start and stop procedure is used for all I2C data-transfer operations. Only one device is configured to the lower level and the remaining devices perform read or write operations by switching the device address within the framework.

All I2C Framework devices on the same bus must use the same lower-level configuration settings, (for example, the I2C HAL module) except for the slave address and addressing mode. The framework will use the configuration of the first device that it opens in the application to configure the bus; this means that all I2C Framework devices on the same bus must have the same lower-level configuration settings (except for the slave address and addressing mode). If different configurations are used, proper operation cannot be guaranteed.

Bus Locking

The I2C Framework supports bus-locking functionality, meaning the bus can be locked for a given slave peripheral. The locking allows devices to reserve a bus to themselves for the period between the lock and unlock commands. This allows devices to complete several reads and writes on the bus without interruption (which can be required in some situations.)

The I2C bus is locked when sf_i2c_api_t::lock or sf_i2c_api_t::lockWait API is called. This API locks the I2C bus by acquiring the mutex for the thread in which the I2C Framework device is used. Once locked, the I2C bus can only be utilized by the associated device. The other I2C Framework devices or the same I2C Framework device from other threads, cannot acquire the mutex so they will not be able to access the bus. Once the bus is unlocked by calling the sf_i2c_api_t::unlock API from the sf_i2c device that locked it, the mutex will be released and the bus becomes available for other sf_i2c devices. The sf_i2c_api_t::lockWait API is similar to the sf_i2c_api_t::lock API except it provides user an option to set timeout value. The sf_i2c_api_t::lockWait API waits for the specified timeout period if the I2C bus is already locked by another device. In case of the sf_i2c_api_t::lock API, the thread waits forever, if the I2C bus is not released by the other device.

I2C Framework Module Important Operational Notes and Limitations

I2C Framework Module Operational Notes

• 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.
• The I2C can trigger the start of other peripherals available from the ELC. See the ELC Module Guide for further information.
• The I2C Framework can support multiple I2C devices on the same bus if the clock rate remains the same for all the devices. That means multiple devices can be opened in the same bus if they are of the same clock rate. If devices have different clock rates, only one device can be opened at a time.
• SDA and SCL output pin type should be n-channel open drain when using I2C on SCI.
• In the I2C Framework configuration, the channel number given to this bus overrides the channel number given in the HAL module.
• Shared bus can be used by multiple slave devices with the respective configuration. The framework also handles mutual exclusion in lock and unlock APIs when multiple devices are using the same I2C channel.
• To configure multiple I2C devices on the same bus, add and configure the following modules for each device connecting to the bus:
  • I2C Framework device module
  • Configure the I2C shared bus module for the first device being configured, then use the same bus for the remaining devices.
  • I2C HAL module
  • DTC module (Optional)
• Lock functionality will be effective for devices from different threads. If multiple devices connected to the bus are from the same thread, the I2C bus will be locked for all devices from that thread. In such cases, even if the bus is locked, all devices from the same thread can access the bus.
• In case a device is being used from multiple threads, and the device locks the I2C bus from one thread, the same device cannot access the I2C bus from other threads.

Note

Each I2C Framework device must be configured with a unique name in the ISDE configurator.

Provide the same configuration settings for all the devices connected on the same bus (except the slave address and addressing modes.)

I2C Framework Module Limitations

The I2C framework module does not currently support the following feature:

• The use of DMA

Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the I2C Framework Module in an Application

This section describes how to include the I2C Framework 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 Framework module to an application, simply add it to a HAL/Common thread using the stacks selection sequence given in the following table. (The default name for the I2C Framework module is g_sf_ i2c_device0. This name can be changed in the associated Properties window.)

I2C Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_i2c_device0 I2C Framework on sf_i2c	Threads	New Stack> Framework> Connectivity> I2C Framework on sf_i2c

When the I2C Framework module on sf_i2c 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.

I2C Framework Module Stack

Configuring the I2C Framework Module

The I2C Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are 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 the SSP.

Configuration Settings for the I2C Framework Device Module on sf_ i2c

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: Enabled	Selects if code for parameter checking is to be included in the build.
Name	g_sf_i2c_device0	Give a name to identify the I2C Framework device. API, Config and Control instances will be created based on this name.
Slave Address	0x00	Specify the address of the I2C slave device.
Address Mode	7-Bit, 10-Bit Default: 7-Bit	Select the I2C address mode.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

In some cases, settings other than the defaults can be desirable. For example, it might be useful to select different byte ordering or pixel-color format. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference.

Note

Most of the property settings for lower level modules are fairly intuitive and can usually be determined by inspection of the associated Properties window from the SSP configurator.

Configuring the I2C Framework Lower-Level Modules

Typically, only a small number of settings must be modified from the default for lower-level drivers as indicated with 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 lower-level modules:

Configuration Settings for the I2C Framework Shared Bus on sf_i2c

ISDE Property	Value	Description
Name	g_sf_i2c_bus0	Module name.

Note

The example values 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 Driver on r_riic

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
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.
Timeout Mode	Short Mode, Long Mode Default: Short Mode	Select the timeout mode.
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.  The 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:14 Priority 15 (lowest - not valid if using ThreadX), Default: Priority 12	Select the receive interrupt priority.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Default: Priority 12	Select the transmit interrupt priority.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Default: Priority 12	Select the transmit end interrupt priority.
Error Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Default: Priority 12	Select the error interrupt priority.

Note

The example values 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 TXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
Software Start	Enabled, Disabled Default: Disabled	Include code for software start in the build.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Section to place the DTC vector table.
Name	g_transfer0	Module name.
Mode	Normal	Specify the hardware channel.
Transfer Size	1 Byte	Select the transfer mode.
Destination Address Mode	Fixed	Select the transfer size.
Source Address Mode	Incremented	Select the address mode for the destination.
Repeat Area (Unused in Normal Mode)	Source	Select the address mode for the source.
Interrupt Frequency	After all transfers have completed	Select the repeat area. Either the source or destination address resets to its initial value after completing Number of Transfers in Repeat or Block mode.
Destination Pointer	NULL	Specify the transfer destination pointer.
Source Pointer	NULL	Specify the transfer source pointer.
Number of Transfers	0	Specify the number of transfers.
Number of Blocks (Valid only in Block Mode)	0	Specify the number of blocks to transfer in Repeat or Block mode.
Activation Source (Must enable IRQ)	Event IIC0 TXI	Select the DTC transfer start event.
Auto Enable	False	Auto enable the transfer in open().
Callback (Only valid with Software start)	NULL	A user callback that is called at the end of the transfer.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Select the transfer end interrupt priority.

Note

The example values 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	If selected code for parameter checking is included in the build.
Software Start	Enabled, Disabled Default: Disabled	Include code for software start in the build.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Section to place the DTC vector table.
Name	g_transfer1	Module name.
Mode	Normal	Specify the hardware channel.
Transfer Size	1 Byte	Select the transfer mode.
Destination Address Mode	Incremented	Select the transfer size.
Source Address Mode	Fixed	Select the address mode for the destination.
Repeat Area (Unused in Normal Mode	Destination	Select the address mode for the source.
Interrupt Frequency	After all transfers have completed	Select the repeat area. Either the source or destination address resets to its initial value after completing Number of Transfers in Repeat or Block mode.
Destination Pointer	NULL	Specify the transfer destination pointer.
Source Pointer	NULL	Specify the transfer source pointer.
Number of Transfers	0	Specify the number of transfers.
Number of Blocks (Valid only in Block Mode)	0	Specify the number of blocks to transfer in Repeat or Block mode.
Activation Source (Must enable IRQ)	Event IIC0 RXI	Select the DTC transfer start event.
Auto Enable	False	Auto enable the transfer in open().
Callback (Only valid with Software start)	NULL	A user callback that is called at the end of the transfer.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Select the transfer end interrupt priority.

Note

The example values 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 Driver on r_sci_i2c

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
Name	g_i2c0	Module name.
Channel	0 to 9	Specify the SCI channel to be used with this configuration. SCI has channels as follows: Series S7: 0 1 2 3 4 5 6 7 8 9; Series S3 : 0 1 2 3 4 - - - - 9; Series S1 : 0 1 - - - - - - - 9.
Rate	Standard, Fast-mode, Fast-mode plus Default: Standard	Select the I2C data rate.
Slave Address	0x00	Specify the slave address.
Address Mode	7-Bit, 10-Bit Default: 7-Bit	Only 7-bit addresses are currently supported.
SDA Output Delay (nano seconds)	300	SDA output delay in nanoseconds.
Bit Rate Modulation Enable	Enable, Disable Default: Enable	Enables bitrate modulation function.
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.  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:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the receive interrupt priority.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the transmit interrupt priority.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the transmit end interrupt priority.
Error Interrupt Priority	Priority 0 (highest), Priority 1:14 Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the error interrupt priority.

Note

The example values 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 SCI0 TXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
Software Start	Enabled, Disabled Default: Disabled	Include code for software start in the build.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Section to place the DTC vector table.
Name	g_transfer0	Module name.
Mode	Block	Specify the hardware channel.
Transfer Size	1 Byte	Select the transfer mode.
Destination Address Mode	Fixed	Select the transfer size.
Source Address Mode	Incremented	Select the address mode for the destination.
Repeat Area (Unused in Normal Mode	Source	Select the address mode for the source.
Interrupt Frequency	After all transfers have completed	Select the repeat area. Either the source or destination address resets to its initial value after completing Number of Transfers in Repeat or Block mode.
Destination Pointer	NULL	Specify the transfer destination pointer.
Source Pointer	NULL	Specify the transfer source pointer.
Number of Transfers	0	Specify the number of transfers.
Number of Blocks (Valid only in Block Mode)	0	Specify the number of blocks to transfer in Repeat or Block mode.
Activation Source (Must enable IRQ)	Event SCI0 TXI	Select the DTC transfer start event.
Auto Enable	False	Auto enable the transfer in open().
Callback (Only valid with Software start)	NULL	A user callback that is called at the end of the transfer.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Select the transfer end interrupt priority.

Note

The example values 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 SCI0 RXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is included in the build.
Software Start	Enabled, Disabled Default: Disabled	Include code for software start in the build.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Section to place the DTC vector table.
Name	g_transfer1	Module name.
Mode	Normal	Specify the hardware channel.
Transfer Size	1 Byte	Select the transfer mode.
Destination Address Mode	Incremented	Select the transfer size.
Source Address Mode	Fixed	Select the address mode for the destination.
Repeat Area (Unused in Normal Mode	Destination	Select the address mode for the source.
Interrupt Frequency	After all transfers have completed	Select the repeat area. Either the source or destination address resets to its initial value after completing Number of Transfers in Repeat or Block mode.
Destination Pointer	NULL	Specify the transfer destination pointer.
Source Pointer	NULL	Specify the transfer source pointer.
Number of Transfers	0	Specify the number of transfers.
Number of Blocks (Valid only in Block Mode)	0	Specify the number of blocks to transfer in Repeat or Block mode.
Activation Source (Must enable IRQ)	Event SCI0 RXI	Select the DTC transfer start event.
Auto Enable	False	Auto enable the transfer in open().
Callback (Only valid with Software start)	NULL	A user callback that is called at the end of the transfer.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled	Select the transfer end interrupt priority.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

I2C Framework Module Clock Configuration

The SCI peripheral module uses the PCLKB as its clock source. The PCLKB frequency is set by using the SSP configurator clock tab prior to a build or by using the CGC Interface at run-time. During configuration, the I2C transfer rate is calculated and set internally by the driver based on the user-selected PCLB rate and the user-selected transfer rate. If the PCLKB is configured in such a manner that the user-selected rate cannot be achieved, an error will be returned when initializing the driver.

I2C Framework Module Pin Configuration

The SCI 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

For some peripherals, the operation-mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for the I2C Framework Module

Resource	ISDE Tab	Pin selection Sequence
SCI	Pins	Select Peripherals> SCI1_3_5_7_9> SCI1

Note

The selection sequence assumes the SCI1 is the desired hardware target of the driver.

Pin Configuration Settings for the I2C Framework Module

Pin Configuration Property	Value	Description
Operation Mode	Disabled, Asynchronous UART, Synchronous UART, Simple I2C, Simple SPI, SmartCard Default: Disabled	Select Simple I2C as the Operation Mode for I2C on SCI.
RXD1_SCL1_MISO1	None, P212, P708 Default: None	SCL pin.
TXD1_SDA1_MOSI1	None, P213, P709 Default: None	SDA pin.

Note

The example values 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.

I2C Framework Module Additional Settings

In addition to the SCL and SDA pins, an I2C RESET signal may be required to reset the I2C slave device. If this is the case, the RESET signal can be added using a GPIO pin and must be controlled directly by the application program. The external device reset function is not supported within the r_sci_i2c module.

Using the I2C Framework Module in an Application

A common application for the I2C framework module requires multiple slave devices on a single bus. The implementation for this common application is described below. (For an application where multiple busses are required, just duplicate the single bus example as needed for each separate bus.)

Implementation Steps for Two Slave Devices on the Same Shared Bus

When using the I2C framework module to create a single bus with multiple slave devices, create two thread stacks each with an I2C framework instance. These instances will each use the same shared bus instance. Follow the steps below to see how this is done within the SSP Configurator.

Note

The following example puts both sf_i2c module instances in the same thread. If the bus locking function is needed, the sf_i2C modules should be put in different threads. Locking applies to all the devices within the locked thread.

The following steps assume some familiarity with the use of the SSP development environment. If any of the following steps are confusing, read over the first few chapters of the SSP User's Manual to become familiar with the SSP development environment.

1. Add the first I2C framework device to a new or existing thread. This creates the I2C master stack. A shared bus on sf_i2c is added along with the I2C driver. The I2C driver can be selected for implementation on r_riic or r_sci_i2c. The DTC transfer driver is also added by default. This can be removed if the CPU transfer mode is needed instead.

The resulting module stack is shown in the following figure. Example configuration settings are given in the tables that follow the figure:

Example configuration setting for the first thread stack are given below:

Configuration Settings for the I2C Framework Device on sf_i2c (Slave #1)

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Name	g_sf_i2c_device0	Give a name to identify the I2C Framework device. API, Config and Control instances will be created based on this name.
Slave Address	0x21	Specify the address of I2C slave 1.
Address Mode	7-bit	Select the I2C address mode.

Configuration Settings for the I2C Framework Shared Bus on sf_i2c

Property	Value	Description
Name	g_sf_i2c_bus0	Give a name to identify the I2C Framework shared bus. This shared bus will be shared by multiple I2C Framework Devices.

Configuration Settings for the I2C Master Driver on r_riic

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Name	g_i2c0	Give a name to identify the I2C Driver device. This will be used internally by Framework.
Channel	0	Specify the I2C channel.
Rate	Standard	Select the speed of the I2C bus.
Slave Address	0	This field will be locked as slave address already configured in the I2C Framework Device on sf_i2c.
Address Mode	7-bit	This field will be locked as address mode already configured in the I2C Framework Device on sf_i2c.
Timeout Mode	Short Mode	Select Timeout mode:  Short mode or Long mode.
Callback	NULL	This field will be locked as Framework does not provide callback handling to the user.
Receive Interrupt Priority	Priority 2	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 2	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 2	Transmit end interrupt priority selection.
Error Interrupt Priority	Priority 2	Error interrupt priority selection.

Configuration Settings for the I2C Master Driver on r_sci_i2c

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Name	g_i2c0	Give a name to identify the I2C Driver device. This will be used by Framework internally.
Channel	0	Specify the address of I2C slave.
Rate	Standard	Select the speed of the I2C bus.
Slave Address	0	This field will be locked as slave address already configured in the I2C Framework Device on sf_i2c.
Address Mode	7-bit	This field will be locked as address mode already configured in the I2C Framework Device on sf_i2c.
Slave Output Delay	300	SDA output delay in nanoseconds.
Bit Rate Modulation Enable	Enable	Enables bitrate modulation function.
Callback	NULL	This field will be locked as Framework does not provide callback handling to the user.
Receive Interrupt Priority	Priority 2	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 2	Transmit interrupt priority selection.
Transmit End Interrupt Priority	Priority 2	Transmit end interrupt priority selection.

Configuration Settings for the Transfer Driver on r_dtc Event IIC0 TXI

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Software Start	Disabled
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. This field is locked.
Transfer Size	1 Byte	Transfer size selection. This field is locked.
Destination Address Mode	Fixed	Destination address mode selection. This field is locked.
Source Address Mode	Incremented	Source address mode selection. This field is locked.
Repeat Area (Unused in Normal Mode	Source	Repeat area selection. This field is locked.
Interrupt Frequency	After all transfers have completed	This field is locked.
Destination Pointer	NULL	Destination pointer selection. This field is locked.
Source Pointer	NULL	Source pointer selection. This field is locked.
Number of Transfers	0	Number of transfer selection. This field is locked.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection. This field is locked.
Activation Source (Must enable IRQ)	Event IIC0 TXI	Activation source selection. This field is locked.
Auto Enable	False	Auto enable selection. This field is locked.
Callback (Only valid with Software start)	NULL	Callback selection. This field is locked.
ELC Software Event Interrupt Priority	Disabled	ELC software event interrupt priority selection.

Configuration Settings for the Transfer Driver on r_dtc Event IIC0 RXI

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Software Start	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. This field is locked.
Transfer Size	1 Byte	Transfer size selection. This field is locked.
Destination Address Mode	Incremented	Destination address mode selection. This field is locked.
Source Address Mode	Fixed	Source address mode selection. This field is locked.
Repeat Area (Unused in Normal Mode	Destination	Repeat area selection. This field is locked.
Interrupt Frequency	After all transfers have completed	This field is locked.
Destination Pointer	NULL	Destination pointer selection. This field is locked.
Source Pointer	NULL	Source pointer selection. This field is locked.
Number of Transfers	0	Number of transfer selection. This field is locked.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection. This field is locked.
Activation Source (Must enable IRQ)	Event IIC0 RXI	Activation source selection. This field is locked.
Auto Enable	False	Auto enable selection. This field is locked.
Callback (Only valid with Software start)	NULL	Callback selection. This field is locked.
ELC Software Event Interrupt Priority	Disabled	ELC software event interrupt priority selection.

2. Add the second I2C Framework Device to the same thread. The I2C Framework Shared Bus on sf_i2c will not get added automatically. Select the option to use the existing shared bus. Then Configurator will automatically add the I2C Framework Shared Bus on sf_i2c and remaining modules.  The lower level modules will be added and configured automatically to be consistent with the previously defined settings from the first I2C framework instance. In fact, if any lower level settings are changed in on stack, they are automatically updated in the other.

The resulting module stack is shown in the following figure:

Example configuration settings for the second thread stack (Slave Device #2) are as follows:

Configuration Settings for the I2C Framework Device on sf_i2c (Slave #2)

Property	Value	Description
Parameter Checking	Default(BSP)	Enable Or Disable Parameter Checking.
Name	g_sf_i2c_device1	Give a name to identify the I2C Framework device. API, Config and Control instances will be created based on this name.
Slave Address	0x28	Specify the address of I2C slave2.
Address Mode	7-bit	Select the I2C address mode.

The step above can be repeated as needed to add more slave devices to the same bus, if they share the same low-level settings.

If a set of slave devices have different lower-level settings than another set, they must use a different bus and can be implemented by repeating the two steps outlined above- defining a different bus and the different lower-level characteristics for the set of slave devices.

Adding Another Shared Bus

1. The I2C framework module which will use a second shared bus can be added to any thread. Starting with the previous example, if it is added to the I2C_Device1 thread, then the module stack would appear as shown below. Available options for the shared bus are New or Use.

2. Select New to and add another I2C Framework Shared Bus on sf_i2c module. Configure the shared bus properties as needed for the application. Select the desired low-level I2C driver. The channel number for the g_i2c1 I2C driver module, must be different from the channel number for the g_i2c0 I2C driver module. The resulting thread stack is shown below:

3. A second device can be added in the I2C_Device2 thread using the same steps described above. The resulting thread stack is shown below:

The typical steps in using the I2C Framework module in an application are:

1. Initialize the I2C Framework module using the sf_i2c_api_t::open API. Each I2C framework module needs to call sf_i2c_api_t::open API at least once before performing any operations on the bus.
2. Reset the I2C MCU peripheral using the sf_i2c_api_t::reset API (if needed)
3. Lock the bus using the sf_i2c_api_t::lock or sf_i2c_api_t::lockWait API for a particular framework module. Once the bus is locked by an I2C framework module it cannot be used by any other I2C framework module on the same bus. This ensures that ownership of the bus remains with the I2C framework module until it unlocks it. Any operation from other I2C framework modules on the bus will fail while the bus is locked. It is not mandatory to lock the bus before any read/write operations on the bus. It is optional (if needed). If thread is not supposed to wait forever when locking the I2C bus, call sf_i2c_api_t::lockWait API with desired timeout value.
4. Write data to the slave using the sf_i2c_api_t::write API. The write operation will not be successful if the bus is already locked by any other I2C framework module.
5. Read data from the slave using sf_i2c_api_t::read API. The read operation will not be successful if the bus is already locked by any other I2C framework module.
6. Unlock the bus using the sf_i2c_api_t::unlock API if it is already locked by the same I2C framework module. Once the bus is unlocked other I2C framework modules can use it. It is necessary to unlock the locked bus after the protected read or write operations are over (if needed).
7. Close the I2C framework module using the sf_i2c_api_t::close API. Each I2C framework module can call the sf_i2c_api_t::close API after all its read and write operations on the bus are completed (if needed).

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

Flow Diagram of a Typical I2C Framework Module Application