esp_board_device.h

Header File

esp_board_manager/include/esp_board_device.h

Functions

esp_err_t esp_board_device_init(const char *name)

Initialize a device by name.

    This function initializes a device with reference counting support. If the device
    is already initialized, it increments the reference count instead of reinitializing
    The device is only actually initialized when the reference count reaches 1

参数:

name – [in] Device name to initialize

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device descriptor or handle not found
ESP_BOARD_ERR_DEVICE_NO_INIT If no init function is available
ESP_ERR_INVALID_STATE If the runtime already marks this device initialized
ESP_ERR_INVALID_SIZE If effective config size differs from the descriptor
Others Error codes from device-specific initialization

esp_err_t esp_board_device_get_handle(const char *name, void **device_handle)

Get device handle by name.

    Retrieves the device handle for a given device name. For GPIO devices,
    the handle is dereferenced to get the actual pin number

参数:

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

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name or device_handle is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device handle not found

esp_err_t esp_board_device_get_config(const char *name, void **config)

Get device configuration by name.

    Retrieves the effective configuration for a given device name. The
    returned pointer is owned by BMGR and may be invalidated by the next
    override or restore operation for this device; copy it if it must be
    retained across those operations.

参数:

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

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name or config is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device configuration not found
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If device has no configuration

esp_err_t esp_board_device_get_config_by_handle(void *device_handle, void **config)

Get device configuration by handle.

    Retrieves the configuration for a given device handle

参数:

device_handle – [in] Device handle
config – [out] Pointer to store the configuration

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If given handle is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device handle or configuration not found

esp_err_t esp_board_device_override_config(const char *name, const void *config, uint16_t config_size)

Override a device configuration at runtime (APP layer)

    Stores a top-level byte copy of config for future get_config, init, and
    callback_register. Nested pointers inside the struct are not deep-copied;
    the caller must keep referenced memory valid until restore_config. Size
    need not match the generated descriptor; a mismatch logs a warning and
    still copies config_size bytes, but esp_board_device_init() rejects a
    mismatched effective size with ESP_ERR_INVALID_SIZE. Repeated calls
    replace the previous APP copy. Rejected while this device's ref_count
    is non-zero or it is marked initialized.

参数:

name – [in] Device name
config – [in] Pointer to the new configuration
config_size – [in] Size of the configuration to copy

返回:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails
ESP_ERR_INVALID_STATE If the device is already initialized
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name/config is NULL or config_size is 0
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device is not found
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If device has no generated configuration

esp_err_t esp_board_device_restore_config(const char *name)

Restore APP-layer configuration for a device.

    Clears only the APP config copy. BOARD override remains if present;
    otherwise effective config falls back to generated. Does not change ops.
    Rejected while this device's ref_count is non-zero or it is marked
    initialized.

参数:

name – [in] Device name

返回:

ESP_OK On success
ESP_ERR_NOT_FOUND If no APP config override exists
ESP_ERR_INVALID_STATE If the device is already initialized
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device is not found

esp_err_t esp_board_device_get_i2c_effective_addr(const char *device_name, uint16_t *addr)

Get the effective 8-bit I2C address published by an initialized device.

    Some I2C devices can probe multiple candidate addresses at runtime.
    This function returns the final 8-bit (left-shifted) I2C address that
    the device published after successful initialization. If the returned
    address is passed to ESP-IDF I2C master APIs, shift it right by one.

参数:

device_name – [in] Device name
addr – [out] Pointer to store the 8-bit I2C address

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If device_name or addr is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device does not exist
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If the device has not published an I2C address

esp_err_t esp_board_device_set_ops(const char *name, esp_board_device_init_func init, esp_board_device_deinit_func deinit)

Set per-name device init/deinit ops (APP layer)

    Does not modify the generated handle init/deinit table. Repeated calls
    replace the previous APP ops. Rejected while ref_count is non-zero or
    the device is marked initialized.

参数:

name – [in] Device name
init – [in] Initialization function pointer
deinit – [in] Deinitialization function pointer

返回:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails
ESP_ERR_INVALID_STATE If the device is already initialized
ESP_BOARD_ERR_DEVICE_INVALID_ARG If any parameter is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device is not found

esp_err_t esp_board_device_restore_ops(const char *name)

Restore APP-layer ops for a device.

    Clears only APP ops. BOARD ops remain if present; otherwise effective
    ops fall back to the generated handle init/deinit. Does not change
    config. Rejected while this device's ref_count is non-zero or it is
    marked initialized.

参数:

name – [in] Device name

返回:

ESP_OK On success
ESP_ERR_NOT_FOUND If no APP ops override exists
ESP_ERR_INVALID_STATE If the device is already initialized
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device is not found

esp_err_t esp_board_device_deinit(const char *name)

Deinitialize a device by name.

    Decrements the reference count for a device. The device is only actually
    deinitialized when the reference count reaches 0. If the device is not
    initialized, this function returns success

参数:

name – [in] Device name to deinitialize

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device handle not found
ESP_BOARD_ERR_DEVICE_NO_INIT If no deinit function is available
Others Error codes from device-specific deinitialization

esp_err_t esp_board_device_show(const char *name)

