| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Enumerations
I2C HAL driver
Inter-Integrated Circuit (I2C)

The section describes the programming interface of the I2C HAL driver. More...

## Data Structures
struct | i2c_config_t
| I2C module configuration. More...

## Enumerations
enum | i2c_status_t { kStatus_I2C_Success = 0, kStatus_I2C_OutOfRange, kStatus_I2C_InvalidArgument, kStatus_I2C_Fail, kStatus_I2C_Busy, kStatus_I2C_Timeout, kStatus_I2C_ReceivedNak, kStatus_I2C_SlaveTxUnderrun, kStatus_I2C_SlaveRxOverrun, kStatus_I2C_AribtrationLost }
| I2C status return codes. More...
enum | i2c_transmit_receive_mode_t { kI2CReceive = 0, kI2CTransmit = 1 }
| Direction of master and slave transfers. More...

## Module controls
void | i2c_hal_init (uint32_t instance, const i2c_config_t *config, uint32_t sourceClockInHz)
| Initializes and configures the I2C peripheral. More...
void | i2c_hal_reset (uint32_t instance)
| Restores the I2C peripheral to reset state. More...
static void | i2c_hal_enable (uint32_t instance)
| Enables the I2C module operation. More...
static void | i2c_hal_disable (uint32_t instance)
| Disables the I2C module operation. More...

## DMA
static void | i2c_hal_set_dma_enable (uint32_t instance, bool enable)
| Enables or disables the DMA support. More...

## Pin functions
static void | i2c_hal_set_high_drive (uint32_t instance, bool enable)
| Controls the drive capability of the I2C pads. More...
static void | i2c_hal_set_glitch_filter (uint32_t instance, uint8_t glitchWidth)
| Controls the width of the programmable glitch filter. More...

## Low power
static void | i2c_hal_set_wakeup_enable (uint32_t instance, bool enable)
| Controls the I2C wakeup enable. More...

## Baud rate
uint32_t | i2c_hal_get_max_baud (uint32_t instance, uint32_t sourceClockInHz)
| brief Returns the maximum supported baud rate in kilohertz. More...
i2c_status_t | i2c_hal_set_baud (uint32_t instance, uint32_t sourceClockInHz, uint32_t kbps, uint32_t *absoluteError_Hz)
| Sets the I2C bus frequency for master transactions. More...
static void | i2c_hal_set_baud_icr (uint32_t instance, uint8_t mult, uint8_t icr)
| Sets the I2C baud rate multiplier and table entry. More...
static void | i2c_hal_set_independent_slave_baud (uint32_t instance, bool enable)
| Slave baud rate control. More...

## Bus operations
void | i2c_hal_send_start (uint32_t instance)
| Sends a START or a Repeated START signal on the I2C bus. More...
static void | i2c_hal_send_stop (uint32_t instance)
| Sends a STOP signal on the I2C bus. More...
static void | i2c_hal_set_direction (uint32_t instance, i2c_transmit_receive_mode_t mode)
| Selects either transmit or receive modes. More...
static i2c_transmit_receive_mode_t | i2c_hal_get_direction (uint32_t instance)
| Returns the currently selected transmit or receive mode. More...
static void | i2c_hal_send_ack (uint32_t instance)
| Causes an ACK to be sent on the bus. More...
static void | i2c_hal_send_nak (uint32_t instance)
| Causes a NAK to be sent on the bus. More...

## Data transfer
static uint8_t | i2c_hal_read (uint32_t instance)
| Returns the last byte of data read from the bus and initiate another read. More...
static void | i2c_hal_write (uint32_t instance, uint8_t data)
| Writes one byte of data to the I2C bus. More...

## Slave address
void | i2c_hal_set_slave_address_7bit (uint32_t instance, uint8_t address)
| Sets the primary 7-bit slave address. More...
void | i2c_hal_set_slave_address_10bit (uint32_t instance, uint16_t address)
| Sets the primary slave address and enables 10-bit address mode. More...
static void | i2c_hal_set_general_call_enable (uint32_t instance, bool enable)
| Controls whether the general call address is recognized. More...
static void | i2c_hal_set_slave_range_address_enable (uint32_t instance, bool enable)
| Enables or disables the slave address range matching. More...
static void | i2c_hal_set_upper_slave_address_7bit (uint32_t instance, uint8_t address)
| Sets the upper slave address. More...

