I2C Driver

The I2C driver is used for allowing a project to have access to and control basic I2C functionality of an end device.

Data Structures

ATMO_I2C_Peripheral_t

I2C peripheral configuration.

Member Name Type Description
baudRate ATMO_I2C_OperatingMode_t operatingMode ATMO_I2C_BaudRate_t I2C operating mode, I2C baud Rate
localAddress uint16_t Peripheral address
bufferSize uint32_t Buffer size used for slave mode
cbFunc void * Unused
cbParam void * Unused

ATMO_I2C_SlaveTransfer_t

I2C slave single transfer event.

Member Name Type Description
event ATMO_I2C_SlaveEvent_t I2C slave event
data uint8_t * Transferred data
dataSize uint32_t Data size in bytes
transferComplete bool Transfer complete flag

ATMO_I2C_MasterTransfer_t

I2C master single transfer event.

Member Name Type Description
event ATMO_I2C_MasterEvent_t I2C master event
data uint8_t * Transferred data
dataSize uint32_t Data size in bytes
transferComplete bool Transfer complete flag

Type Definitions

Name Definition Description
ATMO_I2C_Master_Callback_t typedef void(* ATMO_I2C_Master_Callback_t) (ATMO_I2C_MasterTransfer_t *xfer, void *cbParam)  
ATMO_I2C_Slave_Callback_t typedef void(* ATMO_I2C_Slave_Callback_t) (ATMO_I2C_SlaveTransfer_t *xfer, void *cbParam)  
ATMO_I2C_DriverInstance_t typedef struct ATMO_I2C_DriverInstance_t ATMO_I2C_DriverInstance_t  

Enumerations

enum ATMO_I2C_OperatingMode_t

I2C operating mode.

Name Value
ATMO_I2C_OperatingMode_Uninitialized 0x00u
ATMO_I2C_OperatingMode_Master 0x01u
ATMO_I2C_OperatingMode_Slave 0x02u
ATMO_I2C_OperatingMode_Invalid 0xFFu

enum ATMO_I2C_BaudRate_t

I2C baud rate.

Name Value
ATMO_I2C_BaudRate_Uninitialized 0x00u
ATMO_I2C_BaudRate_Low_Speed_Mode 0x01u
ATMO_I2C_BaudRate_Standard_Mode 0x02u
ATMO_I2C_BaudRate_Fast_Mode 0x03u
ATMO_I2C_BaudRate_Fast_Mode_Plus 0x04u
ATMO_I2C_BaudRate_High_Speed_Mode 0x05u
ATMO_I2C_BaudRate_Ultra_Speed_Mode 0x06u
ATMO_I2C_BaudRate_10kHz 0x81u
ATMO_I2C_BaudRate_100kHz 0x82u
ATMO_I2C_BaudRate_400kHz 0x83u
ATMO_I2C_BaudRate_1000kHz 0x84u
ATMO_I2C_BaudRate_3400kHz 0x85u
ATMO_I2C_BaudRate_5000kHz 0x86u
ATMO_I2C_BaudRate_Invalid 0xFFu

enum ATMO_I2C_Status_t

I2C driver return enumerations.

Name Value Description
ATMO_I2C_Status_Success 0x00u Common - Operation was successful
ATMO_I2C_Status_Fail 0x01u Common - Operation failed
ATMO_I2C_Status_Initialized 0x02u Common - Peripheral already initialized
ATMO_I2C_Status_Invalid 0x03u Common - Invalid operation or result
ATMO_I2C_Status_NotSupported 0x04u Common - Feature not supported by platform
ATMO_I2C_Status_Unknown 0x05u Common - Some other status not defined
ATMO_I2C_Status_Busy 0x06u Common - Transfer in progress
ATMO_I2C_Status_Timeout 0x20u Master - Transfer timed out
ATMO_I2C_Status_ReceivedNak 0x21u Master - Received NAK from slave device
ATMO_I2C_Status_NoReceiveInProgress 0x22u Master - No transfer in progress when attempting to abort receive
ATMO_I2C_Status_NoSendInProgress 0x23u Master - No transfer in progress when attempting to abort send
ATMO_I2C_Status_ArbitrationLost 0x24u Master - Lost arbitration in multi-master mode
ATMO_I2C_Status_TxUnderrun 0x40u Slave - TX underrun error
ATMO_I2C_Status_RxOverrun 0x41u Slave - RX overrun error
ATMO_I2C_Status_Idle 0x42u Slave - Bus is idle

enum ATMO_I2C_MasterEvent_t

SPI master event. Only relevant for non-blocking operations.

Name Value Description
ATMO_I2C_MasterEvent_Unknown 0x00u  
ATMO_I2C_MasterEvent_Complete 0x01u Transfer complete

enum ATMO_I2C_SlaveEvent_t

SPI slave event. Only relevant for non-blocking operations.

Name Value Description
ATMO_I2C_SlaveEvent_Unknown 0x0000u  
ATMO_I2C_SlaveEvent_Complete 0x0001u Transfer Complete
ATMO_I2C_SlaveEvent_WriteRequest 0x0002u Master wants to write to slave
ATMO_I2C_SlaveEvent_ReadRequest 0x0004u Master wants to read from slave
ATMO_I2C_SlaveEvent_TransmitAckRequest 0x0008u Transmit ACK/NAK
ATMO_I2C_SlaveEvent_StartDetect 0x0010u START signal detected
ATMO_I2C_SlaveEvent_StopDetect 0x0020u STOP signal detected
ATMO_I2C_SlaveEvent_TxEmpty 0x0040u Transmit buffer empty
ATMO_I2C_SlaveEvent_RxFull 0x0080u Receive buffer full
ATMO_I2C_SlaveEvent_Abort 0x0100u Slave abort transaction
ATMO_I2C_SlaveEvent_AddressMatch 0x0200u Received the slave address after a start or repeated start
ATMO_I2C_SlaveEvent_GeneralCall 0x0400u General call

