2.13 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

2.13.1 Module Documentation

2.13.1.1 I2C Host Driver

I2C driver for Host Mode using dsPIC MCUs.

2.13.1.1.1 Module description

I2C driver for Host Mode using dsPIC MCUs.

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.1.1.2 Function Documentation

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

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

I2C2_Deinitialize()

void I2C2_Deinitialize (void )

Deinitializes the I2C2 to POR values.

Parameters:
none
Returns:

none

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

I2C2_Initialize()

void I2C2_Initialize (void )

Initializes the I2C2 module.

Parameters:
none
Returns:

none

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

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.

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

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.

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

2.13.1.1.4 Variable Documentation

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.2 Class Documentation

2.13.2.1 I2C_HOST_INTERFACE Struct Reference

Structure containing the function pointers of I2C driver.

2.13.2.1.1 Detailed Description

Structure containing the function pointers of I2C driver.

#include <i2c_host_interface.h>

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.2.1.2 Member Data 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.

2.13.2.2 I2C_TRANSFER_SETUP Struct Reference

I2C Clock Speed (100KHZ to 1MHZ)

2.13.2.2.1 Detailed Description

I2C Clock Speed (100KHZ to 1MHZ)

#include <i2c_host_types.h>

Public Attributes

2.13.2.2.2 Member Data Documentation

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

source/

i2c_host_types.h

clkSpeed

uint32_t clkSpeed

I2C Clock Speed.

2.13.3 File Documentation

2.13.3.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.3.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.3.1.3 Detailed Description

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

I2C2 Generated Driver Header File

2.13.3.2 source/i2c_host_interface.h File Reference

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

2.13.3.2.1 Data structures

2.13.3.2.2 Detailed Description

I2C Generated Driver Interface Header File

2.13.3.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.3.3.3 Detailed Description

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

I2C Generated Driver Types Header File