Core MCP2221 device and I2C master API. More...

#include <stddef.h>
#include <stdint.h>
#include "mcp2221_export.h"
#include "mcp2221_error_codes.h"
#include "mcp2221_errors.h"

Include dependency graph for mcp2221.h:

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

Go to the source code of this file.

Classes
struct	mcp2221_i2c_status_t
	Snapshot of the MCP2221 I2C engine status. More...

struct	mcp2221_revision_t
	MCP2221 hardware and firmware revision. More...

Typedefs
typedef struct mcp2221_device	mcp2221_t
	Opaque MCP2221 device handle. More...

typedef struct mcp2221_i2c_slave	mcp2221_i2c_slave_t
	Caller-owned high-level I2C slave context. More...

Enumerations
enum	mcp2221_i2c_kind_t { MCP2221_I2C_KIND_NORMAL = 0 , MCP2221_I2C_KIND_REPEATED_START = 1 , MCP2221_I2C_KIND_NO_STOP = 2 }
	I2C transfer kind. More...

Functions
mcp2221_error_code_t	mcp2221_open (uint16_t vid, uint16_t pid, int devnum, const char usbserial, int usb_read_timeout_ms, int cmd_retries, int debug_messages, int trace_packets, mcp2221_t *out_dev)
	Open an MCP2221 device. More...

mcp2221_error_code_t	mcp2221_open_scan (uint16_t vid, uint16_t pid, int devnum, const char usbserial, int usb_read_timeout_ms, int cmd_retries, int debug_messages, int trace_packets, int scan_serial, mcp2221_t *out_dev)
	Open an MCP2221 device, optionally scanning the flash serial number. More...

mcp2221_error_code_t	mcp2221_open_simple (uint16_t vid, uint16_t pid, int devnum, const char usbserial, int i2c_speed_hz, mcp2221_t *out_dev)
	Open and initialize an MCP2221 using an EasyMCP2221-style setup. More...

mcp2221_error_code_t	mcp2221_open_simple_scan (uint16_t vid, uint16_t pid, int devnum, const char usbserial, int i2c_speed_hz, int scan_serial, mcp2221_t *out_dev)
	Open and initialize an MCP2221 with optional flash-serial scanning. More...

void	mcp2221_close (mcp2221_t *dev)
	Close an MCP2221 device handle. More...

mcp2221_error_code_t	mcp2221_reset (mcp2221_t *dev)
	Reset the MCP2221. More...

mcp2221_error_code_t	mcp2221_send_cmd (mcp2221_t dev, const uint8_t buf, size_t len, uint8_t *response)
	Send a raw MCP2221 command. More...

mcp2221_error_code_t	mcp2221_i2c_set_speed (mcp2221_t *dev, uint32_t i2c_speed_hz)
	Set the I2C bus clock frequency. More...

mcp2221_error_code_t	mcp2221_i2c_write_ex (mcp2221_t dev, uint8_t addr, const uint8_t data, size_t len, mcp2221_i2c_kind_t kind, int i2c_timeout_ms)
	Write data to an I2C device with an explicit transfer timeout. More...

mcp2221_error_code_t	mcp2221_i2c_write_simple (mcp2221_t dev, uint8_t addr, const uint8_t data, size_t len, mcp2221_i2c_kind_t kind)
	Write data to an I2C device using the default transfer timeout. More...

mcp2221_error_code_t	mcp2221_i2c_read_ex (mcp2221_t dev, uint8_t addr, uint8_t data, size_t len, mcp2221_i2c_kind_t kind, int i2c_timeout_ms)
	Read data from an I2C device with an explicit transfer timeout. More...

mcp2221_error_code_t	mcp2221_i2c_read_simple (mcp2221_t dev, uint8_t addr, uint8_t data, size_t len, mcp2221_i2c_kind_t kind)
	Read data from an I2C device using the default transfer timeout. More...

mcp2221_error_code_t	mcp2221_i2c_status (mcp2221_t dev, mcp2221_i2c_status_t st)
	Read the current MCP2221 I2C engine status. More...

mcp2221_error_code_t	mcp2221_revision (mcp2221_t dev, mcp2221_revision_t revision)
	Read the MCP2221 hardware and firmware revision. More...

mcp2221_error_code_t	mcp2221_i2c_release (mcp2221_t *dev)
	Release the MCP2221 I2C engine. More...

Detailed Description

Core MCP2221 device and I2C master API.

Definition in file mcp2221.h.

Typedef Documentation

◆ mcp2221_i2c_slave_t

typedef struct mcp2221_i2c_slave mcp2221_i2c_slave_t

Caller-owned high-level I2C slave context.

