Overview

This section describes the programming interface of the I2C HAL driver.

I2C 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

I2C Clock rate formulas

I2C baud rate = bus_clock_Hz / (mult * SCL_divider)

SDA hold time = bus_clock_period_s * mult * SDA_hold_value

SCL start hold time = bus_clock_period_s * mult * SCL_start_hold_value

SCL stop hold time = bus_clock_period_s * mult * SCL_stop_hold_value

Enumerations
enum	i2c_status_t { kStatus_I2C_Success = 0x0U, kStatus_I2C_Initialized = 0x1U, kStatus_I2C_Fail = 0x2U, kStatus_I2C_Busy = 0x3U, kStatus_I2C_Timeout = 0x4U, kStatus_I2C_ReceivedNak = 0x5U, kStatus_I2C_SlaveTxUnderrun = 0x6U, kStatus_I2C_SlaveRxOverrun = 0x7U, kStatus_I2C_AribtrationLost = 0x8U, kStatus_I2C_StopSignalFail = 0x9U, kStatus_I2C_Idle = 0xAU, kStatus_I2C_NoReceiveInProgress = 0xBU, kStatus_I2C_NoSendInProgress = 0xCU }
	I2C status return codes. More...

enum	i2c_status_flag_t
	I2C status flags. More...

enum	i2c_direction_t { kI2CReceive = 0U, kI2CSend = 1U }
	Direction of master and slave transfers. More...

Module controls
void	I2C_HAL_Init (I2C_Type *base)
	Restores the I2C peripheral to reset state. More...

static void	I2C_HAL_Enable (I2C_Type *base)
	Enables the I2C module operation. More...

static void	I2C_HAL_Disable (I2C_Type *base)
	Disables the I2C module operation. More...

Pin functions
static void	I2C_HAL_SetGlitchWidth (I2C_Type *base, uint8_t glitchWidth)
	Controls the width of the programmable glitch filter. More...

Low power
static void	I2C_HAL_SetWakeupCmd (I2C_Type *base, bool enable)
	Controls the I2C wakeup enable. More...

Baud rate
void	I2C_HAL_SetBaudRate (I2C_Type base, uint32_t sourceClockInHz, uint32_t kbps, uint32_t absoluteError_Hz)
	Sets the I2C bus frequency for master transactions. More...

static void	I2C_HAL_SetFreqDiv (I2C_Type *base, uint8_t mult, uint8_t icr)
	Sets the I2C baud rate multiplier and table entry. More...

static void	I2C_HAL_SetSlaveBaudCtrlCmd (I2C_Type *base, bool enable)
	Slave baud rate control. More...

Bus operations
void	I2C_HAL_SendStart (I2C_Type *base)
	Sends a START or a Repeated START signal on the I2C bus. More...

i2c_status_t	I2C_HAL_SendStop (I2C_Type *base)
	Sends a STOP signal on the I2C bus. More...

static void	I2C_HAL_SendAck (I2C_Type *base)
	Causes an ACK to be sent on the bus. More...

static void	I2C_HAL_SendNak (I2C_Type *base)
	Causes a NAK to be sent on the bus. More...

static void	I2C_HAL_SetDirMode (I2C_Type *base, i2c_direction_t direction)
	Selects either transmit or receive mode. More...

static i2c_direction_t	I2C_HAL_GetDirMode (I2C_Type *base)
	Returns the currently selected transmit or receive mode. More...

Data transfer
static uint8_t	I2C_HAL_ReadByte (I2C_Type *base)
	Returns the last byte of data read from the bus and initiate another read. More...

static void	I2C_HAL_WriteByte (I2C_Type *base, uint8_t byte)
	Writes one byte of data to the I2C bus. More...

uint8_t	I2C_HAL_ReadByteBlocking (I2C_Type *base)
	Returns the last byte of data read from the bus and initiate another read. More...

bool	I2C_HAL_WriteByteBlocking (I2C_Type *base, uint8_t byte)
	Writes one byte of data to the I2C bus and wait till that byte is transfered successfully. More...

i2c_status_t	I2C_HAL_MasterReceiveDataPolling (I2C_Type base, uint16_t slaveAddr, const uint8_t cmdBuff, uint32_t cmdSize, uint8_t *rxBuff, uint32_t rxSize)
	Performs a polling receive transaction on the I2C bus. More...

i2c_status_t	I2C_HAL_MasterSendDataPolling (I2C_Type base, uint16_t slaveAddr, const uint8_t cmdBuff, uint32_t cmdSize, const uint8_t *txBuff, uint32_t txSize)
	Performs a polling send transaction on the I2C bus. More...

i2c_status_t	I2C_HAL_SlaveSendDataPolling (I2C_Type base, const uint8_t txBuff, uint32_t txSize)
	Send out multiple bytes of data using polling method. More...

i2c_status_t	I2C_HAL_SlaveReceiveDataPolling (I2C_Type base, uint8_t rxBuff, uint32_t rxSize)
	Receive multiple bytes of data using polling method. More...

