3.10 I2C Client Driver

Overview

The Inter-Integrated Circuit (I2C) module is a serial interface useful for communicating with other peripheral or microcontroller devices. These peripheral devices may be serial EEPROMs, display drivers, A/D Converters, etc. The I2C Client Driver implements the I2C Client functionality of the I2C module.

Features

Clock Stretching to provide delays for the Processor.
Both 7-Bit and 10-Bit Device Addresses are supported.
The driver supports configurable Address Masking.

3.10.1 Module Documentation

3.10.1.1 I2C Client Driver

I2C Driver for Client Mode using dsPIC MCUs.

3.10.1.1.1 Module description

I2C Driver for Client Mode using dsPIC MCUs.

Data structures

struct I2C_CLIENT_INTERFACE

Structure containing the function pointers of I2C driver.

Definitions

#define I2C1_Client_Initialize I2C1_Initialize

This macro defines the Custom Name for I2C1_Initialize API.
#define I2C1_Client_Deinitialize I2C1_Deinitialize

This macro defines the Custom Name for I2C1_Deinitialize API.
#define I2C1_Client_WriteByte I2C1_WriteByte

This macro defines the Custom Name for I2C1_WriteByte API.
#define I2C1_Client_ReadByte I2C1_ReadByte

This macro defines the Custom Name for I2C1_ReadByte API.
#define I2C1_Client_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.
#define I2C1_Client_IsBusy I2C1_IsBusy

This macro defines the Custom Name for I2C1_IsBusy API.
#define I2C1_Client_TransferDirGet I2C1_TransferDirGet

This macro defines the Custom Name for I2C1_TransferDirGet API.
#define I2C1_Client_LastByteAckStatusGet I2C1_LastByteAckStatusGet

This macro defines the Custom Name for I2C1_LastByteAckStatusGet API.
#define I2C1_Client_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

Enumerations

enum I2C_CLIENT_TRANSFER_DIR { I2C_CLIENT_TRANSFER_DIR_WRITE = 0, I2C_CLIENT_TRANSFER_DIR_READ = 1 }

This Enum can be used in client application to know the data transfer direction sent from the host using I2Cx_TransferDirGet function e.g. I2C1_TransferDirGet.
enum I2C_CLIENT_ACK_STATUS { I2C_CLIENT_ACK_STATUS_RECEIVED_ACK = 0, I2C_CLIENT_ACK_STATUS_RECEIVED_NACK = 1 }

This Enum can be used in client application to know the ACK/NACK status sent from the host using I2Cx_LastByteAckStatusGet function e.g. I2C1_LastByteAckStatusGet.
enum I2C_CLIENT_TRANSFER_EVENT { I2C_CLIENT_TRANSFER_EVENT_NONE, I2C_CLIENT_TRANSFER_EVENT_ADDR_MATCH, I2C_CLIENT_TRANSFER_EVENT_RX_READY, I2C_CLIENT_TRANSFER_EVENT_TX_READY, I2C_CLIENT_TRANSFER_EVENT_STOP_BIT_RECEIVED, I2C_CLIENT_TRANSFER_EVENT_ERROR }

This Enum can be used to know the Client status. This status information can be used in the callback handling.
enum I2C_CLIENT_ERROR { I2C_CLIENT_ERROR_NONE, I2C_CLIENT_ERROR_BUS_COLLISION, I2C_CLIENT_ERROR_WRITE_COLLISION, I2C_CLIENT_ERROR_RECEIVE_OVERFLOW }

This Enum can be used to know the Client Error type using I2Cx_ErrorGet e.g. I2C1_ErrorGet.

Functions

void I2C1_Initialize (void)

Initializes the I2C1 module.
void I2C1_Deinitialize (void)

Deinitializes the I2C1 to POR values.
void I2C1_WriteByte (uint8_t wrByte)

I2C Client transmits data to Host.
uint8_t I2C1_ReadByte (void)

I2C1 Client reads data transmitted from Host.
enum I2C_CLIENT_ERROR I2C1_ErrorGet (void)

Returns the error occurred during I2C1 Transmit or Receive.
bool I2C1_IsBusy (void)

