ESP-IDF Programming Guide

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/
Admin
Official documentation for Espressif IoT Development Framework (ESP-IDF), the development framework...
Tokens:1,563,897
Snippets:13,420
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Navigate to NimBLE_Connection Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-connection.html

Navigate to the NimBLE_Connection example directory within your ESP-IDF installation. Replace <ESP-IDF Path> with your local ESP-IDF folder path.

```bash
$ cd <ESP-IDF Path>/examples/bluetooth/ble_get_started/nimble/NimBLE_Connection

```

--------------------------------

### Protocomm HTTPD Server Start and Security 2 Setup

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/provisioning/protocomm.html

This C code demonstrates starting a Protocomm server over HTTPD and configuring it with Security 2 parameters, including salt and verifier. It registers a security endpoint for secure communication.

```c
static const char sec2_salt[] = {0xf7, 0x5f, 0xe2, 0xbe, 0xba, 0x7c, 0x81, 0xcd};
static const char sec2_verifier[] = {0xbf, 0x86, 0xce, 0x63, 0x8a, 0xbb, 0x7e, 0x2f, 0x38, 0xa8, 0x19, 0x1b, 0x35,
    0xc9, 0xe3, 0xbe, 0xc3, 0x2b, 0x45, 0xee, 0x10, 0x74, 0x22, 0x1a, 0x95, 0xbe, 0x62, 0xf7, 0x0c, 0x65, 0x83, 0x50,
    0x08, 0xef, 0xaf, 0xa5, 0x94, 0x4b, 0xcb, 0xe1, 0xce, 0x59, 0x2a, 0xe8, 0x7b, 0x27, 0xc8, 0x72, 0x26, 0x71, 0xde,
    0xb2, 0xf2, 0x80, 0x02, 0xdd, 0x11, 0xf0, 0x38, 0x0e, 0x95, 0x25, 0x00, 0xcf, 0xb3, 0x3f, 0xf0, 0x73, 0x2a, 0x25,
    0x03, 0xe8, 0x51, 0x72, 0xef, 0x6d, 0x3e, 0x14, 0xb9, 0x2e, 0x9f, 0x2a, 0x90, 0x9e, 0x26, 0xb6, 0x3e, 0xc7, 0xe4,
    0x9f, 0xe3, 0x20, 0xce, 0x28, 0x7c, 0xbf, 0x89, 0x50, 0xc9, 0xb6, 0xec, 0xdd, 0x81, 0x18, 0xf1, 0x1a, 0xd9, 0x7a,
    0x21, 0x99, 0xf1, 0xee, 0x71, 0x2f, 0xcc, 0x93, 0x16, 0x34, 0x0c, 0x79, 0x46, 0x23, 0xe4, 0x32, 0xec, 0x2d, 0x9e,
    0x18, 0xa6, 0xb9, 0xbb, 0x0a, 0xcf, 0xc4, 0xa8, 0x32, 0xc0, 0x1c, 0x32, 0xa3, 0x97, 0x66, 0xf8, 0x30, 0xb2, 0xda,
    0xf9, 0x8d, 0xc3, 0x72, 0x72, 0x5f, 0xe5, 0xee, 0xc3, 0x5c, 0x24, 0xc8, 0xdd, 0x54, 0x49, 0xfc, 0x12, 0x91, 0x81,
    0x9c, 0xc3, 0xac, 0x64, 0x5e, 0xd6, 0x41, 0x88, 0x2f, 0x23, 0x66, 0xc8, 0xac, 0xb0, 0x35, 0x0b, 0xf6, 0x9c, 0x88,
    0x6f, 0xac, 0xe1, 0xf4, 0xca, 0xc9, 0x07, 0x04, 0x11, 0xda, 0x90, 0x42, 0xa9, 0xf1, 0x97, 0x3d, 0x94, 0x65, 0xe4,
    0xfb, 0x52, 0x22, 0x3b, 0x7a, 0x7b, 0x9e, 0xe9, 0xee, 0x1c, 0x44, 0xd0, 0x73, 0x72, 0x2a, 0xca, 0x85, 0x19, 0x4a,
    0x60, 0xce, 0x0a, 0xc8, 0x7d, 0x57, 0xa4, 0xf8, 0x77, 0x22, 0xc1, 0xa5, 0xfa, 0xfb, 0x7b, 0x91, 0x3b, 0xfe, 0x87,
    0x5f, 0xfe, 0x05, 0xd2, 0xd6, 0xd3, 0x74, 0xe5, 0x2e, 0x68, 0x79, 0x34, 0x70, 0x40, 0x12, 0xa8, 0xe1, 0xb4, 0x6c,
    0xaa, 0x46, 0x73, 0xcd, 0x8d, 0x17, 0x72, 0x67, 0x32, 0x42, 0xdc, 0x10, 0xd3, 0x71, 0x7e, 0x8b, 0x00, 0x46, 0x9b,
    0x0a, 0xe9, 0xb4, 0x0f, 0xeb, 0x70, 0x52, 0xdd, 0x0a, 0x1c, 0x7e, 0x2e, 0xb0, 0x61, 0xa6, 0xe1, 0xa3, 0x34, 0x4b,
    0x2a, 0x3c, 0xc4, 0x5d, 0x42, 0x05, 0x58, 0x25, 0xd3, 0xca, 0x96, 0x5c, 0xb9, 0x52, 0xf9, 0xe9, 0x80, 0x75, 0x3d,
    0xc8, 0x9f, 0xc7, 0xb2, 0xaa, 0x95, 0x2e, 0x76, 0xb3, 0xe1, 0x48, 0xc1, 0x0a, 0xa1, 0x0a, 0xe8, 0xaf, 0x41, 0x28,
    0xd2, 0x16, 0xe1, 0xa6, 0xd0, 0x73, 0x51, 0x73, 0x79, 0x98, 0xd9, 0xb9, 0x00, 0x50, 0xa2, 0x4d, 0x99, 0x18, 0x90,
    0x70, 0x27, 0xe7, 0x8d, 0x56, 0x45, 0x34, 0x1f, 0xb9, 0x30, 0xda, 0xec, 0x4a, 0x08, 0x27, 0x9f, 0xfa, 0x59, 0x2e,
    0x36, 0x77, 0x00, 0xe2, 0xb6, 0xeb, 0xd1, 0x56, 0x50, 0x8e};

/* The example function for launching a protocomm instance over HTTP. */
protocomm_t *start_pc() {
    protocomm_t *pc = protocomm_new();


    /* Config for protocomm_httpd_start(). */
    protocomm_httpd_config_t pc_config = {
        .data = {
        .config = PROTOCOMM_HTTPD_DEFAULT_CONFIG()
        }
    };

    /* Start the protocomm server on top of HTTP. */
    protocomm_httpd_start(pc, &pc_config);

    /* Create Security2 params object from salt and verifier. It must be valid throughout the scope of protocomm endpoint. This does not need to be static, i.e., could be dynamically allocated and freed at the time of endpoint removal. */
    const static protocomm_security2_params_t sec2_params = {
        .salt = (const uint8_t *) sec2_salt,
        .salt_len = sizeof(sec2_salt),
        .verifier = (const uint8_t *) sec2_verifier,
        .verifier_len = sizeof(sec2_verifier),
    };

    /* Set security for communication at the application level. Just like for request handlers, setting security creates an endpoint and registers the handler provided by protocomm_security1. One can similarly use protocomm_security0. Only one type of security can be set for a protocomm instance at a time. */
    protocomm_set_security(pc, "security_endpoint", &protocomm_security2, &sec2_params);

    /* Private data passed to the endpoint must be valid throughout the scope of protocomm endpoint. This need not be static, i.e., could be dynamically allocated and freed at the time of endpoint removal. */
    return pc;
}
```

