ESP-IDF

https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/
Admin
ESP-IDF is the official development framework for Espressif's ESP32, ESP32-S, ESP32-C, ESP32-H, and...
Tokens:939,242
Snippets:8,548
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### esp apptrace start Examples

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/app_trace.html

Examples demonstrating the usage of the 'esp apptrace start' command with various options.

```APIDOC
## `esp apptrace start` Command Examples

### Example 1: Collect 2048 bytes with timeouts

```
esp apptrace start file://trace.log 1 2048 5 0 0
```

**Description:** Collects 2048 bytes of tracing data to `trace.log`. Runs in non-blocking mode (`poll_period` = 1 ms). Stops automatically after 2048 bytes or if no data is available for 5 seconds (`stop_tmo` = 5). Tracing starts immediately (`wait4halt` = 0).

### Example 2: Collect tracing data indefinitely (non-blocking)

```
esp apptrace start file://trace.log 1 -1 -1 0 0
```

**Description:** Collects tracing data indefinitely in non-blocking mode. No limit on data size (`trace_size` = -1) and no data timeout (`stop_tmo` = -1). Tracing starts immediately (`wait4halt` = 0). This can be stopped manually with `esp apptrace stop` or Ctrl+C.

### Example 3: Collect tracing data indefinitely (blocking)

```
esp apptrace start file://trace.log 0 -1 -1 0 0
```

**Description:** Collects tracing data indefinitely in blocking mode (`poll_period` = 0). The OpenOCD telnet prompt will be unavailable until tracing is stopped (e.g., by Ctrl+C).

### Example 4: Wait for halt, then collect 2048 bytes

```
esp apptrace start file://trace.log 0 2048 -1 1 0
```

**Description:** Waits for the target to halt (`wait4halt` = 1), then resumes and starts tracing. Collects 2048 bytes of data (`trace_size` = 2048). Runs in blocking mode (`poll_period` = 0). No data timeout (`stop_tmo` = -1).
```

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

### Navigate to NimBLE_Connection Example

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

Use this command to 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
```

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

### Copying the Hello World Project

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/windows-start-project.html

Commands to navigate to the user directory and copy the hello_world example project from the ESP-IDF installation path.

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

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

### Start HTTP Server

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/protocols/esp_http_server.html

Starts the web server by creating an instance and allocating resources based on the provided configuration. Ensure the handle is checked for NULL after starting.

```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;
}

```

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

### Configuration Examples

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/sdmmc_host.html

Examples for configuring bus frequency, width, and GPIO mapping.

```APIDOC
### Configuring Bus Frequency
```c
sdmmc_host_t host = SDMMC_HOST_DEFAULT();
host.max_freq_khz = SDMMC_FREQ_HIGHSPEED;
```

### Configuring Bus Width
```c
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.width = 1;
```

### Configuring GPIOs
```c
sdmmc_slot_config_t slot = SDMMC_SLOT_CONFIG_DEFAULT();
slot.clk = GPIO_NUM_1;
slot.cmd = GPIO_NUM_2;
slot.d0 = GPIO_NUM_3;
slot.d1 = GPIO_NUM_4;
slot.d2 = GPIO_NUM_5;
slot.d3 = GPIO_NUM_6;
```
```

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

### Build System Output Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/linux-macos-setup.html

Example output showing the build process and the command to flash the device.

```text
$ 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.py v2.3.1

Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -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
or run 'idf.py -p PORT flash'
```

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

### Start Ethernet Driver

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp_eth.html

Initiates the Ethernet driver state machine after successful installation.

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

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

### Installing documentation dependencies

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/contribute/documenting-code.html

Run the install script with the --enable-docs flag to set up the required Python environment.

```bash
./install.sh --enable-docs
```

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

### Implement Post-Attach Callback

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp_netif_driver.html

Example of a post-attach callback function used to register driver configuration and start 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;
}
```

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

### Initialize and Configure Touch Element Library

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/touch_element.html

