3.11 I2C Host 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 Host Driver implements the I2C Host functionality of the I2C module.

Features

The driver is interrupt driven.
User can configure the module using the three standard Frequencies: 100KHz, 400KHz and 1MHz

3.11.1 Module Documentation

3.11.1.1 I2C Host Driver

I2C driver for Host Mode using dsPIC MCUs.

3.11.1.1.1 Module description

I2C driver for Host Mode using dsPIC MCUs.

Data structures

struct I2C_HOST_INTERFACE

Structure containing the function pointers of I2C driver.
struct I2C_TRANSFER_SETUP

I2C Clock Speed (100KHZ to 1MHZ)

Definitions

#define I2C1_CLOCK_FREQUENCY 4000000UL

This macro defines source clock frequency of I2C1.
#define I2C1_Host_Initialize I2C1_Initialize

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

This macro defines the Custom Name for I2C1_Deinitialize API.
#define I2C1_Host_Write I2C1_Write

This macro defines the Custom Name for I2C1_Write API.
#define I2C1_Host_Read I2C1_Read

This macro defines the Custom Name for I2C1_Read API.
#define I2C1_Host_WriteRead I2C1_WriteRead

This macro defines the Custom Name for I2C1_WriteRead API.
#define I2C1_Host_TransferSetup I2C1_TransferSetup

This macro defines the Custom Name for I2C1_TransferSetup API.
#define I2C1_Host_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.
#define I2C1_Host_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

Enumerations

enum I2C_HOST_ERROR { I2C_HOST_ERROR_NONE, I2C_HOST_ERROR_NACK, I2C_HOST_ERROR_BUS_COLLISION }

This Enum can be used to know the Host Error Status. Refer 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.
bool I2C1_Write (uint16_t address, uint8_t *data, size_t dataLength)

Writes the data to a Client on the bus. The function will attempt to write length number of bytes from data buffer to a Client whose address is specified by address. The I2C Host will generate a Start condition, write the data and then generate a Stop Condition. If the Client NACK the request or a bus error was encountered on the bus, the transfer is terminated. The application can call the I2C1_ErrorGet() function to know that cause of the error.
bool I2C1_Read (uint16_t address, uint8_t *data, size_t dataLength)

Reads the data from a Client on the bus. The function will attempt to read length number of bytes into data buffer from a Client whose address is specified as address. The I2C Host generate a Start condition, read the data and then generate a Stop Condition. If the Client NAKs the request or a bus error is encountered on the bus, the transfer is terminated. The application can call I2C1_ErrorGet() function to know that cause of the error.
bool I2C1_WriteRead (uint16_t address, uint8_t *writeData, size_t writeLength, uint8_t *readData, size_t readLength)

