smbus.h File Reference

Interface definitions for the ESP32-compatible SMBus Protocol component. More...

#include <stdbool.h>
#include "driver/i2c.h"

Go to the source code of this file.

Data Structures
struct	smbus_info_t
	Structure containing information related to the SMBus protocol. More...

Macros
#define	SMBUS_DEFAULT_TIMEOUT   (1000 / portTICK_RATE_MS)
	Default transaction timeout in ticks.

Typedefs
typedef uint16_t	i2c_address_t
	7-bit or 10-bit I2C slave address.

Functions
smbus_info_t *	smbus_malloc (void)
	Construct a new SMBus info instance. New instance should be initialised before calling other functions. More...
void	smbus_free (smbus_info_t **smbus_info)
	Delete an existing SMBus info instance. More...
esp_err_t	smbus_init (smbus_info_t *smbus_info, i2c_port_t i2c_port, i2c_address_t address)
	Initialise a SMBus info instance with the specified I2C information. The I2C timeout defaults to approximately 1 second. More...
esp_err_t	smbus_set_timeout (smbus_info_t *smbus_info, portBASE_TYPE timeout)
	Set the I2C timeout. I2C transactions that do not complete within this period are considered an error. More...
esp_err_t	smbus_quick (const smbus_info_t *smbus_info, bool bit)
	Send a single bit to a slave device in the place of the read/write bit. May be used to simply turn a device function on or off, or enable or disable a low-power standby mode. There is no data sent or received. More...
esp_err_t	smbus_send_byte (const smbus_info_t *smbus_info, uint8_t data)
	Send a single byte to a slave device. More...
esp_err_t	smbus_receive_byte (const smbus_info_t *smbus_info, uint8_t *data)
	Receive a single byte from a slave device. More...
esp_err_t	smbus_write_byte (const smbus_info_t *smbus_info, uint8_t command, uint8_t data)
	Write a single byte to a slave device with a command code. More...
esp_err_t	smbus_write_word (const smbus_info_t *smbus_info, uint8_t command, uint16_t data)
	Write a single word (two bytes) to a slave device with a command code. The least significant byte is transmitted first. More...
esp_err_t	smbus_read_byte (const smbus_info_t *smbus_info, uint8_t command, uint8_t *data)
	Read a single byte from a slave device with a command code. More...
esp_err_t	smbus_read_word (const smbus_info_t *smbus_info, uint8_t command, uint16_t *data)
	Read a single word (two bytes) from a slave device with a command code. The first byte received is the least significant byte. More...
esp_err_t	smbus_write_block (const smbus_info_t *smbus_info, uint8_t command, uint8_t *data, uint8_t len)
	Write up to 255 bytes to a slave device with a command code. This uses a byte count to negotiate the length of the transaction. The first byte in the data array is transmitted first. More...
esp_err_t	smbus_read_block (const smbus_info_t *smbus_info, uint8_t command, uint8_t *data, uint8_t *len)
	Read up to 255 bytes from a slave device with a command code. This uses a byte count to negotiate the length of the transaction. The first byte received is placed in the first array location. More...
esp_err_t	smbus_i2c_write_block (const smbus_info_t *smbus_info, uint8_t command, uint8_t *data, size_t len)
	Write bytes to a slave device with a command code. No byte count is used - the transaction lasts as long as the master requires. The first byte in the data array is transmitted first. This operation is not defined by the SMBus specification. More...
esp_err_t	smbus_i2c_read_block (const smbus_info_t *smbus_info, uint8_t command, uint8_t *data, size_t len)
	Read bytes from a slave device with a command code (combined format). No byte count is used - the transaction lasts as long as the master requires. The first byte received is placed in the first array location. This operation is not defined by the SMBus specification. More...

Detailed Description

Interface definitions for the ESP32-compatible SMBus Protocol component.

This component provides structures and functions that are useful for communicating with SMBus-compatible I2C slave devices.