This code demonstrates the initialization flow for the Touch Element library, including global configuration, element installation, instance creation, event subscription, dispatch method selection, and starting the library. It uses default initializers for global configurations.

```c
static touch_xxx_handle_t element_handle; //Declare a touch element handle

//Define the subscribed event handler
void event_handler(touch_xxx_handle_t out_handle, touch_xxx_message_t out_message, void *arg)
{
    //Event handler logic
}

void app_main()
{
    //Using the default initializer to config Touch Element library
    touch_elem_global_config_t global_config = TOUCH_ELEM_GLOBAL_DEFAULT_CONFIG();
    touch_element_install(&global_config);

    //Using the default initializer to config Touch elements
    touch_xxx_global_config_t elem_global_config = TOUCH_XXXX_GLOBAL_DEFAULT_CONFIG();
    touch_xxx_install(&elem_global_config);

    //Create a new instance
    touch_xxx_config_t element_config = {
        ...
        ...
    };
    touch_xxx_create(&element_config, &element_handle);

    //Subscribe the specified events by using the event mask
    touch_xxx_subscribe_event(element_handle, TOUCH_ELEM_EVENT_ON_PRESS | TOUCH_ELEM_EVENT_ON_RELEASE, NULL);

    //Choose CALLBACK as the dispatch method
    touch_xxx_set_dispatch_method(element_handle, TOUCH_ELEM_DISP_CALLBACK);

    //Register the callback routine
    touch_xxx_set_callback(element_handle, event_handler);

    //Start Touch Element library processing
    touch_element_start();

}
```

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

### Create and Start Software Timers

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/freertos_idf.html

This example demonstrates creating multiple software timers, assigning them unique IDs, and starting them. It includes a callback function that increments an expiry counter and stops the timer after a set number of expirations. Ensure timers are created before the scheduler starts for immediate operation.

```c
#define NUM_TIMERS 5

// An array to hold handles to the created timers.
TimerHandle_t xTimers[ NUM_TIMERS ];

// An array to hold a count of the number of times each timer expires.
int32_t lExpireCounters[ NUM_TIMERS ] = { 0 };

// Define a callback function that will be used by multiple timer instances.
// The callback function does nothing but count the number of times the
// associated timer expires, and stop the timer once the timer has expired
// 10 times.
void vTimerCallback( TimerHandle_t pxTimer )
{
    int32_t lArrayIndex;
    const int32_t xMaxExpiryCountBeforeStopping = 10;

    // Optionally do something if the pxTimer parameter is NULL.
    configASSERT( pxTimer );

    // Which timer expired?
    lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );

    // Increment the number of times that pxTimer has expired.
    lExpireCounters[ lArrayIndex ] += 1;

    // If the timer has expired 10 times then stop it from running.
    if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )
    {
        // Do not use a block time if calling a timer API function from a
        // timer callback function, as doing so could cause a deadlock!
        xTimerStop( pxTimer, 0 );
    }
}

void main( void )
{
    int32_t x;

    // Create then start some timers.  Starting the timers before the scheduler
    // has been started means the timers will start running immediately that
    // the scheduler starts.
    for( x = 0; x < NUM_TIMERS; x++ )
    {
        xTimers[ x ] = xTimerCreate(    "Timer",             // Just a text name, not used by the kernel.
                                        ( 100 * ( x + 1 ) ), // The timer period in ticks.
                                        pdTRUE,              // The timers will auto-reload themselves when they expire.
                                        ( void * ) x,        // Assign each timer a unique id equal to its array index.
                                        vTimerCallback       // Each timer calls the same callback when it expires.
                                    );

        if( xTimers[ x ] == NULL )
        {
            // The timer was not created.
        }
        else
        {
            // Start the timer.  No block time is specified, and even if one was
            // it would be ignored because the scheduler has not yet been
            // started.
            if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
            {
                // The timer could not be set into the Active state.
            }
        }
    }

    // ...
    // Create tasks here.
    // ...

    // Starting the scheduler will start the timers running as they have already
    // been set into the active state.
    vTaskStartScheduler();

    // Should not reach here.
    for( ;; );
}

```

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

