Device Base Class

Public header: #include "brookesia/hal_interface/device.hpp"

API Reference

Header File

hal/brookesia_hal_interface/include/brookesia/hal_interface/device.hpp

Classes

class Device

Base class for HAL devices.

A concrete device can publish one or more interface instances through interfaces_ during initialization, then those interfaces can be queried from the global registry.

Subclassed by esp_brookesia::hal::AudioDevice, esp_brookesia::hal::DisplayDevice, esp_brookesia::hal::StorageDevice

Public Functions

virtual bool probe() = 0

Check whether the device is supported on current runtime conditions.

Returns: true if the device can be initialized; otherwise false.

bool register_pre_init_callback(PreInitCallback callback)

Register a callback that runs before this device is initialized.

The callback is invoked once just before on_init() inside init(). If the callback returns false, initialization is aborted. Registering a new callback overwrites any previously registered one.

Parameters: callback -- [in] Callback to invoke; must be non-empty.
Returns: true on success; false if the callback is empty.

bool register_post_deinit_callback(PostDeinitCallback callback)

Register a callback that runs after this device is deinitialized.

The callback is invoked once right after on_deinit() returns. Its return value is only used for logging; deinitialization always proceeds to completion. Registering a new callback overwrites any previously registered one.

Parameters: callback -- [in] Callback to invoke; must be non-empty.
Returns: true on success; false if the callback is empty.

inline const std::string &get_name() const

Get the registry name of this device.

Returns: Device name.

template<typename T> inline requires IsInterface< T > std::shared_ptr< T > get_interface (const std::string &name) const

Retrieve a typed interface owned by this device by interface registry name.

Template Parameters: T -- Interface type that derives from Interface.
Parameters: name -- [in] Fully-qualified interface name in the registry.
Returns: Matching typed interface pointer, or nullptr if the name is missing or the type does not match.

Macros

ESP_BROOKESIA_HAL_DEVICE_REGISTER_ALL_PRE_INIT_CALLBACK(symbol_name, callback)

Auto-register a global pre-init callback used by init_all_devices().

Generates a file-local registrar whose constructor forwards to esp_brookesia::hal::register_pre_init_callback().

Parameters

symbol_name -- Linker-visible identifier used with -u to keep the registrar alive.
callback -- Callback expression convertible to Device::PreInitCallback.

ESP_BROOKESIA_HAL_DEVICE_REGISTER_ALL_POST_DEINIT_CALLBACK(symbol_name, callback)

Auto-register a global post-deinit callback used by deinit_all_devices().

Generates a file-local registrar whose constructor forwards to esp_brookesia::hal::register_post_deinit_callback().

Parameters

symbol_name -- Linker-visible identifier used with -u to keep the registrar alive.
callback -- Callback expression convertible to Device::PostDeinitCallback.

ESP_BROOKESIA_HAL_DEVICE_REGISTER_PRE_INIT_CALLBACKS(symbol_name, ...)

Auto-register pre-init callbacks for multiple HAL devices at static init time.

Each variadic entry must be a brace-enclosed {plugin_name, callback} pair whose types match std::pair<std::string, Device::PreInitCallback>. Because the target devices and these callbacks are both registered through C++ static constructors in different translation units, their relative ordering is unspecified; therefore the macro does not attempt to resolve the device immediately. Instead each entry is queued through detail::enqueue_pending_pre_init_callback() and attached via Device::register_pre_init_callback() inside init_device() when the matching device is known to exist. Entries whose plugin name has no matching device are reported by init_all_devices() after the init pass finishes.

ESP_BROOKESIA_HAL_DEVICE_REGISTER_PRE_INIT_CALLBACKS(
    my_pre_init_callbacks_symbol,
    {"dev_a", []() { return true; }},
    {std::string(hal::AudioDevice::DEVICE_NAME), []() { return true; }}
);

Parameters

symbol_name -- Linker-visible identifier used with -u to keep the registrar alive.
... -- One or more {plugin_name, PreInitCallback} entries separated by commas.

ESP_BROOKESIA_HAL_DEVICE_REGISTER_POST_DEINIT_CALLBACKS(symbol_name, ...)

Auto-register post-deinit callbacks for multiple HAL devices at static init time.

Behaves like ESP_BROOKESIA_HAL_DEVICE_REGISTER_PRE_INIT_CALLBACKS: each entry is queued through detail::enqueue_pending_post_deinit_callback() and attached via Device::register_post_deinit_callback() when the device is initialized, so the callback is in place before Device::deinit() runs.

Parameters

symbol_name -- Linker-visible identifier used with -u to keep the registrar alive.
... -- One or more {plugin_name, PostDeinitCallback} entries separated by commas.

Type Aliases

using esp_brookesia::hal::DeviceRegistry = lib_utils::PluginRegistry<Device>: Registry alias for HAL devices.