2.13 I2C Host Driver

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

2.13.2 Module Documentation

2.13.2.1 I2C Host Driver

I2C driver for Host Mode using dsPIC MCUs.

2.13.2.1.1 Module description

I2C driver for Host Mode using dsPIC MCUs.

2.13.2.1.1.1 Data structures

struct I2C_HOST_INTERFACE

Structure containing the function pointers of I2C driver.
struct I2C_TRANSFER_SETUP

I2C Clock Speed (100KHZ to 1MHZ)

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

2.13.2.1.1.3 Functions

void I2C2_Initialize (void)

Initializes the I2C2 module.
void I2C2_Deinitialize (void)

Deinitializes the I2C2 to POR values.
bool I2C2_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.
bool I2C2_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.
bool I2C2_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.
bool I2C2_TransferSetup (struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

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

Returns the error occurred during I2C Transmit and Receive.
bool I2C2_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 I2C2_CallbackRegister (void(*callback)(void))

This function can be used to overrides default callback I2C2_HostCallback and to define custom callback for I2C2 Host event.
void I2C2_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 I2C2_CallbackRegister.

2.13.2.1.1.4 Variables

const struct I2C_HOST_INTERFACE I2C2_Host

Structure object of type I2C_HOST_INTERFACE with the custom name given by the user in the Melody Driver User interface.

2.13.2.1.2 Function Documentation

2.13.2.1.2.1 I2C2_Callback()

void I2C2_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 I2C2_CallbackRegister.

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

Parameters:
none

Returns:
none

2.13.2.1.2.2 I2C2_CallbackRegister()

void I2C2_CallbackRegister (void(*)(void) callback)

This function can be used to overrides default callback I2C2_HostCallback and to define custom callback for I2C2 Host event.

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

Parameters:
in	address	- Address of the callback function

Returns:
none

2.13.2.1.2.3 I2C2_Deinitialize()

void I2C2_Deinitialize (void )

Deinitializes the I2C2 to POR values.

Parameters:
none

Returns:
none

2.13.2.1.2.4 I2C2_ErrorGet()

enum I2C_HOST_ERROR I2C2_ErrorGet (void )

Returns the error occurred during I2C Transmit and Receive.

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

Parameters:
none

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

2.13.2.1.2.5 I2C2_Initialize()

void I2C2_Initialize (void )

Initializes the I2C2 module.

Parameters:
none

Returns:
none

2.13.2.1.2.6 I2C2_IsBusy()

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

Parameters:
none

Returns:
true - Busy false - Not Busy

2.13.2.1.2.7 I2C2_Read()

bool I2C2_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 I2C2_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:
I2C2_Initialize() must be called for the associated 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.

2.13.2.1.2.8 I2C2_TransferSetup()

bool I2C2_TransferSetup (struct I2C_TRANSFER_SETUP * setup, uint32_t srcClkFreq)

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

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

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

2.13.2.1.2.9 I2C2_Write()

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

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.

2.13.2.1.2.10 I2C2_WriteRead()

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

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.

2.13.2.1.3 Enumeration Type Documentation

2.13.2.1.3.1 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

2.13.2.1.4 Variable Documentation

2.13.2.1.4.1 I2C2_Host

const struct I2C_HOST_INTERFACE I2C2_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.

2.13.3 Class Documentation

2.13.3.1 I2C_HOST_INTERFACE Struct Reference

Structure containing the function pointers of I2C driver.

2.13.3.1.1 Detailed Description

Structure containing the function pointers of I2C driver.

#include <i2c_host_interface.h>

2.13.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.
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)

2.13.3.1.2 Member Data Documentation

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

source/

i2c_host_interface.h

2.13.3.1.2.1 Deinitialize

void(* Deinitialize) (void)

Pointer to I2Cx_Deinitialize e.g. I2C1_Deinitialize.

2.13.3.1.2.2 ErrorGet

enum I2C_HOST_ERROR(* ErrorGet) (void)

Pointer to I2Cx_ErrorGet e.g. I2C1_ErrorGet.

2.13.3.1.2.3 HostCallbackRegister

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

Pointer to I2Cx_CallbackRegister e.g. I2C1_CallbackRegister.

2.13.3.1.2.4 Initialize

void(* Initialize) (void)

Pointer to I2Cx_Initialize e.g. I2C1_Initialize.

2.13.3.1.2.5 IsBusy

bool(* IsBusy) (void)

Pointer to I2Cx_IsBusy e.g. I2C1_IsBusy.

2.13.3.1.2.6 Read

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

Pointer to I2Cx_Read e.g. I2C1_Read.

2.13.3.1.2.7 Tasks

void(* Tasks) (void)

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

2.13.3.1.2.8 TransferSetup

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

Pointer to I2Cx_TransferSetup e.g. I2C1_TransferSetup.

2.13.3.1.2.9 Write

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

Pointer to I2Cx_Write e.g. I2C1_Write.

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

2.13.3.2 I2C_TRANSFER_SETUP Struct Reference

I2C Clock Speed (100KHZ to 1MHZ)

2.13.3.2.1 Detailed Description

I2C Clock Speed (100KHZ to 1MHZ)

#include <i2c_host_types.h>

2.13.3.2.1.1 Public Attributes

uint32_t clkSpeed

I2C Clock Speed.

2.13.3.2.2 Member Data Documentation

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

source/

i2c_host_types.h

2.13.3.2.2.1 clkSpeed

uint32_t clkSpeed

I2C Clock Speed.

2.13.4 File Documentation

2.13.4.1 source/i2c2.h File Reference

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

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

2.13.4.1.1 Functions

void I2C2_Initialize (void)

Initializes the I2C2 module.
void I2C2_Deinitialize (void)

Deinitializes the I2C2 to POR values.
bool I2C2_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.
bool I2C2_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.
bool I2C2_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.
bool I2C2_TransferSetup (struct I2C_TRANSFER_SETUP *setup, uint32_t srcClkFreq)

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

Returns the error occurred during I2C Transmit and Receive.
bool I2C2_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 I2C2_CallbackRegister (void(*callback)(void))

This function can be used to overrides default callback I2C2_HostCallback and to define custom callback for I2C2 Host event.
void I2C2_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 I2C2_CallbackRegister.

2.13.4.1.2 Variables

const struct I2C_HOST_INTERFACE I2C2_Host

Structure object of type I2C_HOST_INTERFACE with the custom name given by the user in the Melody Driver User interface.

2.13.4.1.3 Detailed Description

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

I2C2 Generated Driver Header File

2.13.4.2 source/i2c_host_interface.h File Reference

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

2.13.4.2.1 Data structures

struct I2C_HOST_INTERFACE

Structure containing the function pointers of I2C driver.

2.13.4.2.2 Detailed Description

I2C Generated Driver Interface Header File

2.13.4.3 source/i2c_host_types.h File Reference

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

#include <stdint.h>

2.13.4.3.1 Data structures

struct I2C_TRANSFER_SETUP

I2C Clock Speed (100KHZ to 1MHZ)

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

2.13.4.3.3 Detailed Description

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

I2C Generated Driver Types Header File