hardware_i2c

I2C Controller API. More...

Functions
uint	i2c_init (i2c_inst_t *i2c, uint baudrate)
	Initialise the I2C HW block. More...
void	i2c_deinit (i2c_inst_t *i2c)
	Disable the I2C HW block. More...
uint	i2c_set_baudrate (i2c_inst_t *i2c, uint baudrate)
	Set I2C baudrate. More...
void	i2c_set_slave_mode (i2c_inst_t *i2c, bool slave, uint8_t addr)
	Set I2C port to slave mode. More...
static uint	i2c_hw_index (i2c_inst_t *i2c)
	Convert I2C instance to hardware instance number. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
static size_t	i2c_get_write_available (i2c_inst_t *i2c)
	Determine non-blocking write space available. More...
static size_t	i2c_get_read_available (i2c_inst_t *i2c)
	Determine number of bytes received. More...
static void	i2c_write_raw_blocking (i2c_inst_t *i2c, const uint8_t *src, size_t len)
	Write direct to TX FIFO. More...
static void	i2c_read_raw_blocking (i2c_inst_t *i2c, uint8_t *dst, size_t len)
	Read direct from RX FIFO. More...
static uint8_t	i2c_read_byte_raw (i2c_inst_t *i2c)
	Pop a byte from I2C Rx FIFO. More...
static void	i2c_write_byte_raw (i2c_inst_t *i2c, uint8_t value)
	Push a byte into I2C Tx FIFO. More...
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. More...
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

 
// Sweep through all 7-bit I2C addresses, to see if any slaves are present on
// the I2C bus. Print out a table that looks like this:
//
// I2C Bus Scan
//   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
// 0
// 1       @
// 2
// 3             @
// 4
// 5
// 6
// 7
//
// E.g. if slave addresses 0x12 and 0x34 were acknowledged.
 
#include <stdio.h>
#include "pico/stdlib.h"
#include "pico/binary_info.h"
#include "hardware/i2c.h"
 
// I2C reserves some addresses for special purposes. We exclude these from the scan.
// These are any addresses of the form 000 0xxx or 111 1xxx
bool reserved_addr(uint8_t addr) {
    return (addr & 0x78) == 0 || (addr & 0x78) == 0x78;
}
 
int main() {
    // Enable UART so we can print status output
    stdio_init_all();
#if !defined(i2c_default) || !defined(PICO_DEFAULT_I2C_SDA_PIN) || !defined(PICO_DEFAULT_I2C_SCL_PIN)
#warning i2c/bus_scan example requires a board with I2C pins
    puts("Default I2C pins were not defined");
#else
    // This example will use I2C0 on the default SDA and SCL pins (GP4, GP5 on a Pico)
    i2c_init(i2c_default, 100 * 1000);
    gpio_set_function(PICO_DEFAULT_I2C_SDA_PIN, GPIO_FUNC_I2C);
    gpio_set_function(PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C);
    gpio_pull_up(PICO_DEFAULT_I2C_SDA_PIN);
    gpio_pull_up(PICO_DEFAULT_I2C_SCL_PIN);
    // Make the I2C pins available to picotool
    bi_decl(bi_2pins_with_func(PICO_DEFAULT_I2C_SDA_PIN, PICO_DEFAULT_I2C_SCL_PIN, GPIO_FUNC_I2C));
 
    printf("\nI2C Bus Scan\n");
    printf("   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F\n");
 
    for (int addr = 0; addr < (1 << 7); ++addr) {
        if (addr % 16 == 0) {
            printf("%02x ", addr);
        }
 
        // Perform a 1-byte dummy read from the probe address. If a slave
        // acknowledges this address, the function returns the number of bytes
        // transferred. If the address byte is ignored, the function returns
        // -1.
 
        // Skip over any reserved addresses.
        int ret;
        uint8_t rxdata;
        if (reserved_addr(addr))
            ret = PICO_ERROR_GENERIC;
        else
            ret = i2c_read_blocking(i2c_default, addr, &rxdata, 1, false);
 
        printf(ret < 0 ? "." : "@");
        printf(addr % 16 == 15 ? "\n" : "  ");
    }
    printf("Done.\n");
    return 0;
#endif
}

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()

static uint i2c_get_dreq ( i2c_inst_t *  i2c, bool  is_tx  )

inlinestatic

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_read_available()

static size_t i2c_get_read_available ( i2c_inst_t *  i2c )

inlinestatic

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()

static size_t i2c_get_write_available ( i2c_inst_t *  i2c )

inlinestatic

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_hw_index()

static uint i2c_hw_index ( i2c_inst_t *  i2c )

inlinestatic

Convert I2C instance to hardware instance number.

Parameters

i2c	I2C instance

Returns

Number of I2C, 0 or 1.

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_byte_raw()

static uint8_t i2c_read_byte_raw ( i2c_inst_t *  i2c )

inlinestatic

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()

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

inlinestatic

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()

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

inlinestatic

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_byte_raw()

static void i2c_write_byte_raw ( i2c_inst_t *  i2c, uint8_t  value  )

inlinestatic

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()

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

inlinestatic

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()

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  )

inlinestatic

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

The I2C identifiers for use in I2C functions.

e.g. i2c_init(i2c0, 48000)