SAM SERCOM I2C Common Driver.

#include <compiler.h>
#include <sercom.h>

Macros

Driver Feature Definition

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's SERCOM I²C module, for the transfer of data via an I²C bus.

The following driver API modes are covered by this manual:

The following peripheral is used by this module:

SERCOM (Serial Communication Interface)

The following devices can use this module:

Atmel | SMART SAM D20/D21
Atmel | SMART SAM R21
Atmel | SMART SAM D09/D10/D11
Atmel | SMART SAM L21/L22
Atmel | SMART SAM DA1
Atmel | SMART SAM C20/C21
Atmel | SMART SAM HA1
Atmel | SMART SAM R30
Atmel | SMART SAM R34
Atmel | SMART SAM R35

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites.

Module Overview

The outline of this section is as follows:

Driver Feature Macro Definition

Driver Feature Macro	Supported devices
FEATURE_I2C_FAST_MODE_PLUS_AND_HIGH_SPEED	SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_10_BIT_ADDRESS	SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_SCL_STRETCH_MODE	SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_SCL_EXTEND_TIMEOUT	SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35

Note

The specific features are only available in the driver when the selected device supports those features.

When using the I2C high-speed mode for off-board communication, there are various high frequency interference, which can lead to distortion of the signals and communication failure. When using Xplained Pro boards in order to test I2C high-speed communication, the following recommendation should be followed:

Use the SDA-line on PA08 and SCL-line on PA09 for both boards. This will provide stronger pull-ups on both SDA and SCL.
The SCL should not be higher than 1.5MHz.

Functional Description

The I²C provides a simple two-wire bidirectional bus consisting of a wired-AND type serial clock line (SCL) and a wired-AND type serial data line (SDA).

The I²C bus provides a simple, but efficient method of interconnecting multiple master and slave devices. An arbitration mechanism is provided for resolving bus ownership between masters, as only one master device may own the bus at any given time. The arbitration mechanism relies on the wired-AND connections to avoid bus drivers short-circuiting.

A unique address is assigned to all slave devices connected to the bus. A device can contain both master and slave logic, and can emulate multiple slave devices by responding to more than one address.

Bus Topology

The I²C bus topology is illustrated in the figure below. The pull-up resistors (Rs) will provide a high level on the bus lines when none of the I²C devices are driving the bus. These are optional, and can be replaced with a constant current source.

I2C Bus Topology

Transactions

The I²C standard defines three fundamental transaction formats:

Master Write
- The master transmits data packets to the slave after addressing it
Master Read
- The slave transmits data packets to the master after being addressed
Combined Read/Write
- A combined transaction consists of several write and read transactions

A data transfer starts with the master issuing a Start condition on the bus, followed by the address of the slave together with a bit to indicate whether the master wants to read from or write to the slave. The addressed slave must respond to this by sending an ACK back to the master.

After this, data packets are sent from the master or slave, according to the read/write bit. Each packet must be acknowledged (ACK) or not acknowledged (NACK) by the receiver.

If a slave responds with a NACK, the master must assume that the slave cannot receive any more data and cancel the write operation.

The master completes a transaction by issuing a Stop condition.

A master can issue multiple Start conditions during a transaction; this is then called a Repeated Start condition.

Address Packets

The slave address consists of seven bits. The 8^th bit in the transfer determines the data direction (read or write). An address packet always succeeds a Start or Repeated Start condition. The 8^th bit is handled in the driver, and the user will only have to provide the 7-bit address.

Data Packets

Data packets are nine bits long, consisting of one 8-bit data byte, and an acknowledgement bit. Data packets follow either an address packet or another data packet on the bus.

Transaction Examples

The gray bits in the following examples are sent from master to slave, and the white bits are sent from slave to master. Example of a read transaction is shown in the figure below. Here, the master first issues a Start condition and gets ownership of the bus. An address packet with the direction flag set to read is then sent and acknowledged by the slave. Then the slave sends one data packet which is acknowledged by the master. The slave sends another packet, which is not acknowledged by the master and indicates that the master will terminate the transaction. In the end, the transaction is terminated by the master issuing a Stop condition.

I2C Packet Read

Example of a write transaction is shown in the figure below. Here, the master first issues a Start condition and gets ownership of the bus. An address packet with the dir flag set to write is then sent and acknowledged by the slave. Then the master sends two data packets, each acknowledged by the slave. In the end, the transaction is terminated by the master issuing a Stop condition.