Writes data from the writeData to the bus and then reads data from the Client and stores the received in the readData. The function generate a Start condition on the bus and will then send writeLength number of bytes contained in writeData. The function will then insert a Repeated start condition and proceed to read readLength number of bytes from the client. The received bytes are stored in readData buffer. A Stop condition is generated after the last byte has been received.
bool I2C1_TransferSetup (struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

This function dynamically setup the I2C clock speed (100KHZ to 1MHZ)
enum I2C_HOST_ERROR I2C1_ErrorGet (void)

Returns the error occurred during I2C Transmit and Receive.
bool I2C1_IsBusy (void)

This function true if the I2C module is busy with a transfer. The application can use the function to check if I2C 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.
void I2C1_CallbackRegister (void(*callback)(void))

This function can be used to overrides default callback I2C1_ClientCallback and to define custom callback for I2C1 Client event.
void I2C1_Callback (void)

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_HOST_INTERFACE I2C1_Host

Structure object of type I2C_HOST_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Host 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.11.1.1.2 Definition Documentation

I2C1_CLOCK_FREQUENCY

#define I2C1_CLOCK_FREQUENCY 4000000UL

This macro defines source clock frequency of I2C1.

I2C1_Host_CallbackRegister

#define I2C1_Host_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

I2C1_Host_Deinitialize

#define I2C1_Host_Deinitialize I2C1_Deinitialize

This macro defines the Custom Name for I2C1_Deinitialize API.

I2C1_Host_ErrorGet

#define I2C1_Host_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.

I2C1_Host_Initialize

#define I2C1_Host_Initialize I2C1_Initialize

This macro defines the Custom Name for I2C1_Initialize API.

I2C1_Host_Read

#define I2C1_Host_Read I2C1_Read

This macro defines the Custom Name for I2C1_Read API.

I2C1_Host_TransferSetup

#define I2C1_Host_TransferSetup I2C1_TransferSetup

This macro defines the Custom Name for I2C1_TransferSetup API.

I2C1_Host_Write

#define I2C1_Host_Write I2C1_Write

This macro defines the Custom Name for I2C1_Write API.

I2C1_Host_WriteRead

#define I2C1_Host_WriteRead I2C1_WriteRead

This macro defines the Custom Name for I2C1_WriteRead API.

3.11.1.1.3 Function Documentation

I2C1_Callback()

void I2C1_Callback (void )

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:
none

Returns:
none

I2C1_CallbackRegister()

void I2C1_CallbackRegister (void(*)(void) callback)

This function can be used to overrides 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_HOST_ERROR I2C1_ErrorGet (void )

Returns the error occurred during I2C Transmit and Receive.

Precondition:
none

Parameters:
none

Returns:
I2C_HOST_ERROR_NONE - No Error I2C_HOST_ERROR_NACK - Client returned NACK I2C_HOST_ERROR_BUS_COLLISION - Bus Collision Error

I2C1_Initialize()

void I2C1_Initialize (void )

Initializes the I2C1 module.

Parameters:
none

Returns:
none

I2C1_IsBusy()

bool I2C1_IsBusy (void )

This function true if the I2C module is busy with a transfer. The application can use the function to check if I2C 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

Parameters:
none

Returns:
true - Busy false - Not Busy

I2C1_Read()

bool I2C1_Read (uint16_t address, uint8_t * data, size_t dataLength)

Reads the data from a Client on the bus. The function will attempt to read length number of bytes into data buffer from a Client whose address is specified as address. The I2C Host generate a Start condition, read the data and then generate a Stop Condition. If the Client NAKs the request or a bus error is encountered on the bus, the transfer is terminated. The application can call I2C1_ErrorGet() function to know that cause of the error.

The function is non-blocking. It initiates bus activity and returns immediately. The transfer is completed in the peripheral interrupt. A transfer request cannot be placed when another transfer is in progress. Calling the read function when another function is already in progress will cause the function to return false.

Precondition:
none function to work.

Parameters:
in	address	- 7-bit / 10-bit Client address
out	data	- pointer to source data buffer that contains the data to be transmitted.
in	dataLength	- length of data buffer in number of bytes. Also the number of bytes to be written.

Returns:
true - The request was placed successfully and the bus activity was initiated. false - The request fails,if there was already a transfer in progress when this function was called.

I2C1_TransferSetup()

bool I2C1_TransferSetup (struct I2C_TRANSFER_SETUP * setup, uint32_t srcClkFreq)

This function dynamically setup the I2C clock speed (100KHZ to 1MHZ)

Precondition:
none

Parameters:
in	setup	- Pointer to the structure containing the transfer setup
in	srcClkFreq	- I2C Peripheral Clock Source Frequency(FCY = FOSC/2)

Returns:
true - Transfer setup was updated Successfully false - Failure while updating transfer setup

I2C1_Write()

bool I2C1_Write (uint16_t address, uint8_t * data, size_t dataLength)

Writes the data to a Client on the bus. The function will attempt to write length number of bytes from data buffer to a Client whose address is specified by address. The I2C Host will generate a Start condition, write the data and then generate a Stop Condition. If the Client NACK the request or a bus error was encountered on the bus, the transfer is terminated. The application can call the I2C1_ErrorGet() function to know that cause of the error.

The function is non-blocking. It initiates bus activity and returns immediately. The transfer is then completed in the peripheral interrupt. A transfer request cannot be placed when another transfer is in progress. Calling the write function when another function is already in progress will cause the function to return false.

Precondition:
none

Parameters:
in	address	- 7-bit / 10-bit Client address
in	data	- pointer to source data buffer that contains the data to be transmitted.
in	dataLength	- length of data buffer in number of bytes. Also the number of bytes to be written.

Returns:
true - The request was placed successfully and the bus activity was initiated. false - The request fails,if there was already a transfer in progress when this function was called.

I2C1_WriteRead()

bool I2C1_WriteRead (uint16_t address, uint8_t * writeData, size_t writeLength, uint8_t * readData, size_t readLength)

Writes data from the writeData to the bus and then reads data from the Client and stores the received in the readData. The function generate a Start condition on the bus and will then send writeLength number of bytes contained in writeData. The function will then insert a Repeated start condition and proceed to read readLength number of bytes from the client. The received bytes are stored in readData buffer. A Stop condition is generated after the last byte has been received.

If the Client NAKs the request or a bus error was encountered on the bus, the transfer is terminated. The application can call I2C1_ErrorGet() function to know thatcause of the error.

The function is non-blocking. It initiates bus activity and returns immediately. The transfer is then completed in the peripheral interrupt. A transfer request cannot be placed when another transfer is in progress. Calling this function when another function is already in progress will cause the function to return false.

Precondition:
none

Parameters:
in	address	- 7-bit / 10-bit Client address
in	writeData	- pointer to write data buffer
in	writeLength	- write data length in bytes
out	readData	- pointer to read data buffer
in	readLength	- read data length in bytes

Returns:
true - The request was placed successfully and the bus activity was initiated. false - The request fails,if there was already a transfer in progress when this function was called.

3.11.1.1.4 Enumeration Type Documentation

I2C_HOST_ERROR

enum I2C_HOST_ERROR

This Enum can be used to know the Host Error Status. Refer I2Cx_ErrorGet e.g. I2C1_ErrorGet.


I2C_HOST_ERROR_NONE	No Error
I2C_HOST_ERROR_NACK	Client returned NACK
I2C_HOST_ERROR_BUS_COLLISION	Bus Collision Error

3.11.1.1.5 Variable Documentation

I2C1_Host

const struct I2C_HOST_INTERFACE I2C1_Host

Structure object of type I2C_HOST_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Host 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.11.2 Data Structure Documentation

3.11.2.1 I2C_HOST_INTERFACE Struct Reference

Structure containing the function pointers of I2C driver.

3.11.2.1.1 Detailed Description

Structure containing the function pointers of I2C driver.

#include <i2c_host_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.
bool(* Write )(uint16_t address, uint8_t *data, size_t dataLength)

Pointer to I2Cx_Write e.g. I2C1_Write.
bool(* Read )(uint16_t address, uint8_t *data, size_t dataLength)

Pointer to I2Cx_Read e.g. I2C1_Read.
bool(* WriteRead )(uint16_t address, uint8_t *writeData, size_t writeLength, uint8_t *readData, size_t readLength)

Pointer to I2Cx_WriteRead e.g. I2C1_WriteRead.
bool(* TransferSetup )(struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

Pointer to I2Cx_TransferSetup e.g. I2C1_TransferSetup.
enum I2C_HOST_ERROR(* ErrorGet )(void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.
bool(* IsBusy )(void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.
void(* HostCallbackRegister )(void(*handler)(void))

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.11.2.1.2 Field Documentation

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

source/

i2c_host_interface.h

Deinitialize

void(* Deinitialize) (void)

Pointer to I2Cx_Deinitialize e.g. I2C1_Deinitialize.

ErrorGet

enum I2C_HOST_ERROR(* ErrorGet) (void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.

HostCallbackRegister

void(* HostCallbackRegister) (void(*handler)(void))

Pointer to I2Cx_CallbackRegister e.g. I2C1_CallbackRegister.

Initialize

void(* Initialize) (void)

Pointer to I2Cx_Initialize e.g. I2C1_Initialize.

IsBusy

bool(* IsBusy) (void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.

Read

bool(* Read) (uint16_t address, uint8_t *data, size_t dataLength)

Pointer to I2Cx_Read e.g. I2C1_Read.

Tasks

void(* Tasks) (void)

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

TransferSetup

bool(* TransferSetup) (struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

Pointer to I2Cx_TransferSetup e.g. I2C1_TransferSetup.

Write

bool(* Write) (uint16_t address, uint8_t *data, size_t dataLength)

Pointer to I2Cx_Write e.g. I2C1_Write.

WriteRead

bool(* WriteRead) (uint16_t address, uint8_t *writeData, size_t writeLength, uint8_t *readData, size_t readLength)

Pointer to I2Cx_WriteRead e.g. I2C1_WriteRead.

3.11.2.2 I2C_TRANSFER_SETUP Struct Reference

I2C Clock Speed (100KHZ to 1MHZ)

3.11.2.2.1 Detailed Description

I2C Clock Speed (100KHZ to 1MHZ)

#include <i2c_host_types.h>

Data Fields

uint32_t clkSpeed

I2C Clock Speed.

3.11.2.2.2 Field Documentation

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

source/

i2c_host_types.h

clkSpeed

uint32_t clkSpeed

I2C Clock Speed.

3.11.3 File Documentation

3.11.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 <stddef.h>
#include "i2c_host_types.h"
#include "i2c_host_interface.h"

3.11.3.1.1 Functions

void I2C1_Initialize (void)

Initializes the I2C1 module.
void I2C1_Deinitialize (void)

Deinitializes the I2C1 to POR values.
bool I2C1_Write (uint16_t address, uint8_t *data, size_t dataLength)

Writes the data to a Client on the bus. The function will attempt to write length number of bytes from data buffer to a Client whose address is specified by address. The I2C Host will generate a Start condition, write the data and then generate a Stop Condition. If the Client NACK the request or a bus error was encountered on the bus, the transfer is terminated. The application can call the I2C1_ErrorGet() function to know that cause of the error.
bool I2C1_Read (uint16_t address, uint8_t *data, size_t dataLength)

Reads the data from a Client on the bus. The function will attempt to read length number of bytes into data buffer from a Client whose address is specified as address. The I2C Host generate a Start condition, read the data and then generate a Stop Condition. If the Client NAKs the request or a bus error is encountered on the bus, the transfer is terminated. The application can call I2C1_ErrorGet() function to know that cause of the error.
bool I2C1_WriteRead (uint16_t address, uint8_t *writeData, size_t writeLength, uint8_t *readData, size_t readLength)

Writes data from the writeData to the bus and then reads data from the Client and stores the received in the readData. The function generate a Start condition on the bus and will then send writeLength number of bytes contained in writeData. The function will then insert a Repeated start condition and proceed to read readLength number of bytes from the client. The received bytes are stored in readData buffer. A Stop condition is generated after the last byte has been received.
bool I2C1_TransferSetup (struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

This function dynamically setup the I2C clock speed (100KHZ to 1MHZ)
enum I2C_HOST_ERROR I2C1_ErrorGet (void)

Returns the error occurred during I2C Transmit and Receive.
bool I2C1_IsBusy (void)

This function true if the I2C module is busy with a transfer. The application can use the function to check if I2C 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.
void I2C1_CallbackRegister (void(*callback)(void))

This function can be used to overrides default callback I2C1_ClientCallback and to define custom callback for I2C1 Client event.
void I2C1_Callback (void)

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.11.3.1.2 Macros

#define I2C1_CLOCK_FREQUENCY 4000000UL

This macro defines source clock frequency of I2C1.
#define I2C1_Host_Initialize I2C1_Initialize

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

This macro defines the Custom Name for I2C1_Deinitialize API.
#define I2C1_Host_Write I2C1_Write

This macro defines the Custom Name for I2C1_Write API.
#define I2C1_Host_Read I2C1_Read

This macro defines the Custom Name for I2C1_Read API.
#define I2C1_Host_WriteRead I2C1_WriteRead

This macro defines the Custom Name for I2C1_WriteRead API.
#define I2C1_Host_TransferSetup I2C1_TransferSetup

This macro defines the Custom Name for I2C1_TransferSetup API.
#define I2C1_Host_ErrorGet I2C1_ErrorGet

This macro defines the Custom Name for I2C1_ErrorGet API.
#define I2C1_Host_CallbackRegister I2C1_CallbackRegister

This macro defines the Custom Name for I2C1_CallbackRegister API.

3.11.3.1.3 Variables

const struct I2C_HOST_INTERFACE I2C1_Host

Structure object of type I2C_HOST_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. I2C1_Host 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.11.3.1.4 Detailed Description

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

I2C1 Generated Driver Header File

3.11.3.2 source/i2c_host_interface.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "i2c_host_types.h"

3.11.3.2.1 Data structures

struct I2C_HOST_INTERFACE

Structure containing the function pointers of I2C driver.

3.11.3.2.2 Detailed Description

I2C Generated Driver Interface Header File

3.11.3.3 source/i2c_host_types.h File Reference

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

#include <stdint.h>

3.11.3.3.1 Data structures

struct I2C_TRANSFER_SETUP

I2C Clock Speed (100KHZ to 1MHZ)

3.11.3.3.2 Enumerations

enum I2C_HOST_ERROR { I2C_HOST_ERROR_NONE, I2C_HOST_ERROR_NACK, I2C_HOST_ERROR_BUS_COLLISION }

This Enum can be used to know the Host Error Status. Refer I2Cx_ErrorGet e.g. I2C1_ErrorGet.

3.11.3.3.3 Detailed Description

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

I2C Generated Driver Types Header File