Detailed Description

I2CTarget driver interface.

To use the I2CTarget driver, ensure that the correct driver library for your device is linked in and include this header file as follows:

#include <ti/drivers/I2CTarget.h>

Overview

The I2CTarget driver operates the I2C peripheral as a target on an I2C bus. The I2CTarget driver is event driven. When an I2CTarget_Event occurs, the I2CTarget driver will call a user-specified callback function (from HWI context). It is the user-specified callback's responsibility to process the I2CTarget_Event events, and to manipulate and interperet the data.

Usage

This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.

Synopsis

// Import the I2CTarget driver definitions
#include <ti/drivers/I2CTarget.h>
// Define own I2C bus address
#define OWN_ADDRESS     42
// Initialize I2CTarget driver
I2CTarget_init();
// Initialize I2CTarget parameters
I2CTarget_Params params;
I2CTarget_Params_init(&params);
params.eventCallbackFxn = myEventCallbackFunction;
params.targetAddress = OWN_ADDRESS;
// Open the I2CTarget driver
I2CTarget_Handle i2c;
i2c = I2CTarget_open(CONFIG_I2CTARGET_0, &params);
if (i2C == NULL) {
    // Error opening I2CTarget
    while (1) {}
}
// Start I2C Target operation. The driver will send
// events to the user-specified event callback function
I2CTarget_start(i2c);
// Transmitting and receiving bytes is handled by the
// user-specified callback function. It is up to the user
// to implement the appropriate state machine for its I2C
// protocol.
// Stop operation. The I2CTarget driver will no longer trigger
// events and the device can enter low-power modes.
I2CTarget_stop(i2c);
// Close the I2CTarget driver
I2CTarget_close(i2c);

Examples

Opening the I2CTarget Driver

Opening a I2CTarget requires four steps:

Create and initialize a I2CTarget_Params structure.
Fill in the desired parameters.
Call I2CTarget_open(), passing the index of the I2C in the I2CTarget_config structure, and the address of the I2CTarget_Params structure. The I2C peripheral instance is specified by the index in the I2CTarget_config structure.
Check that the I2CTarget handle returned by I2CTarget_open() is non-NULL, and save it. The handle will be used to start and stop I2C Target operation of the I2C instance you just opened.

I2CTarget_Handle i2c;
I2CTarget_Params params;
params.eventCallbackFxn = myEventCallbackFunction;
params.targetAddress = 42;
i2c = I2CTarget_open(CONFIG_I2CTARGET_0, NULL);
if (i2c == NULL) {
    // Error opening I2CTarget
    while (1) {}
}

Only one I2CTarget index can be used at a time; calling I2CTarget_open() a second time with the same index previosly passed to I2CTarget_open() will result in an error. You can, though, re-use the index if the instance is closed via I2CTarget_close(). In the previous example code, CONFIG_I2CTARGET_0 is passed to I2CTarget_open(). This macro is defined in the example's ti_drivers_config.h file.

Start/Stop I2C Operation

The I2CTarget driver will start operation when calling I2CTarget_start(). It is the application's responsibility to process all incoming I2CTarget_Event events in the I2CTarget_Params::eventCallbackFxn and implement the necessary state machine for the I2C protocol used.

I2CTarget_start(i2cTargetHandle);

The I2CTarget driver operation is stopped by calling I2CTarget_stop().

I2CTarget_stop(i2cTargetHandle);

Transferring data

This example shows a simplified example on how to transmit and receive data.

 // No command input
 #define NO_COMMAND          0x00
 // Define command to reset value of txData
 #define CMD_RESET_TXDATA    0x55
 // Variable storing data to transmit
 volatile uint8_t txData = 0;
 // Variable storing command received from an I2C controller
 volatile uint8_t command = 0;
 // User callback function
 int_fast16_t targetCallbackFxn(I2CTarget_Handle handle, I2CTarget_Event event, uint8_t *val) {
     if (event == I2CTarget_Event_WRITE_REQUESTED)
     {
         // Early event (before data is received) that the controller wants
         //  to write a byte to us (target-receiver).
         // This event may be used to set up receive buffers, or other
         // preparations.
     }
     if (event == I2CTarget_Event_WRITE_RECEIVED) {
         // Controller has written a byte to the target (target-receiver)
         command = *data;
         // Tell driver data has been read
         return I2CTarget_STATUS_SUCCESS;
     }
     if (event  == I2CTarget_Event_READ_REQUESTED || event == I2CTarget_Event_READ_PROCESSED) {
         // Controller wants to read from target (target-transmitter)
         *data = txData++;
         // Tell driver that data has been provided.
         return I2CTarget_STATUS_SUCCESS;
         // If the user callback does not have data, return
         // I2CTarget_STATUS_ERROR and the I2CTarget driver will
         // NACK the request (if supported by the device-specific driver implementation).
     }
     if (event == I2CTarget_Event_STOP) {
         // Stop condition received. Here we could, for example, reset
         // our I2C protocol state machine.
     }
     // Return success by default
     return I2CTarget_STATUS_SUCCESS;
}
 // Main thread
 void *mainThread(void *arg0) {
     // Call driver init functions
     I2CTarget_init();
     // Open I2CTarget driver
     I2CTarget_Params params;
     I2CTarget_Params_init(&params);
     params.eventCallbackFxn = targetCallbackFxn;
     params.targetAddress = 42;
     I2CTarget_Handle handle = I2CTarget_open(CONFIG_I2CTARGET_0, &params);
     if (handle == NULL) {
         // Error
         while (1) {}
     }
     // Start operation
     I2CTarget_start(handle);
     // Data transfers happens in targetCallbackFxn
     while (1) {
         if (command == CMD_RESET_TXDATA) {
             command = NO_COMMAND;
            txData = 0;
         }
     }
 }

