esp_board_manager.h

Header File

esp_board_manager/include/esp_board_manager.h

Functions

esp_err_t esp_board_runtime_pre_init(void)

Board runtime pre-init hook.

    Weak default returns ESP_OK. A final application may provide exactly
    one strong definition to apply BOARD-layer overrides before any
    peripheral or device handle is created. Multiple strong definitions
    fail at link time; there is no function-pointer registry.

    Prepare/init must be called from a task; during the hook only that
    task may call override/set_ops. The hook may edit writable descriptor/
    handle tables, apply generated board revisions, call override_config /
    set_ops, and initialize temporary resources needed for hardware
    detection. Resources created by the hook must be deinitialized before
    returning an error; prepare rollback restores table state but does not
    release hardware resources.

Returns:

ESP_OK On success
Others Propagated to esp_board_manager_prepare()

esp_err_t esp_board_manager_prepare(void)

Prepare board runtime overrides.

    Runs the pre-init hook once when unprepared. Idempotent after success.
    A nested call from the prepare-owner task is an idempotent no-op;
    calls from other tasks while preparing are rejected. Calls before a
    FreeRTOS task exists are also rejected. Single device/peripheral init calls this
    before creating a handle so the hook cannot be skipped.

Returns:

ESP_OK On success or already prepared
ESP_ERR_INVALID_STATE If called by a non-owner task while preparing, or without a current task
Others Error codes from the pre-init hook

esp_err_t esp_board_manager_init(void)

Initialize the board manager.

    Runs prepare and descriptor preflight, then initializes all peripherals
    first, then all devices. If device initialization fails, peripherals are
    deinitialized to maintain consistency. The manager can only be initialized once

Note

Device initialization strictly follows the order defined in board_devices.yaml Peripheral initialization strictly follows the order defined in board_peripherals.yaml If a device depends on a peripheral for power-on, it must be initialized after that peripheral For example, the LCD power control device should be listed before the Display LCD device in board_devices.yaml

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_ALREADY_INIT If manager already initialized
Others Error codes from peripheral or device initialization

esp_err_t esp_board_manager_get_periph_handle(const char *periph_name, void **periph_handle)

Get peripheral handle by name.

    Retrieves a peripheral handle that has been initialized by the board manager
    The board manager must be initialized before calling this function

Parameters:

periph_name – [in] Peripheral name
periph_handle – [out] Pointer to store the peripheral handle

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If periph_name or periph_handle is NULL
ESP_BOARD_ERR_MANAGER_PERIPH_NOT_FOUND If peripheral not found

esp_err_t esp_board_manager_get_device_handle(const char *dev_name, void **device_handle)

Get device handle by name.

    Retrieves a device handle that has been initialized by the board manager
    The board manager must be initialized before calling this function

Parameters:

dev_name – [in] Device name
device_handle – [out] Pointer to store the device handle

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If dev_name or device_handle is NULL
ESP_BOARD_ERR_MANAGER_DEVICE_NOT_FOUND If device not found

bool esp_board_manager_check_name(const char *name)

Check whether a device or peripheral name exists.

    This function checks whether the given name is declared as either a
    device or a peripheral in the current board configuration. It does
    not initialize anything and does not emit error logs when the name
    does not exist

Parameters:

name – [in] Device or peripheral name

Returns:

true If the name exists in the current board configuration
false If the name does not exist or name is NULL

esp_err_t esp_board_manager_get_device_config(const char *dev_name, void **config)

Query device configuration.

    Retrieves the configuration data for a specific device. This function
    returns the raw configuration data that was used to initialize the device

Parameters:

dev_name – [in] Device name
config – [out] Pointer to store the device configuration

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If dev_name or config is NULL
ESP_BOARD_ERR_MANAGER_DEVICE_NOT_FOUND If device not found
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If device has no configuration

esp_err_t esp_board_manager_get_periph_config(const char *periph_name, void **config)

Get peripheral configuration by name.

Parameters:

periph_name – [in] Peripheral name
config – [out] Pointer to store the peripheral configuration

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If periph_name or config is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral configuration not found
ESP_BOARD_ERR_PERIPH_NOT_SUPPORTED If peripheral has no configuration

esp_err_t esp_board_manager_get_board_info(esp_board_info_t *board_info)

Retrieves the board information.

    This function can be called without initializing the board manager

Parameters:

board_info – [out] Pointer to store the board information

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If board_info is NULL

esp_err_t esp_board_manager_register_device_handle(esp_board_device_handle_t *reg_handle)

Register a user-defined device handle (legacy)

    Legacy ABI: splices a caller-owned handle node into the generated device
    handle list. It bypasses the descriptor table and APP/BOARD sidecar layers
    (no effective config/ops, no sidecar entry). For an existing device name,
    change init/deinit with :c:func:`esp_board_device_set_ops`. Do not inject
    unknown devices through this function; new devices must go through the
    descriptor/generator path.

Parameters:

reg_handle – [in] Pointer to the device handle to register

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If reg_handle is NULL

esp_err_t esp_board_manager_init_device_by_name(const char *dev_name)

Initialize a specific device by name.

    Initializes a single device by name. The device must exist in the board
    configuration. This function is useful for lazy initialization of devices

Parameters:

dev_name – [in] Device name to initialize

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If dev_name is NULL
ESP_BOARD_ERR_MANAGER_DEVICE_NOT_FOUND If device not found
Others Error codes from device initialization

esp_err_t esp_board_manager_deinit_device_by_name(const char *dev_name)

Deinitialize a specific device by name.

    Deinitializes a single device by name. The device must exist and be
    initialized. This function is useful for selective cleanup

Parameters:

dev_name – [in] Device name to deinitialize

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_INVALID_ARG If dev_name is NULL
Others Error codes from device deinitialization

esp_err_t esp_board_manager_print(void)

Print board manager status information.

    Displays comprehensive status information including all peripherals,
    devices, and their associations. The board manager must be initialized

Returns:

ESP_OK On success

esp_err_t esp_board_manager_print_board_info(void)

Print board information.

    Displays board metadata including name, chip type, version, description,
    and manufacturer. This function can be called without initializing the
    board manager

Returns:

ESP_OK On success

esp_err_t esp_board_manager_deinit(void)

Deinitialize the board manager.

    Deinitializes all devices first, then all peripherals. This destroys
    driver handles only; BOARD/APP overrides and prepare state are kept.
    The manager init flag is cleared so init may run again.

Returns:

ESP_OK On success
ESP_BOARD_ERR_MANAGER_NOT_INIT If board manager not initialized
Others Error codes from device or peripheral deinitialization

Structures

struct esp_board_info

Board information structure.

Public Members

const char *name: Board name

const char *chip: Chip type

const char *version: Board version

const char *description: Board description

const char *manufacturer: Board manufacturer

Type Definitions

typedef struct esp_board_info esp_board_info_t: Board information structure.

Was this page helpful?

Thank you! We received your feedback.
If you have any comments, fill in Espressif Documentation Feedback Form.

We value your feedback.
Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.