@web-font-path: "roboto-debian.css";
v2.2.0 (RP2040)
Loading...
Searching...
No Matches
hardware_i2c

I2C Controller API. More...

## Macros

#define | I2C_NUM(i2c)
| Returns the I2C number for a I2C instance.
#define | I2C_INSTANCE(num)
| Returns the I2C instance with the given I2C number.
#define | I2C_DREQ_NUM(i2c, is_tx)
| Returns the dreq_num_t used for pacing DMA transfers to or from this I2C instance. If is_tx is true, then it is for transfers to the I2C instance else for transfers from the I2C instance.

## Functions

uint | i2c_init (i2c_inst_t *i2c, uint baudrate)
| Initialise the I2C HW block.
void | i2c_deinit (i2c_inst_t *i2c)
| Disable the I2C HW block.
uint | i2c_set_baudrate (i2c_inst_t *i2c, uint baudrate)
| Set I2C baudrate.
void | i2c_set_slave_mode (i2c_inst_t *i2c, bool slave, uint8_t addr)
| Set I2C port to slave mode.
static uint | i2c_get_index (i2c_inst_t *i2c)
| Convert I2C instance to hardware instance number.
static i2c_hw_t * | i2c_get_hw (i2c_inst_t *i2c)
| Return pointer to structure containing i2c hardware registers.
static i2c_inst_t * | i2c_get_instance (uint num)
| Convert I2C hardware instance number to I2C instance.
int | i2c_write_blocking_until (i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop, absolute_time_t until)
| Attempt to write specified number of bytes to address, blocking until the specified absolute time is reached.
int | i2c_read_blocking_until (i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop, absolute_time_t until)
| Attempt to read specified number of bytes from address, blocking until the specified absolute time is reached.
static int | i2c_write_timeout_us (i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop, uint timeout_us)
| Attempt to write specified number of bytes to address, with timeout.
static int | i2c_read_timeout_us (i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop, uint timeout_us)
| Attempt to read specified number of bytes from address, with timeout.
int | i2c_write_blocking (i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop)
| Attempt to write specified number of bytes to address, blocking.
int | i2c_write_burst_blocking (i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len)
| Attempt to write specified number of bytes to address, blocking in burst mode.
int | i2c_read_blocking (i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop)
| Attempt to read specified number of bytes from address, blocking.
int | i2c_read_burst_blocking (i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len)
| Attempt to read specified number of bytes from address, blocking in burst mode.
static size_t | i2c_get_write_available (i2c_inst_t *i2c)
| Determine non-blocking write space available.
static size_t | i2c_get_read_available (i2c_inst_t *i2c)
| Determine number of bytes received.
static void | i2c_write_raw_blocking (i2c_inst_t *i2c, const uint8_t *src, size_t len)
| Write direct to TX FIFO.
static void | i2c_read_raw_blocking (i2c_inst_t *i2c, uint8_t *dst, size_t len)
| Read direct from RX FIFO.
static uint8_t | i2c_read_byte_raw (i2c_inst_t *i2c)
| Pop a byte from I2C Rx FIFO.
static void | i2c_write_byte_raw (i2c_inst_t *i2c, uint8_t value)
| Push a byte into I2C Tx FIFO.
static uint | i2c_get_dreq (i2c_inst_t *i2c, bool is_tx)
| Return the DREQ to use for pacing transfers to/from a particular I2C instance.
i2c_inst_t | i2c0_inst

## Detailed Description

I2C Controller API.

The I2C bus is a two-wire serial interface, consisting of a serial data line SDA and a serial clock SCL. These wires carry information between the devices connected to the bus. Each device is recognized by a unique 7-bit address and can operate as either a “transmitter” or “receiver”, depending on the function of the device. Devices can also be considered as masters or slaves when performing data transfers. A master is a device that initiates a data transfer on the bus and generates the clock signals to permit that transfer. The first byte in the data transfer always contains the 7-bit address and a read/write bit in the LSB position. This API takes care of toggling the read/write bit. After this, any device addressed is considered a slave.

This API allows the controller to be set up as a master or a slave using the i2c_set_slave_mode function.

The external pins of each controller are connected to GPIO pins as defined in the GPIO muxing table in the datasheet. The muxing options give some IO flexibility, but each controller external pin should be connected to only one GPIO.

Note that the controller does NOT support High speed mode or Ultra-fast speed mode, the fastest operation being fast mode plus at up to 1000Kb/s.

See the datasheet for more information on the I2C controller and its usage.

## Example

## Macro Definition Documentation

## I2C_DREQ_NUM

#define I2C_DREQ_NUM | ( |  | i2c,
|  |  | is_tx )

Returns the dreq_num_t used for pacing DMA transfers to or from this I2C instance. If is_tx is true, then it is for transfers to the I2C instance else for transfers from the I2C instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

## I2C_INSTANCE

#define I2C_INSTANCE | ( |  | num | ) |

Returns the I2C instance with the given I2C number.

Note this macro is intended to resolve at compile time, and does no parameter checking

## I2C_NUM

