Light hardware abstraction layer for peripherals. More...

#include "hV_SDK_Peripherals.h"

Include dependency graph for hV_HAL_Peripherals.h:

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

Macros
#define	hV_HAL_PERIPHERALS_RELEASE 902
	Release.

SDK to HAL equivalences
SDK library
#define	hV_HAL_SPI hV_SDK_SPI
	SPI bus.

#define	hV_HAL_SPI_SPEED hV_SDK_SPI_SPEED
	SPI speed.

#define	hV_HAL_Wire hV_SDK_Wire
	Wire I²C bus.

#define	hV_HAL_Serial hV_SDK_Serial
	Serial bus.

#define	hV_HAL_Serial_Speed hV_SDK_Serial_Speed
	Serial speed.

#define	mySerial hV_HAL_Serial
	Synonym for serial bus.

Log system
#define	LEVEL_CRITICAL 0x0001
	Log level messages.

#define	LEVEL_ERROR 0x0002
	`+` Handled error, continue

#define	LEVEL_WARNING 0x0004
	`!` Warning

#define	LEVEL_INFO 0x0008
	`.` Information

#define	LEVEL_DEBUG 0x0010
	`-` Debug

#define	LEVEL_SYSTEM 0x0020
	`=` System

#define	LEVEL_USER 0x0040
	`>` User

#define	FILTER_ALL 0x00ff
	Allow all log levels.

#define	FILTER_NONE 0x0000
	Deny all log levels.

#define	WITH_COMMENT 0x0100
	= Option with leading `//`

#define	WITH_NO_CRLF 0x0200
	Option with no CR-LF.

#define	WITH_NO_LEVEL 0x0400
	Option with no level.

#define	WITH_CHRONO 0x0800
	Option with chronometer in s.ms.

Functions
void	hV_HAL_log (uint16_t level, const char *format,...)
	Send debug message to console.

void	hV_HAL_setFilter (uint8_t filter=0x00ff)
	Set filter to allow log levels.

void	hV_HAL_setOption (uint16_t option=0x0100)
	Set option for log messages.

General
void	hV_HAL_begin ()
	General initialisation.

void	hV_HAL_end ()
	General end.

void	hV_HAL_exit (uint8_t code=0)
	General exit.

GPIO
Warning Arduino: GPIO requires pin number, example 4 Mbed: GPIO requires pin name, example D4 or PB_5 Mbed: GPIO is created at call Mbed: GPIO not suitable for interrupts Viewer: For compatibility only, GPIO not implemented in Linux
void	hV_HAL_GPIO_begin (void)
	GPIO initialisation.

void	hV_HAL_GPIO_define (uint8_t pin, uint8_t mode)
	Define GPIO mode.

void	hV_HAL_GPIO_set (uint8_t pin)
	Set GPIO.

void	hV_HAL_GPIO_clear (uint8_t pin)
	Clear GPIO.

uint8_t	hV_HAL_GPIO_get (uint8_t pin)
	Get GPIO.

void	hV_HAL_GPIO_write (uint8_t pin, uint8_t value)
	Write GPIO.

uint8_t	hV_HAL_GPIO_read (uint8_t pin)
	Read GPIO.

void	hV_HAL_GPIO_waitFor (uint8_t pin, uint8_t state)
	Wait for GPIO state.

Time
See also https://www.arduino.cc/reference/en/#time
void	hV_HAL_delayMicroseconds (uint32_t us)
	Microsecond non-blocking delay.

void	hV_HAL_delayMilliseconds (uint32_t ms)
	Millisecond non-blocking delay.

uint32_t	hV_HAL_getMilliseconds (void)
	Get milliseconds since start-up.

Serial console
Formatted output to hV_HAL_Serial
void	hV_HAL_Serial_begin (uint32_t speed=115200)
	Initialise console.

void	hV_HAL_Serial_printf (const char *format,...)
	Format and send to console.

void	hV_HAL_Serial_crlf (void)
	Print carriage-return line-feed.

template<typename T>
void	hV_HAL_Serial_print (T text)
	Print to serial console.

template<typename T>
void	hV_HAL_Serial_println (T text)
	Print to serial console with cr-lf at the end.

SPI bus
Warning Arduino: SPI ESP32 uses pins SCK = 14, MISO = 12 and MOSI = 13 Viewer: For compatibility only, not implemented in Linux
void	hV_HAL_SPI_begin (uint32_t speed=8000000)
	Configure and start SPI.