--------------------------------

### Copy 'hello_world' Example Project

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-start-project.html

Copy the 'hello_world' example project from the ESP-IDF examples directory to your desired project location. Ensure there are no spaces in the paths to ESP-IDF or your project.

```bash
cd ~/
esp
cp -r $IDF_PATH/examples/get-started/hello_world .
```

--------------------------------

### Launch ESP-IDF Interactive Installation Wizard

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html

Run this command to launch the interactive installation wizard for customizing ESP-IDF installation options.

```bash
eim wizard

```

--------------------------------

### Scan Specific SBOM File Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-sbom.html

Example of scanning the SPDX SBOM file generated for the `hello_world` example project.

```bash
$ idf.py sbom-check --spdx-file build/hello_world.spdx
```

--------------------------------

### Open NimBLE_Connection Project in VSCode

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-connection.html

After navigating to the example directory, open the project in VSCode. This command assumes VSCode is installed and configured in your system's PATH.

```bash
$ code .

```

--------------------------------

### esp_spp_start_srv_with_cfg

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/esp_spp.html

Starts an SPP server with additional configuration options, including the ability to specify whether to create an SPP record. Useful for advanced server setups.

```APIDOC
## esp_spp_start_srv_with_cfg

### Description

This function is similar to `esp_spp_start_srv`. The only difference is that it adds a parameter to specify whether to create the SPP record.

Note
If the SPP record is not created, it is suggested to use it together with the SDP API.

### Method

ESP_IDF_FUNCTION

### Parameters

#### Path Parameters

- **cfg** (const esp_spp_start_srv_cfg_t *) - Input - Configuration parameters for starting the server.

### Returns

- **ESP_OK**: success
- **other**: failed
```

--------------------------------

### Install ESP-IDF Installation Manager (GUI and CLI) via APT

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html

Installs both the Graphical User Interface (GUI) and Command Line Interface (CLI) versions of the ESP-IDF Installation Manager using APT.

```bash
sudo apt install eim
```

--------------------------------

### Install ESP-IDF Tools (Windows Command Prompt)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-setup-update-legacy.html

Run this script from the Windows Command Prompt to download and install necessary ESP-IDF tools. If a tool is already installed, no action is taken.

```batch
install.bat

```

--------------------------------