#define I2C_NUM | ( |  | i2c | ) |

Returns the I2C number for a I2C instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

## Function Documentation

## i2c_deinit()

void i2c_deinit | ( | i2c_inst_t * | i2c | ) |

Disable the I2C HW block.

Parameters

  i2c | Either i2c0 or i2c1

Disable the I2C again if it is no longer used. Must be reinitialised before being used again.

## i2c_get_dreq()

uint i2c_get_dreq | ( | i2c_inst_t * | i2c,
|  | bool | is_tx )

inline static

Return the DREQ to use for pacing transfers to/from a particular I2C instance.

Parameters

  i2c | Either i2c0 or i2c1
  is_tx | true for sending data to the I2C instance, false for receiving data from the I2C instance

## i2c_get_hw()

i2c_hw_t * i2c_get_hw | ( | i2c_inst_t * | i2c | ) |

inline static

Return pointer to structure containing i2c hardware registers.

Parameters

  i2c | I2C instance

Returns
  pointer to i2c_hw_t

## i2c_get_index()

uint i2c_get_index | ( | i2c_inst_t * | i2c | ) |

inline static

Convert I2C instance to hardware instance number.

Parameters

  i2c | I2C instance

Returns
  Number of I2C, 0 or 1.

## i2c_get_instance()

i2c_inst_t * i2c_get_instance | ( | uint | num | ) |

inline static

Convert I2C hardware instance number to I2C instance.

Parameters

  num | Number of I2C, 0 or 1

Returns
  I2C hardware instance

## i2c_get_read_available()

size_t i2c_get_read_available | ( | i2c_inst_t * | i2c | ) |

inline static

Determine number of bytes received.

Parameters

  i2c | Either i2c0 or i2c1

Returns
  0 if no data available, if return is nonzero at least that many bytes can be read without blocking.

## i2c_get_write_available()

size_t i2c_get_write_available | ( | i2c_inst_t * | i2c | ) |

inline static

Determine non-blocking write space available.

Parameters

  i2c | Either i2c0 or i2c1

Returns
  0 if no space is available in the I2C to write more data. If return is nonzero, at least that many bytes can be written without blocking.

## i2c_init()

uint i2c_init | ( | i2c_inst_t * | i2c,
|  | uint | baudrate )

Initialise the I2C HW block.

Put the I2C hardware into a known state, and enable it. Must be called before other functions. By default, the I2C is configured to operate as a master.

The I2C bus frequency is set as close as possible to requested, and the actual rate set is returned

Parameters

  i2c | Either i2c0 or i2c1
  baudrate | Baudrate in Hz (e.g. 100kHz is 100000)

Returns
  Actual set baudrate

## i2c_read_blocking()

int i2c_read_blocking | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | uint8_t * | dst,
|  | size_t | len,
|  | bool | nostop )

Attempt to read specified number of bytes from address, blocking.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to read from
  dst | Pointer to buffer to receive data
  len | Length of data in bytes to receive
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.

Returns
  Number of bytes read, or PICO_ERROR_GENERIC if address not acknowledged or no device present.

## i2c_read_blocking_until()

int i2c_read_blocking_until | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | uint8_t * | dst,
|  | size_t | len,
|  | bool | nostop,
|  | absolute_time_t | until )

Attempt to read specified number of bytes from address, blocking until the specified absolute time is reached.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to read from
  dst | Pointer to buffer to receive data
  len | Length of data in bytes to receive
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.
  until | The absolute time that the block will wait until the entire transaction is complete.

Returns
  Number of bytes read, or PICO_ERROR_GENERIC if address not acknowledged, no device present, or PICO_ERROR_TIMEOUT if a timeout occurred.

## i2c_read_burst_blocking()

int i2c_read_burst_blocking | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | uint8_t * | dst,
|  | size_t | len )

Attempt to read specified number of bytes from address, blocking in burst mode.

This version of the function will not issue a stop and will not restart on the next read. This allows you to read consecutive bytes of data without having to resend a stop bit and (for example) without having to send address byte(s) repeatedly

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to read from
  dst | Pointer to buffer to receive data
  len | Length of data in bytes to receive

Returns
  Number of bytes read, or PICO_ERROR_GENERIC if address not acknowledged or no device present.

## i2c_read_byte_raw()

uint8_t i2c_read_byte_raw | ( | i2c_inst_t * | i2c | ) |

inline static

Pop a byte from I2C Rx FIFO.

This function is non-blocking and assumes the Rx FIFO isn't empty.

Parameters

  i2c | I2C instance.

Returns
  uint8_t Byte value.

## i2c_read_raw_blocking()

void i2c_read_raw_blocking | ( | i2c_inst_t * | i2c,
|  | uint8_t * | dst,
|  | size_t | len )

inline static

Read direct from RX FIFO.

Parameters

  i2c | Either i2c0 or i2c1
  dst | Buffer to accept data
  len | Number of bytes to read

Reads directly from the I2C RX FIFO which is mainly useful for slave-mode operation.

## i2c_read_timeout_us()