### OpenOCD Version Output Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/jtag-debugging/index.html

This is an example of the expected output when verifying the OpenOCD installation. The version number may differ.

```text
Open On-Chip Debugger v0.12.0-esp32-20240318 (2024-03-18-18:25)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html

```

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

### Install esp-idf-sbom

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/idf-sbom.html

Install the tool from PyPI using pip.

```bash
$ pip install esp-idf-sbom
```

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

### Mbed TLS Direct Usage Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/protocols/esp_crt_bundle.html

Shows how to activate the certificate bundle when using Mbed TLS directly by calling the attach function during the setup process.

```APIDOC
## Mbed TLS Direct Usage Example

If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:

```c
mbedtls_ssl_config conf;
mbedtls_ssl_config_init(&conf);

esp_crt_bundle_attach(&conf);
```
```

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

### Install pre-commit package

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/contribute/install-pre-commit-hook.html

Install the pre-commit framework using pip.

```bash
pip install pre-commit
```

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

### Install ESP-IDF Tools using install.bat

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/windows-setup-update.html

Run this command from the Windows Command Prompt in your ESP-IDF directory to download and install necessary tools. If tools are already installed, no action is taken.

```batch
install.bat
```

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

### Install ESP-IDF Tools using install.ps1

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/windows-setup-update.html

Run this command from PowerShell in your ESP-IDF directory to download and install necessary tools. If tools are already installed, no action is taken.

```powershell
install.ps1
```

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

### Start Provisioning Service

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/provisioning/wifi_provisioning.html

Starts the provisioning service according to the scheme configured during initialization. This can involve starting protocomm_ble for BLE transport or protocomm_httpd for SoftAP mode. An event WIFI_PROV_START is emitted upon successful start.

```APIDOC
## Start Provisioning Service

### Description
Starts the provisioning service according to the scheme configured at the time of initialization. For scheme `wifi_prov_scheme_ble`: This starts `protocomm_ble`, which internally initializes BLE transport and starts a GATT server for handling provisioning requests. For scheme `wifi_prov_scheme_softap`: This activates SoftAP mode of Wi-Fi and starts `protocomm_httpd`, which internally starts an HTTP server for handling provisioning requests (If mDNS is active, it also starts advertising the service with type `_esp_wifi_prov._tcp`). Event `WIFI_PROV_START` is emitted right after provisioning starts without failure. Note: This API will start the provisioning service even if the device is found to be already provisioned (i.e., `wifi_prov_mgr_is_provisioned()` yields true).

### Method
esp_err_t

### Endpoint
wifi_prov_mgr_start_provisioning

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **security** (wifi_prov_security_t) - Required - Specify which protocomm security scheme to use:
  * `WIFI_PROV_SECURITY_0`: For no security.
  * `WIFI_PROV_SECURITY_1`: x25519 secure handshake for session establishment followed by AES-CTR encryption of provisioning messages.
  * `WIFI_PROV_SECURITY_2`: SRP6a based authentication and key exchange followed by AES-GCM encryption/decryption of provisioning messages.
- **wifi_prov_sec_params** (const void *) - Required - Pointer to security parameters (NULL if not needed). This is not needed for `protocomm` security 0. This pointer should hold the struct of type `wifi_prov_security1_params_t` for `protocomm` security 1 and `wifi_prov_security2_params_t` for `protocomm` security 2, respectively. This pointer and its contents should be valid until the provisioning service is running and has not been stopped or de-inited.
- **service_name** (const char *) - Required - Unique name of the service. This translates to:
  * Wi-Fi SSID when provisioning mode is softAP.
  * Device name when provisioning mode is BLE.
- **service_key** (const char *) - Optional - Key required by the client to access the service (NULL if not needed). This translates to:
  * Wi-Fi password when provisioning mode is softAP.
  * Ignored when provisioning mode is BLE.

### Request Example
```c
// Example for WIFI_PROV_SECURITY_0 with SoftAP
esp_err_t ret = wifi_prov_mgr_start_provisioning(WIFI_PROV_SECURITY_0, NULL, "MyDeviceSSID", "MyWiFiPassword");