I2C Packet Write

Packet Timeout

When a master sends an I²C packet, there is no way of being sure that a slave will acknowledge the packet. To avoid stalling the device forever while waiting for an acknowledge, a user selectable timeout is provided in the i2c_master_config struct which lets the driver exit a read or write operation after the specified time. The function will then return the STATUS_ERR_TIMEOUT flag.

This is also the case for the slave when using the functions postfixed _wait.

The time before the timeout occurs, will be the same as for unknown bus state timeout.

Repeated Start

To issue a Repeated Start, the functions postfixed _no_stop must be used. These functions will not send a Stop condition when the transfer is done, thus the next transfer will start with a Repeated Start. To end the transaction, the functions without the _no_stop postfix must be used for the last read/write.

Multi Master

In a multi master environment, arbitration of the bus is important, as only one master can own the bus at any point.

Arbitration

Clock stretching: The serial clock line is always driven by a master device. However, all devices connected to the bus are allowed stretch the low period of the clock to slow down the overall clock frequency or to insert wait states while processing data. Both master and slave can randomly stretch the clock, which will force the other device into a wait-state until the clock line goes high again.

Arbitration on the data line: If two masters start transmitting at the same time, they will both transmit until one master detects that the other master is pulling the data line low. When this is detected, the master not pulling the line low, will stop the transmission and wait until the bus is idle. As it is the master trying to contact the slave with the lowest address that will get the bus ownership, this will create an arbitration scheme always prioritizing the slaves with the lowest address in case of a bus collision.

Clock Synchronization

In situations where more than one master is trying to control the bus clock line at the same time, a clock synchronization algorithm based on the same principles used for clock stretching is necessary.

Bus States

As the I²C bus is limited to one transaction at the time, a master that wants to perform a bus transaction must wait until the bus is free. Because of this, it is necessary for all masters in a multi-master system to know the current status of the bus to be able to avoid conflicts and to ensure data integrity.

IDLE No activity on the bus (between a Stop and a new Start condition)
OWNER If the master initiates a transaction successfully
BUSY If another master is driving the bus
UNKNOWN If the master has recently been enabled or connected to the bus. Is forced to IDLE after given timeout when the master module is enabled

The bus state diagram can be seen in the figure below.

S: Start condition
P: Stop condition
Sr: Repeated start condition

I2C Bus State Diagram

Bus Timing

Inactive bus timeout for the master and SDA hold time is configurable in the drivers.

Unknown Bus State Timeout

When a master is enabled or connected to the bus, the bus state will be unknown until either a given timeout or a stop command has occurred. The timeout is configurable in the i2c_master_config struct. The timeout time will depend on toolchain and optimization level used, as the timeout is a loop incrementing a value until it reaches the specified timeout value.

SDA Hold Timeout

When using the I²C in slave mode, it will be important to set a SDA hold time which assures that the master will be able to pick up the bit sent from the slave. The SDA hold time makes sure that this is the case by holding the data line low for a given period after the negative edge on the clock.

The SDA hold time is also available for the master driver, but is not a necessity.

Operation in Sleep Modes

The I²C module can operate in all sleep modes by setting the run_in_standby Boolean in the i2c_master_config or i2c_slave_config struct. The operation in slave and master mode is shown in the table below.

I2C Standby Operations
Run in standby	Slave	Master
false	Disabled, all reception is dropped	Generic Clock (GCLK) disabled when master is idle
true	Wake on address match when enabled	GCLK enabled while in sleep modes

Special Considerations

There are no special considerations for this driver for the APIs listed in this document.

Extra Information

For extra information, see Extra Information for SERCOM I2C Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for SERCOM I2C Driver.

API Overview

Define SERCOM I²C driver features set according to different device family.

#define FEATURE_I2C_FAST_MODE_PLUS_AND_HIGH_SPEED

Fast mode plus and high speed support. More...

#define FEATURE_I2C_10_BIT_ADDRESS

10-bit address support More...

#define FEATURE_I2C_SCL_STRETCH_MODE

SCL stretch mode support. More...

#define FEATURE_I2C_SCL_EXTEND_TIMEOUT

SCL extend timeout support. More...

#define FEATURE_I2C_DMA_SUPPORT

Enumerations
enum	i2c_transfer_direction { I2C_TRANSFER_WRITE = 0, I2C_TRANSFER_READ = 1 }
	Transfer direction. More...