Functions

ATMO_Status_t ATMO_I2C_AddDriverInstance(const ATMO_I2C_DriverInstance_t *driverInstance, ATMO_DriverInstanceData_t *driverInstanceData, ATMO_DriverInstanceHandle_t *instanceNumber)

This routine will add an instance of a driver for I2C into the I2C driver handler.

Parameter Direction Type
instanceNumber N/A ATMO_DriverInstanceHandle_t *
driverInstanceData N/A ATMO_DriverInstanceData_t *
driverInstance N/A const ATMO_I2C_DriverInstance_t *
Return Type
ATMO_Status_t

ATMO_I2C_Status_t ATMO_I2C_Init(ATMO_DriverInstanceHandle_t instance)

This routine initializes the specified I2C peripheral instance. The specific configuration settings are either hard-coded in the platform driver or are pulled from a configuration header file.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_DeInit(ATMO_DriverInstanceHandle_t instance)

This routine de-initializes the specified I2C peripheral instance.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_SetConfiguration(ATMO_DriverInstanceHandle_t instance, const ATMO_I2C_Peripheral_t *config)

This routine configures the specified I2C peripheral instance. It is similar to the init function except the peripheral configuration settings are passed in via the config structure.

Parameter Direction Type
config N/A const ATMO_I2C_Peripheral_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_GetConfiguration(ATMO_DriverInstanceHandle_t instance, ATMO_I2C_Peripheral_t *config)

This routine retrieves the current configuration of the specified I2C peripheral instance.

Parameter Direction Type
config N/A ATMO_I2C_Peripheral_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterRegisterCallback(ATMO_DriverInstanceHandle_t instance, ATMO_I2C_Master_Callback_t cbFunc)

This routine will register or unregister a user-defined callback function for the specified I2C peripheral instance.

Parameter Direction Type
cbFunc N/A ATMO_I2C_Master_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_SlaveRegisterCallback(ATMO_DriverInstanceHandle_t instance, ATMO_I2C_Slave_Callback_t cbFunc)

This routine will register or unregister a user-defined callback function for the specified I2C peripheral instance.

Parameter Direction Type
cbFunc N/A ATMO_I2C_Slave_Callback_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterWrite(ATMO_DriverInstanceHandle_t instance, uint16_t slaveAddress, const uint8_t *cmdBytes, uint16_t numCmdBytes, const uint8_t *writeBytes, uint16_t numWriteBytes, uint16_t timeout_ms)

This routine will send one or more bytes to a slave device via the specified I2C peripheral. This is a blocking operation and the function will not return until the I2C transfer completes or the timeout expires.

Parameter Direction Type
timeout_ms N/A uint16_t
numWriteBytes N/A uint16_t
writeBytes N/A const uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
slaveAddress N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterWriteNonBlocking(ATMO_DriverInstanceHandle_t instance, uint16_t slaveAddress, const uint8_t *cmdBytes, uint16_t numCmdBytes, const uint8_t *writeBytes, uint16_t numWriteBytes)

This routine will send one or more bytes to a slave device via the specified I2C peripheral. This function does not wait for the I2C transfer to complete before returning (i.e. returns immediately). It is up to the application to wait for the I2C peripheral to become available before performing another data transfer (write or read).

Parameter Direction Type
numWriteBytes N/A uint16_t
writeBytes N/A const uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
slaveAddress N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterRead(ATMO_DriverInstanceHandle_t instance, uint16_t slaveAddress, const uint8_t *cmdBytes, uint16_t numCmdBytes, uint8_t *readBytes, uint16_t numReadBytes, uint16_t timeout_ms)

This routine will read one or more bytes from a slave device via the specified I2C peripheral. If the command buffer has a valid pointer (i.e. not NULL) and the number of command bytes is greater than zero then the values in the command buffer are first sent to the device followed by a repeated START condition. Otherwise a repeated START condition will not be generated. This is a blocking operation and the function will not return until the I2C transfer completes or the timeout expires.

Parameter Direction Type
timeout_ms N/A uint16_t
numReadBytes N/A uint16_t
readBytes N/A uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
slaveAddress N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterReadNonBlocking(ATMO_DriverInstanceHandle_t instance, uint16_t slaveAddress, const uint8_t *cmdBytes, uint16_t numCmdBytes, uint8_t *readBytes, uint16_t numReadBytes)

This routine will read one or more bytes from a slave device via the specified I2C peripheral. If the command buffer has a valid pointer (i.e. not NULL) and the number of command bytes is greater than zero then the values in the command buffer are first sent to the device followed by a repeated START condition. Otherwise a repeated START condition will not be generated. This function does not wait for the I2C transfer to complete before returning (i.e. returns immediately). It is up to the application to wait for the I2C peripheral to become available before performing another data transfer (write or read).

Parameter Direction Type
numReadBytes N/A uint16_t
readBytes N/A uint8_t *
numCmdBytes N/A uint16_t
cmdBytes N/A const uint8_t *
slaveAddress N/A uint16_t
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_MasterGetStatus(ATMO_DriverInstanceHandle_t instance, uint16_t *bytesRemaining)

This routine gets the status of the current non-blocking operation.

Parameter Direction Type
bytesRemaining N/A uint16_t *
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t

ATMO_I2C_Status_t ATMO_I2C_SlaveWaitForReceive(ATMO_DriverInstanceHandle_t instance)

This routine starts the receive process for an I2C peripheral configures in Slave mode. It only needs to be called once.

Parameter Direction Type
instance N/A ATMO_DriverInstanceHandle_t
Return Type
ATMO_I2C_Status_t