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

# I2C Master

## I2C Master Usage

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

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

    i2c_master_t i2c_ctx;

    port_t p_scl = XS1_PORT_1A;
    port_t p_sda = XS1_PORT_1B;

    uint8_t data[1] = {0x99};

    // Initialize the master
    i2c_master_init(
                &i2c_ctx,
                p_scl, 0, 0,
                p_sda, 0, 0,
                100);

    // Write some data
    i2c_master_write(&i2c_ctx, 0x33, data, 1, NULL, 1);

    // Shutdown
    i2c_master_shutdown(&i2c_ctx) ;

## I2C Master API

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

enum i2c_res_t

  Status codes for I2C master operations

  Values:

  enumerator I2C_NACK

    The slave has NACKed the last byte.

  enumerator I2C_ACK

    The slave has ACKed the last byte.

  enumerator I2C_STARTED

    The requested I2C transaction has started.

  enumerator I2C_NOT_STARTED

    The requested I2C transaction could not start.

typedef struct i2c_master_struct i2c_master_t

  Type representing an I2C master context

i2c_res_t i2c_master_write(i2c_master_t *ctx, uint8_t device_addr, uint8_t buf[], size_t n, size_t *num_bytes_sent, int send_stop_bit)

  Writes data to an I2C bus as a master.

  Parameters:

    - ctx – A pointer to the I2C master context to use.

    - device_addr – The address of the device to write to.

    - buf – The buffer containing data to write.

    - n – The number of bytes to write.

    - num_bytes_sent – The function will set this value to the number of bytes actually sent. On success, this will be equal to `n` but it will be less if the slave sends an early NACK on the bus and the transaction fails.

    - send_stop_bit – If this is non-zero then a stop bit will be sent on the bus after the transaction. This is usually required for normal operation. If this parameter is zero then no stop bit will be omitted. In this case, no other task can use the component until a stop bit has been sent.

  Returns:

    I2C_ACK if the write was acknowledged by the device, I2C_NACK otherwise.

i2c_res_t i2c_master_read(i2c_master_t *ctx, uint8_t device_addr, uint8_t buf[], size_t n, int send_stop_bit)

  Reads data from an I2C bus as a master.

  Parameters:

    - ctx – A pointer to the I2C master context to use.

    - device_addr – The address of the device to read from.

    - buf – The buffer to fill with data.

    - n – The number of bytes to read.

    - send_stop_bit – If this is non-zero then a stop bit. will be sent on the bus after the transaction. This is usually required for normal operation. If this parameter is zero then no stop bit will be omitted. In this case, no other task can use the component until a stop bit has been sent.

  Returns:

    I2C_ACK if the read was acknowledged by the device, I2C_NACK otherwise.

void i2c_master_stop_bit_send(i2c_master_t *ctx)

  Send a stop bit to an I2C bus as a master.

  This function will cause a stop bit to be sent on the bus. It should be used to complete/abort a transaction if the `send_stop_bit` argument was not set when calling the i2c_master_read() or i2c_master_write() functions.

  Parameters:

    - ctx – A pointer to the I2C master context to use.

void i2c_master_init(i2c_master_t *ctx, const port_t p_scl, const uint32_t scl_bit_position, const uint32_t scl_other_bits_mask, const port_t p_sda, const uint32_t sda_bit_position, const uint32_t sda_other_bits_mask, const unsigned kbits_per_second)

  Implements an I2C master device on one or two single or multi-bit ports.

  Parameters:

    - ctx – A pointer to the I2C master context to initialize.

    - p_scl – The port containing SCL. This may be either the same as or different than `p_sda`.

    - scl_bit_position – The bit number of the SCL line on the port `p_scl`.

    - scl_other_bits_mask – A value that is ORed into the port value driven to `p_scl` both when SCL is high and low. The bit representing SCL (as well as SDA if they share the same port) must be set to 0.

    - p_sda – The port containing SDA. This may be either the same as or different than `p_scl`.

    - sda_bit_position – The bit number of the SDA line on the port `p_sda`.

    - sda_other_bits_mask – A value that is ORed into the port value driven to `p_sda` both when SDA is high and low. The bit representing SDA (as well as SCL if they share the same port) must be set to 0.

    - kbits_per_second – The speed of the I2C bus. The maximum value allowed is 400.

void i2c_master_shutdown(i2c_master_t *ctx)

  Shuts down the I2C master device.

  This function disables the ports associated with the I2C master and deallocates its timer if it was not provided by the application.

  If subsequent reads or writes need to be performed, then i2c_master_init() must be called again first.

  Parameters:

    - ctx – A pointer to the I2C master context to shut down.

struct i2c_master_struct
  #include <i2c.h>

  Struct to hold an I2C master context.

  The members in this struct should not be accessed directly.