## Status
static bool | i2c_hal_is_master (uint32_t instance)
| Returns whether the I2C module is in master mode. More...
static bool | i2c_hal_is_transfer_complete (uint32_t instance)
| Gets the transfer complete flag. More...
static bool | i2c_hal_is_addressed_as_slave (uint32_t instance)
| Returns whether the I2C slave was addressed. More...
static bool | i2c_hal_is_bus_busy (uint32_t instance)
| Determines whether the I2C bus is busy. More...
static bool | i2c_hal_was_arbitration_lost (uint32_t instance)
| Returns whether the arbitration procedure was lost. More...
static void | i2c_hal_clear_arbitration_lost (uint32_t instance)
| Clears the arbitration lost flag. More...
static bool | i2c_hal_is_range_address_match (uint32_t instance)
| Get the range address match flag. More...
static i2c_transmit_receive_mode_t | i2c_hal_get_slave_direction (uint32_t instance)
| Returns whether the I2C slave was addressed in read or write mode. More...
static bool | i2c_hal_get_receive_ack (uint32_t instance)
| Returns whether an ACK was received after the last byte was transmitted. More...

## Interrupt
static void | i2c_hal_enable_interrupt (uint32_t instance)
| Enables the I2C interrupt requests. More...
static void | i2c_hal_disable_interrupt (uint32_t instance)
| Disables the I2C interrupt requests. More...
static bool | i2c_hal_is_interrupt_enabled (uint32_t instance)
| Returns whether the I2C interrupts are enabled. More...
static bool | i2c_hal_get_interrupt_status (uint32_t instance)
| Returns the current I2C interrupt flag. More...
static void | i2c_hal_clear_interrupt (uint32_t instance)
| Clears the I2C interrupt if set. More...

### I2C HAL Driver

# ICR Table

ICR (hex) | SCL divider | SDA hold value | SCL start hold value | SCL stop hold value
--- | --- | --- | --- | ---
00 | 20 | 7 | 6 | 11
01 | 22 | 7 | 7 | 12
02 | 24 | 8 | 8 | 13
03 | 26 | 8 | 9 | 14
04 | 28 | 9 | 10 | 15
05 | 30 | 9 | 11 | 16
06 | 34 | 10 | 13 | 18
07 | 40 | 10 | 16 | 21

# Clock rate formulas

I2C baud rate = bus_clock_Hz / (mult * SCL_divider)SDA hold time = bus_clock_period_s * mult * SDA_hold_valueSCL start hold time = bus_clock_period_s * mult * SCL_start_hold_valueSCL stop hold time = bus_clock_period_s * mult * SCL_stop_hold_value

## Data Structure Documentation

struct i2c_config_t

Pass an instance of this structure to the i2c_hal_init() to configure the entire I2C peripheral in a single function call.

### Data Fields
bool | enableModule
| Whether the I2C peripheral operation is enabled. More...
uint32_t | baudRate_kbps
| Requested baud rate in kilobits per second, for example, 100 or 400. More...
bool | useIndependentSlaveBaud
| Enables independent slave mode baud rate at maximum frequency. More...
bool | enableInterrupt
| Enable for the I2C interrupt. More...
bool | enableDma
| Enable DMA transfer signalling. More...
bool | enableHighDrive
| Enable high drive pin mode. More...
bool | enableWakeup
| Enable low power wakeup. More...
uint8_t | glitchFilterWidth
| Specify the glitch filter width in terms of bus clock cycles. More...
uint16_t | slaveAddress
| 7-bit or 10-bit slave address. More...
uint8_t | upperSlaveAddress
| 7-bit upper slave address, or zero to disable. More...
bool | use10bitSlaveAddress
| Controls whether 10-bit slave addresses are enabled. More...
bool | enableGeneralCallAddress
| Enable general call address matching. More...
bool | enableRangeAddressMatch
| Determines if addresses between slaveAddress and upperSlaveAddress are matched. More...

#### Field Documentation

bool i2c_config_t::enableModule

uint32_t i2c_config_t::baudRate_kbps

Pass zero to not set the baud rate.

bool i2c_config_t::useIndependentSlaveBaud

bool i2c_config_t::enableInterrupt

bool i2c_config_t::enableDma

bool i2c_config_t::enableHighDrive

bool i2c_config_t::enableWakeup

uint8_t i2c_config_t::glitchFilterWidth

Set this value to zero to disable the glitch filter.

uint16_t i2c_config_t::slaveAddress

uint8_t i2c_config_t::upperSlaveAddress

If 10-bit addresses are enabled, the top 3 bits are provided by the slaveAddress field.

bool i2c_config_t::use10bitSlaveAddress

bool i2c_config_t::enableGeneralCallAddress

bool i2c_config_t::enableRangeAddressMatch

Both of those fields must be non-zero.

## Enumeration Type Documentation

enum i2c_status_t

Enumerator
kStatus_I2C_Busy | The master is already performing a transfer.
kStatus_I2C_Timeout | The transfer timed out.
kStatus_I2C_ReceivedNak | The slave device sent a NAK in response to a byte.
kStatus_I2C_SlaveTxUnderrun | I2C Slave TX Underrun error.
kStatus_I2C_SlaveRxOverrun | I2C Slave RX Overrun error.
kStatus_I2C_AribtrationLost | I2C Arbitration Lost error.