The structure is defined in mcp2221_i2c_slave.h so callers may allocate it statically, on the stack, or as part of another structure. Initialize it with mcp2221_i2c_slave_init().

Definition at line 37 of file mcp2221.h.

◆ mcp2221_t

typedef struct mcp2221_device mcp2221_t

Opaque MCP2221 device handle.

Device handles are created by the mcp2221_open*() family and released with mcp2221_close().

Warning: Operations on the same device handle are not internally serialized. Applications that access one mcp2221_t from multiple threads must provide their own synchronization around I2C, GPIO, flash, and other device operations.

Definition at line 28 of file mcp2221.h.

Enumeration Type Documentation

◆ mcp2221_i2c_kind_t

enum mcp2221_i2c_kind_t

I2C transfer kind.

Enumerator
MCP2221_I2C_KIND_NORMAL	Normal transfer.
MCP2221_I2C_KIND_REPEATED_START	Transfer using a repeated START.
MCP2221_I2C_KIND_NO_STOP	Write without a STOP condition.

Definition at line 69 of file mcp2221.h.

Function Documentation

◆ mcp2221_close()

void mcp2221_close ( mcp2221_t * dev )

Close an MCP2221 device handle.

Releases one reference acquired through the mcp2221_open*() family.

Parameters

[in] dev Device handle to close, or NULL.

Note: Passing NULL is allowed and has no effect.

See also: mcp2221_open()

◆ mcp2221_i2c_read_ex()

mcp2221_error_code_t mcp2221_i2c_read_ex	(	mcp2221_t *	dev,
		uint8_t	addr,
		uint8_t *	data,
		size_t	len,
		mcp2221_i2c_kind_t	kind,
		int	i2c_timeout_ms
	)

Read data from an I2C device with an explicit transfer timeout.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	addr	7-bit I2C device address.
[out]	data	Buffer receiving the read data.
[in]	len	Number of bytes to read. Must be between 1 and MCP2221_I2C_TRANSFER_MAX.
[in]	kind	I2C transfer kind.
[in]	i2c_timeout_ms	Progress watchdog timeout in milliseconds. Values less than or equal to zero select a 20 ms watchdog. The watchdog is restarted only when read data is received, so it is not a hard timeout for the complete transfer.

Returns: MCP2221_ERR_OK on success. A documented GET_I2C_DATA error indication is returned as MCP2221_ERR_I2C; a malformed GET_I2C_DATA response is returned as MCP2221_ERR_PROTOCOL. Other failures return the corresponding mcp2221_error_code_t value.

Note: kind may be MCP2221_I2C_KIND_NORMAL or MCP2221_I2C_KIND_REPEATED_START.

◆ mcp2221_i2c_read_simple()

mcp2221_error_code_t mcp2221_i2c_read_simple	(	mcp2221_t *	dev,
		uint8_t	addr,
		uint8_t *	data,
		size_t	len,
		mcp2221_i2c_kind_t	kind
	)

Read data from an I2C device using the default transfer timeout.

Uses the device's configured USB read timeout as the I2C watchdog when it is positive; otherwise a 20 ms watchdog is used.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	addr	7-bit I2C device address.
[out]	data	Buffer receiving the read data.
[in]	len	Number of bytes to read. Must be between 1 and MCP2221_I2C_TRANSFER_MAX.
[in]	kind	I2C transfer kind.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

See also: mcp2221_i2c_read_ex()

◆ mcp2221_i2c_release()

mcp2221_error_code_t mcp2221_i2c_release ( mcp2221_t * dev )

Release the MCP2221 I2C engine.

Parameters

[in] dev Open MCP2221 device handle.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_i2c_set_speed()

mcp2221_error_code_t mcp2221_i2c_set_speed	(	mcp2221_t *	dev,
		uint32_t	i2c_speed_hz
	)

Set the I2C bus clock frequency.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	i2c_speed_hz	Requested I2C clock frequency in hertz. Must be greater than zero, no greater than MCP2221_I2C_SPEED_MAX_HZ, and representable by the MCP2221 8-bit I2C clock divider.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_i2c_status()

mcp2221_error_code_t mcp2221_i2c_status	(	mcp2221_t *	dev,
		mcp2221_i2c_status_t *	st
	)

Read the current MCP2221 I2C engine status.

Parameters

[in]	dev	Open MCP2221 device handle.
[out]	st	Receives the I2C engine status snapshot.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_i2c_write_ex()

mcp2221_error_code_t mcp2221_i2c_write_ex	(	mcp2221_t *	dev,
		uint8_t	addr,
		const uint8_t *	data,
		size_t	len,
		mcp2221_i2c_kind_t	kind,
		int	i2c_timeout_ms
	)

