ESP-IDF Programming Guide

https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/
Admin
This documentation provides comprehensive guidance for using the Espressif IoT Development Framework...
Tokens:1,568,137
Snippets:13,494
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/esp32s3/api-guides/ble/get-started/ble-connection.html

Navigate to the NimBLE_Connection example directory within your ESP-IDF installation.

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

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

### Navigate to BLE GATT Server Example Directory

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

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

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

### Navigate to NimBLE_Beacon Example Directory

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

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

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

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

### Start Web Server

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

Starts the HTTP server instance with default configuration and registers URI handlers. Ensure the handle is non-NULL before starting.

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

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

### OpenOCD Version Output Example

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

Example output when verifying the OpenOCD installation. This shows the version number and licensing information.

```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/html/bugs.html

```

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

### Create, Enable, and Start GPTimer

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

Demonstrates the process of creating a GPTimer instance with specific configurations, enabling it, and then starting its operation. Ensure the timer is enabled before starting.

```c
gptimer_handle_t gptimer = NULL;
gptimer_config_t timer_config = {
    .clk_src = GPTIMER_CLK_SRC_DEFAULT, // Select the default clock source
    .direction = GPTIMER_COUNT_UP,      // Counting direction is up
    .resolution_hz = 1 * 1000 * 1000,   // Resolution is 1 MHz, i.e., 1 tick equals 1 microsecond
};
// Create a timer instance
ESP_ERROR_CHECK(gptimer_new_timer(&timer_config, &gptimer));
// Enable the timer
ESP_ERROR_CHECK(gptimer_enable(gptimer));
// Start the timer
ESP_ERROR_CHECK(gptimer_start(gptimer));

```

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

### FATFS: Getting Started with Internal Flash

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/storage/index.html

Demonstrates basic common file API (stdio.h) usage over internal flash using FATFS.

```c
fatfs/getting_started
```

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

### Start Listening for DPP Configurations

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

Starts listening on the channels specified during bootstrap generation. The device will listen for a pre-defined time. Ensure WiFi is started before calling this.

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

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

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

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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
```

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

### Scan Specific SBOM File Example

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

Example of scanning the SPDX SBOM file generated for the `hello_world` example project. This command targets a specific SBOM file within the build directory.

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

```

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

### Install Basic Dependencies for CI

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

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

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

```

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

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

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

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

```batch
install.bat

```

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

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

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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 DNF.

```bash
sudo dnf install eim
```

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

### Install EIM GUI with Homebrew

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

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

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

```

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

### Flash Deep-sleep Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/current-consumption-measurement-modules.html

Flash the deep_sleep example to the ESP32-S3 module. Refer to the project setup guides for Linux/macOS or Windows for detailed instructions.

```bash
idf.py flash
```

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

### Copy Example Project

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

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

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

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

### esp_console_new_repl_uart

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

Establishes a console REPL environment over the UART driver. This function is intended for examples and simplifies setup by installing the UART driver, configuring stdin/stdout, initializing linenoise, and spawning a background REPL thread.

```APIDOC
## esp_console_new_repl_uart

### Description
Establish a console REPL environment over UART driver. 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.

### Parameters
#### Path Parameters
- **dev_config** (const esp_console_dev_uart_config_t *) - [in] UART device configuration.
- **repl_config** (const esp_console_repl_config_t *) - [in] REPL configuration.

#### Query Parameters
- **ret_repl** (esp_console_repl_t **) - [out] Return REPL handle after initialization succeed, return NULL otherwise.

### Returns
- **ESP_OK** on success
- **ESP_FAIL** Parameter error
```

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

### Create Project From Example

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

Create a new project from an example component available in the ESP Component Registry.

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

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

### Create project from example using ESP Component Registry

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

Use this command to create a new project from the 'unit-test-app' example available in the ESP Component Registry.

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

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

### Install Tools for Specific Chip Target

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

Installs tools only for the specified chip target, for example, ESP32. This allows for a more targeted installation.

```shell
install.sh esp32
```

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

### Example Build System Output

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

This output shows the detailed steps of the build process, including CMake execution and component compilation. It concludes with the generation of the final firmware binaries.

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

```

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

### Start ESP-IDF Ethernet Driver

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

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

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

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

### Example 1: SDKCONFIG_DEFAULTS with multiple files

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

Demonstrates the order of applying default configuration files when SDKCONFIG_DEFAULTS is set to multiple files, including target-specific variations.

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

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

### Launch GDB with Initialization Files

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

Use this command to launch GDB, load symbols, and connect to the target device using the generated initialization files. The -q option minimizes startup output.

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

```

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

