esp_board_periph.h

Header File

esp_board_manager/include/esp_board_periph.h

Functions

esp_err_t esp_board_periph_init(const char *name)

Initialize a peripheral by name.

    This function initializes a peripheral with reference counting support. If the peripheral
    is already initialized, it increments the reference count instead of reinitializing
    The peripheral is only actually initialized when the reference count reaches 1
    Peripherals are found by matching type and role from the handle list

Parameters:

name – [in] Peripheral name to initialize

Returns:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails for list entry
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral descriptor not found
ESP_BOARD_ERR_PERIPH_NO_HANDLE If no matching handle found for type/role
ESP_BOARD_ERR_PERIPH_NO_INIT If no init function is available
ESP_ERR_INVALID_STATE If the runtime already marks this peripheral initialized
ESP_ERR_INVALID_SIZE If effective config size differs from the descriptor
Others Error codes from peripheral-specific initialization

esp_err_t esp_board_periph_get_handle(const char *name, void **periph_handle)

Get peripheral handle by name.

    Retrieves the peripheral handle for a given peripheral name
    The peripheral is automatically initialized if it is not initialized

Parameters:

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

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name or periph_handle is NULL
ESP_BOARD_ERR_PERIPH_NO_HANDLE If peripheral initialized failed or no handle found

esp_err_t esp_board_periph_get_name_by_handle(void *periph_handle, const char **name)

Get peripheral name by handle.

    Retrieves the peripheral name for a given peripheral handle
    Searches through all initialized peripherals to find the matching handle

Parameters:

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

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If periph_handle or name is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If no peripheral found with the given handle

esp_err_t esp_board_periph_ref_handle(const char *name, void **periph_handle)

Get reference peripheral handle by name.

    Retrieves the peripheral handle for a given peripheral name
    The peripheral is automatically initialized if it is not initialized
    Increases the reference count for the peripheral

Parameters:

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

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name or periph_handle is NULL
ESP_BOARD_ERR_PERIPH_NO_HANDLE If peripheral initialized failed or no handle found

esp_err_t esp_board_periph_unref_handle(const char *name)

Unreference peripheral handle by name.

    Decreases the reference count for the peripheral
    The peripheral is only actually deinitialized when the reference count reaches 0

Parameters:

name – [in] Peripheral name

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral list entry not found
ESP_BOARD_ERR_PERIPH_NO_INIT If no deinit function is available
Others Error codes from peripheral-specific deinitialization

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

Get peripheral configuration by name.

    Returns the effective configuration pointer: APP override, else BOARD
    override, else the generated descriptor config. Sidecar layers hold a
    top-level byte copy only; nested pointers inside the struct still
    alias the caller's memory. The returned pointer may be invalidated by
    the next override or restore operation for this peripheral; copy it
    if it must be retained across those operations.

Parameters:

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

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If 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_periph_override_config(const char *name, const void *config, uint16_t config_size)

Override a peripheral configuration at runtime (APP layer)

    Stores a top-level byte copy of config for future get_config and init.
    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_periph_init() rejects a mismatched
    effective size with ESP_ERR_INVALID_SIZE. Repeated calls replace the
    previous APP copy. Rejected while this peripheral is initialized.

Parameters:

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

Returns:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails
ESP_ERR_INVALID_STATE If the peripheral is already initialized
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name/config is NULL or config_size is 0
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral is not found
ESP_BOARD_ERR_PERIPH_NOT_SUPPORTED If peripheral has no generated configuration

esp_err_t esp_board_periph_restore_config(const char *name)

Restore APP-layer configuration for a peripheral.

    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 peripheral's ref_count is non-zero.

Parameters:

name – [in] Peripheral name

Returns:

ESP_OK On success
ESP_ERR_NOT_FOUND If no APP config override exists
ESP_ERR_INVALID_STATE If the peripheral is already initialized
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL

esp_err_t esp_board_periph_set_ops(const char *name, esp_board_periph_init_func init, esp_board_periph_deinit_func deinit)

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

    Does not modify the shared type/role handler table. Repeated calls
    replace the previous APP ops. Rejected while ref_count is non-zero.

Parameters:

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

Returns:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails
ESP_ERR_INVALID_STATE If the peripheral is already initialized
ESP_BOARD_ERR_PERIPH_INVALID_ARG If any parameter is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral is not found

esp_err_t esp_board_periph_restore_ops(const char *name)

Restore APP-layer ops for a peripheral.

    Clears only APP ops. BOARD ops remain if present; otherwise effective
    ops fall back to the shared type/role handler. Does not change config.
    Rejected while this peripheral's ref_count is non-zero.

Parameters:

name – [in] Peripheral name

Returns:

