Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# I2C Slave

## I2C Slave Usage

The following code snippet demonstrates the basic usage of an I2C slave device.

    #include <xs1.h>
    #include "i2c.h"

    port_t p_scl = XS1_PORT_1A;
    port_t p_sda = XS1_PORT_1B;

    // Setup callbacks
    //  NOTE: See API or SDK examples for more on using the callbacks
    i2c_callback_group_t i_i2c = {
         .ack_read_request = (ack_read_request_t) i2c_ack_read_req,
         .ack_write_request = (ack_write_request_t) i2c_ack_write_req,
         .master_requires_data = (master_requires_data_t) i2c_master_req_data,
         .master_sent_data = (master_sent_data_t) i2c_master_sent_data,
         .stop_bit = (stop_bit_t) i2c_stop_bit,
         .shutdown = (shutdown_t) i2c_shutdown,
         .app_data = NULL,
    };

    // Start the slave device in this thread
    //  NOTE: You may wish to launch the slave device in a different thread.
    //        See the XTC Tools documentation reference for lib_xcore.
    i2c_slave(&i_i2c, p_scl, p_sda, 0x3c);

## I2C Slave API

The following structures and functions are used to initialize and start an I2C slave instance.

enum i2c_slave_ack

  I2C Slave Response

  This type is used to describe the I2C slave response.

  Values:

  enumerator I2C_SLAVE_ACK

    ACK to accept request

  enumerator I2C_SLAVE_NACK

    NACK to ignore request

typedef enum i2c_slave_ack i2c_slave_ack_t

  I2C Slave Response

  This type is used to describe the I2C slave response.

typedef i2c_slave_ack_t (*ack_read_request_t)(void *app_data)

  The bus master has requested a read.

  This callback function is called if the bus master requests a read from this slave device.

  At this point the slave can choose to accept the request (and drive an ACK signal back to the master) or not (and drive a NACK signal).

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

  Return:

    The callback must return either I2C_SLAVE_ACK or I2C_SLAVE_NACK.

typedef i2c_slave_ack_t (*ack_write_request_t)(void *app_data)

  The bus master has requested a write.

  This callback function is called if the bus master requests a write from this slave device.

  At this point the slave can choose to accept the request (and drive an ACK signal back to the master) or not (and drive a NACK signal).

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

  Return:

    The callback must return either I2C_SLAVE_ACK or I2C_SLAVE_NACK.

typedef uint8_t (*master_requires_data_t)(void *app_data)

  The bus master requires data.

  This callback function is called when the bus master requires data from this slave device.

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

  Return:

    a byte of data to send to the master.

typedef i2c_slave_ack_t (*master_sent_data_t)(void *app_data, uint8_t data)

  The bus master has sent some data.

  This callback function is called when the bus master has transferred a byte of data this slave device.

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

  Param data:

    The byte of data received from the bus master.

  Return:

    The callback must return either I2C_SLAVE_ACK or I2C_SLAVE_NACK.

typedef void (*stop_bit_t)(void *app_data)

  The bus master has sent a stop bit.

  This callback function is called when a stop bit is sent by the bus master.

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

typedef int (*shutdown_t)(void *app_data)

  Shuts down the I2C slave device.

  This function can be used to stop the I2C slave task. It will disable the SCL and SDA ports and then return.

  Param app_data:

    A pointer to application specific data provided by the application. Used to share data between the callback functions and the application.

  Return:

    - Non-zero if the I2C slave task should shut down.

    - Zero if the I2C slave task should continue running.

void i2c_slave(const i2c_callback_group_t *const i2c_cbg, port_t p_scl, port_t p_sda, uint8_t device_addr)

  I2C slave task.

  This function instantiates an I2C slave device.

  Parameters:

    - i2c_cbg – The I2C callback group pointing to the application’s functions to use for initialization and getting and receiving frames. Also points to application specific data which will be shared between the callbacks.

    - p_scl – The SCL port of the I2C bus. This should be a 1 bit port. If not, The SCL pin must be at bit 0 and the other bits unused.

    - p_sda – The SDA port of the I2C bus. This should be a 1 bit port. If not, The SDA pin must be at bit 0 and the other bits unused.

    - device_addr – The address of the slave device.

I2C_CALLBACK_ATTR

  This attribute must be specified on all I2C callback functions provided by the application.

struct i2c_callback_group_t
  #include <i2c.h>

  Callback group representing callback events that can occur during the operation of the I2C slave task. Must be initialized by the application prior to passing it to one of the I2C tasks.