Configuration

Refer to the Driver's Configuration section for driver configuration information.

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	I2CTarget_Params
	I2CTarget Parameters. More...

struct	I2CTarget_Config_
	I2CTarget Global configuration. More...

Macros
#define	I2CTarget_STATUS_SUCCESS (0)
	Successful status code returned by application event callback function. More...

#define	I2CTarget_STATUS_ERROR (-1)
	Generic error status code returned by application event callback function. More...

Typedefs
typedef struct I2CTarget_Config_ *	I2CTarget_Handle
	A handle that is returned from a I2CTarget_open() call. More...

typedef int_fast16_t(*	I2CTarget_EventCallbackFxn) (I2CTarget_Handle handle, I2CTarget_Event event, uint8_t *val)
	I2CTarget event callback function. More...

typedef struct I2CTarget_Config_	I2CTarget_Config
	I2CTarget Global configuration. More...

Enumerations
enum	I2CTarget_Event { I2CTarget_Event_WRITE_REQUESTED, I2CTarget_Event_READ_REQUESTED, I2CTarget_Event_WRITE_RECEIVED, I2CTarget_Event_READ_PROCESSED, I2CTarget_Event_STOP }
	I2CTarget events that the application's I2CTarget_EventCallbackFxn must support. More...

Functions
void	I2CTarget_init (void)
	Function to initializes the I2CTarget module. More...

void	I2CTarget_Params_init (I2CTarget_Params *params)
	Function to initialize the I2CTarget_Params struct to its defaults. More...

I2CTarget_Handle	I2CTarget_open (uint_least8_t index, I2CTarget_Params *params)
	Function to initialize a given I2C target peripheral specified by the particular index value. The parameter specifies which mode the I2CTarget will operate. More...

void	I2CTarget_start (I2CTarget_Handle handle)
	Start I2CTarget driver listening on I2C bus. More...

void	I2CTarget_stop (I2CTarget_Handle handle)
	Stop I2CTarget driver from listening on I2C bus. More...

void	I2CTarget_close (I2CTarget_Handle handle)

Variables
const I2CTarget_Config	I2CTarget_config []

const uint_least8_t	I2CTarget_count

Macro Definition Documentation

§ I2CTarget_STATUS_SUCCESS

#define I2CTarget_STATUS_SUCCESS (0)

Successful status code returned by application event callback function.

Status code returned from application's I2CTarget_EventCallbackFxn on success.

§ I2CTarget_STATUS_ERROR

#define I2CTarget_STATUS_ERROR (-1)

Generic error status code returned by application event callback function.

Status code returned from I2CTarget_EventCallbackFxn on error.

Typedef Documentation

§ I2CTarget_Handle

typedef struct I2CTarget_Config_* I2CTarget_Handle

A handle that is returned from a I2CTarget_open() call.

§ I2CTarget_EventCallbackFxn

typedef int_fast16_t(* I2CTarget_EventCallbackFxn) (I2CTarget_Handle handle, I2CTarget_Event event, uint8_t *val)

I2CTarget event callback function.

User defined callback function that is called whenever an I2CTarget_Event event occurs. The callback function must handle all the I2CTarget_Event events.

Parameters

[in]	handle	A I2CTarget_Handle returned from I2CTarget_open
[in]	event	The I2CTarget_Event event causing the callback
[in,out]	val	Parameter containing the data byte

Returns: See I2CTarget_Event

§ I2CTarget_Config

typedef struct I2CTarget_Config_ I2CTarget_Config

