Deutsch
English
Menu
Software / API Bindings / C/C++ for Microcontrollers / API Reference and Examples / HAL Arduino ESP32

C/C++ for Microcontrollers - Arduino ESP32 HAL

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

Supported Hardware

This HAL was tested with the following devices:

But the HAL should work with all modules and boards using the ESP32, as listed for example here.

The HAL 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 the correct board in Arduino IDE. If you are using an ESP32 Brick or ESP32 Ethernet Brick then select "ESP32 Dev Module".

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 folder]
    • [copy the example .c file here]
    • src/
      • bindings/
        • [copy the content of the bindings folder here]
      • hal_arduino_esp32/
        • [copy hal_arduino_esp32.cpp and hal_arduino_esp32.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.

After creating the folder structure, you have to modify the port assignment in the sketch to fit to your set-up (see this section). If you connect multiple Bricklets to the same SPI bus (this is only possible with a tri-state buffer chip, see here), you have to connect all their chip select pins to the Arduino and list them in the port assignment, even if you don't want to communicate with the Bricklets yet. This makes sure the signals are correctly separated.

Now connect the board to the PC then build and upload the sketch. The prints of the example should be listed in the serial console.

Port Specification Format

A port is specified as an instance of the TF_Port structure:

struct TF_Port {
    int chip_select_pin;
    uint8_t spi;
    char port_name;
}

The chip select pin is the pin that has to be pulled to be able to communicate to the port. SPI is the SPI hardware unit to use, valid values are VSPI and HSPI. The port name is a single character that identifies the port. The name is injected into the result of tf_[device]_get_identity calls if the device is connected directly to the host.

The example_driver.ino contains an example port specification for the ESP32 Brick.

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, TF_Port *ports, uint8_t port_count)

Creates a HAL object that can be used to list the available devices. It is also required for the constructor of Bricks and Bricklets.

  • ports is an array of port specifications, as described here
  • port_count is the length of the ports array.
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.