### GDB Command Line Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/debugging-examples.html

This example shows the GDB command line interface after a breakpoint is hit in the app_main function of the blink example.

```gdb
Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43
43      xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
(gdb)

```

--------------------------------

### Install EIM GUI with Homebrew

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html

Installs the Espressif Installation Manager (EIM) Graphical User Interface (GUI) using Homebrew.

```bash
brew install --cask eim-gui

```

--------------------------------

### Install Basic Dependencies for CI

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/esp-idf-tests-with-pytest.html

Installs basic dependencies required for continuous integration by running the ESP-IDF install script with the --enable-ci argument.

```bash
$ install.sh --enable-ci

```

--------------------------------

### Copy Example Project

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-start-project.html

Copies the 'hello_world' example project to your user's esp directory. Ensure that paths do not contain spaces.

```batch
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world

```

--------------------------------

### esp_console_new_repl_uart

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/console.html

Establishes a console REPL (Read-Eval-Print-Loop) environment over a UART driver. This function is intended for example code to simplify setup and includes UART driver installation, stdin/stdout configuration, linenoise initialization, and spawning a background REPL thread.

```APIDOC
## esp_console_new_repl_uart

### Description
Establishes a console REPL environment over the UART driver. This function is meant to be used in examples to make the code more compact. Applications which use console functionality should be based on the underlying linenoise and esp_console functions. This is an all-in-one function to establish the environment needed for REPL, including installing the UART driver, configuring stdin/stdout, initializing linenoise, and spawning a new thread to run REPL in the background.

### Function Signature
```c
esp_err_t esp_console_new_repl_uart(const esp_console_dev_uart_config_t *dev_config, const esp_console_repl_config_t *repl_config, esp_console_repl_t **ret_repl)
```

### Parameters
#### Path Parameters
- **dev_config** (const esp_console_dev_uart_config_t *) - Pointer to the UART device configuration.
- **repl_config** (const esp_console_repl_config_t *) - Pointer to the REPL configuration.
- **ret_repl** (esp_console_repl_t **) - Output pointer that will be assigned the REPL handle after initialization succeeds, or NULL otherwise.

### Returns
- **ESP_OK** on success
- **ESP_FAIL** if a parameter error occurs.
```

--------------------------------

### Install esptool and Start RFC2217 Server on Linux/macOS

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-docker-image.html

Installs the esptool package and starts the RFC2217 server on Linux or macOS for remote serial port access. Replace the device path with your actual serial port.

```bash
pip install esptool

```

```bash
esp_rfc2217_server -v -p 4000 /dev/ttyUSB0

```

--------------------------------

### Create Project From Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html

Creates a new project from a specified example component in the ESP Component Registry.

```bash
idf.py create-project-from-example EXAMPLE
```

--------------------------------

### Install Tools for Specific Chip Target

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html

Installs tools only for the specified chip target, for example, ESP32.

```bash
install.sh esp32
```

--------------------------------

### ESP-IDF Installation Success Message

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html

This message indicates a successful ESP-IDF installation and suggests starting with IDF tools.

```text
2025-11-03T15:54:12.537993300+08:00 - INFO - Wizard result: %{r}
2025-11-03T15:54:12.544174+08:00 - INFO - Successfully installed IDF
2025-11-03T15:54:12.545913900+08:00 - INFO - Now you can start using IDF tools

```

--------------------------------

### Start QEMU with GDB and Monitor

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/qemu.html

Starts QEMU, enables the GDB server, and opens the IDF Monitor. QEMU waits for a GDB connection.

```bash
idf.py qemu --gdb monitor

```

--------------------------------

### Start ESP32 Ethernet Driver

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_eth.html

Starts the Ethernet driver's state machine after it has been installed. This enables network communication.

```c
esp_eth_start(eth_handle); // start Ethernet driver state machine
```

--------------------------------

### Navigate to NimBLE_GATT_Server Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-introduction.html

Use this command to navigate to the example directory for the tutorial. Replace <ESP-IDF Path> with your local ESP-IDF folder path.

```bash
$ cd <ESP-IDF Path>/examples/bluetooth/ble_get_started/nimble/NimBLE_GATT_Server
```

--------------------------------

### Install LEDC Fade Function

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/ledc.html

Installs the LEDC fade function, which requires allocating an interrupt. Call this once before using fade start functions.

```c
esp_err_t ledc_fade_func_install(int intr_alloc_flags)
```

--------------------------------

### Start QEMU with GDB Server

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/qemu.html

Builds the application, starts QEMU with GDB server, and opens an interactive GDB session for debugging.

```bash
idf.py qemu gdb

```

--------------------------------

### Start ESP HTTP Server

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_http_server.html

Starts the web server by creating an instance and allocating resources based on the provided configuration. Ensure URI handlers are registered after successful startup.

```c
httpd_handle_t start_webserver(void)
{
// Generate default configuration
httpd_config_t config = HTTPD_DEFAULT_CONFIG();

// Empty handle to http_server
     httpd_handle_t server = NULL;

// Start the httpd server
if (httpd_start(&server, &config) == ESP_OK) {
// Register URI handlers
         httpd_register_uri_handler(server, &uri_get);
         httpd_register_uri_handler(server, &uri_post);
     }
// If server failed to start, handle will be NULL
return server;
}
```