Slave address
void	I2C_HAL_SetAddress7bit (I2C_Type *base, uint8_t address)
	Sets the primary 7-bit slave address. More...

void	I2C_HAL_SetAddress10bit (I2C_Type *base, uint16_t address)
	Sets the primary slave address and enables 10-bit address mode. More...

static void	I2C_HAL_SetExtensionAddrCmd (I2C_Type *base, bool enable)
	Enables or disables the extension address (10-bit). More...

static bool	I2C_HAL_GetExtensionAddrCmd (I2C_Type *base)
	Returns whether the extension address is enabled or not. More...

static void	I2C_HAL_SetGeneralCallCmd (I2C_Type *base, bool enable)
	Controls whether the general call address is recognized. More...

static void	I2C_HAL_SetRangeMatchCmd (I2C_Type *base, bool enable)
	Enables or disables the slave address range matching. More...

static void	I2C_HAL_SetUpperAddress7bit (I2C_Type *base, uint8_t address)
	Sets the upper slave address. More...

Status
static bool	I2C_HAL_GetStatusFlag (I2C_Type *base, i2c_status_flag_t statusFlag)
	Gets the I2C status flag state. More...

static bool	I2C_HAL_IsMaster (I2C_Type *base)
	Returns whether the I2C module is in master mode. More...

static void	I2C_HAL_ClearArbitrationLost (I2C_Type *base)
	Clears the arbitration lost flag. More...

Interrupt
static void	I2C_HAL_SetIntCmd (I2C_Type *base, bool enable)
	Enables or disables I2C interrupt requests. More...

static bool	I2C_HAL_GetIntCmd (I2C_Type *base)
	Returns whether the I2C interrupts are enabled. More...

static bool	I2C_HAL_IsIntPending (I2C_Type *base)
	Returns the current I2C interrupt flag. More...

static void	I2C_HAL_ClearInt (I2C_Type *base)
	Clears the I2C interrupt if set. More...

Enumeration Type Documentation

enum i2c_status_t

Enumerator
kStatus_I2C_Success	I2C operation has no error.
kStatus_I2C_Initialized	Current I2C is already initialized by one task.
kStatus_I2C_Fail	I2C operation failed.
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.
kStatus_I2C_StopSignalFail	I2C STOP signal could not release bus.
kStatus_I2C_Idle	I2C Slave Bus is Idle.
kStatus_I2C_NoReceiveInProgress	Attempt to abort a receiving when no transfer was in progress.
kStatus_I2C_NoSendInProgress	Attempt to abort a sending when no transfer was in progress.

enum i2c_status_flag_t

enum i2c_direction_t

Enumerator
kI2CReceive	Master transmit, slave receive.
kI2CSend	Master receive, slave transmit.

Function Documentation

void I2C_HAL_Init ( I2C_Type * base )

Parameters

base	The I2C peripheral base pointer

static void I2C_HAL_Enable ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

static void I2C_HAL_Disable ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

static void I2C_HAL_SetGlitchWidth	(	I2C_Type *	base,
		uint8_t	glitchWidth
	)

inlinestatic

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

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

static void I2C_HAL_SetWakeupCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

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

Parameters

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

void I2C_HAL_SetBaudRate	(	I2C_Type *	base,
		uint32_t	sourceClockInHz,
		uint32_t	kbps,
		uint32_t *	absoluteError_Hz
	)

Parameters

base	The I2C peripheral base pointer
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.

static void I2C_HAL_SetFreqDiv	(	I2C_Type *	base,
		uint8_t	mult,
		uint8_t	icr
	)

inlinestatic

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

Parameters

base	The I2C peripheral base pointer
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_SetSlaveBaudCtrlCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

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

Parameters

base	The I2C peripheral base pointer
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_SendStart ( I2C_Type * base )

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

base	The I2C peripheral base pointer

i2c_status_t I2C_HAL_SendStop ( I2C_Type * base )

This function changes the direction to receive.

Parameters

base	The I2C peripheral base pointer

Returns: Whether the sending of STOP single is success or not.

static void I2C_HAL_SendAck ( I2C_Type * base )

inlinestatic

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

base	The I2C peripheral base pointer

static void I2C_HAL_SendNak ( I2C_Type * base )

inlinestatic

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

base	The I2C peripheral base pointer