enum i2c_transmit_receive_mode_t

Enumerator
kI2CReceive | Master and slave receive.
kI2CTransmit | Master and slave transmit.

## Function Documentation

void i2c_hal_init | ( | uint32_t | instance,
|  | const i2c_config_t * | config,
|  | uint32_t | sourceClockInHz
| ) |  |

Parameters

  instance | The I2C peripheral instance number
  config | Pointer to the configuration settings
  sourceClockInHz | I2C source input clock in Hertz.

void i2c_hal_reset | ( | uint32_t | instance | ) |

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_enable | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_disable | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_set_dma_enable | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

Parameters

  instance | The I2C peripheral instance number
  enable | Pass true to enable DMA transfer signalling

static void i2c_hal_set_high_drive | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

Parameters

  instance | The I2C peripheral instance number
  enable | Passing true will enable high drive mode of the I2C pads. False sets normal drive mode.

static void i2c_hal_set_glitch_filter | ( | uint32_t | instance,
|  | uint8_t | glitchWidth
| ) |  |
| inline static

Controls the width of the glitch, in terms of bus clock cycles, that the filter must absorb. The filter does not allow any glitch whose size is less than or equal to this width setting, to pass.

Parameters

  instance | The I2C peripheral instance number
  glitchWidth | Maximum width in bus clock cycles of the glitches that is filtered. Pass zero to disable the glitch filter.

static void i2c_hal_set_wakeup_enable | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

The I2C module can wake the MCU from low power mode with no peripheral bus running when slave address matching occurs.

Parameters

  instance | The I2C peripheral instance number.
  enable | true - Enables the wakeup function in low power mode. false - Normal operation. No interrupt is generated when address matching in low power mode.

uint32_t i2c_hal_get_max_baud | ( | uint32_t | instance,
|  | uint32_t | sourceClockInHz
| ) |  |

Parameters

  instance | The I2C peripheral instance number
  sourceClockInHz | I2C source input clock in Hertz

Returns
  The maximum baud rate in kilohertz

i2c_status_t i2c_hal_set_baud | ( | uint32_t | instance,
|  | uint32_t | sourceClockInHz,
|  | uint32_t | kbps,
|  | uint32_t * | absoluteError_Hz
| ) |  |

Parameters

  instance | The I2C peripheral instance number
  sourceClockInHz | I2C source input clock in Hertz
  kbps | Requested bus frequency in kilohertz. Common values are either 100 or 400.
  absoluteError_Hz | If this parameter is not NULL, it is filled in with the difference in Hertz between the requested bus frequency and the closest frequency possible given available divider values.

Return values

  kStatus_Success | The baud rate was changed successfully. However, there is no guarantee on the minimum error. If you want to ensure that the baud was set to within a certain error, then use the absoluteError_Hz parameter.
  kStatus_OutOfRange | The requested baud rate was not within the range of rates supported by the peripheral.

static void i2c_hal_set_baud_icr | ( | uint32_t | instance,
|  | uint8_t | mult,
|  | uint8_t | icr
| ) |  |
| inline static

Use this function to set the I2C bus frequency register values directly, if they are known in advance.

Parameters

  instance | The I2C peripheral instance number
  mult | Value of the MULT bitfield, ranging from 0-2.
  icr | The ICR bitfield value, which is the index into an internal table in the I2C hardware that selects the baud rate divisor and SCL hold time.

static void i2c_hal_set_independent_slave_baud | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

Enables an independent slave mode baud rate at the maximum frequency. This forces clock stretching on the SCL in very fast I2C modes.

Parameters

  instance | The I2C peripheral instance number
  enable | true - Slave baud rate is independent of the master baud rate; false - The slave baud rate follows the master baud rate and clock stretching may occur.

void i2c_hal_send_start | ( | uint32_t | instance | ) |

This function is used to initiate a new master mode transfer by sending the START signal. It is also used to send a Repeated START signal when a transfer is already in progress.

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_send_stop | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_set_direction | ( | uint32_t | instance,
|  | i2c_transmit_receive_mode_t | mode
| ) |  |
| inline static

Parameters

  instance | The I2C peripheral instance number
  mode | Specifies either transmit mode or receive mode. The valid values are: kI2CTransmit kI2CReceive

static i2c_transmit_receive_mode_t i2c_hal_get_direction | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  kI2CTransmit | I2C is configured for master or slave transmit mode.
  kI2CReceive | I2C is configured for master or slave receive mode.

static void i2c_hal_send_ack | ( | uint32_t | instance | ) |
| inline static