--------------------------------

### Example 1: SDKCONFIG_DEFAULTS with multiple files

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html

Demonstrates the order of applying configuration defaults when SDKCONFIG_DEFAULTS includes multiple files, including target-specific variations.

```shell
SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"
```

--------------------------------

### Get Component Directory Property

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html

Use `idf_component_get_property` to retrieve the directory of a specific component. This example shows how to get the directory for the 'freertos' component and print it.

```cmake
idf_component_get_property(dir freertos COMPONENT_DIR)
message(STATUS "The 'freertos' component directory is: ${dir}")

```

--------------------------------

### Get a Specific Attribute of a Module

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/soc_caps.html

Use the SOC_MODULE_ATTR macro to retrieve a specific attribute of a given module. For example, to get the number of instances for a GPTIMER module.

```c
SOC_MODULE_ATTR(GPTIMER, NUM)
```

--------------------------------

### Example sdkconfig File

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/kconfig/configuration_structure.html

Illustrates a typical `sdkconfig` file, showing both new configuration options and deprecated options used for backward compatibility.

```text
CONFIG_HYPERDRIVE=y
CONFIG_DISABLE_HYPERDRIVE=n
(...)
# Deprecated options for backward compatibility
CONFIG_WARP_DRIVE=y
CONFIG_ENABLE_WARP_DRIVE=y
# End of deprecated options
```

--------------------------------

### httpd_start

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_http_server.html

Starts the web server by creating an instance and allocating resources based on the provided configuration.

```APIDOC
## httpd_start

### Description
Starts the web server. Create an instance of HTTP server and allocate memory/resources for it depending upon the specified configuration.

### Method
httpd_start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
//Function for starting the webserver
httpd_handle_t start_webserver(void)
{
// Generate default configuration
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();

// Empty handle to http_server
     httpd_handle_t server = NULL;

// Start the httpd server
    if (httpd_start(&server, &config) == ESP_OK) {
// Register URI handlers
         httpd_register_uri_handler(server, &uri_get);
         httpd_register_uri_handler(server, &uri_post);
     }
// If server failed to start, handle will be NULL
return server;
}
```

### Response
#### Success Response (ESP_OK)
Instance created successfully.

#### Error Responses
* ESP_ERR_INVALID_ARG : Null argument(s)
* ESP_ERR_HTTPD_ALLOC_MEM : Failed to allocate memory for instance
* ESP_ERR_HTTPD_TASK : Failed to launch server task

#### Response Example
None explicitly provided in source, but returns ESP_OK on success.
```

--------------------------------

### protocomm_ble_start

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/provisioning/protocomm.html

Starts the Bluetooth Low Energy based transport layer for provisioning. It initializes and starts the required BLE service, including characteristics and service setup.

```APIDOC
## protocomm_ble_start

### Description
Starts the Bluetooth Low Energy based transport layer for provisioning. Initializes and starts required BLE service for provisioning. This includes the initialization for characteristics/service for BLE.

### Function Signature
`esp_err_t protocomm_ble_start(protocomm_t *pc, const protocomm_ble_config_t *config)`

### Parameters
#### Path Parameters
- **pc** (protocomm_t *) - [in] Protocomm instance pointer obtained from protocomm_new()
- **config** (const protocomm_ble_config_t *) - [in] Pointer to config structure for initializing BLE

### Returns
- **ESP_OK** : Success
- **ESP_FAIL** : Simple BLE start error
- **ESP_ERR_NO_MEM** : Error allocating memory for internal resources
- **ESP_ERR_INVALID_STATE** : Error in ble config
- **ESP_ERR_INVALID_ARG** : Null arguments
```

--------------------------------

### esp_bt_gap_get_remote_services

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/esp_gap_bt.html

Starts SDP to get remote services. This should be called after esp_bluedroid_enable() completes successfully.

```APIDOC
## esp_bt_gap_get_remote_services

### Description
Starts SDP to get remote services. This function should be called after esp_bluedroid_enable() completes successfully. esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery ends.

### Parameters
#### Path Parameters
- **remote_bda** (esp_bd_addr_t) - Required - Remote Bluetooth device address

### Returns
- ESP_OK : Succeed
- ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
- ESP_FAIL: others
```

--------------------------------

### Install Pre-built QEMU Binaries

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/qemu.html

Installs pre-built QEMU binaries for ESP32 emulation using the idf_tools.py script.

```bash
python $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32

```

--------------------------------

### Run Hello World Test in QEMU

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/contribute/esp-idf-tests-with-pytest.html

Shows how to execute a pytest case in QEMU by adding the @pytest.mark.qemu marker and parameterizing targets.

```python
@pytest.mark.qemu
@idf_parametrize('target', ['esp32', 'esp32c3'], indirect=['target'])
def test_hello_world_qemu(dut) -> None:
    dut.expect('Hello world!')