static void I2C_HAL_SetDirMode	(	I2C_Type *	base,
		i2c_direction_t	direction
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer.
direction	Specifies either transmit mode or receive mode. The valid values are: #kI2CTransmit kI2CReceive

static i2c_direction_t I2C_HAL_GetDirMode ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer.

Returns: Current I2C transfer mode.

Return values

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

static uint8_t I2C_HAL_ReadByte ( I2C_Type * base )

inlinestatic

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

Parameters

base	The I2C peripheral base pointer

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_WriteByte	(	I2C_Type *	base,
		uint8_t	byte
	)

inlinestatic

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

base	The I2C peripheral base pointer.
byte	The byte of data to transmit.

uint8_t I2C_HAL_ReadByteBlocking ( I2C_Type * base )

It will wait till the transfer is actually completed.

Parameters

base	The I2C peripheral base pointer

Returns: Returns the last byte received

bool I2C_HAL_WriteByteBlocking	(	I2C_Type *	base,
		uint8_t	byte
	)

Parameters

base	The I2C peripheral base pointer.
byte	The byte of data to transmit.

Returns: Whether ACK is received(TRUE) or not(FALSE).

i2c_status_t I2C_HAL_MasterReceiveDataPolling	(	I2C_Type *	base,
		uint16_t	slaveAddr,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		uint8_t *	rxBuff,
		uint32_t	rxSize
	)

Parameters

base	The I2C peripheral base pointer.
slaveAddr	The slave address to communicate.
cmdBuff	The pointer to the commands to be transferred.
cmdSize	The length in bytes of the commands to be transferred.
rxBuff	The pointer to the data to be transferred.
rxSize	The length in bytes of the data to be transferred.

Returns: Error or success status returned by API.

i2c_status_t I2C_HAL_MasterSendDataPolling	(	I2C_Type *	base,
		uint16_t	slaveAddr,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		const uint8_t *	txBuff,
		uint32_t	txSize
	)

Parameters

base	The I2C peripheral base pointer.
slaveAddr	The slave address to communicate.
cmdBuff	The pointer to the commands to be transferred.
cmdSize	The length in bytes of the commands to be transferred.
txBuff	The pointer to the data to be transferred.
txSize	The length in bytes of the data to be transferred.

Returns: Error or success status returned by API.

i2c_status_t I2C_HAL_SlaveSendDataPolling	(	I2C_Type *	base,
		const uint8_t *	txBuff,
		uint32_t	txSize
	)

Parameters

base	I2C module base pointer.
txBuff	The buffer pointer which saves the data to be sent.
txSize	Size of data to be sent in unit of byte.

Returns: Whether the transaction is success or not.

Return values

kStatus_I2C_ReceivedNak	if received NACK bit
Error	or success status returned by API.

i2c_status_t I2C_HAL_SlaveReceiveDataPolling	(	I2C_Type *	base,
		uint8_t *	rxBuff,
		uint32_t	rxSize
	)

Parameters

base	I2C module base pointer.
rxBuff	The buffer pointer which saves the data to be received.
rxSize	Size of data need to be received in unit of byte.

Returns: Error or success status returned by API.

void I2C_HAL_SetAddress7bit	(	I2C_Type *	base,
		uint8_t	address
	)

Parameters

base	The I2C peripheral base pointer
address	The slave address in the upper 7 bits. Bit 0 of this value must be 0.

void I2C_HAL_SetAddress10bit	(	I2C_Type *	base,
		uint16_t	address
	)

Parameters

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

static void I2C_HAL_SetExtensionAddrCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer
enable	true: 10-bit address is enabled. false: 10-bit address is not enabled.

static bool I2C_HAL_GetExtensionAddrCmd ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

Returns: true: 10-bit address is enabled. false: 10-bit address is not enabled.

static void I2C_HAL_SetGeneralCallCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer
enable	Whether to enable the general call address.

static void I2C_HAL_SetRangeMatchCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer.
enable	Pass true to enable range address matching. You must also call I2C_HAL_SetUpperAddress7bit() to set the upper address.

static void I2C_HAL_SetUpperAddress7bit	(	I2C_Type *	base,
		uint8_t	address
	)

inlinestatic

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 I2C_HAL_SetAddress10bit(), 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

base	The I2C peripheral base pointer
address	The upper slave address in the upper 7 bits. Bit 0 of this value must be 0. In addition, this address must be greater than the primary slave address that is set by calling I2C_HAL_SetAddress7bit().

static bool I2C_HAL_GetStatusFlag	(	I2C_Type *	base,
		i2c_status_flag_t	statusFlag
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer.
statusFlag	The status flag, defined in type i2c_status_flag_t.

Returns

State of the status flag: asserted (true) or not-asserted (false).

true: related status flag is being set.
false: related status flag is not set.

static bool I2C_HAL_IsMaster ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer.

Returns: Whether current I2C is in master mode or not.

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 void I2C_HAL_ClearArbitrationLost ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

static void I2C_HAL_SetIntCmd	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	The I2C peripheral base pointer
enable	Pass true to enable interrupt, false to disable.

static bool I2C_HAL_GetIntCmd ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

Returns: Whether I2C interrupts are enabled or not.

static bool I2C_HAL_IsIntPending ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

Returns: Whether I2C interrupt is pending or not.

static void I2C_HAL_ClearInt ( I2C_Type * base )

inlinestatic

Parameters

base	The I2C peripheral base pointer

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

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

Overview

I2C ICR Table

I2C Clock rate formulas

Enumerations

Module controls

Pin functions

Low power

Baud rate

Bus operations

Data transfer

Slave address

Status

Interrupt

Enumeration Type Documentation

Function Documentation

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