Show device information.

    Displays detailed information about devices. If name is NULL, shows
    information for all devices. Otherwise, shows information for the
    specified device including type, configuration size, handle status,
    and reference count

参数:

name – [in] Device name (NULL for all devices)

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_NOT_FOUND If specific device not found (when name is not NULL)

esp_err_t esp_board_device_iterate_name_by_type(const char *type, void **cursor, const char **name)

Iterate device names by type.

    Iterates over registered device descriptors that match @p type.
    Set *cursor to NULL before the first call. On success, this
    function updates *cursor to the matched descriptor and outputs
    the corresponding device name in *name.

参数:

type – [in] Device type key (for example ESP_BOARD_DEVICE_TYPE_BUTTON)
cursor – [inout] Opaque iteration cursor (set to NULL to start)
name – [out] Next matching device name

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If type/cursor/name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND No more matching devices

esp_err_t esp_board_device_init_all(void)

Initialize all devices.

    Iterates through all device descriptors and initializes each device
    Continues initializing even if some devices fail, but logs errors

备注

Device initialization strictly follows the order defined in board_devices.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 If initialization fails due to unresolved dependencies, either reorder the YAML entries or manually call the device initialization function

返回:

ESP_OK On success (always returns ESP_OK, errors are logged)

esp_err_t esp_board_device_deinit_all(void)

Deinitialize all devices.

    Iterates through all device handles and deinitializes each device
    Continues deinitializing even if some devices fail, but logs errors

返回:

ESP_OK On success (always returns ESP_OK, errors are logged)

const esp_board_device_handle_t *esp_board_device_find_by_handle(void *device_handle)

Find device handle structure by device-specific handle.

    Searches through the device handle linked list to find the device
    handle structure that contains the specified device-specific handle

参数:

device_handle – [in] Device-specific handle to search for

返回:

NULL If not found or if device_handle is NULL
Others Pointer to device handle structure if found

esp_err_t esp_board_device_power_ctrl(const char *name, bool power_on)

Control power for a device.

    This function controls the power state for a device using its associated
    power control device. If the device has a power_ctrl_device configured,
    this function will call the power control function to enable or disable
    power for the device.

参数:

name – [in] Device name to control power for
power_on – [in] True to enable power, false to disable power

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device or power control device not found
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If device has no power control device configured
Others Error codes from power control device

esp_err_t esp_board_device_callback_register(const char *name, void *callback, void *user_data)

Register a callback for a device.

    This function registers a callback function for a specific device.
    It looks up the device descriptor and the device‑specific callback
    registration function based on the device type, then invokes that
    function with the device handle, configuration, and user data.

    For the detailed callback definitions and actual callback behaviors,
    refer to the corresponding device's header file.

    Whether the device supports re-registering (updating) an existing
    callback also depends on the device implementation. Refer to the
    device-specific documentation for details.

参数:

name – [in] Device name
callback – [in] Callback function pointer (device‑specific)
user_data – [in] User data to pass to the callback (optional)

返回:

ESP_OK On success
ESP_BOARD_ERR_DEVICE_INVALID_ARG If name or call_back_func is NULL
ESP_BOARD_ERR_DEVICE_NOT_FOUND If device not found
ESP_BOARD_ERR_DEVICE_NOT_SUPPORTED If device has no callback register func
ESP_BOARD_ERR_DEVICE_INIT_FAILED If callback registration failed
Others Error codes from power control device

Structures

struct esp_board_device_desc

Structure representing a device descriptor.

Public Members

const struct esp_board_device_desc *next: Pointer to next device descriptor

const char *name: Device name

const char *chip: Device chip type

const char *type: Device type

const char *sub_type: Device sub-type

const void *cfg: Device configuration data

uint16_t cfg_size: Size of configuration data

uint8_t init_skip: Skip initialization when manager initializes all devices

const char *power_ctrl_device: Power control device name for this device

const char *const *depends_on: Array of device names this device depends on

uint8_t depends_on_num: Number of dependencies

struct esp_board_device_handle

Structure representing a device handle.

Public Members

struct esp_board_device_handle *next: Pointer to next device handle

const char *name: Device name

const char *chip: Device chip type

const char *type: Device type

void *device_handle: Device-specific handle

uint8_t ref_count: Reference count

esp_board_device_init_func init: Generated default init (fallback ops)

esp_board_device_deinit_func deinit: Generated default deinit (fallback ops)

Macros

DEVICE_EXTRA_FUNC_REGISTER(name, extra_func)

Type Definitions

typedef int (*esp_board_device_init_func)(void *cfg, int cfg_size, void **device_handle): Function pointer type for device initialization.

typedef int (*esp_board_device_deinit_func)(void *device_handle): Function pointer type for device deinitialization.

typedef int (*esp_board_device_power_ctrl_func)(void *dev_handle, const char *device_name, bool power_on): Function pointer type for device power control.

typedef int (*esp_board_device_callback_register_func)(void *dev_handle, const void *cfg, int cfg_size, void *call_back_func, void *user_data): Function pointer type for device callback_register.

typedef struct esp_board_device_desc esp_board_device_desc_t: Structure representing a device descriptor.

typedef struct esp_board_device_handle esp_board_device_handle_t: Structure representing a device handle.

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。