mcp2221_i2c_slave.h File Reference

High-level helpers for communicating with an I2C target device. More...

#include <stddef.h>
#include <stdint.h>
#include "mcp2221.h"

Include dependency graph for mcp2221_i2c_slave.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	mcp2221_i2c_slave
	Caller-owned I2C target context. More...

Enumerations
enum	mcp2221_i2c_byte_order_t { MCP2221_I2C_BYTE_ORDER_DEFAULT = -1 , MCP2221_I2C_BYTE_ORDER_BIG = 0 , MCP2221_I2C_BYTE_ORDER_LITTLE = 1 }
	Register-address byte order used by I2C slave register helpers. More...

Functions
mcp2221_error_code_t	mcp2221_i2c_slave_init (mcp2221_i2c_slave_t *slave, mcp2221_t *mcp, uint8_t addr, int force, uint32_t i2c_speed_hz, int reg_bytes, mcp2221_i2c_byte_order_t reg_byteorder)
	Initialize a caller-owned I2C target context. More...
mcp2221_error_code_t	mcp2221_i2c_slave_check_present (mcp2221_i2c_slave_t *slave, int *is_present)
	Check whether the configured I2C target acknowledges its address. More...
int	mcp2221_i2c_slave_is_present (mcp2221_i2c_slave_t *slave)
	Boolean-style convenience presence check. More...
mcp2221_error_code_t	mcp2221_i2c_slave_read_register (mcp2221_i2c_slave_t *slave, uint32_t reg, uint8_t *buffer, size_t length, int reg_bytes, mcp2221_i2c_byte_order_t reg_byteorder)
	Read bytes starting at a target register. More...
mcp2221_error_code_t	mcp2221_i2c_slave_read (mcp2221_i2c_slave_t *slave, uint8_t *buffer, size_t length)
	Read bytes directly from the configured I2C target. More...
mcp2221_error_code_t	mcp2221_i2c_slave_write_register (mcp2221_i2c_slave_t *slave, uint32_t reg, const uint8_t *data, size_t length, int reg_bytes, mcp2221_i2c_byte_order_t reg_byteorder)
	Write a register address followed by optional data. More...
mcp2221_error_code_t	mcp2221_i2c_slave_write (mcp2221_i2c_slave_t *slave, const uint8_t *data, size_t length)
	Write bytes directly to the configured I2C target. More...

Detailed Description

High-level helpers for communicating with an I2C target device.

Definition in file mcp2221_i2c_slave.h.

Enumeration Type Documentation

mcp2221_i2c_byte_order_t

enum mcp2221_i2c_byte_order_t

Register-address byte order used by I2C slave register helpers.

Enumerator
MCP2221_I2C_BYTE_ORDER_DEFAULT	Use the default byte order. During mcp2221_i2c_slave_init(), this resolves to big endian. For per-operation register helpers it resolves to the byte order stored in the slave context.
MCP2221_I2C_BYTE_ORDER_BIG	Encode register addresses most-significant byte first.
MCP2221_I2C_BYTE_ORDER_LITTLE	Encode register addresses least-significant byte first.

Definition at line 19 of file mcp2221_i2c_slave.h.

Function Documentation

mcp2221_i2c_slave_check_present()

mcp2221_error_code_t mcp2221_i2c_slave_check_present	(	mcp2221_i2c_slave_t *	slave,
		int *	is_present
	)

Check whether the configured I2C target acknowledges its address.

An address NACK is treated as a successful presence check with *is_present == 0. Transport, timeout, and other I2C failures are returned to the caller.

Parameters

[in]	slave	Initialized I2C target context.
[out]	is_present	Set to 1 when the target acknowledges and 0 when it NACKs its address. Must not be NULL.

Returns

MCP2221_ERR_OK when the presence check itself completed, including the NACK case, or another mcp2221_error_code_t value on failure.

Note

The presence probe uses a one-byte normal I2C read with a 50 ms transfer timeout.

mcp2221_i2c_slave_init()

mcp2221_error_code_t mcp2221_i2c_slave_init	(	mcp2221_i2c_slave_t *	slave,
		mcp2221_t *	mcp,
		uint8_t	addr,
		int	force,
		uint32_t	i2c_speed_hz,
		int	reg_bytes,
		mcp2221_i2c_byte_order_t	reg_byteorder
	)

Initialize a caller-owned I2C target context.

Configures the MCP2221 I2C clock and, unless force is nonzero, verifies that the target acknowledges its address. The context is committed only after all validation and setup steps succeed.

On failure, slave is left invalid with slave->mcp == NULL.