### httpd_start

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

Starts the web server by creating an instance and allocating necessary 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
#### Input Parameters
* **config** (httpd_config_t *) - Configuration for new instance of the server

#### Output Parameters
* **handle** (httpd_handle_t *) - Handle to newly created instance of the server. NULL on error

### Returns
* ESP_OK : Instance created successfully
* 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

### Example Usage:
```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;
}
```
```

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

### Example Post-Attach Callback for I/O Driver

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

An example post-attach callback function that configures the driver interface 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;
}
```

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

### Start RFC2217 Server on Linux/macOS

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

Starts the RFC2217 server on Linux or macOS to access a serial port remotely. Requires esptool to be installed.

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

```

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

### Start QEMU with GDB Server and Open GDB Session

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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

```

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

### Install Python Packages for Core Functionality

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

Installs Python packages required for core ESP-IDF functionality. This command focuses on the Python environment setup.

```shell
idf_tools.py install-python-env --features=core
```

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

### Install Pre-built QEMU Binaries

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

Downloads and installs pre-built QEMU binaries for ESP32-S3 emulation using the IDF tools script.

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

```

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

### Initialize Wokwi Project Configuration

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

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

```bash
wokwi-cli init

```

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

### Start MCP Server using EIM

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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 prior activation of the ESP-IDF environment.

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

```

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

### protocomm_ble_start

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

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

```APIDOC
## protocomm_ble_start

### Description
Initializes and starts the BLE service for provisioning, including the setup of characteristics and services.

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

### Parameters
#### Parameters
- **pc** (protocomm_t *) - [in] Pointer to the Protocomm instance obtained from protocomm_new().
- **config** (const protocomm_ble_config_t *) - [in] Pointer to the configuration 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 configuration.
- **ESP_ERR_INVALID_ARG** : Null arguments provided.
```

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

### Picolibc vs Newlib File I/O Example

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

This example demonstrates file I/O operations that can be used to compare the performance and resource consumption of Picolibc and Newlib. It involves writing to a console device and printing formatted strings.

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


```

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

### Build Custom ESP-IDF Docker Image

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

Builds a custom Docker image for ESP-IDF, specifying a particular branch, shallow clone, and installation targets. This example uses v4.4.1 and installs tools for ESP32-C3 only.

```bash
docker build -t idf-custom:v4.4.1-esp32c3 \
    --build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \
    --build-arg IDF_CLONE_SHALLOW=1 \
    --build-arg IDF_INSTALL_TARGETS=esp32c3 \
    tools/docker

```

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

### Run QEMU with Monitor and Custom eFuse File

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

Starts QEMU with the monitor enabled, using a custom eFuse file (`my_efuse.bin`).

```bash
idf.py qemu --efuse-file my_efuse.bin monitor

```

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

### Mapping Entry with Flags: SURROUND

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/linker-script-generation.html

Example of using the SURROUND flag to generate start and end symbols for a placement.

```linker_script
SURROUND(<name>)

```

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

### Example 2: SDKCONFIG_DEFAULTS with a single file

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

Illustrates the application order of default configuration files when SDKCONFIG_DEFAULTS specifies only one file, and the system's attempt to load a target-specific variation.

```bash
SDKCONFIG_DEFAULTS="sdkconfig_devkit1"
```

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

### Install LCD Controller Driver (ST7789 Example)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd/i80_lcd.html

Installs the driver for a specific LCD controller (e.g., ST7789). This requires the I80 IO device handle and panel-specific configurations like bits per pixel and reset GPIO.

```APIDOC
## esp_lcd_new_panel_st7789

### Description
Installs the driver for the ST7789 LCD controller.

### Function Signature
```c
esp_err_t esp_lcd_new_panel_st7789(esp_lcd_panel_io_handle_t io_handle, const esp_lcd_panel_dev_config_t *panel_config, esp_lcd_panel_handle_t *ret_panel);
```

### Parameters
#### `io_handle`
- **esp_lcd_panel_io_handle_t** - Required - Handle of the LCD IO device.