// Example for WIFI_PROV_SECURITY_1 with BLE (assuming params are set)
// wifi_prov_security1_params_t sec_params = { ... };
// esp_err_t ret = wifi_prov_mgr_start_provisioning(WIFI_PROV_SECURITY_1, &sec_params, "MyDeviceName", NULL);
```

### Response
#### Success Response (ESP_OK)
- **ESP_OK** : Provisioning started successfully

#### Error Response (ESP_FAIL, ESP_ERR_INVALID_STATE)
- **ESP_FAIL** : Failed to start provisioning service
- **ESP_ERR_INVALID_STATE** : Provisioning manager not initialized or already started
```

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

### Install External Hub Driver

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.html

Installs the External Hub Driver. This function should be called to initialize the driver.

```c
ext_hub_install()
```

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

### Install Ethernet Driver with Default Configuration

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp_eth.html

Uses the ETH_DEFAULT_CONFIG macro to initialize the driver configuration and installs it using esp_eth_driver_install.

```c
esp_eth_config_t config = ETH_DEFAULT_CONFIG(mac, phy); // apply default driver configuration
esp_eth_handle_t eth_handle = NULL; // after the driver is installed, we will get the handle of the driver
esp_eth_driver_install(&config, &eth_handle); // install driver
```

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

### Install QEMU System Dependencies

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/qemu.html

Commands to install required system libraries for QEMU on various Linux distributions and macOS.

```bash
sudo apt-get install -y libgcrypt20 libglib2.0-0 libpixman-1-0 libsdl2-2.0-0 libslirp0
```

```bash
sudo yum install -y --enablerepo=powertools libgcrypt glib2 pixman SDL2 libslirp
```

```bash
sudo pacman -S --needed libgcrypt glib2 pixman sdl2 libslirp
```

```bash
brew install libgcrypt glib pixman sdl2 libslirp
```

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

### Copy Hello World Example Project

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/windows-setup.html

Copies the 'hello_world' example project to a specified directory. Ensure that paths do not contain spaces or special characters.

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

```

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

### Get Voltage Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/adc_calibration.html

Example code demonstrating how to get the calibrated voltage from an ADC raw reading using the `adc_cali_raw_to_voltage` function.

```APIDOC
#### Get Voltage
```c
ESP_ERROR_CHECK(adc_cali_raw_to_voltage(adc_cali_handle, adc_raw[0][0], &voltage[0][0]));
ESP_LOGI(TAG, "ADC%d Channel[%d] Cali Voltage: %d mV", ADC_UNIT_1 + 1, EXAMPLE_ADC1_CHAN0, voltage[0][0]);

```
```

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

### Example Usage: Get Temperature Value

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/temp_sensor.html

Demonstrates how to enable, get the temperature, and disable the temperature sensor.

```C
// Enable temperature sensor
ESP_ERROR_CHECK(temperature_sensor_enable(temp_handle));
// Get converted sensor data
float tsens_out;
ESP_ERROR_CHECK(temperature_sensor_get_celsius(temp_handle, &tsens_out));
printf("Temperature in %f °C\n", tsens_out);
// Disable the temperature sensor if it is not needed and save the power
ESP_ERROR_CHECK(temperature_sensor_disable(temp_handle));
```

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

### STAGE_INC Example: Up Counting Loop Setup

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ulp_instruction_set.html

This example is part of an up-counting loop, showing the initialization with STAGE_RST and subsequent increments using STAGE_INC.

```assembly
// Up counting loop example:
          STAGE_RST                  // set stage_cnt to 0
  label:  STAGE_INC  1               // stage_cnt++
          NOP                        // do something
          JUMPS      label, 16, LT   // jump to label if stage_cnt < 16
