Hardware abstraction and low-level utilities. More...

#include "InternalTypes.hpp"
#include "SimWheelTypes.hpp"
#include "driver/i2c_types.h"
#include "driver/i2c_master.h"

Classes
class	i2c_error
	Exception for I2C bus initialization failure. More...

class	i2c_device_not_found
	Exception for I2C devices not found. More...

class	i2c_full_address_unknown
	Exception for unknown full I2C address. More...

Macros
#define	AS_GPIO(pin)
	Cast GPIO to an ESP32 pin number.

#define	AS_PORT(bus)
	Cast I2CBus to an ESP32 port number.

#define	GPIO_SET_LEVEL(pin, level)
	Macro to write a logic level in a GPIO pin.

#define	I2C_SLAVE(dev)
	Cast to an I2C slave device handle.

#define	GPIO_GET_LEVEL(pin)
	Macro to read the logic level in a GPIO pin.

#define	DELAY_TICKS(ticks)
	Macro to wait in tick units.

#define	DELAY_MS(ms)
	Macro to wait in millisecond units.

#define	NS_PER_LOOP ((4000 + CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ - 1) / CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ)
	Time per loop of active_wait_ns() computed as 4 CPU instructions.

#define	active_wait_ns(n)
	Active wait without context switching.

Typedefs
typedef void(*	ISRHandler) (void *arg)
	Interrupt Service Routine.

Functions
void	internals::hal::i2c::initialize (GPIO sda, GPIO scl, I2CBus bus, bool enableInternalPullup=true)
	Initialize an I2C bus to certain pins.

void	internals::hal::i2c::require (I2CBus bus=I2CBus::PRIMARY)
	Ensure the I2C bus is initialized.

i2c_master_dev_handle_t	internals::hal::i2c::add_device (uint8_t address7bits, uint8_t max_speed_multiplier, I2CBus bus)
	Add an slave device ensuring the bus is initialized.

void	internals::hal::i2c::remove_device (i2c_master_dev_handle_t i2c_device)
	Remove an slave device.

bool	internals::hal::i2c::probe (uint8_t address7bits, I2CBus bus=I2CBus::PRIMARY)
	Check slave device availability on an I2C bus.

void	internals::hal::i2c::probe (std::vector< uint8_t > &result, I2CBus bus=I2CBus::PRIMARY)
	Retrieve all devices available on an I2C bus.

void	internals::hal::i2c::abortOnInvalidAddress (uint8_t address7bits, uint8_t minAddress=0, uint8_t maxAddress=127)
	Abort and reboot on an invalid I2C address.

uint8_t	internals::hal::i2c::findFullAddress (std::vector< uint8_t > &fullAddressList, uint8_t hardwareAddress, uint8_t hardwareAddressMask=0b00000111)
	Find the full address of a device.

int	internals::hal::gpio::getADCreading (ADC_GPIO pin, int sampleCount=1)
	Get the mean of some continuous ADC readings.

void	internals::hal::gpio::forOutput (OutputGPIO pin, bool initialLevel, bool openDrain)
	Configure a pin for output.

void	internals::hal::gpio::forInput (InputGPIO pin, bool enablePullDown, bool enablePullUp)
	Configure a pin for digital input.

void	internals::hal::gpio::enableISR (InputGPIO pin, ISRHandler handler, void *param=nullptr)
	Enable an interrupt service routine.

Detailed Description

Hardware abstraction and low-level utilities.

Author: Ángel Fernández Pineda. Madrid. Spain.

Date: 2025-02-11

Copyright: Licensed under the EUPL

Definition in file HAL.hpp.

Macro Definition Documentation

◆ active_wait_ns

#define active_wait_ns ( n )

Value:

for (uint32_t i = 0; i < n; i += NS_PER_LOOP) \

asm("");

NS_PER_LOOP

#define NS_PER_LOOP

Time per loop of active_wait_ns() computed as 4 CPU instructions.

Definition HAL.hpp:57