```

--------------------------------

### Start ESP-IDF MCP Server using EIM

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-py.html

Starts the ESP-IDF MCP server using the ESP-IDF Installation Manager (EIM). This is the recommended method and does not require pre-activation of the ESP-IDF environment.

```bash
eim run "idf.py mcp-server"

```

--------------------------------

### Get Property Values Handler

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_local_ctrl.html

Example implementation of a handler function used to retrieve property values from the device.

```APIDOC
## Get Property Values Handler

### Description
This function is called when a request is made to retrieve the values of one or more properties. It iterates through the requested properties and provides their current values.

### Function Signature
`static esp_err_t get_property_values(size_t props_count, const esp_local_ctrl_prop_t *props, esp_local_ctrl_prop_val_t *prop_values, void *usr_ctx)`

### Parameters
- **props_count** (size_t) - The number of properties to retrieve.
- **props** (`esp_local_ctrl_prop_t`*) - An array of property structures for which values are requested.
- **prop_values** (`esp_local_ctrl_prop_val_t`*) - An array to store the retrieved property values.
- **usr_ctx** (void*) - User-defined context pointer.

### Property Value Structure (`esp_local_ctrl_prop_val_t`)
- **data** (void*) - Pointer to the property's data.
- **size** (size_t) - The size of the property's data.

### Example (Timestamp Property Retrieval)
```c
static esp_err_t get_property_values(size_t props_count,
                                     const esp_local_ctrl_prop_t *props,
                                     esp_local_ctrl_prop_val_t *prop_values,
                                     void *usr_ctx)
{
    for (uint32_t i = 0; i < props_count; i++) {
        ESP_LOGI(TAG, "Reading %s", props[i].name);
        if (props[i].type == TYPE_TIMESTAMP) {
            /* Obtain the timer function from ctx */
            int32_t (*func_get_time)(void) = props[i].ctx;

            /* Use static variable for saving the value. This is essential because the value has to be valid even after this function returns. Alternative is to use dynamic allocation and set the free_fn field */
            static int32_t ts = func_get_time();
            prop_values[i].data = &ts;
            prop_values[i].size = sizeof(ts);
        }
    }
    return ESP_OK;
}
```
```

--------------------------------

### Example Build Configuration Output

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-introduction.html

These messages indicate that the chip has been successfully configured and the build files have been generated.

```text
...
-- Configuring done
-- Generating done
-- Build files have been written to ...
```

--------------------------------

### Install Python Environment with Features

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html

Command to install or update a Python virtual environment, including specific features. Features starting with '-' are removed, while '+' or no prefix add them. A requirements file must exist for each feature.

```shell
idf_tools.py install-python-env --features=-XY,+ABC

```

--------------------------------

### Create a unit-test-app project

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/tools.html

Use this command to create a new project from the 'unit-test-app' example provided by espressif.

```bash
idf.py create-project-from-example espressif/unit-test-app:unit-test-app
```

--------------------------------

### Get Minimum Free Heap Size

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/misc_system_api.html

Retrieve the minimum amount of free heap that has been available since the system started.

```c
uint32_t esp_get_minimum_free_heap_size(void)
```

--------------------------------

### Comparison of Newlib vs Picolibc Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/system.html

This example demonstrates file operations that highlight the differences in memory and stack usage between Newlib and Picolibc. It is used to show the motivation for switching to Picolibc.

```c
FILE *f = fopen("/dev/console", "w");
for (int i = 0; i < 10; i++)
{
    fprintf(f, "hello world %s\n", "🤖");
    fprintf(f, "%.1000f\n", 3.141592653589793);
    fprintf(f, "%1000d\n", 42);
}

```

--------------------------------

### Get Current Tick Count

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/freertos_idf.html

Retrieves the current tick count since the scheduler was started. This function is not safe to call from an ISR.

```c
TickType_t xTaskGetTickCount(void)
```

--------------------------------

### Initialize Network Interface

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_netif.html

This code demonstrates the typical startup sequence for initializing the TCP/IP stack, event loop, creating a network interface handle, attaching a driver's glue layer, and registering user-side event handlers. Error handling is omitted for brevity.

```c
esp_netif_init();
esp_event_loop_create_default();

// 1) Create the network interface handle
esp_netif = esp_netif_new(&config);

// 2) Create the network interface driver (e.g., Ethernet) and it's network layer glue
// and register the ESP-NETIF event (e.g., to bring the interface up upon link-up event)
esp_netif_glue_t glue = driver_glue(driver);

// 3) Attach the driver's glue layer to the network interface handle
esp_netif_attach(esp_netif, glue);

// 4) Register user-side event handlers
esp_event_handler_register(DRIVER_EVENT, ...);  // to observe driver states, e.g., link-up
esp_event_handler_register(IP_EVENT, ...);      // to observe ESP-NETIF states, e.g., get an IP

```

--------------------------------

### DFU Update Operations

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/esp-ble-mesh.html

APIs related to the firmware update process, including getting update information, starting, and applying updates.

```APIDOC
## ESP_BLE_MESH_DFU_OP_UPDATE_INFO_GET