```

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

### Copy the Hello World Project

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

Copies the standard hello_world example project from the ESP-IDF directory to the local workspace.

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

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

### Configure and Start Simultaneous RMT Transmission

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/rmt.html

Installs multiple RMT TX channels and a sync manager to coordinate simultaneous transmission start times.

```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_GATT_Server Example

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

Use this command to navigate to the 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_GATT_Server
```

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

### STAGE_DEC Example: Down Counting Loop Setup

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ulp_instruction_set.html

This example is part of a down-counting loop, demonstrating the initialization of the stage count and subsequent decrements using STAGE_DEC.

```assembly
// Down counting loop example
          STAGE_RST                // set stage_cnt to 0
          STAGE_INC  16            // increment stage_cnt to 16
  label:  STAGE_DEC  1             // stage_cnt--;
          NOP                      // do something
          JUMPS      label, 0, GT  // jump to label if stage_cnt > 0
```

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

### esp_ota_begin

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ota.html

Commences an OTA update session by preparing the target partition.

```APIDOC
## esp_err_t esp_ota_begin(const esp_partition_t *partition, size_t image_size, esp_ota_handle_t *out_handle)

### Description
Starts an OTA update process. The specified partition is erased to accommodate the new image size. On success, it allocates memory and returns a handle for subsequent write and end operations.

### Parameters
- **partition** (const esp_partition_t*) - Pointer to the target OTA partition.
- **image_size** (size_t) - Size of the new image. Use OTA_SIZE_UNKNOWN to erase the entire partition.
- **out_handle** (esp_ota_handle_t*) - Pointer to store the handle for the OTA session.

### Returns
- **esp_err_t** - ESP_OK on success, or an error code (e.g., ESP_ERR_NO_MEM, ESP_ERR_OTA_PARTITION_CONFLICT) on failure.
```

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

### Install Xcode Command Line Tools

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/linux-macos-setup.html

Installs the Xcode command line tools on macOS, which are necessary if you encounter 'xcrun: error: invalid active developer path' errors during setup.

```bash
xcode-select --install

```

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

### Start the graphical configuration tool

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/idf-py.html

Opens the menuconfig interface for project configuration.

```bash
idf.py menuconfig
```

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

### Navigate to NimBLE_Beacon Example Directory

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

Use this command to navigate to the 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
```

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

### Open Project in VSCode

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

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

```bash
$ code .
```

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

### Open Project in VSCode

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/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 RTOS Tick Timestamp

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/log.html

Returns the timestamp in milliseconds, primarily using the FreeRTOS tick count after the scheduler starts. It uses the CPU cycle counter in early boot stages.

```c
uint32_t esp_log_timestamp(void);
```

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

### Install QEMU Binaries

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/qemu.html

Command to install the pre-built QEMU binaries for Xtensa and RISC-V architectures using the ESP-IDF tools script.

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

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

### Install Temperature Sensor

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/temp_sensor.html

Installs the temperature sensor driver and obtains a handle. Configure the minimum and maximum expected temperature range before installation. Use ESP_ERROR_CHECK to handle potential installation errors.

```c
temperature_sensor_handle_t temp_handle = NULL;
temperature_sensor_config_t temp_sensor_config = TEMPERATURE_SENSOR_CONFIG_DEFAULT(20, 50);
ESP_ERROR_CHECK(temperature_sensor_install(&temp_sensor_config, &temp_handle));

```

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

### Build, Flash, and Monitor ESP-IDF Project

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

Connect the development board and run this command to build the firmware, flash it to the board, and monitor the serial output.

```bash
idf.py flash monitor
```

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

### Start Polling SPI Transaction

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/spi_master.html

Starts a polling transaction. Useful for inserting operations between the start and end of a transaction.

```c
spi_device_polling_start(device_handle, &transaction);

```

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

### Build, Flash, and Monitor ESP-IDF Project

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

Connect the development board and run this command to build the firmware, flash it to the board, and monitor the serial output.

```bash
$ idf.py flash monitor
```

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

### Enable Graphics Support

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/qemu.html

Launches QEMU with a virtual framebuffer device for graphics testing.

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

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