#### `panel_config`
- **esp_lcd_panel_dev_config_t*** - Required - Configuration structure for the LCD panel.
  - `reset_gpio_num` (int) - GPIO number for the reset pin (-1 if not available).
  - `rgb_ele_order` (esp_lcd_rgb_element_order_t) - Color element order.
  - `bits_per_pixel` (uint8_t) - Bit width of the pixel color data.

#### `ret_panel`
- **esp_lcd_panel_handle_t*** - Output - Pointer to store the handle of the installed LCD panel driver.

### Return Value
- **esp_err_t** - ESP_OK on success, otherwise an error code.
```

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

### Build Documentation

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

Command to build the documentation after installing dependencies. Navigate to the 'docs' folder and execute this command.

```bash
build-docs build

```

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

### Get Minimum Free Heap Size

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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);

```

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

### View Application Output in Monitor

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

Example of the expected output seen in the IDF Monitor after your application starts running and prints messages.

```text
    ... 
    Hello world!
    Restarting in 10 seconds...
    This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB embedded flash
Minimum free heap size: 390684 bytes
    Restarting in 9 seconds...
    Restarting in 8 seconds...
    Restarting in 7 seconds...


```

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

### Start QEMU with GDB and IDF Monitor

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

Starts QEMU and IDF Monitor, waiting for a GDB connection. Use in the first terminal.

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

```

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

### Get Package Version

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

Retrieves the package version using a special function for frequently used fields. This is an example of a convenience function.

```c
int pkg_ver = esp_efuse_get_pkg_ver();
```

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

### Start GDB Session and Connect to QEMU

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

Starts an interactive GDB session and connects it to QEMU. Use in the second terminal when the first is running the monitor.

```bash
idf.py gdb

```

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

### Namespace Management Example

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/storage/nvs_flash.html

Example showing how key-value pairs are organized into namespaces. Demonstrates entries for defining namespaces and storing keys within specific namespaces.

```text
+-------------------------------------------+
| NS=0 Type=uint8_t Key="wifi" Value=1      |   Entry describing namespace "wifi"
+-------------------------------------------+
| NS=1 Type=uint32_t Key="channel" Value=6  |   Key "channel" in namespace "wifi"
+-------------------------------------------+
| NS=0 Type=uint8_t Key="pwm" Value=2       |   Entry describing namespace "pwm"
+-------------------------------------------+
| NS=2 Type=uint16_t Key="channel" Value=20 |   Key "channel" in namespace "pwm"
+-------------------------------------------+

```

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

### Get Python Interpreter Used for Build

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

This example demonstrates how to retrieve the Python interpreter path configured for the build process using `idf_build_get_property`.

```cmake
idf_build_get_property(python PYTHON)
message(STATUS "The Python interpreter is: ${python}")

```

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

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

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

Build the firmware, flash it to the development board, and monitor the serial output.

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

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

### Example: Resetting a One-Shot Timer for LCD Backlight Control

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

This example demonstrates how to use `xTimerReset` to manage an LCD backlight. The timer is set to turn off the backlight after 5 seconds of inactivity. It shows timer creation, starting, and resetting within an event handler.

```c
/* // When a key is pressed, an LCD back-light is switched on.  If 5 seconds pass
* // without a key being pressed, then the LCD back-light is switched off.
* // In this case, the timer is a one-shot timer.
*
* TimerHandle_t xBacklightTimer = NULL;
*
* // The callback function assigned to the one-shot timer.  In this case the
* // parameter is not used.
* void vBacklightTimerCallback( TimerHandle_t pxTimer )
* {
*     // The timer expired, therefore 5 seconds must have passed since a key
*     // was pressed.  Switch off the LCD back-light.
*     vSetBacklightState( BACKLIGHT_OFF );
* }
* 
* // The key press event handler.
* void vKeyPressEventHandler( char cKey )
* {
*     // Ensure the LCD back-light is on, then reset the timer that is
*     // responsible for turning the back-light off after 5 seconds of
*     // key inactivity.  Wait 10 ticks for the command to be successfully sent
*     // if it cannot be sent immediately.
*     vSetBacklightState( BACKLIGHT_ON );
*     if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
*     {
*         // The reset command was not executed successfully.  Take appropriate
*         // action here.
*     }
*
*     // Perform the rest of the key processing here.
* }
* 
* void main( void )
* {
* int32_t x;
*
*     // Create then start the one-shot timer that is responsible for turning
*     // the back-light off if no keys are pressed within a 5 second period.
*     xBacklightTimer = xTimerCreate( "BacklightTimer",           // Just a text name, not used by the kernel.
*                                     ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks.
*                                     pdFALSE,                    // The timer is a one-shot timer.
*                                     0,                          // The id is not used by the callback so can take any value.
*                                     vBacklightTimerCallback     // The callback function that switches the LCD back-light off.
*                                   );
*
*     if( xBacklightTimer == 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( xBacklightTimer, 0 ) != pdPASS )
*         {
*             // The timer could not be set into the Active state.
*         }
*     }
*
*     // ...
*     // Create tasks here.
*     // ...
*
*     // Starting the scheduler will start the timer running as it has already
*     // been set into the active state.
*     vTaskStartScheduler();
*
*     // Should not reach here.
*     for( ;; );
* }
* 
*/
```

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

### Install LCD Controller Driver (ST7789)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd/i80_lcd.html

Install the LCD controller driver, specifying the I80 IO device handle and panel-specific configurations like bits per pixel, reset GPIO, and RGB element order. This example uses the ST7789 driver.

```c
esp_lcd_panel_dev_config_t panel_config = {
    .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
    .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB,
    .bits_per_pixel = 16,
};
ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));

