Espressif IoT Development Framework

https://docs.platformio.org/en/latest/frameworks/espidf.html
Admin
Espressif IoT Development Framework (ESP-IDF) is the official development framework for the ESP32...
Tokens:5,180
Snippets:80
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Menuconfig Dependencies

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Required system packages for menuconfig on Linux-based systems.

```bash
libncurses5-dev flex bison
```

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

### Configure Project Settings

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Required settings for sdkconfig.defaults to enable Secure Boot v2 on ESP32.

```text
# ESP32-specific settings
CONFIG_ESP32_REV_MIN_3=y

# Secure Boot settings
CONFIG_SECURE_BOOT=y
CONFIG_SECURE_BOOT_V2_ENABLED=y
```

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

### Build and Upload Commands

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Commands for building, signing, and uploading binaries to the target device.

```bash
pio run
```

```bash
pio run -t sign
```

```bash
pio run -t sign -t upload
```

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

### Build and Upload Encrypted Binaries

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Commands to build, encrypt, and upload binaries to the target device.

```bash
pio run
```

```bash
pio run -t encrypt
```

```bash
pio run -t encrypt -t upload
```

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

### Configure ESP-IDF Project Source Directory

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Use the src_dir option in platformio.ini to point to a custom source folder like 'main'.

```ini
[platformio]
src_dir = main

[env:esp32dev]
platform = platformio/espressif32
framework = espidf
board = esp32dev
```

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

### Launch Menuconfig

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Execute the menuconfig target to modify the sdkconfig file.

```bash
pio run -t menuconfig
```

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

### Configure Extra Upload Flags

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

PlatformIO environment configuration and the corresponding extra script to force upload of pre-encrypted binaries.

```ini
[env:esp32dev]
platform = platformio/espressif32
framework = espidf
...
extra_scripts = force_upload.py
...
```

```python
Import ("env")

env.Append(UPLOADCMD=" ".join(["$UPLOADCMD", "--force"]))
```

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

### Configure core_dir in platformio.ini

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Workaround for project path limitations by setting a custom core directory to avoid whitespace issues.

```ini
[platformio]
core_dir = C:/.platformio

[env:esp32dev]
platform = platformio/espressif32
framework = espidf
board = esp32dev
```

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

### Configure ESP-IDF Framework

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Set the framework to espidf in the platformio.ini file.

```ini
framework = `espidf`
```

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

### Generate Secure Boot Signing Private Key

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Creates an RSA-3072 private key file for signing application binaries.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espsecure.py generate_signing_key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
```

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

### Enable Secure Boot

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Sets the ABS_DONE_1 eFuse to permanently enable Secure Boot.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT --chip esp32 burn_efuse ABS_DONE_1
```

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

### Configure Flash Encryption in platformio.ini

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Setting the encryption key path within the PlatformIO environment configuration.

```ini
[env:esp32dev]
platform = platformio/espressif32
framework = espidf
...
board_build.encryption_key = my_flash_encryption_key.bin
```

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

### ULP Project Directory Structure

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Standard project layout requiring a dedicated 'ulp' directory for assembly source files.

```text
project_dir
├── include
├── src
│    ├── CMakeLists.txt
│    └── main.c
├── ulp
│    └── ulp_code.S
├── CMakeLists.txt
└── platformio.ini
```

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

### Configure Flash Encryption in sdkconfig

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Required settings for sdkconfig.defaults to enable Flash Encryption in release mode.

```ini
# Enable Flash Encryption on boot
CONFIG_SECURE_FLASH_ENC_ENABLED=y

# Select the RELEASE mode
CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y

# Select UART ROM download mode (permanently disabled (recommended))
CONFIG_SECURE_DISABLE_ROM_DL_MODE=y

# Select the appropriate bootloader log verbosity (for example info)
CONFIG_BOOTLOADER_LOG_LEVEL_INFO=y
```

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

### Root CMakeLists.txt Boilerplate

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Required boilerplate for the root CMakeLists.txt file to ensure correct ESP-IDF build system integration.

```cmake
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16.0)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(project-name)
```

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

### Specify Extra Components in CMakeLists.txt

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Appends additional directories to the build system search path for components.

```cmake
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
list(APPEND EXTRA_COMPONENT_DIRS esp-aws-iot)
project(subscribe_publish)
```

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

