I2C

Inter-Integrated Circuit (I2C) interface. More...

Collaboration diagram for I2C:

Data Structures
struct	hw_i2c_t
	I2C adapter. More...

Typedefs
typedef struct hw_i2c_t	hw_i2c_t
	I2C adapter. More...

Functions
bool	hw_i2c_init_default (hw_i2c_t *adapter, uint32_t baudrate)
	Initialize an I2C interface using default pins and adapter. More...
bool	hw_i2c_init (hw_i2c_t *adapter, uint8_t index, uint8_t sda, uint8_t scl, uint32_t baudrate)
	Initialize an I2C interface with specific adapter and pins. More...
bool	hw_i2c_init_device (hw_i2c_t *adapter, const char *device, uint32_t baudrate)
	Initialize an I2C interface with device path. More...
void	hw_i2c_finalize (hw_i2c_t *i2c)
	Finalize and release an I2C interface. More...
uint8_t	hw_i2c_count (void)
	Get the total number of available I2C adapters. More...
bool	hw_i2c_valid (hw_i2c_t *i2c)
	Get true if the I2C interface is valid. More...
bool	hw_i2c_detect (hw_i2c_t *i2c, uint8_t addr)
	Detect if an I2C device is present at the specified address. More...
size_t	hw_i2c_xfr (hw_i2c_t *i2c, uint8_t addr, void *data, size_t tx, size_t rx, uint32_t timeout_ms)
	Perform an I2C transfer operation (read, write, or combined). More...
size_t	hw_i2c_read (hw_i2c_t *i2c, uint8_t addr, uint8_t reg, void *data, size_t len, uint32_t timeout_ms)
	Read data from a specific register of an I2C device. More...
size_t	hw_i2c_write (hw_i2c_t *i2c, uint8_t addr, uint8_t reg, const void *data, size_t len, uint32_t timeout_ms)
	Write data to a specific register of an I2C device. More...

Detailed Description

Inter-Integrated Circuit (I2C) interface.

This module provides functions to initialize I2C peripherals, and bi-directional data transfer with I2C devicesin master mode.

Typedef Documentation

hw_i2c_t

typedef struct hw_i2c_t hw_i2c_t

I2C adapter.

Platform-specific I2C interface structure. The internal implementation is opaque and stored in reserved bytes.

Function Documentation

hw_i2c_count()

uint8_t hw_i2c_count

(

void

)

Get the total number of available I2C adapters.

Returns

The number of I2C adapters available on the hardware platform.

Returns the number of logical I2C adapters that can be used in the system. These are usually numbered from 0 to hw_i2c_count() - 1. If zero is returned, it indicates that I2C functionality is not available.

hw_i2c_detect()

bool hw_i2c_detect	(	hw_i2c_t *	i2c,
		uint8_t	addr
	)

Detect if an I2C device is present at the specified address.

Parameters

i2c	Pointer to the I2C structure representing the interface.
addr	The 7-bit I2C slave device address (without R/W bit).

Returns

true if the device responds, false if it does not, or the address is invalid.

This function checks if an I2C device is present at the specified address by attempting to communicate with it. It returns true if the device responds to a basic read/write operation, false otherwise.

hw_i2c_finalize()

void hw_i2c_finalize

(

hw_i2c_t *

i2c

)

Finalize and release an I2C interface.

Parameters

i2c	Pointer to the I2C structure to finalize.

This function releases the I2C interface and frees any associated resources. After calling this function, the I2C interface should not be used for further operations.

hw_i2c_init()

bool hw_i2c_init	(	hw_i2c_t *	adapter,
		uint8_t	index,
		uint8_t	sda,
		uint8_t	scl,
		uint32_t	baudrate
	)

Initialize an I2C interface with specific adapter and pins.

Parameters

adapter	The I2C adapter structure
index	The I2C adapter index to use (0 to hw_i2c_count()-1).
sda	The GPIO pin number to use for I2C data (SDA).
scl	The GPIO pin number to use for I2C clock (SCL).
baudrate	The desired I2C baud rate (e.g., 100000 for 100kHz).

Returns

True if the initialization was successful, false otherwise.

This function initializes an I2C interface using the specified adapter and GPIO pins for SDA and SCL lines. The adapter index should be valid and the specified pins should be capable of I2C functionality.