Parameters

[out]	slave	Caller-owned context to initialize. Must not be NULL.
[in]	mcp	Open MCP2221 device handle.
[in]	addr	7-bit I2C target address.
[in]	force	Nonzero to skip the initial presence check.
[in]	i2c_speed_hz	Requested I2C clock frequency in hertz.
[in]	reg_bytes	Default register-address width. Values less than or equal to 0 select 1 byte; valid explicit widths are 1 through 4 bytes.
[in]	reg_byteorder	Default register-address byte order. MCP2221_I2C_BYTE_ORDER_DEFAULT selects big endian.

Returns

MCP2221_ERR_OK on success. Returns MCP2221_ERR_NOT_ACK when the presence check is enabled and the target does not acknowledge, or another mcp2221_error_code_t value on failure.

mcp2221_i2c_slave_is_present()

int mcp2221_i2c_slave_is_present

(

mcp2221_i2c_slave_t *

slave

)

Boolean-style convenience presence check.

Parameters

[in]

slave

Initialized I2C target context.

Returns

1 when the target acknowledges its address, otherwise 0.

Warning

A return value of 0 does not distinguish an address NACK from transport, timeout, or other errors. Use mcp2221_i2c_slave_check_present() when the distinction matters.

mcp2221_i2c_slave_read()

mcp2221_error_code_t mcp2221_i2c_slave_read	(	mcp2221_i2c_slave_t *	slave,
		uint8_t *	buffer,
		size_t	length
	)

Read bytes directly from the configured I2C target.

Parameters

[in]	slave	Initialized I2C target context.
[out]	buffer	Buffer receiving the data.
[in]	length	Number of bytes to read. Must be from 1 to 256.

Returns

MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Note

Uses a normal I2C read with a 50 ms transfer timeout.

mcp2221_i2c_slave_read_register()

mcp2221_error_code_t mcp2221_i2c_slave_read_register	(	mcp2221_i2c_slave_t *	slave,
		uint32_t	reg,
		uint8_t *	buffer,
		size_t	length,
		int	reg_bytes,
		mcp2221_i2c_byte_order_t	reg_byteorder
	)

Read bytes starting at a target register.

Encodes reg using the selected register width and byte order, writes the register address without a STOP condition, then reads the requested data using a repeated START.

Parameters

[in]	slave	Initialized I2C target context.
[in]	reg	Register address to read from. The value must fit in the effective register-address width.
[out]	buffer	Buffer receiving the data.
[in]	length	Number of data bytes to read. Must be from 1 to 256.
[in]	reg_bytes	Register-address width for this operation. Values less than or equal to 0 use the context default; valid explicit widths are 1 through 4 bytes.
[in]	reg_byteorder	Byte order for this operation. MCP2221_I2C_BYTE_ORDER_DEFAULT uses the context default.

Returns

MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Note

The register write and repeated-start read each use a 50 ms transfer timeout.

mcp2221_i2c_slave_write()

mcp2221_error_code_t mcp2221_i2c_slave_write	(	mcp2221_i2c_slave_t *	slave,
		const uint8_t *	data,
		size_t	length
	)

Write bytes directly to the configured I2C target.

Parameters

[in]	slave	Initialized I2C target context.
[in]	data	Data to write.
[in]	length	Number of bytes to write. Must be from 1 to 256.

Returns

MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Note

Uses a normal I2C write with a 50 ms transfer timeout.

mcp2221_i2c_slave_write_register()

mcp2221_error_code_t mcp2221_i2c_slave_write_register	(	mcp2221_i2c_slave_t *	slave,
		uint32_t	reg,
		const uint8_t *	data,
		size_t	length,
		int	reg_bytes,
		mcp2221_i2c_byte_order_t	reg_byteorder
	)

Write a register address followed by optional data.

Encodes reg using the selected register width and byte order and sends the encoded register address followed by data in one normal I2C write.

Parameters

[in]	slave	Initialized I2C target context.
[in]	reg	Register address to write. The value must fit in the effective register-address width.
[in]	data	Data bytes to append after the register address. May be NULL when length is 0.
[in]	length	Number of data bytes to write. May be 0 and must not exceed 256.
[in]	reg_bytes	Register-address width for this operation. Values less than or equal to 0 use the context default; valid explicit widths are 1 through 4 bytes.
[in]	reg_byteorder	Byte order for this operation. MCP2221_I2C_BYTE_ORDER_DEFAULT uses the context default.

Returns

MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Note

Uses a normal I2C write with a 50 ms transfer timeout.