Returns the bus availability status. The application can use the function to check if I2C1 module is busy before calling any of the data transfer functions. The library does not allow a data transfer operation if another transfer operation is already in progress.
enum I2C_CLIENT_TRANSFER_DIR I2C1_TransferDirGet (void)

Returns the I2C1 Transfer direction status.
enum I2C_CLIENT_ACK_STATUS I2C1_LastByteAckStatusGet (void)

Returns the ACK status sent by the I2C Host.
void I2C1_CallbackRegister (bool(*callback)(enum I2C_CLIENT_TRANSFER_EVENT clientEvent))

This function can be used to override default callback I2C1_ClientCallback and to define custom callback for I2C1 Client event.
bool I2C1_Callback (enum I2C_CLIENT_TRANSFER_EVENT clientEvent)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using I2C1_CallbackRegister.

Variables

const struct I2C_CLIENT_INTERFACE I2C1_Client

Structure object of type I2C_CLIENT_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Client can be changed by the user in the I2C user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.10.1.1.2 Definition Documentation

I2C1_Client_CallbackRegister

#define I2C1_Client_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

I2C1_Client_Deinitialize

#define I2C1_Client_Deinitialize I2C1_Deinitialize

This macro defines the Custom Name for I2C1_Deinitialize API.

I2C1_Client_ErrorGet

#define I2C1_Client_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.

I2C1_Client_Initialize

#define I2C1_Client_Initialize I2C1_Initialize

This macro defines the Custom Name for I2C1_Initialize API.

I2C1_Client_IsBusy

#define I2C1_Client_IsBusy I2C1_IsBusy

This macro defines the Custom Name for I2C1_IsBusy API.

I2C1_Client_LastByteAckStatusGet

#define I2C1_Client_LastByteAckStatusGet I2C1_LastByteAckStatusGet

This macro defines the Custom Name for I2C1_LastByteAckStatusGet API.

I2C1_Client_ReadByte

#define I2C1_Client_ReadByte I2C1_ReadByte

This macro defines the Custom Name for I2C1_ReadByte API.

I2C1_Client_TransferDirGet

#define I2C1_Client_TransferDirGet I2C1_TransferDirGet

This macro defines the Custom Name for I2C1_TransferDirGet API.

I2C1_Client_WriteByte

#define I2C1_Client_WriteByte I2C1_WriteByte

This macro defines the Custom Name for I2C1_WriteByte API.

3.10.1.1.3 Function Documentation

I2C1_Callback()

bool I2C1_Callback (enum I2C_CLIENT_TRANSFER_EVENT clientEvent)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using I2C1_CallbackRegister.

Precondition:
none

Parameters:
in	clientEvent	- Client event status information for callback handling

Returns:
true - I2C1 Client event progress success false - I2C1 Client event progress failure

I2C1_CallbackRegister()

void I2C1_CallbackRegister (bool(*)(enum I2C_CLIENT_TRANSFER_EVENT clientEvent) callback)

This function can be used to override default callback I2C1_ClientCallback and to define custom callback for I2C1 Client event.

Precondition:
none

Parameters:
in	address	- Address of the callback function

Returns:
none

I2C1_Deinitialize()

void I2C1_Deinitialize (void )

Deinitializes the I2C1 to POR values.

Parameters:
none

Returns:
none

I2C1_ErrorGet()

enum I2C_CLIENT_ERROR I2C1_ErrorGet (void )

Returns the error occurred during I2C1 Transmit or Receive.

Precondition:
none

Parameters:
none

Returns:
I2C_CLIENT_ERROR_BUS_COLLISION - I2C1 Bus Collision Error I2C_CLIENT_ERROR_WRITE_COLLISION - I2C1 Write Collision Error I2C_CLIENT_ERROR_RECEIVE_OVERFLOW - I2C1 Receive overflow I2C_CLIENT_ERROR_NONE - No Error

I2C1_Initialize()

void I2C1_Initialize (void )

Initializes the I2C1 module.

Parameters:
none

Returns:
none

I2C1_IsBusy()

bool I2C1_IsBusy (void )

Returns the bus availability status. The application can use the function to check if I2C1 module is busy before calling any of the data transfer functions. The library does not allow a data transfer operation if another transfer operation is already in progress.

Precondition:
none function to work.