This function specifies that an ACK signal is sent in response to the next received byte.

Note that the behavior of this function is changed when the I2C peripheral is placed in Fast ACK mode. In this case, this function causes an ACK signal to be sent in response to the current byte, rather than the next received byte.

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_send_nak | ( | uint32_t | instance | ) |
| inline static

This function specifies that a NAK signal is sent in response to the next received byte.

Note that the behavior of this function is changed when the I2C peripheral is placed in the Fast ACK mode. In this case, this function causes an NAK signal to be sent in response to the current byte, rather than the next received byte.

Parameters

  instance | The I2C peripheral instance number

static uint8_t i2c_hal_read | ( | uint32_t | instance | ) |
| inline static

In a master receive mode, calling this function initiates receiving the next byte of data.

Parameters

  instance | The I2C peripheral instance number

Returns
  This function returns the last byte received while the I2C module is configured in master receive or slave receive mode.

static void i2c_hal_write | ( | uint32_t | instance,
|  | uint8_t | data
| ) |  |
| inline static

When this function is called in the master transmit mode, a data transfer is initiated. In slave mode, the same function is available after an address match occurs.

In a master transmit mode, the first byte of data written following the start bit or repeated start bit is used for the address transfer and must consist of the slave address (in bits 7-1) concatenated with the required R/#W bit (in position bit 0).

Parameters

  instance | The I2C peripheral instance number
  data | The byte of data to transmit

void i2c_hal_set_slave_address_7bit | ( | uint32_t | instance,
|  | uint8_t | address
| ) |  |

Parameters

  instance | The I2C peripheral instance number
  address | The slave address in the upper 7 bits. Bit 0 of this value must be 0.

void i2c_hal_set_slave_address_10bit | ( | uint32_t | instance,
|  | uint16_t | address
| ) |  |

Parameters

  instance | The I2C peripheral instance number
  address | The 10-bit slave address, in bits [10:1] of the value. Bit 0 must be 0.

static void i2c_hal_set_general_call_enable | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

Parameters

  instance | The I2C peripheral instance number
  enable | Whether to enable the general call address.

static void i2c_hal_set_slave_range_address_enable | ( | uint32_t | instance,
|  | bool | enable
| ) |  |
| inline static

Parameters

  instance | The I2C peripheral instance number
  enable | Pass true to enable the range address matching. You must also call the i2c_hal_set_upper_slave_address_7bit() to set the upper address.

static void i2c_hal_set_upper_slave_address_7bit | ( | uint32_t | instance,
|  | uint8_t | address
| ) |  |
| inline static

This slave address is used as a secondary slave address. If range address matching is enabled, this slave address acts as the upper bound on the slave address range.

This function sets only a 7-bit slave address. If 10-bit addressing was enabled by calling the i2c_hal_set_slave_address_10bit(), then the top 3 bits set with that function are also used with the address set with this function to form a 10-bit address.

Passing 0 for the address parameter disables matching the upper slave address.

Parameters

  instance | The I2C peripheral instance number
  address | The upper slave address in the upper 7 bits. Bit 0 of this value must be 0. This address must be greater than the primary slave address that is set by calling the i2c_hal_set_slave_address_7bit().

static bool i2c_hal_is_master | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | The module is in master mode, which implies it is also performing a transfer.
  false | The module is in slave mode.

static bool i2c_hal_is_transfer_complete | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Transfer is complete.
  false | Transfer is in progress.

static bool i2c_hal_is_addressed_as_slave | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Addressed as slave.
  false | Not addressed.

static bool i2c_hal_is_bus_busy | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Bus is busy.
  false | Bus is idle.

static bool i2c_hal_was_arbitration_lost | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Loss of arbitration
  false | Standard bus operation

static void i2c_hal_clear_arbitration_lost | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static bool i2c_hal_is_range_address_match | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Addressed as slave.
  false | Not addressed.

static i2c_transmit_receive_mode_t i2c_hal_get_slave_direction | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  kI2CReceive | Slave receive, master writing to slave
  kI2CTransmit | Slave transmit, master reading from slave

static bool i2c_hal_get_receive_ack | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | Acknowledges that the signal was received after the completion of one byte of data transmission on the bus.
  false | No acknowledgement of the signal is detected.

static void i2c_hal_enable_interrupt | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static void i2c_hal_disable_interrupt | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

static bool i2c_hal_is_interrupt_enabled | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | I2C interrupts are enabled.
  false | I2C interrupts are disabled.

static bool i2c_hal_get_interrupt_status | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number

Return values

  true | An interrupt is pending.
  false | No interrupt is pending.

static void i2c_hal_clear_interrupt | ( | uint32_t | instance | ) |
| inline static

Parameters

  instance | The I2C peripheral instance number