Note

The specified pins must support I2C functionality.

Pin assignments are platform-dependent.

hw_i2c_init_default()

bool hw_i2c_init_default	(	hw_i2c_t *	adapter,
		uint32_t	baudrate
	)

Initialize an I2C interface using default pins and adapter.

Parameters

adapter	The I2C adapter structure
baudrate	The desired I2C baud rate (e.g., 100000 for 100kHz).

Returns

True if the initialization was successful, false otherwise.

This function initializes the default I2C interface using platform-specific default pins and adapter settings. This is the simplest way to get I2C functionality without needing to specify pin assignments.

hw_i2c_init_device()

bool hw_i2c_init_device	(	hw_i2c_t *	adapter,
		const char *	device,
		uint32_t	baudrate
	)

Initialize an I2C interface with device path.

Parameters

adapter	The I2C adapter structure
device	The I2C device path (e.g., "/dev/i2c-0").
baudrate	The desired I2C baud rate (e.g., 100000 for 100kHz).

Returns

True if the initialization was successful, false otherwise.

This function initializes an I2C interface using the specified device path and baud rate. The device path should be valid and correspond to an I2C adapter on the system.

hw_i2c_read()

size_t hw_i2c_read	(	hw_i2c_t *	i2c,
		uint8_t	addr,
		uint8_t	reg,
		void *	data,
		size_t	len,
		uint32_t	timeout_ms
	)

Read data from a specific register of an I2C device.

Parameters

i2c	Pointer to the I2C structure representing the interface.
addr	The 7-bit I2C slave device address (without R/W bit).
reg	The register address to read from.
data	Pointer to the buffer where read data will be stored.
len	Number of bytes to read from the register.
timeout_ms	Timeout value in milliseconds for the operation. Set to 0 for no timeout.

Returns

Number of bytes successfully read. Returns zero if the operation failed or timed out.

hw_i2c_valid()

bool hw_i2c_valid

(

hw_i2c_t *

i2c

)

Get true if the I2C interface is valid.

Parameters

i2c	Pointer to the I2C structure representing the interface.

Returns

True if the I2C interface is valid, false otherwise.

The result of hw_i2c_init can return an empty I2C structure if the initialization fails. This function checks if the I2C interface is valid.

hw_i2c_write()

size_t hw_i2c_write	(	hw_i2c_t *	i2c,
		uint8_t	addr,
		uint8_t	reg,
		const void *	data,
		size_t	len,
		uint32_t	timeout_ms
	)

Write data to a specific register of an I2C device.

Parameters

i2c	Pointer to the I2C structure representing the interface.
addr	The 7-bit I2C slave device address (without R/W bit).
reg	The register address to write to.
data	Pointer to the buffer containing data to write.
len	Number of bytes to write to the register.
timeout_ms	Timeout value in milliseconds for the operation. Set to 0 for no timeout.

Returns

Number of bytes successfully written. Returns zero if the operation failed or timed out.

hw_i2c_xfr()

size_t hw_i2c_xfr	(	hw_i2c_t *	i2c,
		uint8_t	addr,
		void *	data,
		size_t	tx,
		size_t	rx,
		uint32_t	timeout_ms
	)

Perform an I2C transfer operation (read, write, or combined).

Parameters

i2c	Pointer to the I2C structure representing the interface.
addr	The 7-bit I2C slave device address (without R/W bit).
data	Pointer to the data buffer for transmission and/or reception.
tx	Number of bytes to transmit from the data buffer.
rx	Number of bytes to receive into the data buffer (after tx bytes).
timeout_ms	Timeout value in milliseconds for each operation. Set to 0 for no timeout.

Returns

Number of bytes transferred. Returns zero if the transfer failed or timed out.

This function performs I2C transfer operations which can be:

• Write-only: tx > 0, rx = 0 (transmit data to slave)
• Read-only: tx = 0, rx > 0 (receive data from slave)
• Write-then-Read: tx > 0, rx > 0 (write command, then read response)

For combined operations, the function first transmits 'tx' bytes from the data buffer, then receives 'rx' bytes into the same buffer starting at offset 'tx'. The total buffer size should be at least (tx + rx) bytes.