Parameters:
none

Returns:
true - Busy false - Not Busy

I2C1_LastByteAckStatusGet()

enum I2C_CLIENT_ACK_STATUS I2C1_LastByteAckStatusGet (void )

Returns the ACK status sent by the I2C Host.

Precondition:
I2C1_Initialize() must be called for the associated function to work

Parameters:
none

Returns:
I2C_CLIENT_ACK_STATUS_RECEIVED_ACK - I2C1 Host is send ACK to client I2C_CLIENT_ACK_STATUS_RECEIVED_NACK - I2C1 Host is send NACK to client

I2C1_ReadByte()

uint8_t I2C1_ReadByte (void )

I2C1 Client reads data transmitted from Host.

Precondition:
none

Parameters:
none

Returns:
none

I2C1_TransferDirGet()

enum I2C_CLIENT_TRANSFER_DIR I2C1_TransferDirGet (void )

Returns the I2C1 Transfer direction status.

Precondition:
none

Parameters:
none

Returns:
I2C_CLIENT_TRANSFER_DIR_WRITE - I2C1 Host is writing to client I2C_CLIENT_TRANSFER_DIR_READ - I2C1 Host is reading from client

I2C1_WriteByte()

void I2C1_WriteByte (uint8_t wrByte)

I2C Client transmits data to Host.

Precondition:
none

Parameters:
in	wrByte	- I2C1 client write byte

Returns:
none

3.10.1.1.4 Enumeration Type Documentation

I2C_CLIENT_ACK_STATUS

enum I2C_CLIENT_ACK_STATUS

This Enum can be used in client application to know the ACK/NACK status sent from the host using I2Cx_LastByteAckStatusGet function e.g. I2C1_LastByteAckStatusGet.


I2C_CLIENT_ACK_STATUS_RECEIVED_ACK	ACK received by I2C Client
I2C_CLIENT_ACK_STATUS_RECEIVED_NACK	NACK received by I2C Client

I2C_CLIENT_ERROR

enum I2C_CLIENT_ERROR

This Enum can be used to know the Client Error type using I2Cx_ErrorGet e.g. I2C1_ErrorGet.


I2C_CLIENT_ERROR_NONE	I2C error none
I2C_CLIENT_ERROR_BUS_COLLISION	I2C Bus collision occurred
I2C_CLIENT_ERROR_WRITE_COLLISION	I2C Write collision occurred
I2C_CLIENT_ERROR_RECEIVE_OVERFLOW	I2C Receive overflow occurred

I2C_CLIENT_TRANSFER_DIR

enum I2C_CLIENT_TRANSFER_DIR

This Enum can be used in client application to know the data transfer direction sent from the host using I2Cx_TransferDirGet function e.g. I2C1_TransferDirGet.


I2C_CLIENT_TRANSFER_DIR_WRITE	I2C Host is writing to client
I2C_CLIENT_TRANSFER_DIR_READ	I2C Host is reading from client

I2C_CLIENT_TRANSFER_EVENT

enum I2C_CLIENT_TRANSFER_EVENT

This Enum can be used to know the Client status. This status information can be used in the callback handling.


I2C_CLIENT_TRANSFER_EVENT_NONE	I2C Bus Idle state
I2C_CLIENT_TRANSFER_EVENT_ADDR_MATCH	Address match event
I2C_CLIENT_TRANSFER_EVENT_RX_READY	Data sent by I2C Host is available
I2C_CLIENT_TRANSFER_EVENT_TX_READY	I2C client can respond to data read request from I2C Host
I2C_CLIENT_TRANSFER_EVENT_STOP_BIT_RECEIVED	I2C stop bit received
I2C_CLIENT_TRANSFER_EVENT_ERROR	I2C Bus error occurred

3.10.1.1.5 Variable Documentation

I2C1_Client

const struct I2C_CLIENT_INTERFACE I2C1_Client

Structure object of type I2C_CLIENT_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Client can be changed by the user in the I2C user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.10.2 Data Structure Documentation

3.10.2.1 I2C_CLIENT_INTERFACE Struct Reference

Structure containing the function pointers of I2C driver.

3.10.2.1.1 Detailed Description

Structure containing the function pointers of I2C driver.

