Software / API Bindings / C/C++ for Microcontrollers / API Reference and Examples / HAL Arduino ESP32 Ethernet Brick

C/C++ for Microcontrollers - Arduino ESP32 Ethernet Brick HAL¶

The Arduino ESP32 Brick Ethernet Hardware Abstraction Layer (HAL) is used with the C/C++ bindings for microcontrollers to communicate with Bricklets over SPI.

Supported Hardware¶

This HAL is designed to be used with the ESP32 Ethernet Brick only and requires usage of the Arduino ESP32 core.

Testing an Example¶

These examples are made to be used with Arduino ESP32 core in the Arduino IDE. Start by installing both projects according to their manuals. Then select "ESP32 Dev Module" as board in Arduino IDE.

This HAL includes an example driver Arduino sketch that can be used to run any example provided with the bindings.

The Arduino IDE has specific requirements to the sketch folder layout. A valid folder looks like this:

example_driver/
- example_driver.ino [from the hal_arduino_esp32_ethernet_brick folder]
- [copy the example .c file here]
- src/
  - bindings/
    - [copy the content of the bindings folder here]
  - hal_arduino_esp32_ethernet_brick/
    - [copy hal_arduino_esp32_ethernet_brick.cpp and hal_arduino_esp32_ethernet_brick.h here]

Note that the top-level folder has to have the same name as the sketch, i.e. if you rename example_driver.ino, you have to rename the folder as well.

Now connect the ESP32 Ethernet Brick to USB then build and upload the sketch. The prints of the example should be listed in the serial console.

API¶

Most functions of the HAL return an error code (e_code).

Possible error codes are (as defined in errors.h):

TF_E_OK = 0
TF_E_TIMEOUT = -1
TF_E_INVALID_PARAMETER = -2
TF_E_NOT_SUPPORTED = -3
TF_E_UNKNOWN_ERROR_CODE = -4
TF_E_STREAM_OUT_OF_SYNC = -5
TF_E_INVALID_CHAR_IN_UID = -6
TF_E_UID_TOO_LONG = -7
TF_E_UID_OVERFLOW = -8
TF_E_TOO_MANY_DEVICES = -9
TF_E_DEVICE_NOT_FOUND = -10
TF_E_WRONG_DEVICE_TYPE = -11
TF_E_LOCKED = -12
TF_E_PORT_NOT_FOUND = -13
TF_E_NULL = -14
TF_E_DEVICE_ALREADY_IN_USE = -15
TF_E_WRONG_RESPONSE_LENGTH = -16
TF_E_NOT_INITIALIZED = -17

This HAL does not define further error codes. Use tf_hal_strerror() to get an error string for an error code.

Basic Functions¶

int tf_hal_create(TF_HAL *hal)¶: Creates a HAL object that can be used to list the available devices. It is also required for the constructor of Bricks and Bricklets.

int tf_hal_destroy(TF_HAL *hal)¶: Destroys the given TF_HAL.

void tf_hal_set_timeout(TF_HAL *hal, uint32_t timeout_us)¶

Sets the timeout in microseconds for getters and for setters for which the response expected flag is activated.

The default timeout is 2500000 (2.5 seconds).

uint32_t tf_hal_get_timeout(TF_HAL *hal)¶: Returns the timeout as set by tf_hal_set_timeout().

int tf_hal_get_device_info(TF_HAL *hal, uint16_t index, char ret_uid[7], char *ret_port_name, uint16_t *ret_device_id)¶: Returns the UID, port and device identifier of the nth (=index) detected device. This function returns TF_E_DEVICE_NOT_FOUND if the index was equal or higher than the number of detected devices. To list all devices you can call this function in a loop with growing index until TF_E_DEVICE_NOT_FOUND is returned once.

int tf_hal_callback_tick(TF_HAL *hal, uint32_t timeout_us)¶

Polls for callbacks on all devices with an registered callback handler. Will block for the given timeout in microseconds.

This function can be used in a non-blocking fashion by calling it with a timeout of 0. The bindings will then poll a single device for one callback, by clocking out a single byte over SPI, returning immediately if no callback is available. If the device starts sending a callback packet, it will be received, acked and the callback handler will be called.

The polling is scheduled round-robin over multiple calls, so even if you only poll with a timeout of 0, all devices will be polled as fairly as possble.

bool tf_hal_deadline_elapsed(TF_HAL *hal, uint32_t deadline_us)¶: Returns true if the deadline in microseconds is elapsed, false otherwise. Robust against overflows up to UINT32_MAX / 2.

int tf_hal_get_error_counters(TF_HAL *hal, char port_name, uint32_t *ret_spitfp_error_count_checksum, uint32_t *ret_spitfp_error_count_frame, uint32_t *ret_tfp_error_count_frame, uint32_t *ret_tfp_error_count_unexpected)¶

Returns the error counters for the given port. The following errors are counted:

spitfp_error_count_checksum: Received SPITFP packets that where ignored because of a wrong checksum
spitfp_error_count_frame: Received SPITFP packets with an invalid length
tfp_error_count_frame: Received TFP packets with an invalid length
tfp_error_count_unexpected: Received TFP packets that where unexpected because they responded to unknown requests

void tf_hal_log_error(const char *format, ...)¶: Logs an error if the log level in bindings/config.h is TF_LOG_LEVEL_ERROR or more. Supports a subset of the standard printf syntax. See tf_hal_printf() for details.

void tf_hal_log_info(const char *format, ...)¶: Logs an information if the log level in bindings/config.h is TF_LOG_LEVEL_INFO or more. Supports a subset of the standard printf syntax. See tf_hal_printf() for details.

void tf_hal_log_debug(const char *format, ...)¶: Logs a debug message if the log level in bindings/config.h is TF_LOG_LEVEL_DEBUG or more. Supports a subset of the standard printf syntax. See tf_hal_printf() for details.

void tf_hal_printf(const char *format, ...)¶

This function is a minimalistic printf implementation. The following placeholders are supported:

%[prefix]u: An unsigned integer value printed in base 10
%[prefix]d: A signed integer value printed in base 10
%[prefix]b: An unsigned integer value printed in base 2
%[prefix]x and %[prefix]X: An unsigned integer value printed in base 16, in both cases with lower-case letters
%c: A single character
%s: A zero terminated string
%%: A percent sign

With the prefix, you can control the width of printed integers. Valid prefixes are I8, I16, I32 and I64. For example using the placeholder %I16x will print a 16 bit integer hexadecimal.

No padding, grouping , l-modifiers or similar, or floats are supported. The newline character \n is translated to the platform specific newline character(s).

const char *tf_hal_strerror(int e_code)¶: Returns an error string for the given error code.

const char *tf_get_device_display_name(uint16_t device_id)¶: Returns the display name for the given device identifier.