I2C

Inter-Integrated Circuit (I2C) interface for hardware platforms. More...

Collaboration diagram for I2C:

Macros
#define	HW_I2C_BAUD_RATE   100000
	Fixed I2C baud rate in Hz, used for every bus on the Pico. More...

Lifecycle
hw_deviceio_t *	hw_i2c_init_default (uint8_t addr)
	Initialize an I2C interface using the platform default adapter and pins. More...
hw_deviceio_t *	hw_i2c_init (uint8_t index, uint8_t addr, hw_gpio_t *sda_pin, hw_gpio_t *scl_pin)
	Initialize an I2C interface with a specific adapter and pins. More...
hw_deviceio_t *	hw_i2c_init_device (const char *device, uint8_t addr)
	Initialize an I2C interface from a platform-specific device path. More...

Properties
uint8_t	hw_i2c_count (void)
	Get the total number of available I2C adapters. More...

Methods
bool	hw_i2c_detect (hw_deviceio_t *device, uint8_t addr)
	Probe whether any device acknowledges an address on a bus. More...

Detailed Description

Inter-Integrated Circuit (I2C) interface for hardware platforms.

This module provides functions to initialize I2C peripherals in master mode, bound to a specific device address; transfers are performed through the generic hw_deviceio_t interface (see deviceio.h) that hw_i2c_init*() returns a handle to.

Note

On Raspberry Pi OS, I2C controllers are disabled by default and must be enabled. Buses are enabled in config.txt with device tree overlays, for example dtoverlay=i2c3,pins_4_5 for /dev/i2c-3 on GPIO4/GPIO5, or dtoverlay=i2c6,pins_22_23 for /dev/i2c-6 on GPIO22/GPIO23; see /boot/firmware/overlays/README for the full list of overlays, buses, and pin options. dtparam=i2c_baudrate=<hz> sets the primary bus's clock speed (default 100000).

Macro Definition Documentation

HW_I2C_BAUD_RATE

#define HW_I2C_BAUD_RATE   100000

Fixed I2C baud rate in Hz, used for every bus on the Pico.

Standard-mode I2C (100kHz) is supported by the widest range of devices.

Definition at line 34 of file i2c.h.

Function Documentation

hw_i2c_count()

uint8_t hw_i2c_count

(

void

)

Get the total number of available I2C adapters.

Returns

Number of I2C adapters available on the current platform.

On platforms that open I2C buses by device path, this may return 0 even when I2C is supported. In that case, use hw_i2c_init_device() instead of enumerating adapters by index.

hw_i2c_detect()

bool hw_i2c_detect	(	hw_deviceio_t *	device,
		uint8_t	addr
	)

Probe whether any device acknowledges an address on a bus.

Parameters

device	Any already-open handle from hw_i2c_init*() - used only to reach its bus; addr is probed independently of whichever address device itself was opened with. Has no SPI equivalent (SPI has no shared, addressable bus to scan), which is why this lives here rather than in deviceio.h.
addr	7-bit address to probe.

Return values

true	Something acknowledged addr.
false	Nothing acknowledged addr, addr is a reserved address, or device isn't a valid, open I2C handle.

Some devices only ACK a read, others only a write, during scan-style probing with no register address involved - both are tried.

hw_i2c_init()

hw_deviceio_t* hw_i2c_init	(	uint8_t	index,
		uint8_t	addr,
		hw_gpio_t *	sda_pin,
		hw_gpio_t *	scl_pin
	)

Initialize an I2C interface with a specific adapter and pins.

Parameters

index	I2C adapter index to use.
addr	7-bit address of the device to communicate with.
sda_pin	GPIO handle for SDA.
scl_pin	GPIO handle for SCL.

Returns

Device I/O handle bound to the device at addr, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_i2c_deinit().

hw_i2c_init_default()

hw_deviceio_t* hw_i2c_init_default

(

uint8_t

addr

)

Initialize an I2C interface using the platform default adapter and pins.

Parameters

addr	7-bit address of the device to communicate with.

Returns

Device I/O handle bound to the device at addr, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_i2c_deinit().

Note

On platforms where I2C buses are selected by device path instead of index (for example Linux), this function may be unsupported and return NULL by design. Use hw_i2c_init_device() on those platforms.

hw_i2c_init_device()

hw_deviceio_t* hw_i2c_init_device	(	const char *	device,
		uint8_t	addr
	)

Initialize an I2C interface from a platform-specific device path.

Parameters

device	Device identifier such as /dev/i2c-1.
addr	7-bit address of the device to communicate with.

Returns

Device I/O handle bound to the device at addr, or NULL on failure. Release it with hw_deviceio_deinit() - there is no separate hw_i2c_deinit().

This entry point is intended for platforms where I2C buses are exposed as named devices rather than a fixed, enumerable set of adapters.