#include <i2c_client_interface.h>

Data Fields

void(* Initialize )(void)

Pointer to I2Cx_Initialize e.g. I2C1_Initialize.
void(* Deinitialize )(void)

Pointer to I2Cx_Deinitialize e.g. I2C1_Deinitialize.
void(* WriteByte )(uint8_t wrByte)

Pointer to I2Cx_WriteByte e.g. I2C1_WriteByte.
uint8_t(* ReadByte )(void)

Pointer to I2Cx_ReadByte e.g. I2C1_ReadByte.
enum I2C_CLIENT_ERROR(* ErrorGet )(void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.
enum I2C_CLIENT_TRANSFER_DIR(* TransferDirGet )(void)

Pointer to I2Cx_TransferDirGet e.g. I2C1_TransferDirGet.
enum I2C_CLIENT_ACK_STATUS(* LastByteAckStatusGet )(void)

Pointer to I2Cx_LastByteAckStatusGet e.g. I2C1_LastByteAckStatusGet.
bool(* IsBusy )(void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.
void(* ClientCallbackRegister )(bool(*callback)(enum I2C_CLIENT_TRANSFER_EVENT clientEvent))

Pointer to I2Cx_CallbackRegister e.g. I2C1_CallbackRegister.
void(* Tasks )(void)

Pointer to I2Cx_Tasks e.g. I2C1_Tasks (Supported only in polling mode)

3.10.2.1.2 Field Documentation

The documentation for this struct was generated from the following file:

source/

i2c_client_interface.h

ClientCallbackRegister

void(* ClientCallbackRegister) (bool(*callback)(enum I2C_CLIENT_TRANSFER_EVENT clientEvent))

Pointer to I2Cx_CallbackRegister e.g. I2C1_CallbackRegister.

Deinitialize

void(* Deinitialize) (void)

Pointer to I2Cx_Deinitialize e.g. I2C1_Deinitialize.

ErrorGet

enum I2C_CLIENT_ERROR(* ErrorGet) (void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.

Initialize

void(* Initialize) (void)

Pointer to I2Cx_Initialize e.g. I2C1_Initialize.

IsBusy

bool(* IsBusy) (void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.

LastByteAckStatusGet

enum I2C_CLIENT_ACK_STATUS(* LastByteAckStatusGet) (void)

Pointer to I2Cx_LastByteAckStatusGet e.g. I2C1_LastByteAckStatusGet.

ReadByte

uint8_t(* ReadByte) (void)

Pointer to I2Cx_ReadByte e.g. I2C1_ReadByte.

Tasks

void(* Tasks) (void)

Pointer to I2Cx_Tasks e.g. I2C1_Tasks (Supported only in polling mode)

TransferDirGet

enum I2C_CLIENT_TRANSFER_DIR(* TransferDirGet) (void)

Pointer to I2Cx_TransferDirGet e.g. I2C1_TransferDirGet.

WriteByte

void(* WriteByte) (uint8_t wrByte)

Pointer to I2Cx_WriteByte e.g. I2C1_WriteByte.

3.10.3 File Documentation

3.10.3.1 source/i2c1.h File Reference

This is the generated driver header file for the I2C1 driver.

#include <stdint.h>
#include <stdbool.h>
#include <xc.h>
#include "i2c_client_types.h"
#include "i2c_client_interface.h"

3.10.3.1.1 Functions

void I2C1_Initialize (void)

Initializes the I2C1 module.
void I2C1_Deinitialize (void)

Deinitializes the I2C1 to POR values.
void I2C1_WriteByte (uint8_t wrByte)

I2C Client transmits data to Host.
uint8_t I2C1_ReadByte (void)

I2C1 Client reads data transmitted from Host.
enum I2C_CLIENT_ERROR I2C1_ErrorGet (void)

Returns the error occurred during I2C1 Transmit or Receive.
bool I2C1_IsBusy (void)

Returns the bus availability status. The application can use the function to check if I2C1 module is busy before calling any of the data transfer functions. The library does not allow a data transfer operation if another transfer operation is already in progress.
enum I2C_CLIENT_TRANSFER_DIR I2C1_TransferDirGet (void)

Returns the I2C1 Transfer direction status.
enum I2C_CLIENT_ACK_STATUS I2C1_LastByteAckStatusGet (void)

Returns the ACK status sent by the I2C Host.
void I2C1_CallbackRegister (bool(*callback)(enum I2C_CLIENT_TRANSFER_EVENT clientEvent))

This function can be used to override default callback I2C1_ClientCallback and to define custom callback for I2C1 Client event.
bool I2C1_Callback (enum I2C_CLIENT_TRANSFER_EVENT clientEvent)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using I2C1_CallbackRegister.

3.10.3.1.2 Macros

#define I2C1_Client_Initialize I2C1_Initialize

This macro defines the Custom Name for I2C1_Initialize API.
#define I2C1_Client_Deinitialize I2C1_Deinitialize

This macro defines the Custom Name for I2C1_Deinitialize API.
#define I2C1_Client_WriteByte I2C1_WriteByte

This macro defines the Custom Name for I2C1_WriteByte API.
#define I2C1_Client_ReadByte I2C1_ReadByte

This macro defines the Custom Name for I2C1_ReadByte API.
#define I2C1_Client_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.
#define I2C1_Client_IsBusy I2C1_IsBusy

This macro defines the Custom Name for I2C1_IsBusy API.
#define I2C1_Client_TransferDirGet I2C1_TransferDirGet

This macro defines the Custom Name for I2C1_TransferDirGet API.
#define I2C1_Client_LastByteAckStatusGet I2C1_LastByteAckStatusGet

This macro defines the Custom Name for I2C1_LastByteAckStatusGet API.
#define I2C1_Client_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

3.10.3.1.3 Variables

const struct I2C_CLIENT_INTERFACE I2C1_Client

Structure object of type I2C_CLIENT_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Client can be changed by the user in the I2C user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.10.3.1.4 Detailed Description

This is the generated driver header file for the I2C1 driver.

I2C1 Generated Driver Header File

3.10.3.2 source/i2c_client_interface.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include "i2c_client_types.h"

3.10.3.2.1 Data structures

struct I2C_CLIENT_INTERFACE

Structure containing the function pointers of I2C driver.

3.10.3.2.2 Detailed Description

I2C Generated Driver Interface Header File

3.10.3.3 source/i2c_client_types.h File Reference

This is the generated driver types header file for the I2C driver.

3.10.3.3.1 Enumerations

enum I2C_CLIENT_TRANSFER_DIR { I2C_CLIENT_TRANSFER_DIR_WRITE = 0, I2C_CLIENT_TRANSFER_DIR_READ = 1 }

This Enum can be used in client application to know the data transfer direction sent from the host using I2Cx_TransferDirGet function e.g. I2C1_TransferDirGet.
enum I2C_CLIENT_ACK_STATUS { I2C_CLIENT_ACK_STATUS_RECEIVED_ACK = 0, I2C_CLIENT_ACK_STATUS_RECEIVED_NACK = 1 }

This Enum can be used in client application to know the ACK/NACK status sent from the host using I2Cx_LastByteAckStatusGet function e.g. I2C1_LastByteAckStatusGet.
enum I2C_CLIENT_TRANSFER_EVENT { I2C_CLIENT_TRANSFER_EVENT_NONE, I2C_CLIENT_TRANSFER_EVENT_ADDR_MATCH, I2C_CLIENT_TRANSFER_EVENT_RX_READY, I2C_CLIENT_TRANSFER_EVENT_TX_READY, I2C_CLIENT_TRANSFER_EVENT_STOP_BIT_RECEIVED, I2C_CLIENT_TRANSFER_EVENT_ERROR }

This Enum can be used to know the Client status. This status information can be used in the callback handling.
enum I2C_CLIENT_ERROR { I2C_CLIENT_ERROR_NONE, I2C_CLIENT_ERROR_BUS_COLLISION, I2C_CLIENT_ERROR_WRITE_COLLISION, I2C_CLIENT_ERROR_RECEIVE_OVERFLOW }

This Enum can be used to know the Client Error type using I2Cx_ErrorGet e.g. I2C1_ErrorGet.

3.10.3.3.2 Detailed Description

This is the generated driver types header file for the I2C driver.

I2C Generated Driver Types Header File