Write data to an I2C device with an explicit transfer timeout.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	addr	7-bit I2C device address.
[in]	data	Data to write.
[in]	len	Number of bytes to write. Must be between 1 and MCP2221_I2C_TRANSFER_MAX.
[in]	kind	I2C transfer kind.
[in]	i2c_timeout_ms	Per-chunk/progress watchdog timeout in milliseconds. Values less than or equal to zero select a 20 ms watchdog. This is not a hard timeout for the complete multi-chunk transfer.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Note: kind may be MCP2221_I2C_KIND_NORMAL, MCP2221_I2C_KIND_REPEATED_START, or MCP2221_I2C_KIND_NO_STOP.

◆ mcp2221_i2c_write_simple()

mcp2221_error_code_t mcp2221_i2c_write_simple	(	mcp2221_t *	dev,
		uint8_t	addr,
		const uint8_t *	data,
		size_t	len,
		mcp2221_i2c_kind_t	kind
	)

Write data to an I2C device using the default transfer timeout.

Uses the device's configured USB read timeout as the I2C watchdog when it is positive; otherwise a 20 ms watchdog is used.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	addr	7-bit I2C device address.
[in]	data	Data to write.
[in]	len	Number of bytes to write. Must be between 1 and MCP2221_I2C_TRANSFER_MAX.
[in]	kind	I2C transfer kind.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

See also: mcp2221_i2c_write_ex()

◆ mcp2221_open()

mcp2221_error_code_t mcp2221_open	(	uint16_t	vid,
		uint16_t	pid,
		int	devnum,
		const char *	usbserial,
		int	usb_read_timeout_ms,
		int	cmd_retries,
		int	debug_messages,
		int	trace_packets,
		mcp2221_t **	out_dev
	)

Open an MCP2221 device.

Opens the matching device or acquires another reference to an already open matching device.

When a matching device is already open, the existing device context is returned and its reference count is increased. In that case the usb_read_timeout_ms, cmd_retries, debug_messages, and trace_packets values from this call do not replace the settings stored in the existing context.

Each successful call must be matched by a call to mcp2221_close().

Parameters

[in]	vid	USB vendor ID. The MCP2221 default is 0x04D8.
[in]	pid	USB product ID. The MCP2221 default is 0x00DD.
[in]	devnum	Device index when multiple matching devices are present. Use 0 for the first matching device.
[in]	usbserial	USB serial number to match, or `NULL` to ignore the USB serial number.
[in]	usb_read_timeout_ms	USB read timeout in milliseconds. Values less than or equal to zero disable the USB read timeout.
[in]	cmd_retries	Number of retries used by operations whose commands are safe to repeat. Negative values are treated as 0. Mutating commands are not generically retried because a lost response does not prove that the device did not execute the command.
[in]	debug_messages	Nonzero to enable debug messages.
[in]	trace_packets	Nonzero to enable USB packet tracing.
[out]	out_dev	Receives the device handle on success. Must not be `NULL`. `*out_dev` is set to `NULL` before opening is attempted.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

See also: mcp2221_close()

◆ mcp2221_open_scan()

mcp2221_error_code_t mcp2221_open_scan	(	uint16_t	vid,
		uint16_t	pid,
		int	devnum,
		const char *	usbserial,
		int	usb_read_timeout_ms,
		int	cmd_retries,
		int	debug_messages,
		int	trace_packets,
		int	scan_serial,
		mcp2221_t **	out_dev
	)

Open an MCP2221 device, optionally scanning the flash serial number.

This variant can scan the MCP2221 flash serial number when the USB serial is not enumerated.

Parameters

[in]	vid	USB vendor ID.
[in]	pid	USB product ID.
[in]	devnum	Device index when multiple matching devices are present.
[in]	usbserial	USB serial number to match, or `NULL` to ignore it.
[in]	usb_read_timeout_ms	USB read timeout in milliseconds. Values less than or equal to zero disable the USB read timeout.
[in]	cmd_retries	Number of retries used by operations whose commands are safe to repeat. Negative values are treated as 0. Mutating commands are not generically retried because a lost response does not prove that the device did not execute the command.
[in]	debug_messages	Nonzero to enable debug messages.
[in]	trace_packets	Nonzero to enable USB packet tracing.
[in]	scan_serial	Nonzero to enable flash-serial scanning.
[out]	out_dev	Receives the device handle on success. Must not be `NULL`. `*out_dev` is set to `NULL` before opening is attempted.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

See also: mcp2221_open()

◆ mcp2221_open_simple()