void	hV_HAL_SPI_end ()
	End SPI.

uint8_t	hV_HAL_SPI_transfer (uint8_t data)
	Combined write and read of a single byte.

void	hV_HAL_SPI_transfer (uint8_t *data, size_t size)
	Combined write and read.

3-wire SPI bus
Warning Arduino does not support 3-wire SPI, bit-bang simulation Viewer: For compatibility only, not implemented in Linux Note hV_HAL_SPI3_begin() sets the pins for 3-wire SPI.
void	hV_HAL_SPI3_begin ()
	Configure 3-wire SPI.

void	hV_HAL_SPI3_end ()
	End 3-wire SPI.

void	hV_HAL_SPI3_define (uint8_t pinClock=SCK, uint8_t pinData=MOSI)
	Set the 3-wire SPI pins.

uint8_t	hV_HAL_SPI3_read ()
	Read a single byte.

void	hV_HAL_SPI3_write (uint8_t value)
	Write a single byte.

Wire bus
void	hV_HAL_Wire_begin ()
	Configure and start Wire bus.

void	hV_HAL_Wire_end ()
	End Wire bus.

void	hV_HAL_Wire_transfer (uint8_t address, uint8_t dataWrite, size_t sizeWrite, uint8_t dataRead=0, size_t sizeRead=0)
	Combined write and read.

Miscellaneous
Patches for implementations on some platforms
#define	hV_HAL_min(a, b)
	Minimum of two numbers.

#define	hV_HAL_max(a, b)
	Maximum of two numbers.

#define	hV_HAL_swap(x, y)
	Swap numbers.

uint32_t	hV_HAL_random (uint32_t maxNumber)
	Pseudo-random number.

long	hV_HAL_map (long x, long in_min, long in_max, long out_min, long out_max)
	Rescale a value.

State management
#define	STATE_OFF 0x00
	peripheral not ready or off

#define	STATE_ON 0x01
	peripheral ready and on

uint8_t	hV_HAL_GPIO_state
	GPIO state.

uint8_t	hV_HAL_SPI_state
	SPI state.

uint8_t	hV_HAL_SPI3_state
	SPI state.

uint8_t	hV_HAL_Wire_state
	Wire state.

uint8_t	hV_HAL_Serial_state
	Serial state.

Detailed Description

Light hardware abstraction layer for peripherals.

Project Pervasive Displays Library Suite
Based on highView technology

Author: Rei Vilo

Date: 21 Jan 2025

Version: 902

Copyright: (c) Rei Vilo, 2010-2025; All rights reserved; For exclusive use with Pervasive Displays screens

Basic edition: for hobbyists and for basic usage
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
See also
https://creativecommons.org/licenses/by-sa/4.0/

Consider the Evaluation or Commercial editions for professionals or organisations and for commercial usage
Evaluation edition: for professionals or organisations, evaluation only, no commercial usage
All rights reserved
Commercial edition: for professionals or organisations, commercial usage
All rights reserved
Viewer edition: for professionals or organisations
All rights reserved
Documentation
All rights reserved

Macro Definition Documentation

◆ hV_HAL_max

#define hV_HAL_max	(		a,
			b )

Value:

((a) > (b) ? (a) : (b))

Maximum of two numbers.

Parameters

a	first number
b	second number

Returns: maximum of a and b

Note: Macro more robust than bugged implementation on some platforms

◆ hV_HAL_min

#define hV_HAL_min	(		a,
			b )

Value:

((a) < (b) ? (a) : (b))

Minimum of two numbers.

Parameters

a	first number
b	second number

Returns: minimum of a and b

Note: Macro more robust than bugged implementation on some platforms

◆ hV_HAL_PERIPHERALS_RELEASE

#define hV_HAL_PERIPHERALS_RELEASE 902

Release.

Deprecated

Removed synonyms for GPIO (7.0.0)

hV_HAL_GPIO_pinMode() is removed. Use hV_HAL_GPIO_define() instead (7.0.0)
hV_HAL_GPIO_digitalWrite() is removed. Use hV_HAL_GPIO_write(), hV_HAL_GPIO_set() and hV_HAL_GPIO_clear() instead (7.0.0)
hV_HAL_GPIO_digitalRead() is removed. Use hV_HAL_GPIO_read() or hV_HAL_GPIO_get() instead (7.0.0)