Active wait without context switching.

Note: Not accurate but close

Parameters

n	Time to wait in nanoseconds

Definition at line 66 of file HAL.hpp.

◆ AS_GPIO

#define AS_GPIO ( pin )

Value:

static_cast<gpio_num_t>((int)(pin))

Cast GPIO to an ESP32 pin number.

Definition at line 31 of file HAL.hpp.

◆ AS_PORT

#define AS_PORT ( bus )

Value:

static_cast<i2c_port_num_t>(bus)

Cast I2CBus to an ESP32 port number.

Definition at line 33 of file HAL.hpp.

◆ DELAY_MS

#define DELAY_MS ( ms )

Value:

vTaskDelay(pdMS_TO_TICKS(ms))

Macro to wait in millisecond units.

Definition at line 47 of file HAL.hpp.

◆ DELAY_TICKS

#define DELAY_TICKS ( ticks )

Value:

vTaskDelay(ticks)

Macro to wait in tick units.

Definition at line 45 of file HAL.hpp.

◆ GPIO_GET_LEVEL

#define GPIO_GET_LEVEL ( pin )

Value:

gpio_get_level(static_cast<gpio_num_t>((int)(pin)))

Macro to read the logic level in a GPIO pin.

Definition at line 39 of file HAL.hpp.

◆ GPIO_SET_LEVEL

#define GPIO_SET_LEVEL	(		pin,
			level )

Value:

gpio_set_level(static_cast<gpio_num_t>((int)(pin)), (level))

Macro to write a logic level in a GPIO pin.

Definition at line 35 of file HAL.hpp.

◆ I2C_SLAVE

#define I2C_SLAVE ( dev )

Value:

static_cast<i2c_master_dev_handle_t>(dev)

Cast to an I2C slave device handle.

Definition at line 37 of file HAL.hpp.

◆ NS_PER_LOOP

#define NS_PER_LOOP ((4000 + CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ - 1) / CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ)

Time per loop of active_wait_ns() computed as 4 CPU instructions.

Definition at line 57 of file HAL.hpp.

Typedef Documentation

◆ ISRHandler

typedef void(* ISRHandler) (void *arg)

Interrupt Service Routine.

Definition at line 41 of file HAL.hpp.

Function Documentation

◆ abortOnInvalidAddress()

void internals::hal::i2c::abortOnInvalidAddress	(	uint8_t	address7bits,
		uint8_t	minAddress = 0,
		uint8_t	maxAddress = 127 )

Abort and reboot on an invalid I2C address.

Parameters

address7bits	I2C address to check in 7 bits format.
minAddress	Start of custom valid address range, inclusive.
maxAddress	End of custom valid address range, inclusive.

◆ add_device()

i2c_master_dev_handle_t internals::hal::i2c::add_device	(	uint8_t	address7bits,
		uint8_t	max_speed_multiplier,
		I2CBus	bus )

Add an slave device ensuring the bus is initialized.

Parameters

address7bits	Full address in 7 bit format
max_speed_multiplier	A bus speed multiplier in the range [1,4]
bus	I2C bus required

Returns: i2c_master_dev_handle_t Device handle to be used in the ESP-IDF API

◆ enableISR()

void internals::hal::gpio::enableISR	(	InputGPIO	pin,
		ISRHandler	handler,
		void *	param = nullptr )

Enable an interrupt service routine.

Parameters

pin	Pin
handler	Routine
param	Parameter to `handler`

◆ findFullAddress()

uint8_t internals::hal::i2c::findFullAddress	(	std::vector< uint8_t > &	fullAddressList,
		uint8_t	hardwareAddress,
		uint8_t	hardwareAddressMask = 0b00000111 )

Find the full address of a device.

Parameters

[in]	fullAddressList	A list of full addresses obtained from i2c::probe()
[in]	hardwareAddress	A partial 7-bit address
[in]	hardwareAddressMask	A mask. Bits set to 1 will be taken from `hardwareAddress`. Bits set to 0 have to be found.