### Install Pytest-Specific Dependencies

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/contribute/esp-idf-tests-with-pytest.html

Installs additional dependencies required for specific test scripts. Run this after the initial ESP-IDF pytest installation if needed.

```bash
$ install.sh --enable-test-specific

```

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

### esp_console_start_repl

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/console.html

Starts the REPL environment.

```APIDOC
## esp_console_start_repl

### Description
Starts the REPL environment using the provided handle.

### Parameters
- **repl** (esp_console_repl_t*) - Required - REPL handle.

### Response
- **ESP_OK** - Success
- **ESP_ERR_INVALID_STATE** - REPL already started
```

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

### Initialize MQTT Client with URI

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/protocols/mqtt.html

Minimal configuration for an MQTT client using a URI string.

```c
const esp_mqtt_client_config_t mqtt_cfg = {
    .broker.address.uri = "mqtt://mqtt.eclipseprojects.io",
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client);
esp_mqtt_client_start(client);
```

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

### Ext Port Driver Installation and Uninstallation

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/usb_host/usb_host_notes_ext_port.html

The Ext Port Driver can be installed and uninstalled using specific API calls. After installation, the driver API can be accessed.

```APIDOC
## Installation and Uninstallation

### Description
Procedures for installing and uninstalling the Ext Port Driver.

### API Functions
- `ext_port_install(config)`: Installs the Ext Port Driver with the provided configuration.
- `ext_port_uninstall()`: Uninstalls the Ext Port Driver.
- `ext_port_get_driver()`: Retrieves the Ext Port Driver API after installation.
```

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

### Bootloader and Partition Table CSV Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/partition-tables.html

A sample CSV configuration that explicitly includes bootloader and partition table entries.

```csv
# ESP-IDF Partition Table
# Name,           Type,            SubType,  Offset,  Size,     Flags
bootloader,       bootloader,      primary,  N/A,     N/A,
partition_table,  partition_table, primary,  N/A,     N/A,
nvs,              data,            nvs,      ,        0x6000,
phy_init,         data,            phy,      ,        0x1000,
factory,          app,             factory,  ,        1M,
recoveryBloader,  bootloader,      recovery, N/A,     N/A,
```

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

### Run Application in QEMU

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/qemu.html

Starts the application in QEMU and connects the IDF monitor to the emulated UART.

```bash
idf.py qemu monitor
```

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

### Build Project

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/linux-macos-setup.html

Compiles the application and generates the necessary binaries.

```bash
idf.py build
```

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

### Start Listening for DPP Connections

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp_dpp.html

Starts listening on the channels specified during esp_supp_dpp_bootstrap_gen. The device listens for a predefined wait time on each channel. This function requires WiFi to be started.

```c
esp_err_t esp_supp_dpp_start_listen(void)
```

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

### ESP-IDF Build Directory Structure Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/contribute/esp-idf-tests-with-pytest.html

Illustrates the directory structure for built binaries in CI, organized by target and configuration.

```bash
. 
├── build_esp32_history/
│   └── ...
├── build_esp32_nohistory/
│   └── ...
├── build_esp32s2_history/
│   └── ...
├── ...
├── main/
├── CMakeLists.txt
├── sdkconfig.ci.history
├── sdkconfig.ci.nohistory
└── ...

```

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

### Mesh Start and Stop

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp-wifi-mesh.html

APIs for starting and stopping the mesh network.

```APIDOC
## esp_mesh_start()

### Description
Start mesh.
* Initialize mesh IE.
* Start mesh network management service.
* Create TX and RX queues according to the configuration.
* Register mesh packets receive callback.

**Attention**
This API shall be called after mesh initialization and configuration.

### Method
void

### Endpoint
N/A

### Returns
* ESP_OK
* ESP_FAIL
* ESP_ERR_MESH_NOT_INIT
* ESP_ERR_MESH_NOT_CONFIG
* ESP_ERR_MESH_NO_MEMORY

## esp_mesh_stop()

### Description
Stop mesh.
* Deinitialize mesh IE.
* Disconnect with current parent.
* Disassociate all currently associated children.
* Stop mesh network management service.
* Unregister mesh packets receive callback.
* Delete TX and RX queues.
* Release resources.
* Restore Wi-Fi softAP to default settings if Wi-Fi dual mode is enabled.
* Set Wi-Fi Power Save type to WIFI_PS_NONE.

### Method
void

### Endpoint
N/A

### Returns
* ESP_OK
* ESP_FAIL
```

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

