Synergy Software Package User's Manual
I2C SCI Driver

Table of Contents

I2C SCI HAL Module Introduction

The I2C SCI Master HAL module provides a high-level API for I2C industry standard serial device communication applications and uses the SCI peripheral on the Synergy MCU device. Callbacks are provided for transmit complete and receive complete.

I2C SCI HAL Module Features

  • Support for I2C SCI operations
  • Supports following operations with a slave I2C SCI device
    • Read
    • Write
    • Reset
  • Callback support
    • Transfer aborted
    • Transmit complete (number of bytes transmitted provided)
    • Receive complete (number of bytes received provided)
sci_i2c_BD.png
I2C SCI HAL Module Block Diagram

I2C SCI Hardware Support Details

The following hardware features are, or are not, supported by SSP for the I2C over SPI.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 

 

MCU Group Master
Mode 		Slave
mode 		Support all
Interrupt
Sources 		Programmable
digital noise
filter 		Bit rate
modulation 		SDA
delay 		Timeout on bus lockout
S124 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S128 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S1JA ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S3A1 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S3A3 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S3A6 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S3A7 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S5D3 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S5D5 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S5D9 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A
S7G2 ✓ N/A ERI not supported ⌧ ✓ ✓ N/A

I2C SCI HAL Module APIs Overview

The I2C SCI HAL module defines APIs for 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 SCI 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.
slaveAddressSet g_i2c.p_api->slaveAddressSet(g_i2c.p_ctrl,
slave, addr_mode);
Sets address of the slave device without reconfiguring the bus.
versionGet g_i2c.p_api->versionGet(&version);
Retrieve the API version with the version pointer.
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_IN_USE Attempted to open an already open device instance.
SSP_ERR_ABORTED Device was closed while a transfer was in progress.
SSP_ERR_INVALID_RATE The requested rate cannot be set.
SSP_ERR_ASSERTION The parameter p_ctrl is NULL.
SSP_ERR_NOT_OPEN Device was not even opened.
SSP_ERR_IRQ_BSP_DISABLED Event information could not be found.
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 SCI HAL Module Operational Overview

The I2C SCI Master HAL module supports transactions with an I2C slave device. Callbacks are provided to interrupt the CPU when a transmission has been completed or aborted, or receive completed. The I2C SCI 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 SCI HAL Module Important Operational Notes and Limitations

I2C SCI HAL Module Operational Notes

Interrupts

  • The I2C interrupts (SCI Error (EEI), Receive Buffer Full (RXI), Transmit Buffer Empty (TXI), and Transmit End (TEI)) for the selected channel must be enabled in the board support package (BSP), without consideration of whether the user wants to use callbacks.
  • Setting the interrupts to different priority levels could result in improper operation.

IIC Rate Calculation

  • The I2C SCI HAL module calculates the internal baud-rate setting based on the configured transfer rate and passes this 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 is 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 SCI HAL module can trigger the start of other peripherals. See the ELC User Guide for further information.

Multiple Devices on the Same Bus

When communicating with multiple slave devices on the same bus, if these slave devices have the same configuration settings the i2c_api_master_t::slaveAddressSet API function can be used to switch between slave devices without reconfiguring (no need to close and open). The control instance and bus configuration remains the same, but the slave address and addressing mode changes. A single instance of the I2C SCI HAL module is sufficient for this case.

When communicating with multiple slave devices on the same bus, if each slave device requires different configuration settings multiple instances of r_sci_i2c will be used- each configured as required for each slave device.  Each instance of r_sci_i2c will be opened and closed when it is used to communicate with the target slave device.

A mix of the above two approaches can be used with a mix of slave devices. For example, if two slave devices share the same configuration settings, they can share the same instance of r_sci_i2c and the i2c_api_master_t::slaveAddressSet API function can be used to switch between them. If on the same bus, three other slave devices share the same configuration settings, but these settings are different from the first two, they will need a separate r_sci_i2c instance. Switching between each of these three slave devices can again use the i2c_api_master_t::slaveAddressSet API function. When switching between slave devices served by different instances of r_sci_i2c, the open and close technique must be used. In general, the configuration settings of the most recently slave device accessed are 'remembered' and can be re-used if appropriate. If a slave requires a different configuration than the most recently accessed slave, the r_sci_i2c module must be closed and then opened using the required configuration settings.

Applications using multiple devices connected on the same channel need to define the following macro in the pre‑processor settings of the project (or the project may not build correctly):

SSP_SUPPRESS_ISR_<device_name>

Where <device_name> is the name of the additional device connected to the same channel.

I2C SCI HAL Module Limitations

  • The I2C SCI HAL module in IRQ mode may not work with certain slave devices; you need to enable DTC transfer mode to work with such devices.
  • To support high bit rate data transfers when operating in the IRQ mode it is highly recommended that the DTC transfer mode be enabled. This reduces the CPU overhead in responding to interrupts directly and thus removes a potential barrier in successfully implementing high bit-rate transfers.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the I2C SCI HAL Module in an Application

This section describes how to include the I2C SCI 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 SCI HAL Module Selection Sequence

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

When the I2C Master Driver module on r_sci_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.

sci_i2c_MS.png
I2C SCI HAL Module Stack

Configuring the I2C SCI HAL Module

The I2C SCI 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 SCI HAL Module 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

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.
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 SCI 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 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 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 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 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 SCI HAL Module Clock Configuration

The SCI peripheral module uses the PCLKB as its clock source. The actual I2C transfer rate is 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 is returned when initializing the driver.

I2C SCI HAL 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
The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for I2C SCI HAL Module on r_sci_i2c

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

Pin Configuration Settings for the I2C SCI HAL Module on r_sci_i2c

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.
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 SCI HAL Module in an Application

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

  1. Initialize and open the I2C SCI 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. Operate on the received data as needed by the application.
  5. Reset the module with the i2c_api_master_t::reset API (Optional).
  6. Perform transactions with slave device in the application code.
  7. Change the slave address using the i2c_api_master_t::slaveAddressSet API (Optional).
  8. Perform transactions with slave device in the application code (Optional).
  9. Close the channel using the i2c_api_master_t::close API (Optional).

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

sci_i2c_TA.png
Flow Diagram of a Typical I2C SCI HAL Module Application