mcp2221_error_code_t mcp2221_open_simple	(	uint16_t	vid,
		uint16_t	pid,
		int	devnum,
		const char *	usbserial,
		int	i2c_speed_hz,
		mcp2221_t **	out_dev
	)

Open and initialize an MCP2221 using an EasyMCP2221-style setup.

The supplied I2C clock speed is applied during initialization.

Parameters

[in]	vid	USB vendor ID.
[in]	pid	USB product ID.
[in]	devnum	Device index when multiple matching devices are present.
[in]	usbserial	USB serial number to match, or `NULL` to ignore it.
[in]	i2c_speed_hz	Requested I2C clock frequency in hertz. Values greater than MCP2221_I2C_SPEED_MAX_HZ are invalid; values less than or equal to zero select 100 kHz.
[out]	out_dev	Receives the device handle on success. Must not be `NULL`. `*out_dev` is set to `NULL` before opening is attempted.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_open_simple_scan()

mcp2221_error_code_t mcp2221_open_simple_scan	(	uint16_t	vid,
		uint16_t	pid,
		int	devnum,
		const char *	usbserial,
		int	i2c_speed_hz,
		int	scan_serial,
		mcp2221_t **	out_dev
	)

Open and initialize an MCP2221 with optional flash-serial scanning.

Parameters

[in]	vid	USB vendor ID.
[in]	pid	USB product ID.
[in]	devnum	Device index when multiple matching devices are present.
[in]	usbserial	USB serial number to match, or `NULL` to ignore it.
[in]	i2c_speed_hz	Requested I2C clock frequency in hertz. Values greater than MCP2221_I2C_SPEED_MAX_HZ are invalid; values less than or equal to zero select 100 kHz.
[in]	scan_serial	Nonzero to enable flash-serial scanning.
[out]	out_dev	Receives the device handle on success. Must not be `NULL`. `*out_dev` is set to `NULL` before opening is attempted.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

See also: mcp2221_open_simple(); mcp2221_open_scan()

◆ mcp2221_reset()

mcp2221_error_code_t mcp2221_reset ( mcp2221_t * dev )

Reset the MCP2221.

Sends the documented MCP2221 reset command. A successful return means the reset command was written to the USB endpoint; the device disconnects before a normal command response can be read.

The device handle must be closed after this call. Applications that need to continue using the device must wait for USB re-enumeration and open it again.

Parameters

[in] dev Open MCP2221 device handle.

Returns: MCP2221_ERR_OK when the reset command was sent successfully, or another mcp2221_error_code_t value on failure.

◆ mcp2221_revision()

mcp2221_error_code_t mcp2221_revision	(	mcp2221_t *	dev,
		mcp2221_revision_t *	revision
	)

Read the MCP2221 hardware and firmware revision.

The revision bytes are returned by the MCP2221 status command. This mirrors EasyMCP2221's revision() functionality without formatting or interpreting the device-provided major/minor values.

Parameters

[in]	dev	Open MCP2221 device handle.
[out]	revision	Receives hardware and firmware major/minor revisions.

Returns: MCP2221_ERR_OK on success, MCP2221_ERR_INVALID for invalid arguments, or another mcp2221_error_code_t value on transport or command failure.

◆ mcp2221_send_cmd()

mcp2221_error_code_t mcp2221_send_cmd	(	mcp2221_t *	dev,
		const uint8_t *	buf,
		size_t	len,
		uint8_t *	response
	)

Send a raw MCP2221 command.

Commands shorter than MCP2221_PACKET_SIZE are padded internally before transmission.

Parameters

[in]	dev	Open MCP2221 device handle.
[in]	buf	Command bytes to send.
[in]	len	Number of command bytes. Must be between 1 and MCP2221_PACKET_SIZE.
[out]	response	Optional buffer receiving the complete MCP2221_PACKET_SIZE-byte response. When non-`NULL`, the buffer must provide room for at least MCP2221_PACKET_SIZE bytes.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ mcp2221_i2c_slave_t

◆ mcp2221_t

Enumeration Type Documentation

◆ mcp2221_i2c_kind_t

Function Documentation

◆ mcp2221_close()

◆ mcp2221_i2c_read_ex()

◆ mcp2221_i2c_read_simple()

◆ mcp2221_i2c_release()

◆ mcp2221_i2c_set_speed()

◆ mcp2221_i2c_status()

◆ mcp2221_i2c_write_ex()

◆ mcp2221_i2c_write_simple()

◆ mcp2221_open()

◆ mcp2221_open_scan()

◆ mcp2221_open_simple()

◆ mcp2221_open_simple_scan()

◆ mcp2221_reset()

◆ mcp2221_revision()

◆ mcp2221_send_cmd()