I2CTarget Global configuration.

The I2CTarget_Config structure contains a set of pointers used to characterize the I2CTarget driver implementation.

This structure needs to be defined before calling I2CTarget_init() and it must not be changed thereafter.

See also: I2CTarget_init()

Enumeration Type Documentation

§ I2CTarget_Event

enum I2CTarget_Event

I2CTarget events that the application's I2CTarget_EventCallbackFxn must support.

Enumerator
I2CTarget_Event_WRITE_REQUESTED	The target has been addressed with a write (target-receiver). The resulting `val` passed in is unused, the return value should always be I2CTarget_STATUS_SUCCESS.
I2CTarget_Event_READ_REQUESTED	The target has been addressed with a read (target-transmitter). The callback should fill the `val` parameter with the data byte, the return value should always be I2CTarget_STATUS_SUCCESS.
I2CTarget_Event_WRITE_RECEIVED	The target has received a byte of data (target-receiver). The resulting `val` parameter contains this data. The return should be I2CTarget_STATUS_SUCCESS if the byte should be ACKed, or I2CTarget_STATUS_ERROR if the byte should be NACKed.
I2CTarget_Event_READ_PROCESSED	The target driver requests the next read byte (target-transmitter). Note that this does not necessarily mean that the previous byte has been ACKed, or that this next byte will actually be sent. This depends entirely on if the controller sends an ACK for the previous byte. The resulting `val` should be filled in with the next read data byte. The return value should always be I2CTarget_STATUS_SUCCESS.
I2CTarget_Event_STOP	A stop condition was received. The application should reset its state machine.

Function Documentation

§ I2CTarget_init()

void I2CTarget_init ( void )

Function to initializes the I2CTarget module.

Precondition: The I2CTarget_config structure must exist and be persistent before this function can be called. This function must also be called before any other I2CTarget driver APIs. This function call does not modify any peripheral registers.

§ I2CTarget_Params_init()

void I2CTarget_Params_init ( I2CTarget_Params * params )

Function to initialize the I2CTarget_Params struct to its defaults.

Parameters

params An pointer to I2CTarget_Params structure for initialization

Defaults values are: eventCallbackFxn = NULL targetAddress = 0x42

§ I2CTarget_open()

I2CTarget_Handle I2CTarget_open	(	uint_least8_t	index,
		I2CTarget_Params *	params
	)

Function to initialize a given I2C target peripheral specified by the particular index value. The parameter specifies which mode the I2CTarget will operate.

Precondition: I2CTarget_init() has to be called first.

Parameters

index	Logical peripheral number for the I2CTarget indexed into the I2CTarget_config table
params	Pointer to a parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

Returns: A I2CTarget_Handle on success or a NULL on an error or if it has been opened already.

See also: I2CTarget_init(); I2CTarget_start(); I2CTarget_stop(); I2CTarget_close()

§ I2CTarget_start()

void I2CTarget_start ( I2CTarget_Handle handle )

Start I2CTarget driver listening on I2C bus.

Parameters

handle A I2CTarget_Handle returned from I2CTarget_open

See also: I2CTarget_stop()

§ I2CTarget_stop()

void I2CTarget_stop ( I2CTarget_Handle handle )

Stop I2CTarget driver from listening on I2C bus.

Parameters

handle A I2CTarget_Handle returned from I2CTarget_open

See also: I2CTarget_start()

§ I2CTarget_close()

void I2CTarget_close ( I2CTarget_Handle handle )

After calling the close function, the I2C is disabled.

Precondition: I2CTarget_open() has to be called first.

Parameters

handle A I2CTarget_Handle returned from I2CTarget_open

See also: I2CTarget_open(), I2CTarget_start(), I2CTarget_stop()

Variable Documentation

§ I2CTarget_config

const I2CTarget_Config I2CTarget_config[]

§ I2CTarget_count

const uint_least8_t I2CTarget_count

Detailed Description

Overview

Usage

Synopsis

Examples

Opening the I2CTarget Driver

Start/Stop I2C Operation

Transferring data

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ I2CTarget_STATUS_SUCCESS

§ I2CTarget_STATUS_ERROR

Typedef Documentation

§ I2CTarget_Handle

§ I2CTarget_EventCallbackFxn

§ I2CTarget_Config

Enumeration Type Documentation

§ I2CTarget_Event

Function Documentation

§ I2CTarget_init()

§ I2CTarget_Params_init()

§ I2CTarget_open()

§ I2CTarget_start()

§ I2CTarget_stop()

§ I2CTarget_close()

Variable Documentation

§ I2CTarget_config

§ I2CTarget_count