Use I2C in high-level applications

  • Article

Azure Sphere supports Inter-Integrated Circuit (I2C) in master mode. I2C is a serial bus that connects lower-speed peripherals to microcontrollers. I2C uses a multi-master/multi-subordinate model where a master device controls a set of subordinate devices. I2C is often used with peripherals that only require simple lightweight communication with a microcontroller, such as setting controls, power switches, and sensors.

Applications can access peripherals through I2C by calling Applibs I2C APIs to perform operations on an I2C master interface. The LSM6DS3 I2C sample describes how to configure the hardware for I2C on an MT3620 device and use I2C in an application.

I2C Requirements

Applications that use I2C must include the appropriate header files for I2C, and add I2C settings to the application manifest.

All applications must set their target hardware and include the corresponding hardware definition header file.

Header Files

 #define I2C_STRUCTS_VERSION 1
 #include <applibs/i2c.h>
 #include "path-to-your-target-hardware.h"

Declare the I2C_STRUCTS_VERSION preprocessor definition before including the header file. This specifies the struct version that is used by the application.

Replace "path-to-your-target-hardware.h" with the path to the header file for your hardware.

Application manifest settings

To use the I2C APIs, you must add the I2cMaster capability to the application manifest, and then add each I2C master interface to the capability. This enables the application to access the interface. Azure Sphere application manifest has more details about the application manifest.

In your code, use the constants that are defined for your hardware to identify the I2C interfaces. The compiler will translate these values to raw values when you build the app.

For example, here's an excerpt from an application manifest that targets an MT3620 reference development board (RDB) and configures two I2C master interfaces:

"I2cMaster": [ "$MT3620_RDB_HEADER2_ISU0_I2C", "$MT3620_RDB_HEADER4_ISU1_I2C" ],

The following excerpt shows how to specify the same I2C master interfaces in an application that targets the Avnet MT3620 Starter Kit:

"I2cMaster": [ "$AVNET_MT3620_SK_ISU0_I2C", "$AVNET_MT3620_SK_ISU1_I2C" ]

Open an I2C master interface

Before you perform operations on an I2C master interface, you must open it by calling the I2CMaster_Open function.

Update the settings for an I2C master interface

After you open the master interface, you can change the settings:

Perform read and write operations on the I2C master interface

Azure Sphere supports several options for performing read and write operations with I2C. These options are all blocking, synchronous operations.

For one-way write or read operations you can call I2CMaster_Write or I2CMaster_Read. This is the simplest way to perform operations on an I2C master interface because it only specifies one operation and it includes the address of the subordinate device in the function call.

You can call I2CMaster_WriteThenRead to perform a combined write then read operation in a single bus transaction without interruption from another transaction.

For interoperability with some POSIX interfaces, you can call POSIX read(2) and write(2) functions to perform one-way transactions. You must call I2CMaster_SetDefaultTargetAddress to set the address of the subordinate device before you call read(2) or write(2).

You can call these functions to perform 0-byte write operations in order to verify the presence of a subordinate device. If a read or write operation fails, your application must handle reissuing the request.

Close the I2C interface

To close the interface, you must call the standard POSIX function close().

MT3620 support

This section describes the I2C options that only apply when running Azure Sphere on the MT3620.

The I2C specifications for the MT3620 chip are listed in MT3620 Support Status. The MT3620 development board user guide describes the pin layout and functions for wiring.

The HardwareDefinitions folder in the Microsoft Azure Sphere SDK installation directory contains definitions for common Azure Sphere development boards, modules, and chips. It contains header and JSON files that define the master interfaces for the MT3620, MT3620 RDB, along with other MT3620 hardware. The default location for the HardwareDefinitions folder is C:\Program Files (x86)\Microsoft Azure Sphere SDK\Hardware Definitions on Windows and /opt/azurespheresdk/HardwareDefinitions on Linux.

  • When you configure the MT3620 dev board, you can use any ISU port as an I2C master interface. When you use an ISU port as an I2C master interface, you can't use the same port as an SPI or UART interface.
  • 10-bit subordinate device addresses are not supported on the MT3620; only 7-bit addresses are supported.
  • The MT3620 supports 100 KHz, 400 KHz, and 1 MHz bus speeds, but not 3.4 Mhz.
  • 0-byte I2C reads are not supported on the MT3620.
  • When using I2C in a high-level application, only the SCL and SDA pins in the ISU peripheral block are used by the I2C peripheral, and the other pins can be used as GPIOs by the same high-level application. See I/O peripherals for a list of the unused ISU pins that can be reused for GPIO.