2.12 I2C Client Driver

2.12.1 Introduction

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.

2.12.2 Module Documentation

2.12.2.1 I2C Client Driver

I2C Driver for Client Mode using dsPIC MCUs.

2.12.2.1.1 Module description

I2C Driver for Client Mode using dsPIC MCUs.

2.12.2.1.1.1 Data structures

struct I2C_CLIENT_INTERFACE

Structure containing the function pointers of I2C driver.

2.12.2.1.1.2 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.

2.12.2.1.1.3 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.
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.

2.12.2.1.1.4 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.

2.12.2.1.2 Function Documentation

2.12.2.1.2.1 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:
I2C1_Initialize() must be called for the associated function to work

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

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

2.12.2.1.2.2 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:
I2C1_Initialize() must be called for the associated function to work

Parameters:
	none
in	address	- Address of the callback function

Returns:
none

2.12.2.1.2.3 I2C1_Deinitialize()

void I2C1_Deinitialize (void )

Deinitializes the I2C1 to POR values.

Parameters:
none

Returns:
none

2.12.2.1.2.4 I2C1_ErrorGet()

enum I2C_CLIENT_ERROR I2C1_ErrorGet (void )

Returns the error occurred during I2C1 Transmit or Receive.

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

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

2.12.2.1.2.5 I2C1_Initialize()

void I2C1_Initialize (void )

Initializes the I2C1 module.

Returns:

2.12.2.1.2.6 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:
I2C1_Initialize() must be called for the associated function to work.

Parameters:
none

Returns:
true - Busy false - Not Busy

2.12.2.1.2.7 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

2.12.2.1.2.8 I2C1_ReadByte()

uint8_t I2C1_ReadByte (void )

I2C1 Client reads data transmitted from Host.

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

Parameters:
none

Returns:
none

2.12.2.1.2.9 I2C1_TransferDirGet()

enum I2C_CLIENT_TRANSFER_DIR I2C1_TransferDirGet (void )

Returns the I2C1 Transfer direction status.

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

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

2.12.2.1.2.10 I2C1_WriteByte()

void I2C1_WriteByte (uint8_t wrByte)

I2C Client transmits data to Host.

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

Parameters:
in	wrByte	- I2C1 client write byte

Returns:
none

2.12.2.1.3 Enumeration Type Documentation

2.12.2.1.3.1 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

2.12.2.1.3.2 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

2.12.2.1.3.3 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

2.12.2.1.3.4 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

2.12.2.1.4 Variable Documentation

2.12.2.1.4.1 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.

2.12.3 Class Documentation

2.12.3.1 I2C_CLIENT_INTERFACE Struct Reference

Structure containing the function pointers of I2C driver.

2.12.3.1.1 Detailed Description

Structure containing the function pointers of I2C driver.

#include <i2c_client_interface.h>

2.12.3.1.1.1 Public Attributes

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)

2.12.3.1.2 Member Data Documentation

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

source/

i2c_client_interface.h

2.12.3.1.2.1 ClientCallbackRegister

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

Pointer to I2Cx_CallbackRegister e.g. I2C1_CallbackRegister.

2.12.3.1.2.2 Deinitialize

void(* Deinitialize) (void)

Pointer to I2Cx_Deinitialize e.g. I2C1_Deinitialize.

2.12.3.1.2.3 ErrorGet

enum I2C_CLIENT_ERROR(* ErrorGet) (void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.

2.12.3.1.2.4 Initialize

void(* Initialize) (void)

Pointer to I2Cx_Initialize e.g. I2C1_Initialize.

2.12.3.1.2.5 IsBusy

bool(* IsBusy) (void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.

2.12.3.1.2.6 LastByteAckStatusGet

enum I2C_CLIENT_ACK_STATUS(* LastByteAckStatusGet) (void)

Pointer to I2Cx_LastByteAckStatusGet e.g. I2C1_LastByteAckStatusGet.

2.12.3.1.2.7 ReadByte

uint8_t(* ReadByte) (void)

Pointer to I2Cx_ReadByte e.g. I2C1_ReadByte.

2.12.3.1.2.8 Tasks

void(* Tasks) (void)

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

2.12.3.1.2.9 TransferDirGet

enum I2C_CLIENT_TRANSFER_DIR(* TransferDirGet) (void)

Pointer to I2Cx_TransferDirGet e.g. I2C1_TransferDirGet.

2.12.3.1.2.10 WriteByte

void(* WriteByte) (uint8_t wrByte)

Pointer to I2Cx_WriteByte e.g. I2C1_WriteByte.

2.12.4 File Documentation

2.12.4.1 source/i2c1.h File Reference

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

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

2.12.4.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.
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.

2.12.4.1.2 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.

2.12.4.1.3 Detailed Description

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

I2C1 Generated Driver Header File

2.12.4.2 source/i2c_client_interface.h File Reference

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

2.12.4.2.1 Data structures

struct I2C_CLIENT_INTERFACE

Structure containing the function pointers of I2C driver.

2.12.4.2.2 Detailed Description

I2C Generated Driver Interface Header File

2.12.4.3 source/i2c_client_types.h File Reference

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

2.12.4.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.

2.12.4.3.2 Detailed Description

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

I2C Generated Driver Types Header File