### Description
Get update information.

## ESP_BLE_MESH_DFU_OP_UPDATE_INFO_STATUS

### Description
Status of update information.

## ESP_BLE_MESH_DFU_OP_UPDATE_METADATA_CHECK

### Description
Check firmware metadata.

## ESP_BLE_MESH_DFU_OP_UPDATE_METADATA_STATUS

### Description
Status of firmware metadata check.

## ESP_BLE_MESH_DFU_OP_UPDATE_GET

### Description
Get current update status.

## ESP_BLE_MESH_DFU_OP_UPDATE_START

### Description
Start firmware update.

## ESP_BLE_MESH_DFU_OP_UPDATE_CANCEL

### Description
Cancel firmware update.

## ESP_BLE_MESH_DFU_OP_UPDATE_APPLY

### Description
Apply firmware update.

## ESP_BLE_MESH_DFU_OP_UPDATE_STATUS

### Description
Firmware update status.
```

--------------------------------

### Configure Project Target and Settings

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-start-project.html

Navigate to your project directory, set the target chip to 'esp32', and launch the project configuration utility 'menuconfig'. This step initializes the project and clears existing configurations.

```bash
cd ~/
esp/hello_world
idf.py set-target esp32
idf.py menuconfig
```

--------------------------------

### Example Post-Attach Callback

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_netif_driver.html

A sample post-attach callback function for an I/O driver. It sets the driver configuration, registers callbacks with ESP-NETIF, and starts the driver.

```c
static esp_err_t my_post_attach_start(esp_netif_t * esp_netif, void * args)
{
    my_netif_driver_t *driver = args;
    const esp_netif_driver_ifconfig_t driver_ifconfig = {
            .driver_free_rx_buffer = my_free_rx_buf,
            .transmit = my_transmit,
            .handle = driver->driver_impl
    };
    driver->base.netif = esp_netif;
    ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig));
    my_driver_start(driver->driver_impl);
    return ESP_OK;
}
```

--------------------------------

### Full Build Output Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-start-project.html

This is an example of the detailed output you might see during the build process, including cmake execution and final binary generation.

```bash
$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...

... (more lines of build system output)

[527/527] Generating hello_world.bin
esptool v5.0.2

Project build complete. To flash, run:
  idf.py flash
or
  idf.py -p PORT flash
or
  esptool -p (PORT) -b 921600 write-flash --flash-mode dio --flash-size detect --flash-freq 40m 0x10000 build/hello_world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin

```

--------------------------------

### Get Ethernet PHY Address

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_eth.html

Retrieves the PHY address of the Ethernet interface using the esp_eth_ioctl function with the ETH_CMD_G_PHY_ADDR command. This should be invoked after the Ethernet driver has been installed.

```c
/* get PHY address */
int phy_addr = -1;
esp_eth_ioctl(eth_handle, ETH_CMD_G_PHY_ADDR, &phy_addr);
ESP_LOGI(TAG, "Ethernet PHY Address: %d", phy_addr);

```

--------------------------------

### Open Project in VSCode

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-introduction.html

After navigating to the example directory, use this command to open the project in VSCode.

```bash
$ code .
```

--------------------------------

### Get Ethernet MAC Address

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_eth.html

Retrieves the MAC address of the Ethernet interface using the esp_eth_ioctl function with the ETH_CMD_G_MAC_ADDR command. This should be invoked after the Ethernet driver has been installed.

```c
/* get MAC address */
uint8_t mac_addr[6];
memset(mac_addr, 0, sizeof(mac_addr));
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr);
ESP_LOGI(TAG, "Ethernet MAC Address: %02x:%02x:%02x:%02x:%02x:%02x",
         mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_addr[4], mac_addr[5]);

```

--------------------------------

### Initialize Wokwi Project Configuration

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/third-party-tools/wokwi.html

Use wokwi-cli init to automatically create necessary configuration files for Wokwi simulation in your ESP-IDF project directory.

```bash
wokwi-cli init

```

--------------------------------

### Default ESP32 EMAC Configuration

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_eth.html

Get the default configuration for the ESP32's EMAC specific settings. This provides a starting point for customizing the Ethernet MAC configuration.

```c
eth_esp32_emac_config_t esp32_config = ETH_ESP32_EMAC_DEFAULT_CONFIG();

```

--------------------------------

### New Socket-Based Ping API in ESP-IDF v6.0

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/networking.html

Replace deprecated ping APIs with the new socket-based API from ping/ping_sock.h. This example shows how to create, configure, and start a new ping session.

```c
#include "ping/ping_sock.h"

