The ESP32 has one or two built-in I2C controller interfaces, this code provides a VFS interface that can be used by various I2C drivers to access the underlying I2C bus. More...

#include <Esp32HardwareI2C.hxx>

Inheritance diagram for openmrn_arduino::Esp32HardwareI2C:

Classes
struct	i2c_device_t
	Tracking structure used to map file handles to an I2C controller and address. More...

Public Member Functions
	Esp32HardwareI2C (const char *const path="/dev/i2c")
	Constructor.

	~Esp32HardwareI2C ()
	Destructor.

void	hw_init (const gpio_num_t sda, const gpio_num_t scl, const uint32_t bus_speed, const i2c_port_t port=I2C_NUM_0)
	Initializes the underlying I2C controller hardware and VFS interface.

void	scan (const i2c_port_t port)
	Utility method to perform a scan for all devices on the I2C bus.

ssize_t	write (int fd, const void *buf, size_t size)
	VFS implementation of write(fd, buf, size)

ssize_t	read (int fd, void *buf, size_t size)
	VFS implementation of read(fd, buf, size)

int	open (const char *path, int flags, int mode)
	VFS implementation of open(path, flags, mode).

int	close (int fd)
	VFS implementation of close(fd).

int	ioctl (int fd, int cmd, va_list args)
	VFS implementation of ioctl.

Private Member Functions
int	transfer_messages (const i2c_port_t port, struct i2c_msg *msgs, int num)
	Transfers multiple payloads to I2C devices.

Private Member Functions inherited from Atomic
void	lock ()

void	unlock ()

Private Attributes
const char *const	path_
	VFS Mount point.

std::vector< i2c_device_t >	devices_
	Collection of I2C devices that have been opened.

bool	i2cInitialized_ [SOC_I2C_NUM]
	Internal tracking for initialization of the underlying I2C hardware.

bool	vfsInitialized_ {false}
	Internal tracking for the VFS adapter layer.

Static Private Attributes
static constexpr TickType_t	I2C_OP_TIMEOUT = pdMS_TO_TICKS(1000)
	Timeout to use for I2C operations, default is one second.

static constexpr TickType_t	I2C_SCAN_TIMEOUT = pdMS_TO_TICKS(50)
	Timeout to use for I2C device scanning, default is 50 milliseconds.

static constexpr int	I2C_ISR_FLAGS = ESP_INTR_FLAG_SHARED
	ISR flags to use for I2C, this defaults to allowing usage of a shared interupt.

static constexpr size_t	I2C_SLAVE_RX_BUF_SIZE = 0
	I2C "Slave" RX buffer size, we do not use/support this feature so it is set to zero.

static constexpr size_t	I2C_SLAVE_TX_BUF_SIZE = 0
	I2C "Slave" TX buffer size, we do not use/support this feature so it is set to zero.

Detailed Description

The ESP32 has one or two built-in I2C controller interfaces, this code provides a VFS interface that can be used by various I2C drivers to access the underlying I2C bus.

Only one instance of this class should be created in the application so the memory overhead is minimized and performance of the VFS minimally impacted.

Example usage (scanner):

Esp32HardwareI2C i2c;
 
void setup()
{
  i2c.hw_init(GPIO_NUM_4, GPIO_NUM_5, 100000);
  i2c.scan();
}

Example usage (MCP23017):

Esp32HardwareI2C i2c;
Executor<1> io_executor("io_thread", 1, 1300);
MCP23017 expander(&io_executor, 0, 0, 0);
 
void setup()
{
  i2c.hw_init(GPIO_NUM_4, GPIO_NUM_5, 100000);
  expander.init("/dev/i2c/0");
  ...
}

Definition at line 82 of file Esp32HardwareI2C.hxx.

Constructor & Destructor Documentation

◆ Esp32HardwareI2C()

openmrn_arduino::Esp32HardwareI2C::Esp32HardwareI2C ( const char *const path = "/dev/i2c" )

Constructor.

Parameters

path	Base path to use for I2C drivers.

Member Function Documentation

◆ close()

int openmrn_arduino::Esp32HardwareI2C::close ( int fd )

VFS implementation of close(fd).

Parameters

fd	is the file descriptor to close.

When this method is invoked it will disable the TWAI driver and stop the periodic timer used for RX/TX of frame data if it is running.

Returns: zero upon success, negative value with errno for failure.

◆ hw_init()

void openmrn_arduino::Esp32HardwareI2C::hw_init	(	const gpio_num_t	sda,
		const gpio_num_t	scl,
		const uint32_t	bus_speed,
		const i2c_port_t	port = `I2C_NUM_0`
	)

Initializes the underlying I2C controller hardware and VFS interface.

Parameters

sda	GPIO pin to use for I2C data transfer.
scl	GPIO pin to use for I2C clock.
bus_speed	I2C clock frequency.
port	I2C controller to initialize.

For hardware which supports more than one I2C controller, this method must be called once per controller being used.

NOTE: This must be called prior to usage of any other methods for each I2C controller being used.

◆ ioctl()

int openmrn_arduino::Esp32HardwareI2C::ioctl	(	int	fd,
		int	cmd,
		va_list	args
	)

VFS implementation of ioctl.

Parameters

fd	is the file descriptor to operate on.
cmd	is the command to execute.
args	is the args for the command.

Returns: zero upon success, negative value with errno for failure.

◆ open()

int openmrn_arduino::Esp32HardwareI2C::open	(	const char *	path,
		int	flags,
		int	mode
	)

