Peripherals library¶
The peripherals library provides a light hardware abstraction layer to manage the GPIO, UART, SPI and I²C peripherals. It also provides miscellaneous functions for time and numbers.
The provided version targets the Arduino and compatible SDKs, with a C-like syntax for all the functions. The technical note Migrate to another SDK describes how to adapt the library to other SDKs.
On the Commercial edition, the strings could be either the String object provided by the Arduino SDK, or the C-standard char array supported by the cstring library. The option is set on the configuration header file. On the Basic edition, only the Arduino SDK option is provided.
On the Evaluation, Commercial and Viewer editions, the architecture of the peripherals library consists of two layers:
-
The top layer with the library
hV_HAL_Peripheralsexposes all the functions, withhV_HALas prefix, to the other libraries and application code; -
The underlying layer with SDK- or API-specific library
hV_SDK_Peripheralsincludes the limited set of functions specific to the SDK or API, withhV_SDKas prefix, to be ported when using another SDK or API.
Basic edition
On the Basic edition, the architecture of the peripherals library consists of one single layer:
- The library
hV_HAL_Peripheralsexposes all the functions, withhV_HALas prefix, to the other libraries and application code. Using another SDK or API requires porting those functions.
Warning
All the other libraries and the application code shall call the functions from hV_HAL_Peripherals, with hV_HAL as prefix.
Configure¶
``` cpp // SDK and configuration
include “PDLS_Common.h”¶
```
The pre-processor statement calls the shared libraries. The PDLS_Common umbrella header file includes the SDK with the peripherals library, and the configuration with the common library.
Use¶
cpp
hV_HAL_begin();
hV_HAL_begin()- proceeds with the general initialisation. It configures and starts the peripherals GPIO, UART, SPI, and I²C if needed.
For each peripheral, the library exposes a limited set of functions with a C-like syntax.
The names of the functions start with hV_HAL, then the peripherals like _GPIO, and finally the command like _begin(), to form hV_HAL_GPIO_begin().
GPIO¶
``` cpp hV_HAL_GPIO_begin();
hV_HAL_GPIO_define(PIN1, OUTPUT); hV_HAL_GPIO_set(PIN1); hV_HAL_GPIO_clear(PIN1); // hV_HAL_GPIO_write(PIN1, HIGH);
hV_HAL_GPIO_define(PIN2, INPUT_PULLUP); uint8_t result = hV_HAL_GPIO_get(PIN2); // uint8_t result = hV_HAL_GPIO_read(PIN2); ```
hV_HAL_GPIO_begin()- initialises the GPIO peripherals.
hV_HAL_GPIO_define()- defines the pin as output or input, with pull-up or pull-down options.
hV_HAL_GPIO_set()andhV_HAL_GPIO_clear()- turn the pin as output high and low, with
hV_HAL_GPIO_write()as synonym hV_HAL_GPIO_get()- reads the value from the pins as input, with
hV_HAL_GPIO_read()as synonym.
Serial¶
cpp
hV_HAL_Serial_begin(115200);
hV_HAL_Serial_begin()- initialises the UART interface.
cpp
hV_HAL_Serial_printf("Value= %i", 0);
hV_HAL_Serial_crlf();
The resulting line sent to the console is
Value= 0
hV_HAL_Serial_printf()- sends a format and the values. It corresponds to the standard function
printf(). hV_HAL_Serial_crlf()- performs a carriage return and line feed.
SPI¶
``` cpp hV_HAL_SPI_begin();
uint8_t answer = hV_HAL_SPI_transfer(data); ```
hV_HAL_SPI_begin()- configures the SPI bus at 8 MHz, MSB first, and launches it.
hV_HAL_SPI_transfer()- sends data and receives an answer.
Optionally,
cpp
hV_HAL_SPI_end();
//
hV_HAL_SPI_begin();
hV_HAL_SPI_end()- deactivates the SPI bus, to be reactivated with
hV_HAL_SPI_begin().
Warning
The ESP32 boards have a specific implementation of SPI on the Arduino SDK. The source code may require to be manually adapted.
3-wire SPI¶
The 3-wire SPI bus is a variant of the SPI bus with a unique bi-directional data line.
``` cpp hV_HAL_SPI3_define(pinSCK, pinSDIO);
hV_HAL_SPI3_begin(); ```
hV_HAL_SPI3_define()- defines the GPIOs for the clock and data in-out signals.
hV_HAL_SPI3_begin()- configures and launches the 3-wire SPI bus.
``` cpp hV_HAL_GPIO_clear(b_pin.panelDC); // Command hV_HAL_GPIO_clear(b_pin.panelCS); // Select hV_HAL_SPI3_write(0xb9); hV_HAL_delayMilliseconds(5);
hV_HAL_GPIO_set(b_pin.panelDC); // Data ui8 = hV_HAL_SPI3_read(); // Read hV_HAL_GPIO_set(b_pin.panelCS); // Unselect ```
hV_HAL_SPI3_write()andhV_HAL_SPI3_read()- writes and reads data to and from the 3-wire SPI bus.
Warning
The ESP32 boards have a specific implementation of SPI on the Arduino SDK. The source code may require to be manually adapted.
I²C¶
I²C is also called Wire.
``` cpp hV_HAL_Wire_begin();
hV_HAL_Wire_transfer(address, data, sizeData, answer, sizeAnswer, ms); ```
hV_HAL_Wire_begin()- configures the I²C bus in fast mode at 400 kHz and launches it.
hV_HAL_Wire_transfer()- connects to the I²C device at the specified address, sends the data and optionnally retrieves the answer.
Optionally,
cpp
hV_HAL_Wire_end();
// ...
hV_HAL_Wire_begin();
hV_HAL_Wire_end()- deactivates the I²C bus, to be reactivated with
hV_HAL_Wire_begin().
Time¶
cpp
hV_HAL_delayMicroseconds(100);
hV_HAL_delayMilliseconds(100);
uint32_t chrono32 = hV_HAL_getMilliseconds();
hV_HAL_delayMicroseconds()- performs a blocking delay of the specified duration in microseconds.
hV_HAL_delayMilliseconds()performs a non-blocking delay of the specified duration in milliseconds. hV_HAL_getMilliseconds()- returns the number of milliseconds since the start of the system. As a 32-bit integer, it is limited to ~50 days.
Log system¶
The log system displays messages with a level to the UART interface.
The UART interface is initialised by hV_HAL_begin().
cpp
hV_HAL_log(LEVEL_INFO, "Value= %i", 1);
hV_HAL_log()- sends a log message with a level, a format and the values.
The resulting line sent to the console is
hV . Value= 1
| Level | Symbol | Details |
|---|---|---|
LEVEL_CRITICAL |
* | Non-handled error |
LEVEL_ERROR |
+ | Handled error |
LEVEL_WARNING |
! | Warning |
LEVEL_INFO |
. | Information |
LEVEL_DEBUG |
- | Debug |
LEVEL_SYSTEM |
= | System |
LEVEL_USER |
> | User |
| Option | Details |
|---|---|
WITH_COMMENT |
Line starting with // |
WITH_NO_CRLF |
No carriage return-line feed |
WITH_NO_LEVEL |
Level not printed |
WITH_CHRONO |
Chronometer in s.ms |
cpp
hV_HAL_log(LEVEL_INFO | WITH_COMMENT, "Value= %i", 2);
hV_HAL_log(LEVEL_INFO | WITH_NO_CRLF, "Value= %i and ", 3);
hV_HAL_log(LEVEL_INFO | WITH_NO_LEVEL, "Value= %i", 4);
The resulting lines sent to the console are
// hV . Value= 2 hV . Value= 3 and Value= 4
cpp
hV_HAL_setFilter(LEVEL_CRITICAL | LEVEL_ERROR);
hV_HAL_setFilter()- sets a filter to the messages and prints those with the mentioned levels.
The example above will only print the messages with a critical or an error level.
cpp
hV_HAL_setOption(WITH_COMMENT);
hV_HAL_log(LEVEL_INFO, "Value= %i", 5);
hV_HAL_setOption(WITH_COMMENT | WITH_CHRONO);
hV_HAL_log(LEVEL_INFO, "Value= %i", 6);
hV_HAL_setOption()- defines a default option for all the messages sent.
The resulting line sent to the console is
// hV . Value= 5 // hV . 1.551 Value= 6
Note
hV_HAL_setFilter() and hV_HAL_setOption() can be set before calling hV_HAL_begin().
Miscellaneous¶
cpp
uint32_t random hV_HAL_random(maxNumber);
hV_HAL_random()- generates a pseudo-random number between
0andmaxNumber - 1, both included.
cpp
int32_t outputValue = hV_HAL_map(inputValue, inputMin, inputMax, outputMin, outputMax)
hV_HAL_map()- scales a value.
Formula is
Terminate¶
cpp
hV_HAL_end();
hV_HAL_end()- enters an endless loop for micro-controllers or exits with a
RESULT_SUCCESSor0value for Linux. It corresponds tohV_HAL_exit(RESULT_SUCCESS).
cpp
hV_HAL_exit(code);
hV_HAL_exit()- displays the
codevalue, and enters an endless loop for micro-controllers or exits with thecodevalue for Linux.