```

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

### FreeRTOS Time Slicing Example: Starting State

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

Illustrates the initial state of ready tasks before any scheduling occurs. Tasks are listed in priority order.

```text
Head [ AX , B0 , C1 , D0 ] Tail
```

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

### Example sdkconfig File

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

Illustrates the content of an sdkconfig file, showing both new configuration options and deprecated ones for backward compatibility.

```ini
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

```

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

### Open Project in VSCode

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

After navigating to the example directory, you can open the project in VSCode using this command.

```bash
$ code .
```

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

### Start GDB GUI with idf.py

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

Launches the gdbgui debugger frontend, which opens an active debugger interface in a web browser. Requires installation via pipx.

```bash
idf.py gdbgui
```

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

### esp_console_new_repl_usb_serial_jtag

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

Establishes a console REPL environment over USB-SERIAL-JTAG. This function, mainly for examples, simplifies REPL setup by initializing linenoise and spawning a background REPL thread.

```APIDOC
## esp_console_new_repl_usb_serial_jtag

### Description
Establish a console REPL (Read-eval-print loop) environment over USB-SERIAL-JTAG. This is an all-in-one function to establish the environment needed for REPL, including initializing linenoise and spawning a new thread to run REPL in the background.

### Parameters
#### Path Parameters
- **dev_config** (const esp_console_dev_usb_serial_jtag_config_t *) - [in] USB-SERIAL-JTAG configuration.
- **repl_config** (const esp_console_repl_config_t *) - [in] REPL configuration.

#### Query Parameters
- **ret_repl** (esp_console_repl_t **) - [out] Return REPL handle after initialization succeed, return NULL otherwise.

### Returns
- **ESP_OK** on success
- **ESP_FAIL** Parameter error
```

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

### Install QEMU System Dependencies (Ubuntu/Debian)

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

Installs necessary system libraries on Ubuntu and Debian for QEMU to function correctly.

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

```

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

### Python API: Getting Partition Information

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

Demonstrates how to retrieve information about a partition, such as its size, using the ParttoolTarget object. This example retrieves the size of the default boot partition.

```python
# Print the size of default boot partition
  storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
  print(storage.size)

```

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

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

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/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 initialized. It includes registering an IP event handler 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());

```

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

### esp_console_new_repl_usb_cdc

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

Establishes a console REPL environment over USB CDC. This function is primarily for examples and simplifies REPL setup by initializing linenoise and spawning a background REPL thread.

```APIDOC
## esp_console_new_repl_usb_cdc

### Description
Establish a console REPL environment over USB CDC. This is a all-in-one function to establish the environment needed for REPL, including initializing linenoise and spawning a new thread to run REPL in the background.

### Parameters
#### Path Parameters
- **dev_config** (const esp_console_dev_usb_cdc_config_t *) - [in] USB CDC configuration.
- **repl_config** (const esp_console_repl_config_t *) - [in] REPL configuration.

#### Query Parameters
- **ret_repl** (esp_console_repl_t **) - [out] Return REPL handle after initialization succeed, return NULL otherwise.