Function Documentation

smbus_info_t* smbus_malloc

(

void

)

Construct a new SMBus info instance. New instance should be initialised before calling other functions.

Returns

Pointer to new device info instance, or NULL if it cannot be created.

void smbus_free

(

smbus_info_t **

smbus_info

)

Delete an existing SMBus info instance.

Parameters

[in,out]

smbus_info

Pointer to SMBus info instance that will be freed and set to NULL.

esp_err_t smbus_init	(	smbus_info_t *	smbus_info,
		i2c_port_t	i2c_port,
		i2c_address_t	address
	)

Initialise a SMBus info instance with the specified I2C information. The I2C timeout defaults to approximately 1 second.

Parameters

[in]	smbus_info	Pointer to SMBus info instance.
[in]	i2c_port	I2C port to associate with this SMBus instance.
[in]	address	Address of I2C slave device.

esp_err_t smbus_set_timeout	(	smbus_info_t *	smbus_info,
		portBASE_TYPE	timeout
	)

Set the I2C timeout. I2C transactions that do not complete within this period are considered an error.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	timeout	Number of ticks to wait until the transaction is considered in error.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_quick	(	const smbus_info_t *	smbus_info,
		bool	bit
	)

Send a single bit to a slave device in the place of the read/write bit. May be used to simply turn a device function on or off, or enable or disable a low-power standby mode. There is no data sent or received.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	bit	Data bit to send.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_send_byte	(	const smbus_info_t *	smbus_info,
		uint8_t	data
	)

Send a single byte to a slave device.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	data	Data byte to send to slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_receive_byte	(	const smbus_info_t *	smbus_info,
		uint8_t *	data
	)

Receive a single byte from a slave device.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[out]	data	Data byte received from slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_write_byte	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t	data
	)

Write a single byte to a slave device with a command code.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[in]	data	Data byte to send to slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_write_word	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint16_t	data
	)

Write a single word (two bytes) to a slave device with a command code. The least significant byte is transmitted first.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[in]	data	Data word to send to slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_read_byte	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t *	data
	)

Read a single byte from a slave device with a command code.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[out]	data	Data byte received from slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_read_word	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint16_t *	data
	)

Read a single word (two bytes) from a slave device with a command code. The first byte received is the least significant byte.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[out]	data	Data byte received from slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_write_block	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t *	data,
		uint8_t	len
	)

Write up to 255 bytes to a slave device with a command code. This uses a byte count to negotiate the length of the transaction. The first byte in the data array is transmitted first.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[in]	data	Data bytes to send to slave.
[in]	len	Number of bytes to send to slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_read_block	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t *	data,
		uint8_t *	len
	)

Read up to 255 bytes from a slave device with a command code. This uses a byte count to negotiate the length of the transaction. The first byte received is placed in the first array location.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[out]	data	Data bytes received from slave.
	in/out]	len Size of data array, and number of bytes actually received.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_i2c_write_block	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t *	data,
		size_t	len
	)

Write bytes to a slave device with a command code. No byte count is used - the transaction lasts as long as the master requires. The first byte in the data array is transmitted first. This operation is not defined by the SMBus specification.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[in]	data	Data bytes to send to slave.
[in]	len	Number of bytes to send to slave.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t smbus_i2c_read_block	(	const smbus_info_t *	smbus_info,
		uint8_t	command,
		uint8_t *	data,
		size_t	len
	)

Read bytes from a slave device with a command code (combined format). No byte count is used - the transaction lasts as long as the master requires. The first byte received is placed in the first array location. This operation is not defined by the SMBus specification.

Parameters

[in]	smbus_info	Pointer to initialised SMBus info instance.
[in]	command	Device-specific command byte.
[out]	data	Data bytes received from slave.
	in/out]	len Size of data array. If the slave fails to provide sufficient bytes, ESP_ERR_TIMEOUT will be returned.

Returns

ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.