### Start Provisioning Service

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/provisioning/wifi_provisioning.html

Initiate the provisioning service using `wifi_prov_mgr_start_provisioning()`. Specify security level, proof of possession, service name, and service key. Security 1 offers secure communication with handshake and encryption, while Security 0 uses plain text.

```c
const char *service_name = "my_device";
const char *service_key  = "password";

wifi_prov_security_t security = WIFI_PROV_SECURITY_1;
const char *pop = "abcd1234";

ESP_ERROR_CHECK( wifi_prov_mgr_start_provisioning(security, pop, service_name, service_key) );
```

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

### Flash the project

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/idf-py.html

Flashes the project to the target, automatically building it first if necessary.

```bash
idf.py flash
```

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

### Install PCNT Unit

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/peripherals/pcnt.html

Configure and install a new PCNT unit. Ensure interrupt priorities are consistent if installing multiple units. Returns `ESP_ERR_NOT_FOUND` if no free units are available.

```c
#define EXAMPLE_PCNT_HIGH_LIMIT 100
#define EXAMPLE_PCNT_LOW_LIMIT  -100

pcnt_unit_config_t unit_config = {
    .high_limit = EXAMPLE_PCNT_HIGH_LIMIT,
    .low_limit = EXAMPLE_PCNT_LOW_LIMIT,
};
pcnt_unit_handle_t pcnt_unit = NULL;
ESP_ERROR_CHECK(pcnt_new_unit(&unit_config, &pcnt_unit));

```

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

### Ethernet Driver Installation and Uninstallation

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/network/esp_eth.html

APIs for installing and uninstalling the Ethernet driver.

```APIDOC
## esp_eth_driver_install

### Description
Installs the Ethernet driver with the provided configuration.

### Method
`esp_err_t esp_eth_driver_install(const esp_eth_config_t *config, esp_eth_handle_t *out_hdl)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (ESP_OK)
Ethernet driver installed successfully.

#### Error Responses
- **ESP_ERR_INVALID_ARG**: Invalid argument provided.
- **ESP_ERR_NO_MEM**: Not enough memory available.
- **ESP_FAIL**: An unspecified error occurred.

### Response Example
None

## esp_eth_driver_uninstall

### Description
Uninstalls the Ethernet driver. It is recommended to use this only when the driver will no longer be used, ensuring all references are released and the reference counter is one.

### Method
`esp_err_t esp_eth_driver_uninstall(esp_eth_handle_t hdl)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (ESP_OK)
Ethernet driver uninstalled successfully.

#### Error Responses
- **ESP_ERR_INVALID_ARG**: Invalid argument provided.
- **ESP_ERR_INVALID_STATE**: Driver has more than one reference.
- **ESP_FAIL**: An unspecified error occurred.

### Response Example
None
```

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

### Configure NimBLE Host

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

Sets up stack callbacks and initializes host configuration storage.

```c
static void nimble_host_config_init(void) {
    /* Set host callbacks */
    ble_hs_cfg.reset_cb = on_stack_reset;
    ble_hs_cfg.sync_cb = on_stack_sync;
    ble_hs_cfg.store_status_cb = ble_store_util_status_rr;

    /* Store host configuration */
    ble_store_config_init();
}

void app_main(void) {
    ...

    /* NimBLE host configuration initialization */
    nimble_host_config_init();

    ...
}
```

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

### Perform Unattended Installation

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/idf-windows-installer.html

Executes the installer in silent mode without user interaction.

```bash
esp-idf-tools-setup-x.x.exe /VERYSILENT /SUPPRESSMSGBOXES /SP- /NOCANCEL
```

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