### Returns
- **ESP_OK** on success
- **ESP_FAIL** Parameter error
```

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

### Start Protocomm over HTTP with Security 1

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

Launches a Protocomm instance using HTTP transport with Security 1. Requires a 'pop_string' for security parameters. Handles endpoint and security setup.

```c
/* The example function for launching a protocomm instance over HTTP. */
protocomm_t *start_pc(const char *pop_string)
{
    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 security1 params object from pop_string. It 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. */
    const static protocomm_security1_params_t sec1_params = {
        .data = (const uint8_t *) strdup(pop_string),
        .len = strlen(pop_string)
    };

    /* 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_security1, &sec1_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. */
    static uint32_t priv_data = 1234;

    /* Add a new endpoint for the protocomm instance identified by a unique name, and register a handler function along with the private data to be passed at the time of handler execution. Multiple endpoints can be added as long as they are identified by unique names. */
    protocomm_add_endpoint(pc, "echo_req_endpoint",
                           echo_req_handler, (void *) &priv_data);
    return pc;
}
```

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

### Command-line: Reading a Partition to File

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

This command-line example demonstrates reading a partition identified by its type and subtype, and saving its contents to a file. The output file name is specified using the --output argument.

```bash
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"

```

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

### Example Text Configuration Report

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/kconfig/project-configuration-guide.html

This is an example of the console output for a project's configuration report, highlighting potential issues like multiple symbol definitions.

```text
Configuration report
--------------------

Parser Version: 1
Verbosity: default
Status: Finished with notifications

Multiple Symbol/Choice Definitions
----------------------------------

SYMBOL_NAME
    path/to/first/Kconfig_with_definition:line_number
    path/to/second/Kconfig_with_definition:line_number

ANOTHER_SYMBOL_NAME
    another/path/to/first/Kconfig_with_definition:line_number
    another/path/to/second/Kconfig_with_definition:line_number
```

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

### Configure and Install RMT TX Channels for Synchronized Transmission

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

This snippet demonstrates how to configure, install, and enable two RMT TX channels. It then sets up a sync manager to coordinate transmissions across these channels, ensuring they start simultaneously. This is useful for applications requiring precise timing, such as controlling multiple LEDs or IR emitters in unison.

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

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

### uart_detect_bitrate_start

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

Starts the bitrate detection process for an incoming data signal, commonly known as auto baud rate detection. This function can be used independently and does not require the UART driver to be installed beforehand.

```APIDOC
## uart_detect_bitrate_start

### Description
Start to do a bitrate detection for an incoming data signal (auto baud rate detection). This function can act as a standalone API. No need to install UART driver before calling this function. It is recommended that the incoming data line contains alternating bit sequence, data bytes such as `0x55` or `0xAA`. Characters ‘NULL’, `0xCC` are not good for the measurement.

### Parameters
* **uart_num** (uart_port_t) - The ID of the UART port to be used to do the measurement. Note that only HP UART ports have the capability.
* **config** (const uart_bitrate_detect_config_t *) - Pointer to the configuration structure for the UART port. If the port has already been acquired, this parameter is ignored.

### Returns
* ESP_OK on success
* ESP_ERR_INVALID_ARG Parameter error
* ESP_FAIL No free uart port or source_clk invalid
```

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

### Start Protocomm Instance over HTTP

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

This function initializes and starts a protocomm instance over HTTP. It configures the HTTP server, sets up Security 2 parameters, and registers the security endpoint.

```c
/* 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;
}
```

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

### Example Serial Log Output

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/establish-serial-connection.html

This log output indicates a successful serial connection. If you do not see similar output, reset the board. This output is essential for proceeding with ESP-IDF installation and application uploading.

```log
ets Jun  8 2016 00:22:57 

rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun  8 2016 00:22:57 

rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0008,len:8
load:0x3fff0010,len:3464
load:0x40078000,len:7828
load:0x40080000,len:252
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...


```

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

### Install QEMU System Dependencies (CentOS)

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

Installs required system libraries on CentOS for QEMU emulation.

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

```

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

### Get Ethernet MAC and PHY Address

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

This snippet demonstrates how to retrieve the MAC address and PHY address of the Ethernet interface using the esp_eth_ioctl function. These commands are used 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]);

/* 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);

```

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

### Implement Property Get Handler for Timestamp

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

Handles requests to retrieve property values. This example specifically retrieves a timestamp, using the `ctx` field to obtain the time-getting function and a static variable to store the value.

```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;
}
```
Tokens:
Raw