Deprecated

Removed synonyms for Time (7.0.0)

hV_HAL_delay() is removed. Use hV_HAL_delayMilliseconds() instead (7.0.0)

Deprecated

Removed synonyms for Serial (7.0.0)

hV_HAL_printf() is removed. Use hV_HAL_Serial_printf() instead (7.0.0)
hV_HAL_crlf() is removed. Use hV_HAL_Serial_crlf() instead (7.0.0)
hV_HAL_Serial_print() and hV_HAL_Serial_println() are not recommended. Use hV_HAL_Serial_printf() and hV_HAL_Serial_crlf() instead (7.0.0)

Deprecated

Removed synonyms for SPI (7.0.0)

hV_HAL_SPI_configure() is removed. Use hV_HAL_SPI_begin() instead (7.0.0)

Deprecated

Removed synonyms for Wire (7.0.0)

hV_HAL_Wire_writeRead() is removed. Use hV_HAL_Wire_transfer() instead (7.0.0)

◆ hV_HAL_swap

#define hV_HAL_swap	(		x,
			y )

Value:

do { __typeof__(x) WORK = x; x = y; y = WORK; } while (0)

Swap numbers.

Parameters

[out]	x	first number
[out]	y	second number

Note: Macro more robust than template for some platforms

template <typename T> T
hV_HAL_swap(T &x, T &y)
{
    T w = x;
    x = y;
    y = w;
}

Note: __typeof__ recommended over typeof

◆ LEVEL_CRITICAL

#define LEVEL_CRITICAL 0x0001

Log level messages.

* Non-handled error, stop or exit

Function Documentation

◆ hV_HAL_begin()

void hV_HAL_begin ( )

General initialisation.

hV_HAL_Serial initialised at hV_HAL_Serial_Speed

◆ hV_HAL_delayMicroseconds()

void hV_HAL_delayMicroseconds ( uint32_t us )

Microsecond non-blocking delay.

Parameters

us delay, us

◆ hV_HAL_delayMilliseconds()

void hV_HAL_delayMilliseconds ( uint32_t ms )

Millisecond non-blocking delay.

Parameters

ms delay, ms

◆ hV_HAL_end()

void hV_HAL_end ( )

General end.

Note: Same as hV_HAL_exit(0)

◆ hV_HAL_exit()

void hV_HAL_exit ( uint8_t code = 0 )

General exit.

Parameters

code	default = 0 = success, otherwise error

Note: Only used on Linux

◆ hV_HAL_getMilliseconds()

uint32_t hV_HAL_getMilliseconds ( void )

Get milliseconds since start-up.

Returns: uint32_t milliseconds since start-up

Note: Limit of 2^32 ms or ~49.7 days

◆ hV_HAL_GPIO_begin()

void hV_HAL_GPIO_begin ( void )

GPIO initialisation.

Required for GPIO expander

Warning: begin() does not initialise SPI; begin() initialises I2C

◆ hV_HAL_GPIO_clear()

void hV_HAL_GPIO_clear ( uint8_t pin )

Clear GPIO.

Parameters

pin	pin number or pin name according to SDK

Note: Same as hV_HAL_GPIO_write(pin, LOW);

◆ hV_HAL_GPIO_define()

void hV_HAL_GPIO_define	(	uint8_t	pin,
		uint8_t	mode )

Define GPIO mode.

Parameters

pin	pin number or pin name according to SDK
mode	OUTPUT or INPUT

Note: Same as hV_HAL_GPIO_pinMode(pin, mode);

◆ hV_HAL_GPIO_get()

uint8_t hV_HAL_GPIO_get ( uint8_t pin )

Get GPIO.

Parameters

pin	pin number or pin name according to SDK

Returns: uint8_t HIGH = true or LOW = false

Note: Same as hV_HAL_GPIO_read(pin);

◆ hV_HAL_GPIO_read()

uint8_t hV_HAL_GPIO_read ( uint8_t pin )

Read GPIO.

Parameters

pin	pin number or pin name according to SDK

Returns: uint8_t HIGH = true or LOW = false

Note: Synonym of hV_HAL_GPIO_get();

◆ hV_HAL_GPIO_set()

void hV_HAL_GPIO_set ( uint8_t pin )

Set GPIO.

Parameters

pin	pin number or pin name according to SDK

Note: Same as hV_HAL_GPIO_write(pin, HIGH);