// Create ping session
esp_ping_config_t config = ESP_PING_DEFAULT_CONFIG();
config.target_addr = target_ip;
esp_ping_callbacks_t cbs = {
    .on_ping_success = on_ping_success,
    .on_ping_timeout = on_ping_timeout,
    .on_ping_end = on_ping_end,
};
esp_ping_handle_t ping;
esp_ping_new_session(&config, &cbs, &ping);
esp_ping_start(ping);
```

--------------------------------

### Initialize Wi-Fi and LwIP for ESP-WIFI-MESH

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp-wifi-mesh.html

This snippet shows the prerequisite steps for initializing LwIP and Wi-Fi before ESP-WIFI-MESH can be set up. It includes event loop creation, Wi-Fi initialization, IP event handler registration, and starting Wi-Fi.

```c
ESP_ERROR_CHECK(esp_netif_init());

/*  event initialization */
ESP_ERROR_CHECK(esp_event_loop_create_default());

/*  Wi-Fi initialization */
wifi_init_config_t config = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&config));
/*  register IP events handler */
ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &ip_event_handler, NULL));
ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
ESP_ERROR_CHECK(esp_wifi_start());

```

--------------------------------

### Implement Property Get Handler for Timestamp

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_local_ctrl.html

An example of a 'get_prop_values()' handler that retrieves timestamp properties. It demonstrates how to access custom context functions and use static variables to ensure data validity after function return.

```c
static esp_err_t get_property_values(size_t props_count,
                                     const esp_local_ctrl_prop_t *props,
                                     esp_local_ctrl_prop_val_t *prop_values,
                                     void *usr_ctx)
{
    for (uint32_t i = 0; i < props_count; i++) {
        ESP_LOGI(TAG, "Reading %s", props[i].name);
        if (props[i].type == TYPE_TIMESTAMP) {
            /* Obtain the timer function from ctx */
            int32_t (*func_get_time)(void) = props[i].ctx;

            /* Use static variable for saving the value. This is essential because the value has to be valid even after this function returns. Alternative is to use dynamic allocation and set the free_fn field */
            static int32_t ts = func_get_time();
            prop_values[i].data = &ts;
        }
    }
    return ESP_OK;
}
```

--------------------------------

### Launch GDB with Initialization Files

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/using-debugger.html

Use this command to launch the GDB debugger, loading necessary symbol information, prefix maps, and connection configurations for the target device. The '-q' option minimizes startup output.

```bash
xtensa-esp32-elf-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map -x build/gdbinit/connect build/blink.elf

```

--------------------------------

### Example Build Output

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-start-project.html

This output shows the detailed process of the build system compiling the project, including CMake execution and component processing.

```bash
$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...

... (more lines of build system output)

[527/527] Generating hello_world.bin
esptool v5.0.2

Project build complete. To flash, run:
  idf.py flash
or
  idf.py -p PORT flash
or
  esptool -p (PORT) -b 921600 write-flash --flash-mode dio --flash-size detect --flash-freq 40m 0x10000 build/hello_world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin


```

--------------------------------

### Configure Component Mock with idf_component_mock

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/unit-tests.html

Use IDF build system functions to define mock component headers, include paths, and dependencies. This example shows how to get the original component directory and register mock parts.

```cmake
idf_component_get_property(original_component_dir <original-component-name> COMPONENT_OVERRIDEN_DIR)
...
idf_component_mock(INCLUDE_DIRS "${original_component_dir}/include"
    REQUIRES freertos
    MOCK_HEADER_FILES ${original_component_dir}/include/header_containing_functions_to_mock.h)

```

--------------------------------

### GDB Session Output and Breakpoint Confirmation

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/using-debugger.html

This is an example of the output you will see after launching GDB, including symbol loading, connection messages, and confirmation that the debugger has halted at a breakpoint in the app_main function. This indicates a successful setup for debugging.

```text
xtensa-esp32-elf-gdb -q -x build/gdbinit/symbols -x build/gdbinit/connect build/blink.elf
Reading symbols from build/blink.elf...
add symbol table from file "/home/user-name/esp-idf/examples/get-started/blink/build/bootloader/bootloader.elf"
[Switching to Thread 1070141764]
app_main () at /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c:95
95          configure_led();
add symbol table from file "/home/alex/.espressif/tools/esp-rom-elfs/20241011/esp32_rev0_rom.elf"
JTAG tap: esp32.tap0 tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
[esp32] Reset cause (3) - (Software core reset)
Hardware assisted breakpoint 1 at 0x42009436: file /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c, line 92.
[Switching to Thread 1070139884]