int i2c_read_timeout_us | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | uint8_t * | dst,
|  | size_t | len,
|  | bool | nostop,
|  | uint | timeout_us )

inline static

Attempt to read specified number of bytes from address, with timeout.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to read from
  dst | Pointer to buffer to receive data
  len | Length of data in bytes to receive
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.
  timeout_us | The time that the function will wait for the entire transaction to complete

Returns
  Number of bytes read, or PICO_ERROR_GENERIC if address not acknowledged, no device present, or PICO_ERROR_TIMEOUT if a timeout occurred.

## i2c_set_baudrate()

uint i2c_set_baudrate | ( | i2c_inst_t * | i2c,
|  | uint | baudrate )

Set I2C baudrate.

Set I2C bus frequency as close as possible to requested, and return actual rate set. Baudrate may not be as exactly requested due to clocking limitations.

Parameters

  i2c | Either i2c0 or i2c1
  baudrate | Baudrate in Hz (e.g. 100kHz is 100000)

Returns
  Actual set baudrate

## i2c_set_slave_mode()

void i2c_set_slave_mode | ( | i2c_inst_t * | i2c,
|  | bool | slave,
|  | uint8_t | addr )

Set I2C port to slave mode.

Parameters

  i2c | Either i2c0 or i2c1
  slave | true to use slave mode, false to use master mode
  addr | If `slave` is true, set the slave address to this value

## i2c_write_blocking()

int i2c_write_blocking | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | const uint8_t * | src,
|  | size_t | len,
|  | bool | nostop )

Attempt to write specified number of bytes to address, blocking.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to write to
  src | Pointer to data to send
  len | Length of data in bytes to send
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.

Returns
  Number of bytes written, or PICO_ERROR_GENERIC if address not acknowledged, no device present.

## i2c_write_blocking_until()

int i2c_write_blocking_until | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | const uint8_t * | src,
|  | size_t | len,
|  | bool | nostop,
|  | absolute_time_t | until )

Attempt to write specified number of bytes to address, blocking until the specified absolute time is reached.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to write to
  src | Pointer to data to send
  len | Length of data in bytes to send
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.
  until | The absolute time that the block will wait until the entire transaction is complete. Note, an individual timeout of this value divided by the length of data is applied for each byte transfer, so if the first or subsequent bytes fails to transfer within that sub timeout, the function will return with an error.

Returns
  Number of bytes written, or PICO_ERROR_GENERIC if address not acknowledged, no device present, or PICO_ERROR_TIMEOUT if a timeout occurred.

## i2c_write_burst_blocking()

int i2c_write_burst_blocking | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | const uint8_t * | src,
|  | size_t | len )

Attempt to write specified number of bytes to address, blocking in burst mode.

This version of the function will not issue a stop and will not restart on the next write. This allows you to write consecutive bytes of data without having to resend a stop bit and (for example) without having to send address byte(s) repeatedly

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to write to
  src | Pointer to data to send
  len | Length of data in bytes to send

Returns
  Number of bytes written, or PICO_ERROR_GENERIC if address not acknowledged or no device present.

## i2c_write_byte_raw()

void i2c_write_byte_raw | ( | i2c_inst_t * | i2c,
|  | uint8_t | value )

inline static

Push a byte into I2C Tx FIFO.

This function is non-blocking and assumes the Tx FIFO isn't full.

Parameters

  i2c | I2C instance.
  value | Byte value.

## i2c_write_raw_blocking()

void i2c_write_raw_blocking | ( | i2c_inst_t * | i2c,
|  | const uint8_t * | src,
|  | size_t | len )

inline static

Write direct to TX FIFO.

Parameters

  i2c | Either i2c0 or i2c1
  src | Data to send
  len | Number of bytes to send

Writes directly to the I2C TX FIFO which is mainly useful for slave-mode operation.

## i2c_write_timeout_us()

int i2c_write_timeout_us | ( | i2c_inst_t * | i2c,
|  | uint8_t | addr,
|  | const uint8_t * | src,
|  | size_t | len,
|  | bool | nostop,
|  | uint | timeout_us )

inline static

Attempt to write specified number of bytes to address, with timeout.

Parameters

  i2c | Either i2c0 or i2c1
  addr | 7-bit address of device to write to
  src | Pointer to data to send
  len | Length of data in bytes to send
  nostop | If true, master retains control of the bus at the end of the transfer (no Stop is issued), and the next transfer will begin with a Restart rather than a Start.
  timeout_us | The time that the function will wait for the entire transaction to complete. Note, an individual timeout of this value divided by the length of data is applied for each byte transfer, so if the first or subsequent bytes fails to transfer within that sub timeout, the function will return with an error.

Returns
  Number of bytes written, or PICO_ERROR_GENERIC if address not acknowledged, no device present, or PICO_ERROR_TIMEOUT if a timeout occurred.

## Variable Documentation

## i2c0_inst

i2c_inst_t i2c0_inst

extern

The I2C identifiers for use in I2C functions.

e.g. i2c_init(i2c0, 48000)