### Flash Encrypted Binaries

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Uploads the encrypted NVS key and partition binaries to the target device.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- esptool.py --chip esp32 -p $PORT --before=default_reset --after=no_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 4MB 0x120000 keys/nvs_encr_key-encrypted.bin 0x121000 nvs_encr_partition-encrypted.bin --force
```

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

### ESP-IDF Project Directory Structure

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

The standard directory layout for an ESP-IDF project in PlatformIO.

```text
project_dir
├── include
├── src
│    ├── CMakeLists.txt
│    └── main.c
├── CMakeLists.txt
└── platformio.ini
```

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

### Configure ULP in CMakeLists.txt

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Required CMake configuration to register ULP assembly sources and embed the binary into the ESP-IDF project.

```cmake
idf_component_register(SRCS "ulp_adc_example_main.c")
#
# ULP support additions to component CMakeLists.txt.
#
# 1. The ULP app name must be "ulp_main"
set(ulp_app_name ulp_main)
#
# 2. Specify all assembly source files.
#    Paths are relative because ULP files are placed into a special directory "ulp"
#    in the root of the project
set(ulp_s_sources "../ulp/adc.S")
#
# 3. List all the component source files which include automatically
#    generated ULP export file, ${ulp_app_name}.h:
set(ulp_exp_dep_srcs "ulp_adc_example_main.c")
#
# 4. Call function to build ULP binary and embed in project using the argument
#    values above.
ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs})
```

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

### Configure NVS Encryption in sdkconfig

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Enables NVS encryption and key protection in the project's sdkconfig.defaults file.

```text
CONFIG_NVS_ENCRYPTION=y
CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
```

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

### Register Component in CMakeLists.txt

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Registers source files for a component within the build system.

```cmake
idf_component_register(SRCS "foo.c" "bar.c")
```

```cmake
idf_component_register(SRCS "main.c" REQUIRES idf::mbedtls)
```

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

### Generate NVS Encryption Key

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Creates an NVS encryption key file using the ESP-IDF framework tools.

```bash
pio pkg exec --package "platformio/framework-espidf" -- components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py generate-key --keyfile nvs_encr_key.bin
```

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

### Generate Flash Encryption Key

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Command to generate a random binary key for flash encryption using the esptoolpy package.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
```

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

### Encrypt NVS Key Partition

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Encrypts the NVS key partition using the Flash Encryption key before flashing.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espsecure.py encrypt_flash_data --keyfile my_flash_encryption_key.bin --address 0x120000
--output keys/nvs_encr_key-encrypted.bin keys/nvs_encr_key.bin
```

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

### Generate Encrypted NVS Partition

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Generates an encrypted binary partition from a CSV file using the previously generated key.

```bash
pio pkg exec --package "platformio/framework-espidf" -- components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py encrypt nvs_data.csv nvs_encr_partition.bin 0x121000 --inputkey keys/nvs_encr_key.bin
```

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

### Write Protect Security eFuses

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Command to write protect the DIS_CACHE eFuse, which also affects other security configurations.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT write_protect_efuse DIS_CACHE
```

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

### Generate Public Key Digest

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Extracts the public key digest from the generated private key file.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output digest.bin
```

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

### Burn Flash Encryption eFuses

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Commands to configure Flash Encryption and related security eFuses using the esptoolpy package.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT --chip esp32 burn_efuse FLASH_CRYPT_CNT 127
```

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT --chip esp32 burn_efuse FLASH_CRYPT_CONFIG 0xF
```

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py burn_efuse --port $PORT EFUSE_NAME 0x1
```

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

### Burn Flash Encryption Key to eFuse

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Command to permanently burn the generated key into the device's eFuse memory.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT burn_key flash_encryption my_flash_encryption_key.bin
```

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

### Burn Key Digest in eFuse

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Writes the public key digest to the device's eFuse memory.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT --chip esp32 burn_key secure_boot_v2 digest.bin
```

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

### Write Protect eFuse

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Prevents accidental modification of eFuse read protection settings.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py -p $PORT write_protect_efuse RD_DIS
```

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

### Disable UART ROM Download Mode

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Final security step to disable UART ROM download mode, preventing further eFuse modifications.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py --port $PORT burn_efuse UART_DOWNLOAD_DIS
```

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

### Disable JTAG

Source: https://docs.platformio.org/en/latest/frameworks/espidf.html

Disables the JTAG interface for security purposes.

```bash
pio pkg exec --package "platformio/tool-esptoolpy" -- espefuse.py burn_efuse --port $PORT JTAG_DISABLE 0x1
```
Tokens:
Raw