ESP_OK On success
ESP_ERR_NOT_FOUND If no APP ops override exists
ESP_ERR_INVALID_STATE If the peripheral is already initialized
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL

esp_err_t esp_board_periph_init_custom(const char *name, esp_board_periph_init_func init, esp_board_periph_deinit_func deinit)

Initialize peripheral with custom functions (legacy)

    Legacy ABI: updates the shared (type, role) handler table and initializes
    the named peripheral immediately. It is not the per-name variant mechanism
    and does not write APP/BOARD sidecar ops or use effective config priority;
    init uses the generated descriptor config. New code should use the board
    pre-init hook (BOARD ``set_ops``) or APP :c:func:`esp_board_periph_set_ops`.
    If the peripheral is already initialized, only the shared handler is updated.

Parameters:

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

Returns:

ESP_OK On success
ESP_ERR_NO_MEM If memory allocation fails for list entry
ESP_BOARD_ERR_PERIPH_INVALID_ARG If any parameter is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral descriptor not found
ESP_BOARD_ERR_PERIPH_NO_HANDLE If no matching handle found for type/role
ESP_BOARD_ERR_PERIPH_INIT_FAILED If initialization fails

esp_err_t esp_board_periph_deinit(const char *name)

Deinitialize a peripheral by name.

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

Parameters:

name – [in] Peripheral name to deinitialize

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_INVALID_ARG If name is NULL
ESP_BOARD_ERR_PERIPH_NOT_FOUND If peripheral list entry not found
ESP_BOARD_ERR_PERIPH_NO_INIT If no deinit function is available
Others Error codes from peripheral-specific deinitialization

esp_err_t esp_board_periph_show(const char *name)

Show peripheral information.

    Displays detailed information about peripherals. If name is NULL, shows
    information for all peripherals. Otherwise, shows information for the
    specified peripheral including type, role, handle status, and reference count

Parameters:

name – [in] Peripheral name (NULL for all peripherals)

Returns:

ESP_OK On success
ESP_BOARD_ERR_PERIPH_NOT_FOUND If specific peripheral not found (when name is not NULL)

esp_err_t esp_board_periph_init_all(void)

Initialize all peripherals.

    Iterates through all peripheral descriptors and initializes each peripheral
    Continues initializing even if some peripherals fail, but logs errors
    Descriptors with init_skip set are left uninitialized; call
    esp_board_periph_init() later if that peripheral is needed

Note

Peripheral initialization follows the order defined in board_peripherals.yaml

Returns:

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

esp_err_t esp_board_periph_deinit_all(void)

Deinitialize all peripherals.

    Iterates through all peripheral list entries and deinitializes each peripheral
    Continues deinitializing even if some peripherals fail, but logs errors

Returns:

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

Structures

struct esp_board_periph_desc

Structure representing a peripheral descriptor.

Public Members

const struct esp_board_periph_desc *next: Pointer to next peripheral descriptor

const char *name: Peripheral name

const char *type: Peripheral type

esp_board_periph_role_t role: Peripheral role

const char *format: Peripheral format

const void *cfg: Peripheral configuration data

int cfg_size: Size of configuration data

int id: Peripheral ID extracted from name (e.g., 48 from gpio48, 0 from iic0)

uint8_t init_skip: Skip initialization when manager initializes all peripherals

struct esp_board_periph_entry

Structure representing a peripheral entry.

Public Members

struct esp_board_periph_entry *next: Pointer to next peripheral entry

const char *type: Peripheral type

esp_board_periph_role_t role: Peripheral role

esp_board_periph_init_func init: Peripheral initialization function

esp_board_periph_deinit_func deinit: Peripheral deinitialization function

struct esp_board_periph_list

Structure representing a peripheral list entry.

Public Members

struct esp_board_periph_list *next: Pointer to next peripheral list entry

const char *name: Peripheral name

const char *type: Peripheral type

esp_board_periph_role_t role: Peripheral role

void *periph_handle: Peripheral-specific handle

uint8_t ref_count: Reference count

Macros

PERIPHERAL_EXTRA_FUNC_REGISTER(name, extra_func)

Type Definitions

typedef esp_err_t (*esp_board_periph_init_func)(void *cfg, int cfg_size, void **periph_handle): Function pointer type for peripheral initialization.

typedef esp_err_t (*esp_board_periph_deinit_func)(void *periph_handle): Function pointer type for peripheral deinitialization.

typedef struct esp_board_periph_desc esp_board_periph_desc_t: Structure representing a peripheral descriptor.

typedef struct esp_board_periph_entry esp_board_periph_entry_t: Structure representing a peripheral entry.

typedef struct esp_board_periph_list esp_board_periph_list_t: Structure representing a peripheral list entry.

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.