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
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.

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_init_custom(const char *name, esp_board_periph_init_func init, esp_board_periph_deinit_func deinit)

Initialize peripheral with custom functions.

    Associates custom init and deinit functions with a peripheral and initializes it
    This allows runtime configuration of peripheral behavior. If the peripheral
    is already initialized, only the functions are 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

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)

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.