◆ hV_HAL_GPIO_waitFor()

void hV_HAL_GPIO_waitFor	(	uint8_t	pin,
		uint8_t	state )

Wait for GPIO state.

Parameters

pin	pin number or pin name according to SDK
state	state to wait for, HIGH or LOW

Note: Overtime management should be placed here.

◆ hV_HAL_GPIO_write()

void hV_HAL_GPIO_write	(	uint8_t	pin,
		uint8_t	value )

Write GPIO.

Parameters

pin	pin number or pin name according to SDK
value	HIGH = true or LOW = false

Note: Synonym of hV_HAL_GPIO_set() and hV_HAL_GPIO_clear()

◆ hV_HAL_log()

void hV_HAL_log	(	uint16_t	level,
		const char *	format,
			... )

Send debug message to console.

Parameters

level	Debug level message
format	see https://www.cplusplus.com/reference/cstdio/printf/ for tokens

Note: With final CR-LF

◆ hV_HAL_map()

long hV_HAL_map	(	long	x,
		long	in_min,
		long	in_max,
		long	out_min,
		long	out_max )

Rescale a value.

Parameters

x	input value
in_min	minimal input value
in_max	maximum input value
out_min	minimum output value
out_max	maximum output value

Returns: long output value

Note: Formula is
(x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;

◆ hV_HAL_random()

uint32_t hV_HAL_random ( uint32_t maxNumber )

Pseudo-random number.

Parameters

maxNumber maximum random number

Returns: uint32_t 0..number - 1

◆ hV_HAL_Serial_begin()

void hV_HAL_Serial_begin ( uint32_t speed = 115200 )

Initialise console.

Parameters

speed in bps, eg. 115200

Deprecated: Console already initialised at 115200 by hV_HAL_begin() (6.0.7)

◆ hV_HAL_Serial_print()

template<typename T>

void hV_HAL_Serial_print ( T text )

Print to serial console.

Template Parameters

T	type of the element, [u]int{8\|16\|32}_t float String char*

Parameters

text	element to print

Warning: Because of <template>, code follows definition in header file

Deprecated: Use hV_HAL_Serial_printf() and hV_HAL_Serial_crlf() instead (6.1.0)

◆ hV_HAL_Serial_printf()

void hV_HAL_Serial_printf	(	const char *	format,
			... )

Format and send to console.

Parameters

format see https://www.cplusplus.com/reference/cstdio/printf/ for tokens

◆ hV_HAL_Serial_println()

template<typename T>

void hV_HAL_Serial_println ( T text )

Print to serial console with cr-lf at the end.

Template Parameters

T	type of the element: [u]int{8\|16\|32}_t float String char*

Parameters

text	element to print

Warning: Because of <template>, code follows definition in header file

Deprecated: Use hV_HAL_Serial_printf() and hV_HAL_Serial_crlf() instead (6.1.0)

◆ hV_HAL_setFilter()

void hV_HAL_setFilter ( uint8_t filter = 0x00ff )

Set filter to allow log levels.

Parameters

filter default = FILTER_ALL

Note: Numbers are bit-based and or-combinable The following code displays the critical and system messages.
hV_HAL_setFilter(LEVEL_CRITICAL | LEVEL_SYSTEM);

LEVEL_SYSTEM
#define LEVEL_SYSTEM
= System
Definition hV_HAL_Peripherals.h:421

hV_HAL_setFilter
void hV_HAL_setFilter(uint8_t filter=0x00ff)
Set filter to allow log levels.

LEVEL_CRITICAL
#define LEVEL_CRITICAL
Log level messages.
Definition hV_HAL_Peripherals.h:416

◆ hV_HAL_setOption()

void hV_HAL_setOption ( uint16_t option = 0x0100 )

Set option for log messages.

Parameters

option WITH_COMMENT = default, WITH_NO_CRLF, WITH_NO_LEVEL

Note: Numbers are bit-based and or-combinable

◆ hV_HAL_SPI3_begin()

void hV_HAL_SPI3_begin ( )

Configure 3-wire SPI.

Note: Select default SCK as clock and MOSI as data (SDIO)

◆ hV_HAL_SPI3_define()

void hV_HAL_SPI3_define	(	uint8_t	pinClock = SCK,
		uint8_t	pinData = MOSI )

Set the 3-wire SPI pins.

Parameters

pinClock	clock, default = SCK
pinData	combined data, default = MOSI

Note: For manual configuration only

◆ hV_HAL_SPI3_read()

uint8_t hV_HAL_SPI3_read ( )

Read a single byte.

Returns: read byte

Note: Configure the clock pin as output and data pin as input.

Warning: /CS to be managed externally.

◆ hV_HAL_SPI3_write()

void hV_HAL_SPI3_write ( uint8_t value )

Write a single byte.

Parameters

data byte

Note: Configure the clock and data pins as output.

Warning: /CS to be managed externally.

◆ hV_HAL_SPI_begin()

void hV_HAL_SPI_begin ( uint32_t speed = 8000000 )

Configure and start SPI.

Parameters

speed SPI speed in Hz, hV_HAL_SPI_SPEED = default Other values are SPI_SPEED_4_MHz, SPI_SPEED_8_MHz, SPI_SPEED_16_MHz

Note

Other parameters are

Bit order: MSBFIRST
Data mode: SPI_MODE0

With check for unique initialisation

◆ hV_HAL_SPI_end()

void hV_HAL_SPI_end ( )

End SPI.

Note: With check for unique deinitialisation

◆ hV_HAL_SPI_transfer() [1/2]

void hV_HAL_SPI_transfer	(	uint8_t *	data,
		size_t	size )

Combined write and read.

Parameters

data	array of uint8_t to send
size	length

Note: Array may be updated with read data

◆ hV_HAL_SPI_transfer() [2/2]

uint8_t hV_HAL_SPI_transfer ( uint8_t data )

Combined write and read of a single byte.

Parameters

data byte

Returns: read byte

Warning: No check for previous initialisation

◆ hV_HAL_Wire_begin()

void hV_HAL_Wire_begin ( )

Configure and start Wire bus.

Note: Master mode only; With check for unique initialisation

◆ hV_HAL_Wire_end()

void hV_HAL_Wire_end ( )

End Wire bus.

Note: With check for unique deinitialisation

◆ hV_HAL_Wire_transfer()

void hV_HAL_Wire_transfer	(	uint8_t	address,
		uint8_t *	dataWrite,
		size_t	sizeWrite,
		uint8_t *	dataRead = 0,
		size_t	sizeRead = 0 )

Combined write and read.

Parameters

[in]	address	I2C device address
[in]	dataWrite	buffer to write
[in]	sizeWrite	number of bytes
[out]	dataRead	buffer to read
[in]	sizeRead	number of bytes

Note: If sizeRead = 0, no read performed

Warning: No check for previous initialisation

Macros

Functions

Miscellaneous

State management

Detailed Description

Macro Definition Documentation

◆ hV_HAL_max

◆ hV_HAL_min

◆ hV_HAL_PERIPHERALS_RELEASE

◆ hV_HAL_swap

◆ LEVEL_CRITICAL

Function Documentation

◆ hV_HAL_begin()

◆ hV_HAL_delayMicroseconds()

◆ hV_HAL_delayMilliseconds()

◆ hV_HAL_end()

◆ hV_HAL_exit()

◆ hV_HAL_getMilliseconds()

◆ hV_HAL_GPIO_begin()

◆ hV_HAL_GPIO_clear()

◆ hV_HAL_GPIO_define()

◆ hV_HAL_GPIO_get()

◆ hV_HAL_GPIO_read()

◆ hV_HAL_GPIO_set()

◆ hV_HAL_GPIO_waitFor()

◆ hV_HAL_GPIO_write()

◆ hV_HAL_log()

◆ hV_HAL_map()

◆ hV_HAL_random()

◆ hV_HAL_Serial_begin()

◆ hV_HAL_Serial_print()

◆ hV_HAL_Serial_printf()

◆ hV_HAL_Serial_println()

◆ hV_HAL_setFilter()

◆ hV_HAL_setOption()

◆ hV_HAL_SPI3_begin()

◆ hV_HAL_SPI3_define()

◆ hV_HAL_SPI3_read()

◆ hV_HAL_SPI3_write()

◆ hV_HAL_SPI_begin()

◆ hV_HAL_SPI_end()

◆ hV_HAL_SPI_transfer() [1/2]

◆ hV_HAL_SPI_transfer() [2/2]

◆ hV_HAL_Wire_begin()

◆ hV_HAL_Wire_end()

◆ hV_HAL_Wire_transfer()