Processor SDK RTOS I2C

From Texas Instruments Wiki
Jump to: navigation, search


RTOS Software Developer Guide I2C



Overview

User Interface

Application

Debug

Introduction

I2C module provides an interface to any I2C-bus-compatible device accessible via I2C serial bus. External components attached to I2C bus can serially transmit/receive data to/from the CPU through two-wire interface. Driver supports three types of transfers in both I2C master mode and slave mode

  • Read
  • Write
  • Write followed by read

In addition driver supports following modes of operation:

  • I2C_MODE_BLOCKING: By default, driver operates in blocking mode. In blocking mode, a Task’s code execution is blocked until transaction is complete. This ensures only one transaction operates at a given time. Driver supports both interrupt or non-interrupt based blocking modes.
  • I2C_MODE_CALLBACK In callback mode, an I2C transaction functions asynchronously, which means that it does not block a Task’s code execution. After an I2C transaction is complete, I2C driver calls a user-provided hook function. Only interrupt based callback is supported.

NOTE

If I2C peripheral is in reset during a transfer, it can cause the I2C bus to hang. I2C V0 IP (Keystone SoCs) does not have hardware support to recover the I2C bus from hanging, user needs to power cycle the board as a workaround. For I2C V1 IP (AM3/4/5 SoCs), the application can call I2C_control() API and use I2C_CMD_RECOVER_BUS to recover the I2C bus.

Driver Configuration

Board Specific Configuration

All the board specific configurations eg:enabling and pin-mux of I2C pins should be performed before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs.Refer Processor SDK RTOS Board Support for additional details.

Once the board specific configuration is complete driver API I2C_init() can be called to initialize driver

I2C Configuration Structure

I2C_soc.c file binds driver with hardware attributes on the board through I2C_config structure. This structure must be provided to I2C driver. It must be initialized before the I2C_init() function is called and cannot be changed afterwards. For details about the individual fields of this structure, see the Doxygen help by opening PDK_INSTALL_DIR\packages\ti\drv\i2c\docs\doxygen\html\index.html.

APIs

API reference for application:

#include <ti/drv/i2c/I2C.h>

 Sample code for initiating I2C transaction:

...
Board_init(boardCfg);
...
I2C_socGetInitCfg(peripheralNum, &i2c_cfg);
...
I2C_socSetInitCfg(peripheralNum, &i2c_cfg);
...
i2c = I2C_open(peripheralNum, &i2cParams);
...
...

/* Initiate I2C transfers. Refer Example for details
*/
I2C_transactionInit(&i2cTransaction);
transaction.masterMode   = true;
...
...
transferOK = I2C_transfer(i2c, &i2cTransaction);
if (transferOK != I2C_STS_SUCCESS) {
/* I2C transaction failed */
} 

Examples

Refer Release Note for I2C support across different EVMs

Name
Description
Expected Results
I2C_EepromRead Example application

Simple example to read fixed number of bytes from EEPROM on board and compares it with expected data.

Following prints will come on console based on pass/fail criteria:

Pass criteria:

EEPROM data matched
All tests have passed.

I2C_TestApplication

Driver Unit Test application for additional I2C speed

Following prints will come on console based on pass/fail criteria:

Pass criteria:

I2C Test: 400Kbps: PASS

I2C Test: 100Kbps: PASS

All tests have passed.

I2C_TemperatureSensor Example to get the temperature value from the temperature sensor and displays on the serial console.

Following prints will come on console based on pass/fail criteria:

Pass criteria:

Temperature = "value in centigrades" C
All tests have passed.

I2C_master/slave

Application demonstrates master/slave transfer of I2C. Application use case requires two EVMs. One acts as Master and the other as slave. I2C connections information and addtional details are as follows:

AM57xx boards I2C bus connection on J9 (master board <--> slave board)

pin22 (SCL)<--> pin22 (SCL)

pin24 (SDA)<--> pin24 (SDA)

pin21 (GND)<--> pin21 (GND)


K2G boards I2C bus connection on J12 (master board <--> slave board)
pin28 (SCL)<--> pin28 (SCL)
pin30 (SDA)<--> pin30 (SDA)
pin50 (GND)<--> pin50 (GND)


OMAPL138/C6748 boards I2C bus connection on J15 (master board <--> slave board)
pin13 (SCL)<--> pin13 (SCL)
pin15 (SDA)<--> pin15 (SDA)
pin35 (GND)<--> pin35 (GND)


Run "I2C_Slave_<BoardType>_<arm/c66x/m4>TestProject" first on Slave EVM and then "I2C_Master_<BoardType>_<arm/c66x/m4>TestProject" on Master EVM.

Following prints will come on console based on pass/fail criteria:

Pass criteria:

All tests have passed.

NOTE

I2C_Test Application supports write test on Keystone II EVMs, by default write test is disabled, user can enable the write test by defining I2C_EEPROM_WRITE_ENABLE in test/eeprom_read/src/I2C_board.h. I2C_TemperatureSensor Application is supported only on AM572x GP EVM.

Additional References

Document Location
API Reference Manual $(TI_PDK_INSTALL_DIR)\packages\ti\drv\i2c\docs\doxygen\html\index.html
Release Notes $(TI_PDK_INSTALL_DIR)\packages\ti\drv\i2c\docs\ReleaseNotes_I2C_LLD.pdf