### Install OpenOCD Dependencies

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/jtag-debugging/building-openocd-macos.html

Use Homebrew to install the required packages for compiling OpenOCD.

```bash
brew install automake libtool libusb wget gcc@4.9 pkg-config
```

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

### Configure the Project Target and Settings

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

Sets the build target to esp32s3 and opens the project configuration menu.

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

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

### ST32 Instruction Examples

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ulp_instruction_set.html

Examples demonstrating the use of the ST32 instruction for memory storage.

```assembly
1:        ST32  R1, R2, 0x12, 0       // MEM[R2 + 0x12 / 4][31:0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]}

2:        .data                       // Data section definition
  Addr1:  .word     123               // Define label Addr1 16 bit
          .set      offs, 0x00        // Define constant offs
          .text                       // Text section definition
          MOVE      R1, 1             // R1 = 1
          MOVE      R2, Addr1         // R2 = Addr1
          ST32      R1, R2, offs, 1   // MEM[R2 +  0] = {PC[10:0],0[2:0],Label[1:0],Rsrc[15:0]}
                                      // MEM[Addr1 + 0] will be 32'h00010001
```

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

### STH Instruction Examples

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ulp_instruction_set.html

Examples demonstrating the use of the STH instruction for memory storage.

```assembly
1:        STH  R1, R2, 0x12           // MEM[R2 + 0x12 / 4][31:16] = R1

2:        .data                       // Data section definition
  Addr1:  .word     123               // Define label Addr1 16 bit
          .set      offs, 0x00        // Define constant offs
          .text                       // Text section definition
          MOVE      R1, 1             // R1 = 1
          MOVE      R2, Addr1         // R2 = Addr1
          STH       R1, R2, offs      // MEM[R2 +  0 / 4] = R1
                                      // MEM[Addr1 + 0] will be 32'h0001xxxx
3:
          MOVE      R1, 1             // R1 = 1
          STH       R1, R2, 0x12, 1   // MEM[R2 + 0x12 / 4] 0x4001xxxx
```

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

### Open Project Documentation

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/tools/idf-py.html

Opens the project-specific documentation in the default web browser.

```bash
idf.py docs
```

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

### STL Instruction Examples

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-reference/system/ulp_instruction_set.html

Examples demonstrating the use of the STL instruction for memory storage.

```assembly
1:        STL  R1, R2, 0x12           // MEM[R2 + 0x12 / 4] = R1

2:        .data                       // Data section definition
  Addr1:  .word     123               // Define label Addr1 16 bit
          .set      offs, 0x00        // Define constant offs
          .text                       // Text section definition
          MOVE      R1, 1             // R1 = 1
          MOVE      R2, Addr1         // R2 = Addr1
          STL       R1, R2, offs      // MEM[R2 +  0 / 4] = R1
                                      // MEM[Addr1 + 0] will be 32'hxxxx0001
3:
          MOVE      R1, 1             // R1 = 1
          STL       R1, R2, 0x12, 1   // MEM[R2 + 0x12 / 4] = 0xxxxx4001
```

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

### ESP_ERROR_CHECK Output Example

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/api-guides/error-handling.html

Example of the console output generated when an ESP_ERROR_CHECK macro fails.

```text
ESP_ERROR_CHECK failed: esp_err_t 0x107 (ESP_ERR_TIMEOUT) at 0x400d1fdf

file: "/Users/user/esp/example/main/main.c" line 20
func: app_main
expression: sdmmc_card_init(host, &card)

Backtrace: 0x40086e7c:0x3ffb4ff0 0x40087328:0x3ffb5010 0x400d1fdf:0x3ffb5030 0x400d0816:0x3ffb5050
```

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

### Install pre-commit hooks

Source: https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/contribute/install-pre-commit-hook.html

Initialize the hooks in the project directory, allowing commits even if the configuration file is missing.

```bash
pre-commit install --allow-missing-config -t pre-commit -t commit-msg
```
Tokens:
Raw