Thread 2 "main" hit Temporary breakpoint 1, app_main () at /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c:92
92      {
(gdb) 

```

--------------------------------

### v2 Component CMakeLists.txt Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system-v2.html

Example CMakeLists.txt for a v2 component, demonstrating how to include dependencies, add libraries, set include directories, and link libraries.

```cmake
idf_component_include(spi_flash)

add_library(${COMPONENT_TARGET} STATIC
    "hello_world_main.c"
)

target_include_directories(${COMPONENT_TARGET} PUBLIC
    "${CMAKE_CURRENT_LIST_DIR}"
)

target_link_libraries(${COMPONENT_TARGET} PRIVATE
    idf::spi_flash
)


```

--------------------------------

### Configure and Transmit with RMT Sync Manager

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/rmt.html

This snippet demonstrates how to configure two RMT TX channels, install a sync manager to ensure simultaneous transmission, and initiate the transmission process. It highlights the dependency of one channel's transmission start on the other.

```c
rmt_channel_handle_t tx_channels[2] = {NULL}; // declare two channels
int tx_gpio_number[2] = {0, 2};
// install channels one by one
for (int i = 0; i < 2; i++) {
    rmt_tx_channel_config_t tx_chan_config = {
        .clk_src = RMT_CLK_SRC_DEFAULT,       // select source clock
        .gpio_num = tx_gpio_number[i],    // GPIO number
        .mem_block_symbols = 64,          // memory block size, 64 * 4 = 256 Bytes
        .resolution_hz = 1 * 1000 * 1000, // 1 MHz resolution
        .trans_queue_depth = 1,           // set the number of transactions that can pend in the background
    };
    ESP_ERROR_CHECK(rmt_new_tx_channel(&tx_chan_config, &tx_channels[i]));
}
// enable the channels
for (int i = 0; i < 2; i++) {
    ESP_ERROR_CHECK(rmt_enable(tx_channels[i]));
}
// install sync manager
rmt_sync_manager_handle_t synchro = NULL;
rmt_sync_manager_config_t synchro_config = {
    .tx_channel_array = tx_channels,
    .array_size = sizeof(tx_channels) / sizeof(tx_channels[0]),
};
ESP_ERROR_CHECK(rmt_new_sync_manager(&synchro_config, &synchro));

ESP_ERROR_CHECK(rmt_transmit(tx_channels[0], led_strip_encoders[0], led_data, led_num * 3, &transmit_config));
// tx_channels[0] does not start transmission until call of `rmt_transmit()` for tx_channels[1] returns
ESP_ERROR_CHECK(rmt_transmit(tx_channels[1], led_strip_encoders[1], led_data, led_num * 3, &transmit_config));

```

--------------------------------

### Navigate to NimBLE_Beacon Example Directory

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/ble/get-started/ble-device-discovery.html

Navigate to the NimBLE_Beacon example directory. Replace <ESP-IDF Path> with your local ESP-IDF folder path.

```bash
cd <ESP-IDF Path>/examples/bluetooth/ble_get_started/nimble/NimBLE_Beacon
```

--------------------------------

### Connect Ethernet Driver to TCP/IP Stack

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_eth.html

This section details the steps and provides code examples for connecting the installed Ethernet driver to the LwIP TCP/IP stack. It covers initializing the network interface, attaching it to the driver, and registering IP event handlers.

```APIDOC
## Connect Ethernet Driver to TCP/IP Stack

This operation involves initializing the TCP/IP network interface, creating a network interface for the Ethernet driver, attaching the network interface to the Ethernet driver, and registering IP event handlers.

### Steps:
1. Initialize TCP/IP network interface: `esp_netif_init()`
2. Configure network interface for Ethernet: `ESP_NETIF_DEFAULT_ETH()`
3. Create network interface: `esp_netif_new()`
4. Attach Ethernet driver to TCP/IP stack: `esp_netif_attach()`
5. Register IP event handlers, specifically for `IP_EVENT_ETH_GOT_IP`.
6. Start the Ethernet driver: `esp_eth_start()`

### Example Code:
```c
// Event handler for IP_EVENT_ETH_GOT_IP
static void got_ip_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
{
    ip_event_got_ip_t *event = (ip_event_got_ip_t *) event_data;
    const esp_netif_ip_info_t *ip_info = &event->ip_info;

    ESP_LOGI(TAG, "Ethernet Got IP Address");
    ESP_LOGI(TAG, "~~~~~~~~~~~");
    ESP_LOGI(TAG, "ETHIP:" IPSTR, IP2STR(&ip_info->ip));
    ESP_LOGI(TAG, "ETHMASK:" IPSTR, IP2STR(&ip_info->netmask));
    ESP_LOGI(TAG, "ETHGW:" IPSTR, IP2STR(&ip_info->gw));
    ESP_LOGI(TAG, "~~~~~~~~~~~");
}

// Initialization and connection steps
esp_netif_init(); // Initialize TCP/IP network interface
esp_netif_config_t cfg = ESP_NETIF_DEFAULT_ETH(); // Apply default network interface configuration for Ethernet
esp_netif_t *eth_netif = esp_netif_new(&cfg); // Create network interface for Ethernet driver
esp_netif_attach(eth_netif, esp_eth_new_netif_glue(eth_handle)); // Attach Ethernet driver to TCP/IP stack
esp_event_handler_register(IP_EVENT, IP_EVENT_ETH_GOT_IP, &got_ip_event_handler, NULL); // Register user defined IP event handlers
esp_eth_start(eth_handle); // Start Ethernet driver state machine
```

### Warning:
Register event handlers as the last step before starting the Ethernet driver to ensure proper system state.
```

--------------------------------

### Start SystemView Tracing (Basic)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html

Begin SystemView tracing, saving data from PRO CPU and APP CPU to specified files. This command operates in non-blocking mode.

```bash
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat

```
Tokens:
Raw