Returns: 0xFF If no device was found matching the partial hardwareAddress; 0xFE If two or more devices where found matching the partial hardwareAddress; uint8_t Otherwise, a full address in 7-bit format.

◆ forInput()

void internals::hal::gpio::forInput	(	InputGPIO	pin,
		bool	enablePullDown,
		bool	enablePullUp )

Configure a pin for digital input.

Parameters

pin
enablePullDown
enablePullUp

◆ forOutput()

void internals::hal::gpio::forOutput	(	OutputGPIO	pin,
		bool	initialLevel,
		bool	openDrain )

Configure a pin for output.

Parameters

pin	Pin number
initialLevel	If true, set to HIGH after initialization. Otherwise, set to LOW after initialization.
openDrain	If true, configure in open drain mode. If false, configure in output mode.

◆ getADCreading()

int internals::hal::gpio::getADCreading	(	ADC_GPIO	pin,
		int	sampleCount = 1 )

Get the mean of some continuous ADC readings.

Parameters

pin	Pin number. Must be ADC-capable.
sampleCount	Number of continuous ADC samples. Pass 1 for a single reading (default). Must be greater than zero.

Returns: int Mean of all continuous ADC samples or -1 if sampleCount is not greater than zero.

◆ initialize()

void internals::hal::i2c::initialize	(	GPIO	sda,
		GPIO	scl,
		I2CBus	bus,
		bool	enableInternalPullup = true )

Initialize an I2C bus to certain pins.

Note: Must be called if you want to initialize a secondary bus. Otherwise, there is no need to call, since the bus will be automatically initialized.; If required, must be called before using any I2C hardware.; If external pullup resistors are in place, the internal ones will reduce wire capacitance as there are two resistors in parallel. This is good or bad depending on the case.

Parameters

sda	SDA pin for the I2C bus.
scl	SCL pin for the I2C bus.
bus	I2C bus to initialize.
enableInternalPullup	If true (default), the bus is pulled up using internal pullup resistors. If false, external pullup resistors must be in place as the internal ones are not enabled. Otherwise, the bus won't work.

◆ probe() [1/2]

void internals::hal::i2c::probe	(	std::vector< uint8_t > &	result,
		I2CBus	bus = I2CBus::PRIMARY )

Retrieve all devices available on an I2C bus.

Parameters

[out]	result	List of addresses found, in 7-bit format.
[in]	bus	I2C bus.

◆ probe() [2/2]

bool internals::hal::i2c::probe	(	uint8_t	address7bits,
		I2CBus	bus = I2CBus::PRIMARY )

Check slave device availability on an I2C bus.

Note: require() must be called first.

Parameters

address7bits	I2C address of a slave device in 7 bits format.
bus	I2C bus.

Returns: true If the slave device is available and ready.; false If the slave device is not responding or the bus was not initialized.

◆ remove_device()

void internals::hal::i2c::remove_device ( i2c_master_dev_handle_t i2c_device )

Remove an slave device.

Parameters

i2c_device Device handle

◆ require()

void internals::hal::i2c::require ( I2CBus bus = I2CBus::PRIMARY )

Ensure the I2C bus is initialized.

Note: Called from other namespaces. No need to call in user code.

Parameters

bus	I2C bus required.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ active_wait_ns

◆ AS_GPIO

◆ AS_PORT

◆ DELAY_MS

◆ DELAY_TICKS

◆ GPIO_GET_LEVEL

◆ GPIO_SET_LEVEL

◆ I2C_SLAVE

◆ NS_PER_LOOP

Typedef Documentation

◆ ISRHandler

Function Documentation

◆ abortOnInvalidAddress()

◆ add_device()

◆ enableISR()

◆ findFullAddress()

◆ forInput()

◆ forOutput()

◆ getADCreading()

◆ initialize()

◆ probe() [1/2]

◆ probe() [2/2]

◆ remove_device()

◆ require()