VFS implementation of open(path, flags, mode).

Parameters

path	is the path to the file being opened.
flags	are the flags to use for opened file.
mode	is the mode to use for the opened file.

When this method is invoked it will enable the TWAI driver and start the periodic timer used for RX/TX of frame data.

Returns: 0 upon success, -1 upon failure with errno containing the cause.

◆ read()

ssize_t openmrn_arduino::Esp32HardwareI2C::read	(	int	fd,
		void *	buf,
		size_t	size
	)

VFS implementation of read(fd, buf, size)

Parameters

fd	is the file descriptor being read from.
buf	is the buffer to write into.
size	is the size of the buffer.

Returns: number of bytes read or -1 if there is the read would be a blocking operation.

◆ scan()

void openmrn_arduino::Esp32HardwareI2C::scan ( const i2c_port_t port )

Utility method to perform a scan for all devices on the I2C bus.

Parameters

port	Hardware I2C controller port number to use for scanning.

NOTE: The hw_init method must have been run prior to calling this method. Failure to do so will result in an error being raised.

◆ transfer_messages()

int openmrn_arduino::Esp32HardwareI2C::transfer_messages	(	const i2c_port_t	port,
		struct i2c_msg *	msgs,
		int	num
	)

private

Transfers multiple payloads to I2C devices.

Parameters

port	Underlying i2c_port_t to use for I2C transfers.
msgs	payloads to be transfered, this includes the target device address, data to transfer and length of data.
num	Number of transfers to perform.

Returns: Number of bytes transfered or an error code (negative value).

◆ write()

ssize_t openmrn_arduino::Esp32HardwareI2C::write	(	int	fd,
		const void *	buf,
		size_t	size
	)

VFS implementation of write(fd, buf, size)

Parameters

fd	is the file descriptor being written to.
buf	is the buffer containing the data to be written.
size	is the size of the buffer.

Returns: number of bytes written or -1 if there is the write would be a blocking operation.

NOTE: The provided fd is used internally to determine which I2C controller should be used and the address to write the data to. If the address has not been set

Member Data Documentation

◆ devices_

std::vector<i2c_device_t> openmrn_arduino::Esp32HardwareI2C::devices_

private

Collection of I2C devices that have been opened.

Definition at line 207 of file Esp32HardwareI2C.hxx.

◆ I2C_ISR_FLAGS

constexpr int openmrn_arduino::Esp32HardwareI2C::I2C_ISR_FLAGS = ESP_INTR_FLAG_SHARED

staticconstexprprivate

ISR flags to use for I2C, this defaults to allowing usage of a shared interupt.

Definition at line 182 of file Esp32HardwareI2C.hxx.

◆ I2C_OP_TIMEOUT

constexpr TickType_t openmrn_arduino::Esp32HardwareI2C::I2C_OP_TIMEOUT = pdMS_TO_TICKS(1000)

staticconstexprprivate

Timeout to use for I2C operations, default is one second.

Definition at line 175 of file Esp32HardwareI2C.hxx.

◆ I2C_SCAN_TIMEOUT

constexpr TickType_t openmrn_arduino::Esp32HardwareI2C::I2C_SCAN_TIMEOUT = pdMS_TO_TICKS(50)

staticconstexprprivate

Timeout to use for I2C device scanning, default is 50 milliseconds.

Definition at line 178 of file Esp32HardwareI2C.hxx.

◆ I2C_SLAVE_RX_BUF_SIZE

constexpr size_t openmrn_arduino::Esp32HardwareI2C::I2C_SLAVE_RX_BUF_SIZE = 0

staticconstexprprivate

I2C "Slave" RX buffer size, we do not use/support this feature so it is set to zero.

Definition at line 186 of file Esp32HardwareI2C.hxx.

◆ I2C_SLAVE_TX_BUF_SIZE

constexpr size_t openmrn_arduino::Esp32HardwareI2C::I2C_SLAVE_TX_BUF_SIZE = 0

staticconstexprprivate

I2C "Slave" TX buffer size, we do not use/support this feature so it is set to zero.

Definition at line 190 of file Esp32HardwareI2C.hxx.

◆ i2cInitialized_

bool openmrn_arduino::Esp32HardwareI2C::i2cInitialized_[SOC_I2C_NUM]

private

Internal tracking for initialization of the underlying I2C hardware.

Definition at line 210 of file Esp32HardwareI2C.hxx.

◆ path_

const char* const openmrn_arduino::Esp32HardwareI2C::path_

private

VFS Mount point.

Definition at line 172 of file Esp32HardwareI2C.hxx.

◆ vfsInitialized_

bool openmrn_arduino::Esp32HardwareI2C::vfsInitialized_ {false}

private

Internal tracking for the VFS adapter layer.

Definition at line 213 of file Esp32HardwareI2C.hxx.

The documentation for this class was generated from the following file:

Esp32HardwareI2C.hxx

Classes

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Esp32HardwareI2C()

Member Function Documentation

◆ close()

◆ hw_init()

◆ ioctl()

◆ open()

◆ read()

◆ scan()

◆ transfer_messages()

◆ write()

Member Data Documentation

◆ devices_

◆ I2C_ISR_FLAGS

◆ I2C_OP_TIMEOUT

◆ I2C_SCAN_TIMEOUT

◆ I2C_SLAVE_RX_BUF_SIZE

◆ I2C_SLAVE_TX_BUF_SIZE

◆ i2cInitialized_

◆ path_

◆ vfsInitialized_