Configuration Options

Introduction

ESP-IDF uses Kconfig system to provide a compile-time configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc.

Applications developers can use make menuconfig build target to edit components’ configuration. This configuration is saved inside sdkconfig file in the project root directory. Based on sdkconfig, application build targets will generate sdkconfig.h file in the build directory, and will make sdkconfig options available to component makefiles.

Using sdkconfig.defaults

When updating ESP-IDF version, it is not uncommon to find that new Kconfig options are introduced. When this happens, application build targets will offer an interactive prompt to select values for the new options. New values are then written into sdkconfig file. To supress interactive prompts, applications can either define BATCH_BUILD environment variable, which will cause all prompts to be suppressed. This is the same effect as that of V or VERBOSE variables. Alternatively, defconfig build target can be used to update configuration for all new variables to the default values.

In some cases, such as when sdkconfig file is under revision control, the fact that sdkconfig file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of sdkconfig.defaults file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the sdkconfig file. Once sdkconfig.defaults is created, sdkconfig can be deleted and added to the ignore list of the revision control system (e.g. .gitignore file for git). Project build targets will automatically create sdkconfig file, populated with the settings from sdkconfig.defaults file, and the rest of the settings will be set to their default values. Note that when make defconfig is used, settings in sdkconfig will be overriden by the ones in sdkconfig.defaults. For more information, see Custom sdkconfig defaults.

Configuration Options Reference

Subsequent sections contain the list of available ESP-IDF options, automatically generated from Kconfig files. Note that depending on the options selected, some options listed here may not be visible by default in the interface of menuconfig.

By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with CONFIG_. So if an option ENABLE_FOO is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have CONFIG_ENABLE_FOO defined. In this reference, option names are also prefixed with CONFIG_, same as in the source code.

SDK tool configuration

CONFIG_TOOLPREFIX

Compiler toolchain path/prefix

The prefix/path that is used to call the toolchain. The default setting assumes a crosstool-ng gcc setup that is in your PATH.

Found in
SDK tool configuration
CONFIG_PYTHON

Python 2 interpreter

The executable name/path that is used to run python. On some systems Python 2.x may need to be invoked as python2.

(Note: This option is used with the GNU Make build system only, not idf.py or CMake-based builds.)

Found in
SDK tool configuration
CONFIG_MAKE_WARN_UNDEFINED_VARIABLES

‘make’ warns on undefined variables

Adds –warn-undefined-variables to MAKEFLAGS. This causes make to print a warning any time an undefined variable is referenced.

This option helps find places where a variable reference is misspelled or otherwise missing, but it can be unwanted if you have Makefiles which depend on undefined variables expanding to an empty string.

Found in
SDK tool configuration

Partition Table

CONFIG_PARTITION_TABLE_TYPE

Partition Table

The partition table to flash to the ESP32. The partition table determines where apps, data and other resources are expected to be found.

The predefined partition table CSV descriptions can be found in the components/partition_table directory. Otherwise it’s possible to create a new custom partition CSV for your application.

Found in
Partition Table
Available options:
  • Single factory app, no OTA (CONFIG_PARTITION_TABLE_SINGLE_APP)
  • Factory app, two OTA definitions (CONFIG_PARTITION_TABLE_TWO_OTA)
  • Custom partition table CSV (CONFIG_PARTITION_TABLE_CUSTOM)
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME

Custom partition CSV file

Name of the custom partition CSV filename. This path is evaluated relative to the project root directory.

Found in
Partition Table
CONFIG_PARTITION_TABLE_OFFSET

Offset of partition table

The address of partition table (by default 0x8000). Allows you to move the partition table, it gives more space for the bootloader. Note that the bootloader and app will both need to be compiled with the same PARTITION_TABLE_OFFSET value.

Found in
Partition Table
CONFIG_PARTITION_TABLE_MD5

Generate an MD5 checksum for the partition table

Generate an MD5 checksum for the partition table for protecting the integrity of the table. The generation should be turned off for legacy bootloaders which cannot recognize the MD5 checksum in the partition table.

Found in
Partition Table

Bootloader config

CONFIG_LOG_BOOTLOADER_LEVEL

Bootloader log verbosity

Specify how much output to see in bootloader logs.

Found in
Bootloader config
Available options:
  • No output (CONFIG_LOG_BOOTLOADER_LEVEL_NONE)
  • Error (CONFIG_LOG_BOOTLOADER_LEVEL_ERROR)
  • Warning (CONFIG_LOG_BOOTLOADER_LEVEL_WARN)
  • Info (CONFIG_LOG_BOOTLOADER_LEVEL_INFO)
  • Debug (CONFIG_LOG_BOOTLOADER_LEVEL_DEBUG)
  • Verbose (CONFIG_LOG_BOOTLOADER_LEVEL_VERBOSE)
CONFIG_BOOTLOADER_SPI_WP_PIN

SPI Flash WP Pin when customising pins via efuse (read help)

This value is ignored unless flash mode is set to QIO or QOUT *and* the SPI flash pins have been overriden by setting the efuses SPI_PAD_CONFIG_xxx.

When this is the case, the Efuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka ESP32 pin “SD_DATA_3” or SPI flash pin “IO2”) is not specified in Efuse. That pin number is compiled into the bootloader instead.

The default value (GPIO 7) is correct for WP pin on ESP32-D2WD integrated flash.

Found in
Bootloader config
CONFIG_BOOTLOADER_VDDSDIO_BOOST

VDDSDIO LDO voltage

If this option is enabled, and VDDSDIO LDO is set to 1.8V (using EFUSE or MTDI bootstrapping pin), bootloader will change LDO settings to output 1.9V instead. This helps prevent flash chip from browning out during flash programming operations.

This option has no effect if VDDSDIO is set to 3.3V, or if the internal VDDSDIO regulator is disabled via efuse.

Found in
Bootloader config
Available options:
  • 1.8V (CONFIG_BOOTLOADER_VDDSDIO_BOOST_1_8V)
  • 1.9V (CONFIG_BOOTLOADER_VDDSDIO_BOOST_1_9V)
CONFIG_BOOTLOADER_FACTORY_RESET

GPIO triggers factory reset

Allows to reset the device to factory settings: - clear one or more data partitions; - boot from “factory” partition. The factory reset will occur if there is a GPIO input pulled low while device starts up. See settings below.

Found in
Bootloader config
CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET

Number of the GPIO input for factory reset

The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a factory reset, this GPIO must be pulled low on reset. Note that GPIO34-39 do not have an internal pullup and an external one must be provided.

Found in
Bootloader config
CONFIG_BOOTLOADER_OTA_DATA_ERASE

Clear OTA data on factory reset (select factory partition)

The device will boot from “factory” partition (or OTA slot 0 if no factory partition is present) after a factory reset.

Found in
Bootloader config
CONFIG_BOOTLOADER_DATA_FACTORY_RESET

Comma-separated names of partitions to clear on factory reset

Allows customers to select which data partitions will be erased while factory reset.

Specify the names of partitions as a comma-delimited with optional spaces for readability. (Like this: “nvs, phy_init, …”) Make sure that the name specified in the partition table and here are the same. Partitions of type “app” cannot be specified here.

Found in
Bootloader config
CONFIG_BOOTLOADER_APP_TEST

GPIO triggers boot from test app partition

Allows to run the test app from “TEST” partition. A boot from “test” partition will occur if there is a GPIO input pulled low while device starts up. See settings below.

Found in
Bootloader config
CONFIG_BOOTLOADER_NUM_PIN_APP_TEST

Number of the GPIO input to boot TEST partition

The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset. After the GPIO input is deactivated and the device reboots, the old application will boot. (factory or OTA[x]). Note that GPIO34-39 do not have an internal pullup and an external one must be provided.

Found in
Bootloader config
CONFIG_BOOTLOADER_HOLD_TIME_GPIO

Hold time of GPIO for reset/test mode (seconds)

The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.

Found in
Bootloader config

Security features

CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT

Require signed app images

Require apps to be signed to verify their integrity.

This option uses the same app signature scheme as hardware secure boot, but unlike hardware secure boot it does not prevent the bootloader from being physically updated. This means that the device can be secured against remote network access, but not physical access. Compared to using hardware Secure Boot this option is much simpler to implement.

Found in
Security features
CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT

Bootloader verifies app signatures

If this option is set, the bootloader will be compiled with code to verify that an app is signed before booting it.

If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option doesn’t add significant security by itself so most users will want to leave it disabled.

Found in
Security features
CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT

Verify app signature on update

If this option is set, any OTA updated apps will have the signature verified before being considered valid.

When enabled, the signature is automatically checked whenever the esp_ota_ops.h APIs are used for OTA updates, or esp_image_format.h APIs are used to verify apps.

If hardware secure boot is enabled, this option is always enabled and cannot be disabled. If hardware secure boot is not enabled, this option still adds significant security against network-based attackers by preventing spoofing of OTA updates.

Found in
Security features
CONFIG_SECURE_BOOT_ENABLED

Enable hardware secure boot in bootloader (READ DOCS FIRST)

Build a bootloader which enables secure boot on first boot.

Once enabled, secure boot will not boot a modified bootloader. The bootloader will only load a partition table or boot an app if the data has a verified digital signature. There are implications for reflashing updated apps once secure boot is enabled.

When enabling secure boot, JTAG and ROM BASIC Interpreter are permanently disabled by default.

Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.

Found in
Security features
CONFIG_SECURE_BOOTLOADER_MODE

Secure bootloader mode

Found in
Security features
Available options:

  • One-time flash (CONFIG_SECURE_BOOTLOADER_ONE_TIME_FLASH)

    On first boot, the bootloader will generate a key which is not readable externally or by software. A digest is generated from the bootloader image itself. This digest will be verified on each subsequent boot.

    Enabling this option means that the bootloader cannot be changed after the first time it is booted.

  • Reflashable (CONFIG_SECURE_BOOTLOADER_REFLASHABLE)

    Generate a reusable secure bootloader key, derived (via SHA-256) from the secure boot signing key.

    This allows the secure bootloader to be re-flashed by anyone with access to the secure boot signing key.

    This option is less secure than one-time flash, because a leak of the digest key from one device allows reflashing of any device that uses it.

CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES

Sign binaries during build

Once secure boot or signed app requirement is enabled, app images are required to be signed.

If enabled (default), these binary files are signed as part of the build process. The file named in “Secure boot private signing key” will be used to sign the image.

If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py (for example, on a remote signing server.)

Found in
Security features
CONFIG_SECURE_BOOT_SIGNING_KEY

Secure boot private signing key

Path to the key file used to sign app images.

Key file is an ECDSA private key (NIST256p curve) in PEM format.

Path is evaluated relative to the project directory.

You can generate a new signing key by running the following command: espsecure.py generate_signing_key secure_boot_signing_key.pem

See docs/security/secure-boot.rst for details.

Found in
Security features
CONFIG_SECURE_BOOT_VERIFICATION_KEY

Secure boot public signature verification key

Path to a public key file used to verify signed images. This key is compiled into the bootloader and/or app, to verify app images.

Key file is in raw binary format, and can be extracted from a PEM formatted private key using the espsecure.py extract_public_key command.

Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.

Found in
Security features
CONFIG_SECURE_BOOTLOADER_KEY_ENCODING

Hardware Key Encoding

In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256) and can be written to efuse with espefuse.py.

Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the efuse key is truncated to 192 bits.

This configuration item doesn’t change any firmware code, it only changes the size of key binary which is generated at build time.

Found in
Security features
Available options:
  • No encoding (256 bit key) (CONFIG_SECURE_BOOTLOADER_KEY_ENCODING_256BIT)
  • 3/4 encoding (192 bit key) (CONFIG_SECURE_BOOTLOADER_KEY_ENCODING_192BIT)
CONFIG_SECURE_BOOT_INSECURE

Allow potentially insecure options

You can disable some of the default protections offered by secure boot, in order to enable testing or a custom combination of security features.

Only enable these options if you are very sure.

Refer to https://docs.espressif.com/projects/esp-idf/en/latest/security/secure-boot.html before enabling.

Found in
Security features
CONFIG_FLASH_ENCRYPTION_ENABLED

Enable flash encryption on boot (READ DOCS FIRST)

If this option is set, flash contents will be encrypted by the bootloader on first boot.

Note: After first boot, the system will be permanently encrypted. Re-flashing an encrypted system is complicated and not always possible.

Read https://docs.espressif.com/projects/esp-idf/en/latest/security/flash-encryption.html before enabling.

Found in
Security features
CONFIG_FLASH_ENCRYPTION_INSECURE

Allow potentially insecure options

You can disable some of the default protections offered by flash encryption, in order to enable testing or a custom combination of security features.

Only enable these options if you are very sure.

Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.

Found in
Security features

Potentially insecure options

CONFIG_SECURE_BOOT_ALLOW_ROM_BASIC

Leave ROM BASIC Interpreter available on reset

By default, the BASIC ROM Console starts on reset if no valid bootloader is read from the flash.

When either flash encryption or secure boot are enabled, the default is to disable this BASIC fallback mode permanently via efuse.

If this option is set, this efuse is not burned and the BASIC ROM Console may remain accessible. Only set this option in testing environments.

Found in
Security features > Potentially insecure options
CONFIG_SECURE_BOOT_ALLOW_JTAG

Allow JTAG Debugging

If not set (default), the bootloader will permanently disable JTAG (across entire chip) on first boot when either secure boot or flash encryption is enabled.

Setting this option leaves JTAG on for debugging, which negates all protections of flash encryption and some of the protections of secure boot.

Only set this option in testing environments.

Found in
Security features > Potentially insecure options
CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION

Allow app partition length not 64KB aligned

If not set (default), app partition size must be a multiple of 64KB. App images are padded to 64KB length, and the bootloader checks any trailing bytes after the signature (before the next 64KB boundary) have not been written. This is because flash cache maps entire 64KB pages into the address space. This prevents an attacker from appending unverified data after the app image in the flash, causing it to be mapped into the address space.

Setting this option allows the app partition length to be unaligned, and disables padding of the app image to this length. It is generally not recommended to set this option, unless you have a legacy partitioning scheme which doesn’t support 64KB aligned partition lengths.

Found in
Security features > Potentially insecure options
CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT

Leave UART bootloader encryption enabled

If not set (default), the bootloader will permanently disable UART bootloader encryption access on first boot. If set, the UART bootloader will still be able to access hardware encryption.

It is recommended to only set this option in testing environments.

Found in
Security features > Potentially insecure options
CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT

Leave UART bootloader decryption enabled

If not set (default), the bootloader will permanently disable UART bootloader decryption access on first boot. If set, the UART bootloader will still be able to access hardware decryption.

Only set this option in testing environments. Setting this option allows complete bypass of flash encryption.

Found in
Security features > Potentially insecure options
CONFIG_FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_CACHE

Leave UART bootloader flash cache enabled

If not set (default), the bootloader will permanently disable UART bootloader flash cache access on first boot. If set, the UART bootloader will still be able to access the flash cache.

Only set this option in testing environments.

Found in
Security features > Potentially insecure options
CONFIG_SECURE_BOOT_TEST_MODE

Secure boot test mode: don’t permanently set any efuses

If this option is set, all permanent secure boot changes (via Efuse) are disabled.

Log output will state changes which would be applied, but they will not be.

This option is for testing purposes only - it completely disables secure boot protection.

Found in
Security features > Potentially insecure options
CONFIG_FLASH_ENCRYPTION_DISABLE_PLAINTEXT

Disable serial reflashing of plaintext firmware

If this option is enabled, flash encryption is permanently enabled after first boot by write-protecting the FLASH_CRYPT_CNT efuse. This is the recommended configuration for a secure production system.

If this option is disabled, FLASH_CRYPT_CNT is left writeable and up to 4 plaintext re-flashes are allowed. An attacker with physical access will be able to read out encrypted flash contents until all plaintext re-flashes have been used up.

If this option is disabled and hardware Secure Boot is enabled, Secure Boot must be configured in Reflashable mode so that a new Secure Boot digest can be flashed at the same time as plaintext firmware. This combination is not secure and should not be used for a production system.

Found in
Security features

Serial flasher config

CONFIG_ESPTOOLPY_PORT

Default serial port

The serial port that’s connected to the ESP chip. This can be overridden by setting the ESPPORT environment variable.

This value is ignored when using the CMake-based build system or idf.py.

Found in
Serial flasher config
CONFIG_ESPTOOLPY_BAUD

Default baud rate

Default baud rate to use while communicating with the ESP chip. Can be overridden by setting the ESPBAUD variable.

This value is ignored when using the CMake-based build system or idf.py.

Found in
Serial flasher config
Available options:
  • 115200 baud (CONFIG_ESPTOOLPY_BAUD_115200B)
  • 230400 baud (CONFIG_ESPTOOLPY_BAUD_230400B)
  • 921600 baud (CONFIG_ESPTOOLPY_BAUD_921600B)
  • 2Mbaud (CONFIG_ESPTOOLPY_BAUD_2MB)
  • Other baud rate (CONFIG_ESPTOOLPY_BAUD_OTHER)
CONFIG_ESPTOOLPY_BAUD_OTHER_VAL

Other baud rate value

Found in
Serial flasher config
CONFIG_ESPTOOLPY_COMPRESSED

Use compressed upload

The flasher tool can send data compressed using zlib, letting the ROM on the ESP chip decompress it on the fly before flashing it. For most payloads, this should result in a speed increase.

Found in
Serial flasher config
CONFIG_FLASHMODE

Flash SPI mode

Mode the flash chip is flashed in, as well as the default mode for the binary to run in.

Found in
Serial flasher config
Available options:
  • QIO (CONFIG_FLASHMODE_QIO)
  • QOUT (CONFIG_FLASHMODE_QOUT)
  • DIO (CONFIG_FLASHMODE_DIO)
  • DOUT (CONFIG_FLASHMODE_DOUT)
CONFIG_ESPTOOLPY_FLASHFREQ

Flash SPI speed

The SPI flash frequency to be used.

Found in
Serial flasher config
Available options:
  • 80 MHz (CONFIG_ESPTOOLPY_FLASHFREQ_80M)
  • 40 MHz (CONFIG_ESPTOOLPY_FLASHFREQ_40M)
  • 26 MHz (CONFIG_ESPTOOLPY_FLASHFREQ_26M)
  • 20 MHz (CONFIG_ESPTOOLPY_FLASHFREQ_20M)
CONFIG_ESPTOOLPY_FLASHSIZE

Flash size

SPI flash size, in megabytes

Found in
Serial flasher config
Available options:
  • 1 MB (CONFIG_ESPTOOLPY_FLASHSIZE_1MB)
  • 2 MB (CONFIG_ESPTOOLPY_FLASHSIZE_2MB)
  • 4 MB (CONFIG_ESPTOOLPY_FLASHSIZE_4MB)
  • 8 MB (CONFIG_ESPTOOLPY_FLASHSIZE_8MB)
  • 16 MB (CONFIG_ESPTOOLPY_FLASHSIZE_16MB)
CONFIG_ESPTOOLPY_FLASHSIZE_DETECT

Detect flash size when flashing bootloader

If this option is set, ‘make flash’ targets will automatically detect the flash size and update the bootloader image when flashing.

Found in
Serial flasher config
CONFIG_ESPTOOLPY_BEFORE

Before flashing

Configure whether esptool.py should reset the ESP32 before flashing.

Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32. Most USB development boards do this internally.

Found in
Serial flasher config
Available options:
  • Reset to bootloader (CONFIG_ESPTOOLPY_BEFORE_RESET)
  • No reset (CONFIG_ESPTOOLPY_BEFORE_NORESET)
CONFIG_ESPTOOLPY_AFTER

After flashing

Configure whether esptool.py should reset the ESP32 after flashing.

Automatic resetting depends on the RTS & DTR signals being wired from the serial port to the ESP32. Most USB development boards do this internally.

Found in
Serial flasher config
Available options:
  • Reset after flashing (CONFIG_ESPTOOLPY_AFTER_RESET)
  • Stay in bootloader (CONFIG_ESPTOOLPY_AFTER_NORESET)
CONFIG_MONITOR_BAUD

‘make monitor’ baud rate

Baud rate to use when running ‘make monitor’ to view serial output from a running chip.

Can override by setting the MONITORBAUD environment variable.

Found in
Serial flasher config
Available options:
  • 9600 bps (CONFIG_MONITOR_BAUD_9600B)
  • 57600 bps (CONFIG_MONITOR_BAUD_57600B)
  • 115200 bps (CONFIG_MONITOR_BAUD_115200B)
  • 230400 bps (CONFIG_MONITOR_BAUD_230400B)
  • 921600 bps (CONFIG_MONITOR_BAUD_921600B)
  • 2 Mbps (CONFIG_MONITOR_BAUD_2MB)
  • Custom baud rate (CONFIG_MONITOR_BAUD_OTHER)
CONFIG_MONITOR_BAUD_OTHER_VAL

Custom baud rate value

Found in
Serial flasher config

Compiler options

CONFIG_OPTIMIZATION_COMPILER

Optimization Level

This option sets compiler optimization level (gcc -O argument).

  • for “Release” setting, -Os flag is added to CFLAGS.
  • for “Debug” setting, -Og flag is added to CFLAGS.

“Release” with -Os produces smaller & faster compiled code but it may be harder to correlated code addresses to source files when debugging.

To add custom optimization settings, set CFLAGS and/or CPPFLAGS in project makefile, before including $(IDF_PATH)/make/project.mk. Note that custom optimization levels may be unsupported.

Found in
Compiler options
Available options:
  • Debug (-Og) (CONFIG_OPTIMIZATION_LEVEL_DEBUG)
  • Release (-Os) (CONFIG_OPTIMIZATION_LEVEL_RELEASE)
CONFIG_OPTIMIZATION_ASSERTION_LEVEL

Assertion level

Assertions can be:

  • Enabled. Failure will print verbose assertion details. This is the default.
  • Set to “silent” to save code size (failed assertions will abort() but user needs to use the aborting address to find the line number with the failed assertion.)
  • Disabled entirely (not recommended for most configurations.) -DNDEBUG is added to CPPFLAGS in this case.
Found in
Compiler options
Available options:

  • Enabled (CONFIG_OPTIMIZATION_ASSERTIONS_ENABLED)

    Enable assertions. Assertion content and line number will be printed on failure.

  • Silent (saves code size) (CONFIG_OPTIMIZATION_ASSERTIONS_SILENT)

    Enable silent assertions. Failed assertions will abort(), user needs to use the aborting address to find the line number with the failed assertion.

  • Disabled (sets -DNDEBUG) (CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED)

    If assertions are disabled, -DNDEBUG is added to CPPFLAGS.

CONFIG_CXX_EXCEPTIONS

Enable C++ exceptions

Enable C++ exceptions

Enabling this option compiles all IDF C++ files with exception support enabled.

Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which throws an exception will abort instead.

Enabling this option currently adds an additional ~500 bytes of heap overhead when an exception is thrown in user code for the first time.

CONFIG_CXX_EXCEPTIONS_EMG_POOL_SIZE

Emergency Pool Size

Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate memory for thrown exceptions when there is not enough memory on the heap.

Found in
Compiler options > Enable C++ exceptions
CONFIG_STACK_CHECK_MODE

Stack smashing protection mode

Stack smashing protection mode. Emit extra code to check for buffer overflows, such as stack smashing attacks. This is done by adding a guard variable to functions with vulnerable objects. The guards are initialized when a function is entered and then checked when the function exits. If a guard check fails, program is halted. Protection has the following modes:

  • In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca, and functions with buffers larger than 8 bytes are protected.
  • STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes additional functions to be protected – those that have local array definitions, or have references to local frame addresses.
  • In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected.

Modes have the following impact on code performance and coverage:

  • performance: NORMAL > STRONG > OVERALL
  • coverage: NORMAL < STRONG < OVERALL
Found in
Compiler options
Available options:
  • None (CONFIG_STACK_CHECK_NONE)
  • Normal (CONFIG_STACK_CHECK_NORM)
  • Strong (CONFIG_STACK_CHECK_STRONG)
  • Overall (CONFIG_STACK_CHECK_ALL)
CONFIG_WARN_WRITE_STRINGS

Enable -Wwrite-strings warning flag

Adds -Wwrite-strings flag for the C/C++ compilers.

For C, this gives string constants the type const char[] so that copying the address of one into a non-const char \* pointer produces a warning. This warning helps to find at compile time code that tries to write into a string constant.

For C++, this warns about the deprecated conversion from string literals to char \*.

Found in
Compiler options

Component config

LWIP

CONFIG_L2_TO_L3_COPY

Enable copy between Layer2 and Layer3 packets

If this feature is enabled, all traffic from layer2(WIFI Driver) will be copied to a new buffer before sending it to layer3(LWIP stack), freeing the layer2 buffer. Please be notified that the total layer2 receiving buffer is fixed and ESP32 currently supports 25 layer2 receiving buffer, when layer2 buffer runs out of memory, then the incoming packets will be dropped in hardware. The layer3 buffer is allocated from the heap, so the total layer3 receiving buffer depends on the available heap size, when heap runs out of memory, no copy will be sent to layer3 and packet will be dropped in layer2. Please make sure you fully understand the impact of this feature before enabling it.

Found in
Component config > LWIP
CONFIG_LWIP_IRAM_OPTIMIZATION

Enable LWIP IRAM optimization

If this feature is enabled, some functions relating to RX/TX in LWIP will be put into IRAM, it can improve UDP/TCP throughput by >10% for single core mode, it doesn’t help too much for dual core mode. On the other hand, it needs about 10KB IRAM for these optimizations.

If this feature is disabled, all lwip functions will be put into FLASH.

Found in
Component config > LWIP
CONFIG_LWIP_MAX_SOCKETS

Max number of open sockets

Sockets take up a certain amount of memory, and allowing fewer sockets to be open at the same time conserves memory. Specify the maximum amount of sockets here. The valid value is from 1 to 16.

Found in
Component config > LWIP
CONFIG_USE_ONLY_LWIP_SELECT

Support LWIP socket select() only

The virtual filesystem layer of select() redirects sockets to lwip_select() and non-socket file descriptors to their respective driver implementations. If this option is enabled then all calls of select() will be redirected to lwip_select(), therefore, select can be used for sockets only.

Found in
Component config > LWIP
CONFIG_LWIP_SO_REUSE

Enable SO_REUSEADDR option

Enabling this option allows binding to a port which remains in TIME_WAIT.

Found in
Component config > LWIP
CONFIG_LWIP_SO_REUSE_RXTOALL

SO_REUSEADDR copies broadcast/multicast to all matches

Enabling this option means that any incoming broadcast or multicast packet will be copied to all of the local sockets that it matches (may be more than one if SO_REUSEADDR is set on the socket.)

This increases memory overhead as the packets need to be copied, however they are only copied per matching socket. You can safely disable it if you don’t plan to receive broadcast or multicast traffic on more than one socket at a time.

Found in
Component config > LWIP
CONFIG_LWIP_SO_RCVBUF

Enable SO_RCVBUF option

Enabling this option allows checking for available data on a netconn.

Found in
Component config > LWIP
CONFIG_LWIP_DHCP_MAX_NTP_SERVERS

Maximum number of NTP servers

Set maximum number of NTP servers used by LwIP SNTP module. First argument of sntp_setserver/sntp_setservername functions is limited to this value.

Found in
Component config > LWIP
CONFIG_LWIP_IP_FRAG

Enable fragment outgoing IP packets

Enabling this option allows fragmenting outgoing IP packets if their size exceeds MTU.

Found in
Component config > LWIP
CONFIG_LWIP_IP_REASSEMBLY

Enable reassembly incoming fragmented IP packets

Enabling this option allows reassemblying incoming fragmented IP packets.

Found in
Component config > LWIP
CONFIG_LWIP_STATS

Enable LWIP statistics

Enabling this option allows LWIP statistics

Found in
Component config > LWIP
CONFIG_LWIP_ETHARP_TRUST_IP_MAC

Enable LWIP ARP trust

Enabling this option allows ARP table to be updated.

If this option is enabled, the incoming IP packets cause the ARP table to be updated with the source MAC and IP addresses supplied in the packet. You may want to disable this if you do not trust LAN peers to have the correct addresses, or as a limited approach to attempt to handle spoofing. If disabled, lwIP will need to make a new ARP request if the peer is not already in the ARP table, adding a little latency. The peer *is* in the ARP table if it requested our address before. Also notice that this slows down input processing of every IP packet!

There are two known issues in real application if this feature is enabled:
  • The LAN peer may have bug to update the ARP table after the ARP entry is aged out. If the ARP entry on the LAN peer is aged out but failed to be updated, all IP packets sent from LWIP to the LAN peer will be dropped by LAN peer.
  • The LAN peer may not be trustful, the LAN peer may send IP packets to LWIP with two different MACs, but the same IP address. If this happens, the LWIP has problem to receive IP packets from LAN peer.

So the recommendation is to disable this option. Here the LAN peer means the other side to which the ESP station or soft-AP is connected.

Found in
Component config > LWIP
CONFIG_ESP_GRATUITOUS_ARP

Send gratuitous ARP periodically

Enable this option allows to send gratuitous ARP periodically.

This option solve the compatibility issues.If the ARP table of the AP is old, and the AP doesn’t send ARP request to update it’s ARP table, this will lead to the STA sending IP packet fail. Thus we send gratuitous ARP periodically to let AP update it’s ARP table.

Found in
Component config > LWIP
CONFIG_GARP_TMR_INTERVAL

GARP timer interval(seconds)

Set the timer interval for gratuitous ARP. The default value is 60s

Found in
Component config > LWIP
CONFIG_TCPIP_RECVMBOX_SIZE

TCPIP task receive mail box size

Set TCPIP task receive mail box size. Generally bigger value means higher throughput but more memory. The value should be bigger than UDP/TCP mail box size.

Found in
Component config > LWIP
CONFIG_LWIP_DHCP_DOES_ARP_CHECK

DHCP: Perform ARP check on any offered address

Enabling this option performs a check (via ARP request) if the offered IP address is not already in use by another host on the network.

Found in
Component config > LWIP

DHCP server

CONFIG_LWIP_DHCPS_LEASE_UNIT

Multiplier for lease time, in seconds

The DHCP server is calculating lease time multiplying the sent and received times by this number of seconds per unit. The default is 60, that equals one minute.

Found in
Component config > LWIP > DHCP server
CONFIG_LWIP_DHCPS_MAX_STATION_NUM

Maximum number of stations

The maximum number of DHCP clients that are connected to the server. After this number is exceeded, DHCP server removes of the oldest device from it’s address pool, without notification.

Found in
Component config > LWIP > DHCP server
CONFIG_LWIP_AUTOIP

Support per-interface loopback

  • CONFIG_LWIP_LOOPBACK_MAX_PBUFS

    Support per-interface loopback

    Enabling this option means that if a packet is sent with a destination address equal to the interface’s own IP address, it will “loop back” and be received by this interface.

CONFIG_LWIP_LOOPBACK_MAX_PBUFS

Max queued loopback packets per interface

Configure the maximum number of packets which can be queued for loopback on a given interface. Reducing this number may cause packets to be dropped, but will avoid filling memory with queued packet data.

Found in
Component config > LWIP > Support per-interface loopback

TCP

CONFIG_LWIP_MAX_ACTIVE_TCP

Maximum active TCP Connections

The maximum number of simultaneously active TCP connections. The practical maximum limit is determined by available heap memory at runtime.

Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new TCP connections after the limit is reached.

Found in
Component config > LWIP > TCP
CONFIG_LWIP_MAX_LISTENING_TCP

Maximum listening TCP Connections

The maximum number of simultaneously listening TCP connections. The practical maximum limit is determined by available heap memory at runtime.

Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new listening TCP connections after the limit is reached.

Found in
Component config > LWIP > TCP
CONFIG_TCP_MAXRTX

Maximum number of retransmissions of data segments

Set maximum number of retransmissions of data segments.

Found in
Component config > LWIP > TCP
CONFIG_TCP_SYNMAXRTX

Maximum number of retransmissions of SYN segments

Set maximum number of retransmissions of SYN segments.

Found in
Component config > LWIP > TCP
CONFIG_TCP_MSS

Maximum Segment Size (MSS)

Set maximum segment size for TCP transmission.

Can be set lower to save RAM, the default value 1436 will give best throughput.

Found in
Component config > LWIP > TCP
CONFIG_TCP_MSL

Maximum segment lifetime (MSL)

Set maximum segment lifetime in in milliseconds.

Found in
Component config > LWIP > TCP
CONFIG_TCP_SND_BUF_DEFAULT

Default send buffer size

Set default send buffer size for new TCP sockets.

Per-socket send buffer size can be changed at runtime with lwip_setsockopt(s, TCP_SNDBUF, …).

This value must be at least 2x the MSS size, and the default is 4x the default MSS size.

Setting a smaller default SNDBUF size can save some RAM, but will decrease performance.

Found in
Component config > LWIP > TCP
CONFIG_TCP_WND_DEFAULT

Default receive window size

Set default TCP receive window size for new TCP sockets.

Per-socket receive window size can be changed at runtime with lwip_setsockopt(s, TCP_WINDOW, …).

Setting a smaller default receive window size can save some RAM, but will significantly decrease performance.

Found in
Component config > LWIP > TCP
CONFIG_TCP_RECVMBOX_SIZE

Default TCP receive mail box size

Set TCP receive mail box size. Generally bigger value means higher throughput but more memory. The recommended value is: TCP_WND_DEFAULT/TCP_MSS + 2, e.g. if TCP_WND_DEFAULT=14360, TCP_MSS=1436, then the recommended receive mail box size is (14360/1436 + 2) = 12.

TCP receive mail box is a per socket mail box, when the application receives packets from TCP socket, LWIP core firstly posts the packets to TCP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum TCP_RECCVMBOX_SIZE packets for each TCP socket, so the maximum possible cached TCP packets for all TCP sockets is TCP_RECCVMBOX_SIZE multiples the maximum TCP socket number. In other words, the bigger TCP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we need to make sure the TCP receive mail box is big enough to avoid packet drop between LWIP core and application.

Found in
Component config > LWIP > TCP
CONFIG_TCP_QUEUE_OOSEQ

Queue incoming out-of-order segments

Queue incoming out-of-order segments for later use.

Disable this option to save some RAM during TCP sessions, at the expense of increased retransmissions if segments arrive out of order.

Found in
Component config > LWIP > TCP
CONFIG_ESP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES

Keep TCP connections when IP changed

This option is enabled when the following scenario happen: network dropped and reconnected, IP changes is like: 192.168.0.2->0.0.0.0->192.168.0.2

Disable this option to keep consistent with the original LWIP code behavior.

Found in
Component config > LWIP > TCP
CONFIG_TCP_OVERSIZE

Pre-allocate transmit PBUF size

Allows enabling “oversize” allocation of TCP transmission pbufs ahead of time, which can reduce the length of pbuf chains used for transmission.

This will not make a difference to sockets where Nagle’s algorithm is disabled.

Default value of MSS is fine for most applications, 25% MSS may save some RAM when only transmitting small amounts of data. Disabled will have worst performance and fragmentation characteristics, but uses least RAM overall.

Found in
Component config > LWIP > TCP
Available options:
  • MSS (CONFIG_TCP_OVERSIZE_MSS)
  • 25% MSS (CONFIG_TCP_OVERSIZE_QUARTER_MSS)
  • Disabled (CONFIG_TCP_OVERSIZE_DISABLE)
CONFIG_LWIP_WND_SCALE

Support TCP window scale

Enable this feature to support TCP window scaling.

Found in
Component config > LWIP > TCP
CONFIG_TCP_RCV_SCALE

Set TCP receiving window scaling factor

Enable this feature to support TCP window scaling.

Found in
Component config > LWIP > TCP

UDP

CONFIG_LWIP_MAX_UDP_PCBS

Maximum active UDP control blocks

The maximum number of active UDP “connections” (ie UDP sockets sending/receiving data). The practical maximum limit is determined by available heap memory at runtime.

Found in
Component config > LWIP > UDP
CONFIG_UDP_RECVMBOX_SIZE

Default UDP receive mail box size

Set UDP receive mail box size. The recommended value is 6.

UDP receive mail box is a per socket mail box, when the application receives packets from UDP socket, LWIP core firstly posts the packets to UDP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum UDP_RECCVMBOX_SIZE packets for each UDP socket, so the maximum possible cached UDP packets for all UDP sockets is UDP_RECCVMBOX_SIZE multiples the maximum UDP socket number. In other words, the bigger UDP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we need to make sure the UDP receive mail box is big enough to avoid packet drop between LWIP core and application.

Found in
Component config > LWIP > UDP
CONFIG_TCPIP_TASK_STACK_SIZE

TCP/IP Task Stack Size

Configure TCP/IP task stack size, used by LWIP to process multi-threaded TCP/IP operations. Setting this stack too small will result in stack overflow crashes.

Found in
Component config > LWIP
CONFIG_PPP_SUPPORT

Enable PPP support (new/experimental)

CONFIG_PPP_PAP_SUPPORT

Enable PAP support

Enable Password Authentication Protocol (PAP) support

Found in
Component config > LWIP > Enable PPP support (new/experimental)
CONFIG_PPP_CHAP_SUPPORT

Enable CHAP support

Enable Challenge Handshake Authentication Protocol (CHAP) support

Found in
Component config > LWIP > Enable PPP support (new/experimental)
CONFIG_PPP_MSCHAP_SUPPORT

Enable MSCHAP support

Enable Microsoft version of the Challenge-Handshake Authentication Protocol (MSCHAP) support

Found in
Component config > LWIP > Enable PPP support (new/experimental)
CONFIG_PPP_MPPE_SUPPORT

Enable MPPE support

Enable Microsoft Point-to-Point Encryption (MPPE) support

Found in
Component config > LWIP > Enable PPP support (new/experimental)
CONFIG_PPP_DEBUG_ON

Enable PPP debug log output

Enable PPP debug log output

Found in
Component config > LWIP > Enable PPP support (new/experimental)

ICMP

CONFIG_LWIP_MULTICAST_PING

Respond to multicast pings

Found in
Component config > LWIP > ICMP
CONFIG_LWIP_BROADCAST_PING

Respond to broadcast pings

Found in
Component config > LWIP > ICMP

LWIP RAW API

CONFIG_LWIP_MAX_RAW_PCBS

Maximum LWIP RAW PCBs

The maximum number of simultaneously active LWIP RAW protocol control blocks. The practical maximum limit is determined by available heap memory at runtime.

Found in
Component config > LWIP > LWIP RAW API

libsodium

CONFIG_LIBSODIUM_USE_MBEDTLS_SHA

Use mbedTLS SHA256 & SHA512 implementations

If this option is enabled, libsodium will use thin wrappers around mbedTLS for SHA256 & SHA512 operations.

This saves some code size if mbedTLS is also used. However it is incompatible with hardware SHA acceleration (due to the way libsodium’s API manages SHA state).

Found in
Component config > libsodium

ESP HTTP client

CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS

Enable https

This option will enable https protocol by linking mbedtls library and initializing SSL transport

Found in
Component config > ESP HTTP client

FreeRTOS

CONFIG_FREERTOS_UNICORE

Run FreeRTOS only on first core

This version of FreeRTOS normally takes control of all cores of the CPU. Select this if you only want to start it on the first core. This is needed when e.g. another process needs complete control over the second core.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_CORETIMER

Xtensa timer to use as the FreeRTOS tick source

FreeRTOS needs a timer with an associated interrupt to use as the main tick source to increase counters, run timers and do pre-emptive multitasking with. There are multiple timers available to do this, with different interrupt priorities. Check

Found in
Component config > FreeRTOS
Available options:

  • Timer 0 (int 6, level 1) (CONFIG_FREERTOS_CORETIMER_0)

    Select this to use timer 0

  • Timer 1 (int 15, level 3) (CONFIG_FREERTOS_CORETIMER_1)

    Select this to use timer 1

CONFIG_FREERTOS_HZ

Tick rate (Hz)

Select the tick rate at which FreeRTOS does pre-emptive context switching.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION

Halt when an SMP-untested function is called

Some functions in FreeRTOS have not been thoroughly tested yet when moving to the SMP implementation of FreeRTOS. When this option is enabled, these fuctions will throw an assert().

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_CHECK_STACKOVERFLOW

Check for stack overflow

FreeRTOS can check for stack overflows in threads and trigger an user function called vApplicationStackOverflowHook when this happens.

Found in
Component config > FreeRTOS
Available options:

  • No checking (CONFIG_FREERTOS_CHECK_STACKOVERFLOW_NONE)

    Do not check for stack overflows (configCHECK_FOR_STACK_OVERFLOW=0)

  • Check by stack pointer value (CONFIG_FREERTOS_CHECK_STACKOVERFLOW_PTRVAL)

    Check for stack overflows on each context switch by checking if the stack pointer is in a valid range. Quick but does not detect stack overflows that happened between context switches (configCHECK_FOR_STACK_OVERFLOW=1)

  • Check using canary bytes (CONFIG_FREERTOS_CHECK_STACKOVERFLOW_CANARY)

    Places some magic bytes at the end of the stack area and on each context switch, check if these bytes are still intact. More thorough than just checking the pointer, but also slightly slower. (configCHECK_FOR_STACK_OVERFLOW=2)

CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK

Set a debug watchpoint as a stack overflow check

FreeRTOS can check if a stack has overflown its bounds by checking either the value of the stack pointer or by checking the integrity of canary bytes. (See FREERTOS_CHECK_STACKOVERFLOW for more information.) These checks only happen on a context switch, and the situation that caused the stack overflow may already be long gone by then. This option will use the debug memory watchpoint 1 (the second one) to allow breaking into the debugger (or panic’ing) as soon as any of the last 32 bytes on the stack of a task are overwritten. The side effect is that using gdb, you effectively only have one watchpoint; the 2nd one is overwritten as soon as a task switch happens.

This check only triggers if the stack overflow writes within 4 bytes of the end of the stack, rather than overshooting further, so it is worth combining this approach with one of the other stack overflow check methods.

When this watchpoint is hit, gdb will stop with a SIGTRAP message. When no JTAG OCD is attached, esp-idf will panic on an unhandled debug exception.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_INTERRUPT_BACKTRACE

Enable backtrace from interrupt to task context

If this option is enabled, interrupt stack frame will be modified to point to the code of the interrupted task as its return address. This helps the debugger (or the panic handler) show a backtrace from the interrupt to the task which was interrupted. This also works for nested interrupts: higer level interrupt stack can be traced back to the lower level interrupt. This option adds 4 instructions to the interrupt dispatching code.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS

Number of thread local storage pointers

FreeRTOS has the ability to store per-thread pointers in the task control block. This controls the number of pointers available.

This value must be at least 1. Index 0 is reserved for use by the pthreads API thread-local-storage. Other indexes can be used for any desired purpose.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_ASSERT

FreeRTOS assertions

Failed FreeRTOS configASSERT() assertions can be configured to behave in different ways.

Found in
Component config > FreeRTOS
Available options:

  • abort() on failed assertions (CONFIG_FREERTOS_ASSERT_FAIL_ABORT)

    If a FreeRTOS configASSERT() fails, FreeRTOS will abort() and halt execution. The panic handler can be configured to handle the outcome of an abort() in different ways.

  • Print and continue failed assertions (CONFIG_FREERTOS_ASSERT_FAIL_PRINT_CONTINUE)

    If a FreeRTOS assertion fails, print it out and continue.

  • Disable FreeRTOS assertions (CONFIG_FREERTOS_ASSERT_DISABLE)

    FreeRTOS configASSERT() will not be compiled into the binary.

CONFIG_FREERTOS_IDLE_TASK_STACKSIZE

Idle Task stack size

The idle task has its own stack, sized in bytes. The default size is enough for most uses. Size can be reduced to 768 bytes if no (or simple) FreeRTOS idle hooks are used and pthread local storage or FreeRTOS local storage cleanup callbacks are not used.

The stack size may need to be increased above the default if the app installs idle or thread local storage cleanup hooks that use a lot of stack memory.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_ISR_STACKSIZE

ISR stack size

The interrupt handlers have their own stack. The size of the stack can be defined here. Each processor has its own stack, so the total size occupied will be twice this.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_LEGACY_HOOKS

Use FreeRTOS legacy hooks

FreeRTOS offers a number of hooks/callback functions that are called when a timer tick happens, the idle thread runs etc. esp-idf replaces these by runtime registerable hooks using the esp_register_freertos_xxx_hook system, but for legacy reasons the old hooks can also still be enabled. Please enable this only if you have code that for some reason can’t be migrated to the esp_register_freertos_xxx_hook system.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_LEGACY_IDLE_HOOK

Enable legacy idle hook

If enabled, FreeRTOS will call a function called vApplicationIdleHook when the idle thread on a CPU is running. Please make sure your code defines such a function.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_LEGACY_TICK_HOOK

Enable legacy tick hook

If enabled, FreeRTOS will call a function called vApplicationTickHook when a FreeRTOS tick is executed. Please make sure your code defines such a function.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_MAX_TASK_NAME_LEN

Maximum task name length

Changes the maximum task name length. Each task allocated will include this many bytes for a task name. Using a shorter value saves a small amount of RAM, a longer value allows more complex names.

For most uses, the default of 16 is OK.

Found in
Component config > FreeRTOS
CONFIG_SUPPORT_STATIC_ALLOCATION

Enable FreeRTOS static allocation API

FreeRTOS gives the application writer the ability to instead provide the memory themselves, allowing the following objects to optionally be created without any memory being allocated dynamically:

  • Tasks
  • Software Timers (Daemon task is still dynamic. See documentation)
  • Queues
  • Event Groups
  • Binary Semaphores
  • Counting Semaphores
  • Recursive Semaphores
  • Mutexes

Whether it is preferable to use static or dynamic memory allocation is dependent on the application, and the preference of the application writer. Both methods have pros and cons, and both methods can be used within the same RTOS application.

Creating RTOS objects using statically allocated RAM has the benefit of providing the application writer with more control: RTOS objects can be placed at specific memory locations. The maximum RAM footprint can be determined at link time, rather than run time. The application writer does not need to concern themselves with graceful handling of memory allocation failures. It allows the RTOS to be used in applications that simply don’t allow any dynamic memory allocation (although FreeRTOS includes allocation schemes that can overcome most objections).

Found in
Component config > FreeRTOS
CONFIG_ENABLE_STATIC_TASK_CLEAN_UP_HOOK

Enable static task clean up hook

Enable this option to make FreeRTOS call the static task clean up hook when a task is deleted.

Bear in mind that if this option is enabled you will need to implement the following function:

void vPortCleanUpTCB ( void \*pxTCB ) {
    // place clean up code here
}
Found in
Component config > FreeRTOS
CONFIG_TIMER_TASK_PRIORITY

FreeRTOS timer task priority

The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the application’s executable binary.

Use this constant to define the priority that the timer task will run at.

Found in
Component config > FreeRTOS
CONFIG_TIMER_TASK_STACK_DEPTH

FreeRTOS timer task stack size

The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the application’s executable binary.

Use this constant to define the size (in bytes) of the stack allocated for the timer task.

Found in
Component config > FreeRTOS
CONFIG_TIMER_QUEUE_LENGTH

FreeRTOS timer queue length

FreeRTOS provides a set of timer related API functions. Many of these functions use a standard FreeRTOS queue to send commands to the timer service task. The queue used for this purpose is called the ‘timer command queue’. The ‘timer command queue’ is private to the FreeRTOS timer implementation, and cannot be accessed directly.

For most uses the default value of 10 is OK.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE

FreeRTOS queue registry size

FreeRTOS uses the queue registry as a means for kernel aware debuggers to locate queues, semaphores, and mutexes. The registry allows for a textual name to be associated with a queue for easy identification within a debugging GUI. A value of 0 will disable queue registry functionality, and a value larger than 0 will specify the number of queues/semaphores/mutexes that the registry can hold.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_USE_TRACE_FACILITY

Enable FreeRTOS trace facility

If enabled, configUSE_TRACE_FACILITY will be defined as 1 in FreeRTOS. This will allow the usage of trace facility functions such as uxTaskGetSystemState().

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS

Enable FreeRTOS stats formatting functions

If enabled, configUSE_STATS_FORMATTING_FUNCTIONS will be defined as 1 in FreeRTOS. This will allow the usage of stats formatting functions such as vTaskList().

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS

Enable FreeRTOS to collect run time stats

If enabled, configGENERATE_RUN_TIME_STATS will be defined as 1 in FreeRTOS. This will allow FreeRTOS to collect information regarding the usage of processor time amongst FreeRTOS tasks. Run time stats are generated using either the ESP Timer or the CPU Clock as the clock source (Note that run time stats are only valid until the clock source overflows). The function vTaskGetRunTimeStats() will also be available if FREERTOS_USE_STATS_FORMATTING_FUNCTIONS and FREERTOS_USE_TRACE_FACILITY are enabled. vTaskGetRunTimeStats() will display the run time of each task as a % of the total run time of all CPUs (task run time / no of CPUs) / (total run time / 100 )

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_RUN_TIME_STATS_CLK

Choose the clock source for run time stats

Choose the clock source for FreeRTOS run time stats. Options are CPU0’s CPU Clock or the ESP Timer. Both clock sources are 32 bits. The CPU Clock can run at a higher frequency hence provide a finer resolution but will overflow much quicker. Note that run time stats are only valid until the clock source overflows.

Found in
Component config > FreeRTOS
Available options:

  • Use ESP TIMER for run time stats (CONFIG_FREERTOS_RUN_TIME_STATS_USING_ESP_TIMER)

    ESP Timer will be used as the clock source for FreeRTOS run time stats. The ESP Timer runs at a frequency of 1MHz regardless of Dynamic Frequency Scaling. Therefore the ESP Timer will overflow in approximately 4290 seconds.

  • Use CPU Clock for run time stats (CONFIG_FREERTOS_RUN_TIME_STATS_USING_CPU_CLK)

    CPU Clock will be used as the clock source for the generation of run time stats. The CPU Clock has a frequency dependent on ESP32_DEFAULT_CPU_FREQ_MHZ and Dynamic Frequency Scaling (DFS). Therefore the CPU Clock frequency can fluctuate between 80 to 240MHz. Run time stats generated using the CPU Clock represents the number of CPU cycles each task is allocated and DOES NOT reflect the amount of time each task runs for (as CPU clock frequency can change). If the CPU clock consistently runs at the maximum frequency of 240MHz, it will overflow in approximately 17 seconds.

CONFIG_FREERTOS_USE_TICKLESS_IDLE

Tickless idle support

If power management support is enabled, FreeRTOS will be able to put the system into light sleep mode when no tasks need to run for a number of ticks. This number can be set using FREERTOS_IDLE_TIME_BEFORE_SLEEP option. This feature is also known as “automatic light sleep”.

Note that timers created using esp_timer APIs may prevent the system from entering sleep mode, even when no tasks need to run.

If disabled, automatic light sleep support will be disabled.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP

Minimum number of ticks to enter sleep mode for

FreeRTOS will enter light sleep mode if no tasks need to run for this number of ticks.

Found in
Component config > FreeRTOS
CONFIG_FREERTOS_DEBUG_INTERNALS

Debug FreeRTOS internals

CONFIG_FREERTOS_PORTMUX_DEBUG

Debug portMUX portENTER_CRITICAL/portEXIT_CRITICAL

If enabled, debug information (including integrity checks) will be printed to UART for the port-specific MUX implementation.

Found in
Component config > FreeRTOS > Debug FreeRTOS internals
CONFIG_FREERTOS_PORTMUX_DEBUG_RECURSIVE

Debug portMUX Recursion

If enabled, additional debug information will be printed for recursive portMUX usage.

Found in
Component config > FreeRTOS > Debug FreeRTOS internals

ADC-Calibration

CONFIG_ADC_CAL_EFUSE_TP_ENABLE

Use Two Point Values

Some ESP32s have Two Point calibration values burned into eFuse BLOCK3. This option will allow the ADC calibration component to characterize the ADC-Voltage curve using Two Point values if they are available.

Found in
Component config > ADC-Calibration
CONFIG_ADC_CAL_EFUSE_VREF_ENABLE

Use eFuse Vref

Some ESP32s have Vref burned into eFuse BLOCK0. This option will allow the ADC calibration component to characterize the ADC-Voltage curve using eFuse Vref if it is available.

Found in
Component config > ADC-Calibration
CONFIG_ADC_CAL_LUT_ENABLE

Use Lookup Tables

This option will allow the ADC calibration component to use Lookup Tables to correct for non-linear behavior in 11db attenuation. Other attenuations do not exhibit non-linear behavior hence will not be affected by this option.

Found in
Component config > ADC-Calibration

Wear Levelling

CONFIG_WL_SECTOR_SIZE

Wear Levelling library sector size

Sector size used by wear levelling library. You can set default sector size or size that will fit to the flash device sector size.

With sector size set to 4096 bytes, wear levelling library is more efficient. However if FAT filesystem is used on top of wear levelling library, it will need more temporary storage: 4096 bytes for each mounted filesystem and 4096 bytes for each opened file.

With sector size set to 512 bytes, wear levelling library will perform more operations with flash memory, but less RAM will be used by FAT filesystem library (512 bytes for the filesystem and 512 bytes for each file opened).

Found in
Component config > Wear Levelling
Available options:
  • 512 (CONFIG_WL_SECTOR_SIZE_512)
  • 4096 (CONFIG_WL_SECTOR_SIZE_4096)
CONFIG_WL_SECTOR_MODE

Sector store mode

Specify the mode to store data into flash:

  • In Performance mode a data will be stored to the RAM and then stored back to the flash. Compared to the Safety mode, this operation is faster, but if power will be lost when erase sector operation is in progress, then the data from complete flash device sector will be lost.
  • In Safety mode data from complete flash device sector will be read from flash, modified, and then stored back to flash. Compared to the Performance mode, this operation is slower, but if power is lost during erase sector operation, then the data from full flash device sector will not be lost.
Found in
Component config > Wear Levelling
Available options:
  • Perfomance (CONFIG_WL_SECTOR_MODE_PERF)
  • Safety (CONFIG_WL_SECTOR_MODE_SAFE)

Heap memory debugging

CONFIG_HEAP_CORRUPTION_DETECTION

Heap corruption detection

Enable heap poisoning features to detect heap corruption caused by out-of-bounds access to heap memory.

See the “Heap Memory Debugging” page of the IDF documentation for a description of each level of heap corruption detection.

Found in
Component config > Heap memory debugging
Available options:
  • Basic (no poisoning) (CONFIG_HEAP_POISONING_DISABLED)
  • Light impact (CONFIG_HEAP_POISONING_LIGHT)
  • Comprehensive (CONFIG_HEAP_POISONING_COMPREHENSIVE)
CONFIG_HEAP_TRACING

Enable heap tracing

Enables the heap tracing API defined in esp_heap_trace.h.

This function causes a moderate increase in IRAM code side and a minor increase in heap function (malloc/free/realloc) CPU overhead, even when the tracing feature is not used. So it’s best to keep it disabled unless tracing is being used.

Found in
Component config > Heap memory debugging
CONFIG_HEAP_TRACING_STACK_DEPTH

Heap tracing stack depth

Number of stack frames to save when tracing heap operation callers.

More stack frames uses more memory in the heap trace buffer (and slows down allocation), but can provide useful information.

Found in
Component config > Heap memory debugging
CONFIG_HEAP_TASK_TRACKING

Enable heap task tracking

Enables tracking the task responsible for each heap allocation.

This function depends on heap poisoning being enabled and adds four more bytes of overhead for each block allocated.

Found in
Component config > Heap memory debugging

ESP32-specific

CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ

CPU frequency

CPU frequency to be set on application startup.

Found in
Component config > ESP32-specific
Available options:
  • 80 MHz (CONFIG_ESP32_DEFAULT_CPU_FREQ_80)
  • 160 MHz (CONFIG_ESP32_DEFAULT_CPU_FREQ_160)
  • 240 MHz (CONFIG_ESP32_DEFAULT_CPU_FREQ_240)
CONFIG_SPIRAM_SUPPORT

Support for external, SPI-connected RAM

This enables support for an external SPI RAM chip, connected in parallel with the main SPI flash chip.

Found in
Component config > ESP32-specific

SPI RAM config

CONFIG_SPIRAM_BOOT_INIT

Initialize SPI RAM when booting the ESP32

If this is enabled, the SPI RAM will be enabled during initial boot. Unless you have specific requirements, you’ll want to leave this enabled so memory allocated during boot-up can also be placed in SPI RAM.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_IGNORE_NOTFOUND

Ignore PSRAM when not found

Normally, if psram initialization is enabled during compile time but not found at runtime, it is seen as an error making the ESP32 panic. If this is enabled, the ESP32 will keep on running but will not add the (non-existing) RAM to any allocator.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_USE

SPI RAM access method

The SPI RAM can be accessed in multiple methods: by just having it available as an unmanaged memory region in the ESP32 memory map, by integrating it in the ESP32s heap as ‘special’ memory needing heap_caps_malloc to allocate, or by fully integrating it making malloc() also able to return SPI RAM pointers.

Found in
Component config > ESP32-specific > SPI RAM config
Available options:
  • Integrate RAM into ESP32 memory map (CONFIG_SPIRAM_USE_MEMMAP)
  • Make RAM allocatable using heap_caps_malloc(…, MALLOC_CAP_SPIRAM) (CONFIG_SPIRAM_USE_CAPS_ALLOC)
  • Make RAM allocatable using malloc() as well (CONFIG_SPIRAM_USE_MALLOC)
CONFIG_SPIRAM_TYPE

Type of SPI RAM chip in use

Found in
Component config > ESP32-specific > SPI RAM config
Available options:
  • ESP-PSRAM32 or IS25WP032 (CONFIG_SPIRAM_TYPE_ESPPSRAM32)
CONFIG_SPIRAM_SPEED

Set RAM clock speed

Select the speed for the SPI RAM chip. If SPI RAM is enabled, we only support three combinations of SPI speed mode we supported now:

  1. Flash SPI running at 40Mhz and RAM SPI running at 40Mhz

  2. Flash SPI running at 80Mhz and RAM SPI running at 40Mhz

  3. Flash SPI running at 80Mhz and RAM SPI running at 80Mhz

    Note: If the third mode(80Mhz+80Mhz) is enabled, the VSPI port will be occupied by the system.

    Application code should never touch VSPI hardware in this case. The option to select 80MHz will only be visible if the flash SPI speed is also 80MHz. (ESPTOOLPY_FLASHFREQ_80M is true)

Found in
Component config > ESP32-specific > SPI RAM config
Available options:
  • 40MHz clock speed (CONFIG_SPIRAM_SPEED_40M)
  • 80MHz clock speed (CONFIG_SPIRAM_SPEED_80M)
CONFIG_SPIRAM_MEMTEST

Run memory test on SPI RAM initialization

Runs a rudimentary memory test on initialization. Aborts when memory test fails. Disable this for slightly faster startop.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_CACHE_WORKAROUND

Enable workaround for bug in SPI RAM cache for Rev1 ESP32s

Revision 1 of the ESP32 has a bug that can cause a write to PSRAM not to take place in some situations when the cache line needs to be fetched from external RAM and an interrupt occurs. This enables a fix in the compiler (-mfix-esp32-psram-cache-issue) that makes sure the specific code that is vulnerable to this will not be emitted.

This will also not use any bits of newlib that are located in ROM, opting for a version that is compiled with the workaround and located in flash instead.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL

Maximum malloc() size, in bytes, to always put in internal memory

If malloc() is capable of also allocating SPI-connected ram, its allocation strategy will prefer to allocate chunks less than this size in internal memory, while allocations larger than this will be done from external RAM. If allocation from the preferred region fails, an attempt is made to allocate from the non-preferred region instead, so malloc() will not suddenly fail when either internal or external memory is full.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_WIFI_LWIP_ALLOCATION_FROM_SPIRAM_FIRST

Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, allocate internal memory

Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, try to allocate internal memory then.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL

Reserve this amount of bytes for data that specifically needs to be in DMA or internal memory

Because the external/internal RAM allocation strategy is not always perfect, it sometimes may happen that the internal memory is entirely filled up. This causes allocations that are specifically done in internal memory, for example the stack for new tasks or memory to service DMA or have memory that’s also available when SPI cache is down, to fail. This option reserves a pool specifically for requests like that; the memory in this pool is not given out when a normal malloc() is called.

Set this to 0 to disable this feature.

Note that because FreeRTOS stacks are forced to internal memory, they will also use this memory pool; be sure to keep this in mind when adjusting this value.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY

Allow external memory as an argument to xTaskCreateStatic

Because some bits of the ESP32 code environment cannot be recompiled with the cache workaround, normally tasks cannot be safely run with their stack residing in external memory; for this reason xTaskCreate and friends always allocate stack in internal memory and xTaskCreateStatic will check if the memory passed to it is in internal memory. If you have a task that needs a large amount of stack and does not call on ROM code in any way (no direct calls, but also no Bluetooth/WiFi), you can try to disable this and use xTaskCreateStatic to create the tasks stack in external memory.

Found in
Component config > ESP32-specific > SPI RAM config
CONFIG_ESP32_TRAX

Use TRAX tracing feature

The ESP32 contains a feature which allows you to trace the execution path the processor has taken through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that can’t be used for general purposes anymore. Disable this if you do not know what this is.

Found in
Component config > ESP32-specific
CONFIG_ESP32_TRAX_TWOBANKS

Reserve memory for tracing both pro as well as app cpu execution

The ESP32 contains a feature which allows you to trace the execution path the processor has taken through the program. This is stored in a chunk of 32K (16K for single-processor) of memory that can’t be used for general purposes anymore. Disable this if you do not know what this is.

Found in
Component config > ESP32-specific
CONFIG_ESP32_COREDUMP_TO_FLASH_OR_UART

Core dump destination

Select place to store core dump: flash, uart or none (to disable core dumps generation).

If core dump is configured to be stored in flash and custom partition table is used add corresponding entry to your CSV. For examples, please see predefined partition table CSV descriptions in the components/partition_table directory.

Found in
Component config > ESP32-specific
Available options:
  • Flash (CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH)
  • UART (CONFIG_ESP32_ENABLE_COREDUMP_TO_UART)
  • None (CONFIG_ESP32_ENABLE_COREDUMP_TO_NONE)
CONFIG_ESP32_CORE_DUMP_UART_DELAY

Core dump print to UART delay

Config delay (in ms) before printing core dump to UART. Delay can be interrupted by pressing Enter key.

Found in
Component config > ESP32-specific
CONFIG_ESP32_CORE_DUMP_LOG_LEVEL

Core dump module logging level

Config core dump module logging level (0-5).

Found in
Component config > ESP32-specific
CONFIG_NUMBER_OF_UNIVERSAL_MAC_ADDRESS

Number of universally administered (by IEEE) MAC address

Configure the number of universally administered (by IEEE) MAC addresses. During initialisation, MAC addresses for each network interface are generated or derived from a single base MAC address. If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. If the number of universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet) receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC addresses, respectively. When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)

Found in
Component config > ESP32-specific
Available options:
  • Two (CONFIG_TWO_UNIVERSAL_MAC_ADDRESS)
  • Four (CONFIG_FOUR_UNIVERSAL_MAC_ADDRESS)
CONFIG_SYSTEM_EVENT_QUEUE_SIZE

System event queue size

Config system event queue size in different application.

Found in
Component config > ESP32-specific
CONFIG_SYSTEM_EVENT_TASK_STACK_SIZE

Event loop task stack size

Config system event task stack size in different application.

Found in
Component config > ESP32-specific
CONFIG_MAIN_TASK_STACK_SIZE

Main task stack size

Configure the “main task” stack size. This is the stack of the task which calls app_main(). If app_main() returns then this task is deleted and its stack memory is freed.

Found in
Component config > ESP32-specific
CONFIG_IPC_TASK_STACK_SIZE

Inter-Processor Call (IPC) task stack size

Configure the IPC tasks stack size. One IPC task runs on each core (in dual core mode), and allows for cross-core function calls.

See IPC documentation for more details.

The default stack size should be enough for most common use cases. It can be shrunk if you are sure that you do not use any custom IPC functionality.

Found in
Component config > ESP32-specific
CONFIG_TIMER_TASK_STACK_SIZE

High-resolution timer task stack size

Configure the stack size of esp_timer/ets_timer task. This task is used to dispatch callbacks of timers created using ets_timer and esp_timer APIs. If you are seing stack overflow errors in timer task, increase this value.

Note that this is not the same as FreeRTOS timer task. To configure FreeRTOS timer task size, see “FreeRTOS timer task stack size” option in “FreeRTOS” menu.

Found in
Component config > ESP32-specific
CONFIG_NEWLIB_STDOUT_LINE_ENDING

Line ending for UART output

This option allows configuring the desired line endings sent to UART when a newline (‘n’, LF) appears on stdout. Three options are possible:

CRLF: whenever LF is encountered, prepend it with CR

LF: no modification is applied, stdout is sent as is

CR: each occurence of LF is replaced with CR

This option doesn’t affect behavior of the UART driver (drivers/uart.h).

Found in
Component config > ESP32-specific
Available options:
  • CRLF (CONFIG_NEWLIB_STDOUT_LINE_ENDING_CRLF)
  • LF (CONFIG_NEWLIB_STDOUT_LINE_ENDING_LF)
  • CR (CONFIG_NEWLIB_STDOUT_LINE_ENDING_CR)
CONFIG_NEWLIB_STDIN_LINE_ENDING

Line ending for UART input

This option allows configuring which input sequence on UART produces a newline (‘n’, LF) on stdin. Three options are possible:

CRLF: CRLF is converted to LF

LF: no modification is applied, input is sent to stdin as is

CR: each occurence of CR is replaced with LF

This option doesn’t affect behavior of the UART driver (drivers/uart.h).

Found in
Component config > ESP32-specific
Available options:
  • CRLF (CONFIG_NEWLIB_STDIN_LINE_ENDING_CRLF)
  • LF (CONFIG_NEWLIB_STDIN_LINE_ENDING_LF)
  • CR (CONFIG_NEWLIB_STDIN_LINE_ENDING_CR)
CONFIG_NEWLIB_NANO_FORMAT

Enable ‘nano’ formatting options for printf/scanf family

ESP32 ROM contains parts of newlib C library, including printf/scanf family of functions. These functions have been compiled with so-called “nano” formatting option. This option doesn’t support 64-bit integer formats and C99 features, such as positional arguments.

For more details about “nano” formatting option, please see newlib readme file, search for ‘–enable-newlib-nano-formatted-io’: https://sourceware.org/newlib/README

If this option is enabled, build system will use functions available in ROM, reducing the application binary size. Functions available in ROM run faster than functions which run from flash. Functions available in ROM can also run when flash instruction cache is disabled.

If you need 64-bit integer formatting support or C99 features, keep this option disabled.

Found in
Component config > ESP32-specific
CONFIG_CONSOLE_UART

UART for console output

Select whether to use UART for console output (through stdout and stderr).

  • Default is to use UART0 on pins GPIO1(TX) and GPIO3(RX).
  • If “Custom” is selected, UART0 or UART1 can be chosen, and any pins can be selected.
  • If “None” is selected, there will be no console output on any UART, except for initial output from ROM bootloader. This output can be further suppressed by bootstrapping GPIO13 pin to low logic level.
Found in
Component config > ESP32-specific
Available options:
  • Default: UART0, TX=GPIO1, RX=GPIO3 (CONFIG_CONSOLE_UART_DEFAULT)
  • Custom (CONFIG_CONSOLE_UART_CUSTOM)
  • None (CONFIG_CONSOLE_UART_NONE)
CONFIG_CONSOLE_UART_NUM

UART peripheral to use for console output (0-1)

Due of a ROM bug, UART2 is not supported for console output via ets_printf.

Found in
Component config > ESP32-specific
Available options:
  • UART0 (CONFIG_CONSOLE_UART_CUSTOM_NUM_0)
  • UART1 (CONFIG_CONSOLE_UART_CUSTOM_NUM_1)
CONFIG_CONSOLE_UART_TX_GPIO

UART TX on GPIO#

Found in
Component config > ESP32-specific
CONFIG_CONSOLE_UART_RX_GPIO

UART RX on GPIO#

Found in
Component config > ESP32-specific
CONFIG_CONSOLE_UART_BAUDRATE

UART console baud rate

Found in
Component config > ESP32-specific
CONFIG_ULP_COPROC_ENABLED

Enable Ultra Low Power (ULP) Coprocessor

Set to ‘y’ if you plan to load a firmware for the coprocessor.

If this option is enabled, further coprocessor configuration will appear in the Components menu.

Found in
Component config > ESP32-specific
CONFIG_ULP_COPROC_RESERVE_MEM

RTC slow memory reserved for coprocessor

Bytes of memory to reserve for ULP coprocessor firmware & data.

Data is reserved at the beginning of RTC slow memory.

Found in
Component config > ESP32-specific
CONFIG_ESP32_PANIC

Panic handler behaviour

If FreeRTOS detects unexpected behaviour or an unhandled exception, the panic handler is invoked. Configure the panic handlers action here.

Found in
Component config > ESP32-specific
Available options:

  • Print registers and halt (CONFIG_ESP32_PANIC_PRINT_HALT)

    Outputs the relevant registers over the serial port and halt the processor. Needs a manual reset to restart.

  • Print registers and reboot (CONFIG_ESP32_PANIC_PRINT_REBOOT)

    Outputs the relevant registers over the serial port and immediately reset the processor.

  • Silent reboot (CONFIG_ESP32_PANIC_SILENT_REBOOT)

    Just resets the processor without outputting anything

  • Invoke GDBStub (CONFIG_ESP32_PANIC_GDBSTUB)

    Invoke gdbstub on the serial port, allowing for gdb to attach to it to do a postmortem of the crash.

CONFIG_ESP32_DEBUG_OCDAWARE

Make exception and panic handlers JTAG/OCD aware

The FreeRTOS panic and unhandled exception handers can detect a JTAG OCD debugger and instead of panicking, have the debugger stop on the offending instruction.

Found in
Component config > ESP32-specific
CONFIG_ESP32_DEBUG_STUBS_ENABLE

OpenOCD debug stubs

Debug stubs are used by OpenOCD to execute pre-compiled onboard code which does some useful debugging, e.g. GCOV data dump.

Found in
Component config > ESP32-specific
CONFIG_INT_WDT

Interrupt watchdog

This watchdog timer can detect if the FreeRTOS tick interrupt has not been called for a certain time, either because a task turned off interrupts and did not turn them on for a long time, or because an interrupt handler did not return. It will try to invoke the panic handler first and failing that reset the SoC.

Found in
Component config > ESP32-specific
CONFIG_INT_WDT_TIMEOUT_MS

Interrupt watchdog timeout (ms)

The timeout of the watchdog, in miliseconds. Make this higher than the FreeRTOS tick rate.

Found in
Component config > ESP32-specific
CONFIG_INT_WDT_CHECK_CPU1

Also watch CPU1 tick interrupt

Also detect if interrupts on CPU 1 are disabled for too long.

Found in
Component config > ESP32-specific
CONFIG_TASK_WDT

Initialize Task Watchdog Timer on startup

The Task Watchdog Timer can be used to make sure individual tasks are still running. Enabling this option will cause the Task Watchdog Timer to be initialized automatically at startup. The Task Watchdog timer can be initialized after startup as well (see Task Watchdog Timer API Reference)

Found in
Component config > ESP32-specific
CONFIG_TASK_WDT_PANIC

Invoke panic handler on Task Watchdog timeout

If this option is enabled, the Task Watchdog Timer will be configured to trigger the panic handler when it times out. This can also be configured at run time (see Task Watchdog Timer API Reference)

Found in
Component config > ESP32-specific
CONFIG_TASK_WDT_TIMEOUT_S

Task Watchdog timeout period (seconds)

Timeout period configuration for the Task Watchdog Timer in seconds. This is also configurable at run time (see Task Watchdog Timer API Reference)

Found in
Component config > ESP32-specific
CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU0

Watch CPU0 Idle Task

If this option is enabled, the Task Watchdog Timer will watch the CPU0 Idle Task. Having the Task Watchdog watch the Idle Task allows for detection of CPU starvation as the Idle Task not being called is usually a symptom of CPU starvation. Starvation of the Idle Task is detrimental as FreeRTOS household tasks depend on the Idle Task getting some runtime every now and then.

Found in
Component config > ESP32-specific
CONFIG_TASK_WDT_CHECK_IDLE_TASK_CPU1

Watch CPU1 Idle Task

If this option is enabled, the Task Wtachdog Timer will wach the CPU1 Idle Task.

Found in
Component config > ESP32-specific
CONFIG_BROWNOUT_DET

Hardware brownout detect & reset

The ESP32 has a built-in brownout detector which can detect if the voltage is lower than a specific value. If this happens, it will reset the chip in order to prevent unintended behaviour.

Found in
Component config > ESP32-specific
CONFIG_BROWNOUT_DET_LVL_SEL

Brownout voltage level

The brownout detector will reset the chip when the supply voltage is approximately below this level. Note that there may be some variation of brownout voltage level between each ESP32 chip.

Found in
Component config > ESP32-specific
Available options:
  • 2.43V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_0)
  • 2.48V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_1)
  • 2.58V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_2)
  • 2.62V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_3)
  • 2.67V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_4)
  • 2.70V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_5)
  • 2.77V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_6)
  • 2.80V +/- 0.05 (CONFIG_BROWNOUT_DET_LVL_SEL_7)
CONFIG_ESP32_TIME_SYSCALL

Timers used for gettimeofday function

This setting defines which hardware timers are used to implement ‘gettimeofday’ and ‘time’ functions in C library.

  • If both high-resolution and RTC timers are used, timekeeping will continue in deep sleep. Time will be reported at 1 microsecond resolution. This is the default, and the recommended option.
  • If only high-resolution timer is used, gettimeofday will provide time at microsecond resolution. Time will not be preserved when going into deep sleep mode.
  • If only RTC timer is used, timekeeping will continue in deep sleep, but time will be measured at 6.(6) microsecond resolution. Also the gettimeofday function itself may take longer to run.
  • If no timers are used, gettimeofday and time functions return -1 and set errno to ENOSYS.
  • When RTC is used for timekeeping, two RTC_STORE registers are used to keep time in deep sleep mode.
Found in
Component config > ESP32-specific
Available options:
  • RTC and high-resolution timer (CONFIG_ESP32_TIME_SYSCALL_USE_RTC_FRC1)
  • RTC (CONFIG_ESP32_TIME_SYSCALL_USE_RTC)
  • High-resolution timer (CONFIG_ESP32_TIME_SYSCALL_USE_FRC1)
  • None (CONFIG_ESP32_TIME_SYSCALL_USE_NONE)
CONFIG_ESP32_RTC_CLOCK_SOURCE

RTC clock source

Choose which clock is used as RTC clock source.

Found in
Component config > ESP32-specific
Available options:
  • Internal 150kHz RC oscillator (CONFIG_ESP32_RTC_CLOCK_SOURCE_INTERNAL_RC)
  • External 32kHz crystal (CONFIG_ESP32_RTC_CLOCK_SOURCE_EXTERNAL_CRYSTAL)
CONFIG_ESP32_RTC_EXTERNAL_CRYSTAL_ADDITIONAL_CURRENT

Additional current for external 32kHz crystal

Choose which additional current is used for rtc external crystal.

  • With some 32kHz crystal configurations, the X32N and X32P pins may not have enough drive strength to keep the crystal oscillating during deep sleep. If this option is enabled, additional current from touchpad 9 is provided internally to drive the 32kHz crystal. If this option is enabled, deep sleep current is slightly higher (4-5uA) and the touchpad and ULP wakeup sources are not available.
Found in
Component config > ESP32-specific
CONFIG_ESP32_RTC_CLK_CAL_CYCLES

Number of cycles for RTC_SLOW_CLK calibration

When the startup code initializes RTC_SLOW_CLK, it can perform calibration by comparing the RTC_SLOW_CLK frequency with main XTAL frequency. This option sets the number of RTC_SLOW_CLK cycles measured by the calibration routine. Higher numbers increase calibration precision, which may be important for applications which spend a lot of time in deep sleep. Lower numbers reduce startup time.

When this option is set to 0, clock calibration will not be performed at startup, and approximate clock frequencies will be assumed:

  • 150000 Hz if internal RC oscillator is used as clock source. For this use value 1024.
  • 32768 Hz if the 32k crystal oscillator is used. For this use value 3000 or more. In case more value will help improve the definition of the launch of the crystal. If the crystal could not start, it will be switched to internal RC.
Found in
Component config > ESP32-specific
CONFIG_ESP32_RTC_XTAL_BOOTSTRAP_CYCLES

Bootstrap cycles for external 32kHz crystal

To reduce the startup time of an external RTC crystal, we bootstrap it with a 32kHz square wave for a fixed number of cycles. Setting 0 will disable bootstrapping (if disabled, the crystal may take longer to start up or fail to oscillate under some conditions).

If this value is too high, a faulty crystal may initially start and then fail. If this value is too low, an otherwise good crystal may not start.

To accurately determine if the crystal has started, set a larger “Number of cycles for RTC_SLOW_CLK calibration” (about 3000).

Found in
Component config > ESP32-specific
CONFIG_ESP32_DEEP_SLEEP_WAKEUP_DELAY

Extra delay in deep sleep wake stub (in us)

When ESP32 exits deep sleep, the CPU and the flash chip are powered on at the same time. CPU will run deep sleep stub first, and then proceed to load code from flash. Some flash chips need sufficient time to pass between power on and first read operation. By default, without any extra delay, this time is approximately 900us, although some flash chip types need more than that.

By default extra delay is set to 2000us. When optimizing startup time for applications which require it, this value may be reduced.

If you are seeing “flash read err, 1000” message printed to the console after deep sleep reset, try increasing this value.

Found in
Component config > ESP32-specific
CONFIG_ESP32_XTAL_FREQ_SEL

Main XTAL frequency

ESP32 currently supports the following XTAL frequencies:

  • 26 MHz
  • 40 MHz

Startup code can automatically estimate XTAL frequency. This feature uses the internal 8MHz oscillator as a reference. Because the internal oscillator frequency is temperature dependent, it is not recommended to use automatic XTAL frequency detection in applications which need to work at high ambient temperatures and use high-temperature qualified chips and modules.

Found in
Component config > ESP32-specific
Available options:
  • 40 MHz (CONFIG_ESP32_XTAL_FREQ_40)
  • 26 MHz (CONFIG_ESP32_XTAL_FREQ_26)
  • Autodetect (CONFIG_ESP32_XTAL_FREQ_AUTO)
CONFIG_DISABLE_BASIC_ROM_CONSOLE

Permanently disable BASIC ROM Console

If set, the first time the app boots it will disable the BASIC ROM Console permanently (by burning an efuse).

Otherwise, the BASIC ROM Console starts on reset if no valid bootloader is read from the flash.

(Enabling secure boot also disables the BASIC ROM Console by default.)

Found in
Component config > ESP32-specific
CONFIG_NO_BLOBS

No Binary Blobs

If enabled, this disables the linking of binary libraries in the application build. Note that after enabling this Wi-Fi/Bluetooth will not work.

Found in
Component config > ESP32-specific
CONFIG_ESP_TIMER_PROFILING

Enable esp_timer profiling features

If enabled, esp_timer_dump will dump information such as number of times the timer was started, number of times the timer has triggered, and the total time it took for the callback to run. This option has some effect on timer performance and the amount of memory used for timer storage, and should only be used for debugging/testing purposes.

Found in
Component config > ESP32-specific
CONFIG_COMPATIBLE_PRE_V2_1_BOOTLOADERS

App compatible with bootloaders before IDF v2.1

Bootloaders before IDF v2.1 did less initialisation of the system clock. This setting needs to be enabled to build an app which can be booted by these older bootloaders.

If this setting is enabled, the app can be booted by any bootloader from IDF v1.0 up to the current version.

If this setting is disabled, the app can only be booted by bootloaders from IDF v2.1 or newer.

Enabling this setting adds approximately 1KB to the app’s IRAM usage.

Found in
Component config > ESP32-specific
CONFIG_ESP_ERR_TO_NAME_LOOKUP

Enable lookup of error code strings

Functions esp_err_to_name() and esp_err_to_name_r() return string representations of error codes from a pre-generated lookup table. This option can be used to turn off the use of the look-up table in order to save memory but this comes at the price of sacrificing distinguishable (meaningful) output string representations.

Found in
Component config > ESP32-specific

Wi-Fi

CONFIG_SW_COEXIST_ENABLE

Software controls WiFi/Bluetooth coexistence

If enabled, WiFi & Bluetooth coexistence is controlled by software rather than hardware. Recommended for heavy traffic scenarios. Both coexistence configuration options are automatically managed, no user intervention is required.

Found in
Component config > Wi-Fi
CONFIG_SW_COEXIST_PREFERENCE

WiFi/Bluetooth coexistence performance preference

Choose Bluetooth/WiFi/Balance for different preference. If choose WiFi, it will make WiFi performance better. Such, keep WiFi Audio more fluent. If choose Bluetooth, it will make Bluetooth performance better. Such, keep Bluetooth(A2DP) Audio more fluent. If choose Balance, the performance of WiFi and bluetooth will be balance. It’s default. Normally, just choose balance, the A2DP audio can play fluently, too. Except config preference in menuconfig, you can also call esp_coex_preference_set() dynamically.

Found in
Component config > Wi-Fi
Available options:
  • WiFi (CONFIG_SW_COEXIST_PREFERENCE_WIFI)
  • Bluetooth(include BR/EDR and BLE) (CONFIG_SW_COEXIST_PREFERENCE_BT)
  • Balance (CONFIG_SW_COEXIST_PREFERENCE_BALANCE)
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM

Max number of WiFi static RX buffers

Set the number of WiFi static RX buffers. Each buffer takes approximately 1.6KB of RAM. The static rx buffers are allocated when esp_wifi_init is called, they are not freed until esp_wifi_deinit is called.

WiFi hardware use these buffers to receive all 802.11 frames. A higher number may allow higher throughput but increases memory use. If ESP32_WIFI_AMPDU_RX_ENABLED is enabled, this value is recommended to set equal or bigger than ESP32_WIFI_RX_BA_WIN in order to achieve better throughput and compatibility with both stations and APs.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM

Max number of WiFi dynamic RX buffers

Set the number of WiFi dynamic RX buffers, 0 means unlimited RX buffers will be allocated (provided sufficient free RAM). The size of each dynamic RX buffer depends on the size of the received data frame.

For each received data frame, the WiFi driver makes a copy to an RX buffer and then delivers it to the high layer TCP/IP stack. The dynamic RX buffer is freed after the higher layer has successfully received the data frame.

For some applications, WiFi data frames may be received faster than the application can process them. In these cases we may run out of memory if RX buffer number is unlimited (0).

If a dynamic RX buffer limit is set, it should be at least the number of static RX buffers.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_TX_BUFFER

Type of WiFi TX buffers

Select type of WiFi TX buffers:

If “Static” is selected, WiFi TX buffers are allocated when WiFi is initialized and released when WiFi is de-initialized. The size of each static TX buffer is fixed to about 1.6KB.

If “Dynamic” is selected, each WiFi TX buffer is allocated as needed when a data frame is delivered to the Wifi driver from the TCP/IP stack. The buffer is freed after the data frame has been sent by the WiFi driver. The size of each dynamic TX buffer depends on the length of each data frame sent by the TCP/IP layer.

If PSRAM is enabled, “Static” should be selected to guarantee enough WiFi TX buffers. If PSRAM is disabled, “Dynamic” should be selected to improve the utilization of RAM.

Found in
Component config > Wi-Fi
Available options:
  • Static (CONFIG_ESP32_WIFI_STATIC_TX_BUFFER)
  • Dynamic (CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER)
CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM

Max number of WiFi static TX buffers

Set the number of WiFi static TX buffers. Each buffer takes approximately 1.6KB of RAM. The static RX buffers are allocated when esp_wifi_init() is called, they are not released until esp_wifi_deinit() is called.

For each transmitted data frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM

Max number of WiFi dynamic TX buffers

Set the number of WiFi dynamic TX buffers. The size of each dynamic TX buffer is not fixed, it depends on the size of each transmitted data frame.

For each transmitted frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications, especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_CSI_ENABLED

WiFi CSI(Channel State Information)

Select this option to enable CSI(Channel State Information) feature. CSI takes about CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM KB of RAM. If CSI is not used, it is better to disable this feature in order to save memory.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED

WiFi AMPDU TX

Select this option to enable AMPDU TX feature

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_TX_BA_WIN

WiFi AMPDU TX BA window size

Set the size of WiFi Block Ack TX window. Generally a bigger value means higher throughput but more memory. Most of time we should NOT change the default value unless special reason, e.g. test the maximum UDP TX throughput with iperf etc. For iperf test in shieldbox, the recommended value is 9~12.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED

WiFi AMPDU RX

Select this option to enable AMPDU RX feature

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_RX_BA_WIN

WiFi AMPDU RX BA window size

Set the size of WiFi Block Ack RX window. Generally a bigger value means higher throughput and better compatibility but more memory. Most of time we should NOT change the default value unless special reason, e.g. test the maximum UDP RX throughput with iperf etc. For iperf test in shieldbox, the recommended value is 9~12. If PSRAM is used and WiFi memory is prefered to allocat in PSRAM first, the default and minimum value should be 16 to achieve better throughput and compatibility with both stations and APs.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_NVS_ENABLED

WiFi NVS flash

Select this option to enable WiFi NVS flash

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_TASK_CORE_ID

WiFi Task Core ID

Pinned WiFi task to core 0 or core 1.

Found in
Component config > Wi-Fi
Available options:
  • Core 0 (CONFIG_ESP32_WIFI_TASK_PINNED_TO_CORE_0)
  • Core 1 (CONFIG_ESP32_WIFI_TASK_PINNED_TO_CORE_1)
CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN

Max length of WiFi SoftAP Beacon

ESP-MESH utilizes beacon frames to detect and resolve root node conflicts (see documentation). However the default length of a beacon frame can simultaneously hold only five root node identifier structures, meaning that a root node conflict of up to five nodes can be detected at one time. In the occurence of more root nodes conflict involving more than five root nodes, the conflict resolution process will detect five of the root nodes, resolve the conflict, and re-detect more root nodes. This process will repeat until all root node conflicts are resolved. However this process can generally take a very long time.

To counter this situation, the beacon frame length can be increased such that more root nodes can be detected simultaneously. Each additional root node will require 36 bytes and should be added ontop of the default beacon frame length of 752 bytes. For example, if you want to detect 10 root nodes simultaneously, you need to set the beacon frame length as 932 (752+36*5).

Setting a longer beacon length also assists with debugging as the conflicting root nodes can be identified more quickly.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_IRAM_OPT

WiFi IRAM speed optimization

Select this option to place frequently called Wi-Fi library functions in IRAM. When this option is disabled, more than 10Kbytes of IRAM memory will be saved but Wi-Fi throughput will be reduced.

Found in
Component config > Wi-Fi
CONFIG_ESP32_WIFI_MGMT_SBUF_NUM

WiFi mgmt short buffer number

Set the number of WiFi management short buffer.

Found in
Component config > Wi-Fi

PHY

CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE

Store phy calibration data in NVS

If this option is enabled, NVS will be initialized and calibration data will be loaded from there. PHY calibration will be skipped on deep sleep wakeup. If calibration data is not found, full calibration will be performed and stored in NVS. Normally, only partial calibration will be performed. If this option is disabled, full calibration will be performed.

If it’s easy that your board calibrate bad data, choose ‘n’. Two cases for example, you should choose ‘n’: 1.If your board is easy to be booted up with antenna disconnected. 2.Because of your board design, each time when you do calibration, the result are too unstable. If unsure, choose ‘y’.

Found in
Component config > PHY
CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION

Use a partition to store PHY init data

If enabled, PHY init data will be loaded from a partition. When using a custom partition table, make sure that PHY data partition is included (type: ‘data’, subtype: ‘phy’). With default partition tables, this is done automatically. If PHY init data is stored in a partition, it has to be flashed there, otherwise runtime error will occur.

If this option is not enabled, PHY init data will be embedded into the application binary.

If unsure, choose ‘n’.

Found in
Component config > PHY
CONFIG_ESP32_PHY_MAX_WIFI_TX_POWER

Max WiFi TX power (dBm)

Set maximum transmit power for WiFi radio. Actual transmit power for high data rates may be lower than this setting.

Found in
Component config > PHY
CONFIG_ESP32_DPORT_DIS_INTERRUPT_LVL

Disable the interrupt level for the DPORT workarounds

To prevent interrupting DPORT workarounds, need to disable interrupt with a maximum used level in the system.

Found in
Component config

Power Management

CONFIG_PM_ENABLE

Support for power management

If enabled, application is compiled with support for power management. This option has run-time overhead (increased interrupt latency, longer time to enter idle state), and it also reduces accuracy of RTOS ticks and timers used for timekeeping. Enable this option if application uses power management APIs.

Found in
Component config > Power Management
CONFIG_PM_DFS_INIT_AUTO

Enable dynamic frequency scaling (DFS) at startup

If enabled, startup code configures dynamic frequency scaling. Max CPU frequency is set to CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ setting, min frequency is set to XTAL frequency. If disabled, DFS will not be active until the application configures it using esp_pm_configure function.

Found in
Component config > Power Management
CONFIG_PM_USE_RTC_TIMER_REF

Use RTC timer to prevent time drift (EXPERIMENTAL)

When APB clock frequency changes, high-resolution timer (esp_timer) scale and base value need to be adjusted. Each adjustment may cause small error, and over time such small errors may cause time drift. If this option is enabled, RTC timer will be used as a reference to compensate for the drift. It is recommended that this option is only used if 32k XTAL is selected as RTC clock source.

Found in
Component config > Power Management
CONFIG_PM_PROFILING

Enable profiling counters for PM locks

If enabled, esp_pm_* functions will keep track of the amount of time each of the power management locks has been held, and esp_pm_dump_locks function will print this information. This feature can be used to analyze which locks are preventing the chip from going into a lower power state, and see what time the chip spends in each power saving mode. This feature does incur some run-time overhead, so should typically be disabled in production builds.

Found in
Component config > Power Management
CONFIG_PM_TRACE

Enable debug tracing of PM using GPIOs

If enabled, some GPIOs will be used to signal events such as RTOS ticks, frequency switching, entry/exit from idle state. Refer to pm_trace.c file for the list of GPIOs. This feature is intended to be used when analyzing/debugging behavior of power management implementation, and should be kept disabled in applications.

Found in
Component config > Power Management

Log output

CONFIG_LOG_DEFAULT_LEVEL

Default log verbosity

Specify how much output to see in logs by default. You can set lower verbosity level at runtime using esp_log_level_set function.

Note that this setting limits which log statements are compiled into the program. So setting this to, say, “Warning” would mean that changing log level to “Debug” at runtime will not be possible.

Found in
Component config > Log output
Available options:
  • No output (CONFIG_LOG_DEFAULT_LEVEL_NONE)
  • Error (CONFIG_LOG_DEFAULT_LEVEL_ERROR)
  • Warning (CONFIG_LOG_DEFAULT_LEVEL_WARN)
  • Info (CONFIG_LOG_DEFAULT_LEVEL_INFO)
  • Debug (CONFIG_LOG_DEFAULT_LEVEL_DEBUG)
  • Verbose (CONFIG_LOG_DEFAULT_LEVEL_VERBOSE)
CONFIG_LOG_COLORS

Use ANSI terminal colors in log output

Enable ANSI terminal color codes in bootloader output.

In order to view these, your terminal program must support ANSI color codes.

Found in
Component config > Log output

PThreads

CONFIG_ESP32_PTHREAD_TASK_PRIO_DEFAULT

Default task priority

Priority used to create new tasks with default pthread parameters.

Found in
Component config > PThreads
CONFIG_ESP32_PTHREAD_TASK_STACK_SIZE_DEFAULT

Default task stack size

Stack size used to create new tasks with default pthread parameters.

Found in
Component config > PThreads

Application Level Tracing

CONFIG_ESP32_APPTRACE_DESTINATION

Data Destination

Select destination for application trace: trace memory or none (to disable).

Found in
Component config > Application Level Tracing
Available options:
  • Trace memory (CONFIG_ESP32_APPTRACE_DEST_TRAX)
  • None (CONFIG_ESP32_APPTRACE_DEST_NONE)
CONFIG_ESP32_APPTRACE_ONPANIC_HOST_FLUSH_TMO

Timeout for flushing last trace data to host on panic

Timeout for flushing last trace data to host in case of panic. In ms. Use -1 to disable timeout and wait forever.

Found in
Component config > Application Level Tracing
CONFIG_ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_THRESH

Threshold for flushing last trace data to host on panic

Threshold for flushing last trace data to host on panic in post-mortem mode. This is minimal amount of data needed to perform flush. In bytes.

Found in
Component config > Application Level Tracing
CONFIG_ESP32_APPTRACE_PENDING_DATA_SIZE_MAX

Size of the pending data buffer

Size of the buffer for events in bytes. It is useful for buffering events from the time critical code (scheduler, ISRs etc). If this parameter is 0 then events will be discarded when main HW buffer is full.

Found in
Component config > Application Level Tracing

FreeRTOS SystemView Tracing

CONFIG_SYSVIEW_ENABLE

SystemView Tracing Enable

Enables supporrt for SEGGER SystemView tracing functionality.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_TS_SOURCE

Timer to use as timestamp source

SystemView needs to use a hardware timer as the source of timestamps when tracing. This option selects the timer for it.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Available options:
  • CPU cycle counter (CCOUNT) (CONFIG_SYSVIEW_TS_SOURCE_CCOUNT)
  • Timer 0, Group 0 (CONFIG_SYSVIEW_TS_SOURCE_TIMER_00)
  • Timer 1, Group 0 (CONFIG_SYSVIEW_TS_SOURCE_TIMER_01)
  • Timer 0, Group 1 (CONFIG_SYSVIEW_TS_SOURCE_TIMER_10)
  • Timer 1, Group 1 (CONFIG_SYSVIEW_TS_SOURCE_TIMER_11)
  • esp_timer high resolution timer (CONFIG_SYSVIEW_TS_SOURCE_ESP_TIMER)
CONFIG_SYSVIEW_EVT_OVERFLOW_ENABLE

Trace Buffer Overflow Event

Enables “Trace Buffer Overflow” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_ISR_ENTER_ENABLE

ISR Enter Event

Enables “ISR Enter” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_ISR_EXIT_ENABLE

ISR Exit Event

Enables “ISR Exit” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_ISR_TO_SCHEDULER_ENABLE

ISR Exit to Scheduler Event

Enables “ISR to Scheduler” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_START_EXEC_ENABLE

Task Start Execution Event

Enables “Task Start Execution” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_STOP_EXEC_ENABLE

Task Stop Execution Event

Enables “Task Stop Execution” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_START_READY_ENABLE

Task Start Ready State Event

Enables “Task Start Ready State” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_STOP_READY_ENABLE

Task Stop Ready State Event

Enables “Task Stop Ready State” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_CREATE_ENABLE

Task Create Event

Enables “Task Create” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TASK_TERMINATE_ENABLE

Task Terminate Event

Enables “Task Terminate” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_IDLE_ENABLE

System Idle Event

Enables “System Idle” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TIMER_ENTER_ENABLE

Timer Enter Event

Enables “Timer Enter” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_SYSVIEW_EVT_TIMER_EXIT_ENABLE

Timer Exit Event

Enables “Timer Exit” event.

Found in
Component config > Application Level Tracing > FreeRTOS SystemView Tracing
CONFIG_ESP32_GCOV_ENABLE

GCOV to Host Enable

Enables support for GCOV data transfer to host.

Found in
Component config > Application Level Tracing

Ethernet

CONFIG_DMA_RX_BUF_NUM

Number of DMA RX buffers

Number of DMA receive buffers. Each buffer is 1600 bytes. Buffers are allocated statically. Larger number of buffers increases throughput. If enable flow ctrl, the num must be above 9 .

Found in
Component config > Ethernet
CONFIG_DMA_TX_BUF_NUM

Number of DMA TX buffers

Number of DMA transmit buffers. Each buffer is 1600 bytes. Buffers are allocated statically. Larger number of buffers increases throughput.

Found in
Component config > Ethernet
CONFIG_EMAC_L2_TO_L3_RX_BUF_MODE

Enable copy between Layer2 and Layer3

If this options is selected, a copy of each received buffer will be created when passing it from the Ethernet MAC (L2) to the IP stack (L3). Otherwise, IP stack will receive pointers to the DMA buffers used by Ethernet MAC.

When Ethernet MAC doesn’t have any unused buffers left, it will drop incomming packets (flow control may help with this problem, to some extent).

The buffers for the IP stack are allocated from the heap, so the total number of receive buffers is limited by the available heap size, if this option is selected.

If unsure, choose n.

Found in
Component config > Ethernet
CONFIG_EMAC_TASK_PRIORITY

EMAC_TASK_PRIORITY

Ethernet MAC task priority.

Found in
Component config > Ethernet
CONFIG_EMAC_TASK_STACK_SIZE

Stack Size of EMAC Task

Stack Size of Ethernet MAC task.

Found in
Component config > Ethernet

OpenSSL

CONFIG_OPENSSL_DEBUG

Enable OpenSSL debugging

Enable OpenSSL debugging function.

If the option is enabled, “SSL_DEBUG” works.

Found in
Component config > OpenSSL
CONFIG_OPENSSL_DEBUG_LEVEL

OpenSSL debugging level

OpenSSL debugging level.

Only function whose debugging level is higher than “OPENSSL_DEBUG_LEVEL” works.

For example:
If OPENSSL_DEBUG_LEVEL = 2, you use function “SSL_DEBUG(1, “malloc failed”)”. Because 1 < 2, it will not print.
Found in
Component config > OpenSSL
CONFIG_OPENSSL_LOWLEVEL_DEBUG

Enable OpenSSL low-level module debugging

If the option is enabled, low-level module debugging function of OpenSSL is enabled, e.g. mbedtls internal debugging function.

Found in
Component config > OpenSSL
CONFIG_OPENSSL_ASSERT

Select OpenSSL assert function

OpenSSL function needs “assert” function to check if input parameters are valid.

If you want to use assert debugging function, “OPENSSL_DEBUG” should be enabled.

Found in
Component config > OpenSSL
Available options:

  • Do nothing (CONFIG_OPENSSL_ASSERT_DO_NOTHING)

    Do nothing and “SSL_ASSERT” does not work.

  • Check and exit (CONFIG_OPENSSL_ASSERT_EXIT)

    Enable assert exiting, it will check and return error code.

  • Show debugging message (CONFIG_OPENSSL_ASSERT_DEBUG)

    Enable assert debugging, it will check and show debugging message.

  • Show debugging message and exit (CONFIG_OPENSSL_ASSERT_DEBUG_EXIT)

    Enable assert debugging and exiting, it will check, show debugging message and return error code.

  • Show debugging message and block (CONFIG_OPENSSL_ASSERT_DEBUG_BLOCK)

    Enable assert debugging and blocking, it will check, show debugging message and block by “while (1);”.

NVS

CONFIG_MP_BLOB_SUPPORT

Enable multi-page blob support

When enabled, blobs larger than the sector size are split and stored on multiple sectors. This removes the earlier limitation of 1984 bytes for storing data-blobs.

Found in
Component config > NVS
CONFIG_NVS_ENCRYPTION

Enable NVS encryption

This option enables encryption for NVS. When enabled, AES-XTS is used to encrypt the complete NVS data, except the page headers. It requires XTS encryption keys to be stored in an encrypted partition. This means enabling flash encryption is a pre-requisite for this feature.

Found in
Component config > NVS

Driver configurations

ADC configuration

CONFIG_ADC_FORCE_XPD_FSM

Use the FSM to control ADC power

ADC power can be controlled by the FSM instead of software. This allows the ADC to be shut off when it is not working leading to lower power consumption. However using the FSM control ADC power will increase the noise of ADC.

Found in
Component config > Driver configurations > ADC configuration
CONFIG_ADC2_DISABLE_DAC

Disable DAC when ADC2 is used on GPIO 25 and 26

If this is set, the ADC2 driver will disables the output of the DAC corresponding to the specified channel. This is the default value.

For testing, disable this option so that we can measure the output of DAC by internal ADC.

Found in
Component config > Driver configurations > ADC configuration

SPI master configuration

CONFIG_SPI_MASTER_IN_IRAM

Place transmitting functions of SPI master into IRAM

Normally only the ISR of SPI master is placed in the IRAM, so that it can work without the flash when interrupt is triggered. For other functions, there’s some possibility that the flash cache miss when running inside and out of SPI functions, which may increase the interval of SPI transactions. Enable this to put queue\_trans, get\_trans\_result and transmit functions into the IRAM to avoid possible cache miss.

During unit test, this is enabled to measure the ideal case of api.

Found in
Component config > Driver configurations > SPI master configuration
CONFIG_SPI_MASTER_ISR_IN_IRAM

Place SPI master ISR function into IRAM

Place the SPI master ISR in to IRAM to avoid possible cache miss.

Also you can forbid the ISR being disabled during flash writing access, by add ESP_INTR_FLAG_IRAM when initializing the driver.

Found in
Component config > Driver configurations > SPI master configuration
CONFIG_AWS_IOT_SDK

Amazon Web Services IoT Platform

Amazon Web Services IoT Platform

Select this option to enable support for the AWS IoT platform, via the esp-idf component for the AWS IoT Device C SDK.

CONFIG_AWS_IOT_MQTT_HOST

AWS IoT Endpoint Hostname

Default endpoint host name to connect to AWS IoT MQTT/S gateway

This is the custom endpoint hostname and is specific to an AWS IoT account. You can find it by logging into your AWS IoT Console and clicking the Settings button. The endpoint hostname is shown under the “Custom Endpoint” heading on this page.

If you need per-device hostnames for different regions or accounts, you can override the default hostname in your app.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_PORT

AWS IoT MQTT Port

Default port number to connect to AWS IoT MQTT/S gateway

If you need per-device port numbers for different regions, you can override the default port number in your app.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_TX_BUF_LEN

MQTT TX Buffer Length

Maximum MQTT transmit buffer size. This is the maximum MQTT message length (including protocol overhead) which can be sent.

Sending longer messages will fail.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_RX_BUF_LEN

MQTT RX Buffer Length

Maximum MQTT receive buffer size. This is the maximum MQTT message length (including protocol overhead) which can be received.

Longer messages are dropped.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS

Maximum MQTT Topic Filters

Maximum number of concurrent MQTT topic filters.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_MIN_RECONNECT_WAIT_INTERVAL

Auto reconnect initial interval (ms)

Initial delay before making first reconnect attempt, if the AWS IoT connection fails. Client will perform exponential backoff, starting from this value.

Found in
Component config > Amazon Web Services IoT Platform
CONFIG_AWS_IOT_MQTT_MAX_RECONNECT_WAIT_INTERVAL

Auto reconnect maximum interval (ms)

Maximum delay between reconnection attempts. If the exponentially increased delay interval reaches this value, the client will stop automatically attempting to reconnect.

Found in
Component config > Amazon Web Services IoT Platform

Thing Shadow

CONFIG_AWS_IOT_OVERRIDE_THING_SHADOW_RX_BUFFER

Override Shadow RX buffer size

Allows setting a different Thing Shadow RX buffer size. This is the maximum size of a Thing Shadow message in bytes, plus one.

If not overridden, the default value is the MQTT RX Buffer length plus one. If overriden, do not set higher than the default value.

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SIZE_OF_RX_BUFFER

Maximum RX Buffer (bytes)

Allows setting a different Thing Shadow RX buffer size. This is the maximum size of a Thing Shadow message in bytes, plus one.

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SIZE_OF_UNIQUE_CLIENT_ID_BYTES

Maximum unique client ID size (bytes)

Maximum size of the Unique Client Id.

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SIMULTANEOUS_ACKS

Maximum simultaneous responses

At any given time we will wait for this many responses. This will correlate to the rate at which the shadow actions are requested

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SIMULTANEOUS_THINGNAMES

Maximum simultaneous Thing Name operations

We could perform shadow action on any thing Name and this is maximum Thing Names we can act on at any given time

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_JSON_TOKEN_EXPECTED

Maximum expected JSON tokens

These are the max tokens that is expected to be in the Shadow JSON document. Includes the metadata which is published

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SHADOW_TOPIC_LENGTH_WITHOUT_THINGNAME

Maximum topic length (not including Thing Name)

All shadow actions have to be published or subscribed to a topic which is of the format $aws/things/{thingName}/shadow/update/accepted. This refers to the size of the topic without the Thing Name

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow
CONFIG_AWS_IOT_SHADOW_MAX_SIZE_OF_THING_NAME

Maximum Thing Name length

Maximum length of a Thing Name.

Found in
Component config > Amazon Web Services IoT Platform > Thing Shadow

Bluetooth

CONFIG_BT_ENABLED

Bluetooth

Select this option to enable Bluetooth and show the submenu with Bluetooth configuration choices.

Found in
Component config > Bluetooth
CONFIG_BTDM_CONTROLLER_BR_EDR_SCO_DATA_PATH

BR/EDR Sync(SCO/eSCO) default data path

SCO data path, i.e. HCI or PCM. SCO data can be sent/received through HCI synchronous packets, or the data can be routed to on-chip PCM module on ESP32. PCM input/output signals can be “matrixed” to GPIOs. The default data path can also be set using API “esp_bredr_sco_datapath_set”

Found in
Component config > Bluetooth
Available options:
  • HCI (CONFIG_BTDM_CONTROLLER_BR_EDR_SCO_DATA_PATH_HCI)
  • PCM (CONFIG_BTDM_CONTROLLER_BR_EDR_SCO_DATA_PATH_PCM)
CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_CHOICE

The cpu core which bluetooth controller run

Specify the cpu core to run bluetooth controller. Can not specify no-affinity.

Found in
Component config > Bluetooth
Available options:
  • Core 0 (PRO CPU) (CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_0)
  • Core 1 (APP CPU) (CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_1)
CONFIG_BTDM_CONTROLLER_HCI_MODE_CHOICE

HCI mode

Speicify HCI mode as VHCI or UART(H4)

Found in
Component config > Bluetooth
Available options:

  • VHCI (CONFIG_BTDM_CONTROLLER_HCI_MODE_VHCI)

    Normal option. Mostly, choose this VHCI when bluetooth host run on ESP32, too.

  • UART(H4) (CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4)

    If use external bluetooth host which run on other hardware and use UART as the HCI interface, choose this option.

HCI UART(H4) Options

CONFIG_BT_HCI_UART_NO

UART Number for HCI

Uart number for HCI. The available uart is UART1 and UART2.

Found in
Component config > Bluetooth > HCI UART(H4) Options
CONFIG_BT_HCI_UART_BAUDRATE

UART Baudrate for HCI

UART Baudrate for HCI. Please use standard baudrate.

Found in
Component config > Bluetooth > HCI UART(H4) Options

MODEM SLEEP Options

CONFIG_BTDM_CONTROLLER_MODEM_SLEEP

Bluetooth modem sleep

Enable/disable bluetooth controller low power mode.

Found in
Component config > Bluetooth > MODEM SLEEP Options
CONFIG_BTDM_MODEM_SLEEP_MODE

Bluetooth Modem sleep mode

To select which strategy to use for modem sleep

Found in
Component config > Bluetooth > MODEM SLEEP Options
Available options:

  • ORIG Mode(sleep with low power clock) (CONFIG_BTDM_MODEM_SLEEP_MODE_ORIG)

    ORIG mode is a bluetooth sleep mode that can be used for dual mode controller. In this mode, bluetooth controller sleeps between BR/EDR frames and BLE events. A low power clock is used to maintain bluetooth reference clock.

  • EVED Mode(For internal test only) (CONFIG_BTDM_MODEM_SLEEP_MODE_EVED)

    EVED mode is for BLE only and is only for internal test. Do not use it for production. this mode is not compatible with DFS nor light sleep

CONFIG_BTDM_LOW_POWER_CLOCK

Bluetooth low power clock

Select the low power clock source for bluetooth controller

Found in
Component config > Bluetooth > MODEM SLEEP Options
Available options:

  • Main crystal (CONFIG_BTDM_LPCLK_SEL_MAIN_XTAL)

    Main crystal can be used as low power clock for bluetooth modem sleep. If this option is selected, bluetooth modem sleep can work under Dynamic Frequency Scaling(DFS) enabled, but cannot work when light sleep is enabled. Main crystal has a relatively better performance than other bluetooth low power clock sources.

  • External 32kHz crystal (CONFIG_BTDM_LPCLK_SEL_EXT_32K_XTAL)

CONFIG_BLUEDROID_ENABLED

Bluedroid Enable

CONFIG_BLUEDROID_PINNED_TO_CORE_CHOICE

The cpu core which Bluedroid run

Which the cpu core to run Bluedroid. Can choose core0 and core1. Can not specify no-affinity.

Found in
Component config > Bluetooth > Bluedroid Enable
Available options:
  • Core 0 (PRO CPU) (CONFIG_BLUEDROID_PINNED_TO_CORE_0)
  • Core 1 (APP CPU) (CONFIG_BLUEDROID_PINNED_TO_CORE_1)
CONFIG_BTC_TASK_STACK_SIZE

Bluetooth event (callback to application) task stack size

This select btc task stack size

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLUEDROID_MEM_DEBUG

Bluedroid memory debug

Bluedroid memory debug

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_CLASSIC_BT_ENABLED

Classic Bluetooth

For now this option needs “SMP_ENABLE” to be set to yes

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_A2DP_ENABLE

A2DP

Advanced Audio Distrubution Profile

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_A2DP_SINK_TASK_STACK_SIZE

A2DP sink (audio stream decoding) task stack size

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_A2DP_SOURCE_TASK_STACK_SIZE

A2DP source (audio stream encoding) task stack size

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BT_SPP_ENABLED

SPP

This enables the Serial Port Profile

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_HFP_ENABLE

Hands Free/Handset Profile

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_HFP_ROLE

Hands-free Profile Role configuration

Found in
Component config > Bluetooth > Bluedroid Enable
Available options:
  • Hands Free Unit (CONFIG_HFP_CLIENT_ENABLE)
CONFIG_HFP_AUDIO_DATA_PATH

audio(SCO) data path

SCO data path, i.e. HCI or PCM. This option is set using API “esp_bredr_sco_datapath_set” in Bluetooth host. Default SCO data path can also be set in Bluetooth Controller.

Found in
Component config > Bluetooth > Bluedroid Enable
Available options:
  • PCM (CONFIG_HFP_AUDIO_DATA_PATH_PCM)
  • HCI (CONFIG_HFP_AUDIO_DATA_PATH_HCI)
CONFIG_GATTS_ENABLE

Include GATT server module(GATTS)

This option can be disabled when the app work only on gatt client mode

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_GATTC_ENABLE

Include GATT client module(GATTC)

This option can be close when the app work only on gatt server mode

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_GATTC_CACHE_NVS_FLASH

Save gattc cache data to nvs flash

This select can save gattc cache data to nvs flash

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_SMP_ENABLE

Include BLE security module(SMP)

This option can be close when the app not used the ble security connect.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_SMP_SLAVE_CON_PARAMS_UPD_ENABLE

Slave enable connection parameters update during pairing

In order to reduce the pairing time, slave actively initiates connection parameters update during pairing.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BT_STACK_NO_LOG

Disable BT debug logs (minimize bin size)

This select can save the rodata code size

Found in
Component config > Bluetooth > Bluedroid Enable
BT DEBUG LOG LEVEL
CONFIG_HCI_INITIAL_TRACE_LEVEL

HCI layer

Define BT trace level for HCI layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_HCI_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_HCI_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_HCI_TRACE_LEVEL_WARNING)
  • API (CONFIG_HCI_TRACE_LEVEL_API)
  • EVENT (CONFIG_HCI_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_HCI_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_HCI_TRACE_LEVEL_VERBOSE)
CONFIG_BTM_INITIAL_TRACE_LEVEL

BTM layer

Define BT trace level for BTM layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_BTM_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_BTM_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_BTM_TRACE_LEVEL_WARNING)
  • API (CONFIG_BTM_TRACE_LEVEL_API)
  • EVENT (CONFIG_BTM_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_BTM_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_BTM_TRACE_LEVEL_VERBOSE)
CONFIG_L2CAP_INITIAL_TRACE_LEVEL

L2CAP layer

Define BT trace level for L2CAP layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_L2CAP_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_L2CAP_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_L2CAP_TRACE_LEVEL_WARNING)
  • API (CONFIG_L2CAP_TRACE_LEVEL_API)
  • EVENT (CONFIG_L2CAP_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_L2CAP_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_L2CAP_TRACE_LEVEL_VERBOSE)
CONFIG_RFCOMM_INITIAL_TRACE_LEVEL

RFCOMM layer

Define BT trace level for RFCOMM layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_RFCOMM_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_RFCOMM_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_RFCOMM_TRACE_LEVEL_WARNING)
  • API (CONFIG_RFCOMM_TRACE_LEVEL_API)
  • EVENT (CONFIG_RFCOMM_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_RFCOMM_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_RFCOMM_TRACE_LEVEL_VERBOSE)
CONFIG_SDP_INITIAL_TRACE_LEVEL

SDP layer

Define BT trace level for SDP layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_SDP_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_SDP_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_SDP_TRACE_LEVEL_WARNING)
  • API (CONFIG_SDP_TRACE_LEVEL_API)
  • EVENT (CONFIG_SDP_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_SDP_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_SDP_TRACE_LEVEL_VERBOSE)
CONFIG_GAP_INITIAL_TRACE_LEVEL

GAP layer

Define BT trace level for GAP layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_GAP_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_GAP_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_GAP_TRACE_LEVEL_WARNING)
  • API (CONFIG_GAP_TRACE_LEVEL_API)
  • EVENT (CONFIG_GAP_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_GAP_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_GAP_TRACE_LEVEL_VERBOSE)
CONFIG_BNEP_INITIAL_TRACE_LEVEL

BNEP layer

Define BT trace level for BNEP layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_BNEP_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_BNEP_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_BNEP_TRACE_LEVEL_WARNING)
  • API (CONFIG_BNEP_TRACE_LEVEL_API)
  • EVENT (CONFIG_BNEP_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_BNEP_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_BNEP_TRACE_LEVEL_VERBOSE)
CONFIG_PAN_INITIAL_TRACE_LEVEL

PAN layer

Define BT trace level for PAN layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_PAN_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_PAN_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_PAN_TRACE_LEVEL_WARNING)
  • API (CONFIG_PAN_TRACE_LEVEL_API)
  • EVENT (CONFIG_PAN_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_PAN_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_PAN_TRACE_LEVEL_VERBOSE)
CONFIG_A2D_INITIAL_TRACE_LEVEL

A2D layer

Define BT trace level for A2D layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_A2D_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_A2D_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_A2D_TRACE_LEVEL_WARNING)
  • API (CONFIG_A2D_TRACE_LEVEL_API)
  • EVENT (CONFIG_A2D_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_A2D_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_A2D_TRACE_LEVEL_VERBOSE)
CONFIG_AVDT_INITIAL_TRACE_LEVEL

AVDT layer

Define BT trace level for AVDT layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_AVDT_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_AVDT_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_AVDT_TRACE_LEVEL_WARNING)
  • API (CONFIG_AVDT_TRACE_LEVEL_API)
  • EVENT (CONFIG_AVDT_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_AVDT_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_AVDT_TRACE_LEVEL_VERBOSE)
CONFIG_AVCT_INITIAL_TRACE_LEVEL

AVCT layer

Define BT trace level for AVCT layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_AVCT_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_AVCT_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_AVCT_TRACE_LEVEL_WARNING)
  • API (CONFIG_AVCT_TRACE_LEVEL_API)
  • EVENT (CONFIG_AVCT_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_AVCT_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_AVCT_TRACE_LEVEL_VERBOSE)
CONFIG_AVRC_INITIAL_TRACE_LEVEL

AVRC layer

Define BT trace level for AVRC layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_AVRC_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_AVRC_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_AVRC_TRACE_LEVEL_WARNING)
  • API (CONFIG_AVRC_TRACE_LEVEL_API)
  • EVENT (CONFIG_AVRC_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_AVRC_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_AVRC_TRACE_LEVEL_VERBOSE)
CONFIG_MCA_INITIAL_TRACE_LEVEL

MCA layer

Define BT trace level for MCA layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_MCA_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_MCA_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_MCA_TRACE_LEVEL_WARNING)
  • API (CONFIG_MCA_TRACE_LEVEL_API)
  • EVENT (CONFIG_MCA_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_MCA_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_MCA_TRACE_LEVEL_VERBOSE)
CONFIG_HID_INITIAL_TRACE_LEVEL

HID layer

Define BT trace level for HID layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_HID_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_HID_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_HID_TRACE_LEVEL_WARNING)
  • API (CONFIG_HID_TRACE_LEVEL_API)
  • EVENT (CONFIG_HID_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_HID_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_HID_TRACE_LEVEL_VERBOSE)
CONFIG_APPL_INITIAL_TRACE_LEVEL

APPL layer

Define BT trace level for APPL layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_APPL_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_APPL_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_APPL_TRACE_LEVEL_WARNING)
  • API (CONFIG_APPL_TRACE_LEVEL_API)
  • EVENT (CONFIG_APPL_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_APPL_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_APPL_TRACE_LEVEL_VERBOSE)
CONFIG_GATT_INITIAL_TRACE_LEVEL

GATT layer

Define BT trace level for GATT layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_GATT_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_GATT_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_GATT_TRACE_LEVEL_WARNING)
  • API (CONFIG_GATT_TRACE_LEVEL_API)
  • EVENT (CONFIG_GATT_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_GATT_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_GATT_TRACE_LEVEL_VERBOSE)
CONFIG_SMP_INITIAL_TRACE_LEVEL

SMP layer

Define BT trace level for SMP layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_SMP_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_SMP_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_SMP_TRACE_LEVEL_WARNING)
  • API (CONFIG_SMP_TRACE_LEVEL_API)
  • EVENT (CONFIG_SMP_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_SMP_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_SMP_TRACE_LEVEL_VERBOSE)
CONFIG_BTIF_INITIAL_TRACE_LEVEL

BTIF layer

Define BT trace level for BTIF layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_BTIF_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_BTIF_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_BTIF_TRACE_LEVEL_WARNING)
  • API (CONFIG_BTIF_TRACE_LEVEL_API)
  • EVENT (CONFIG_BTIF_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_BTIF_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_BTIF_TRACE_LEVEL_VERBOSE)
CONFIG_BTC_INITIAL_TRACE_LEVEL

BTC layer

Define BT trace level for BTC layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_BTC_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_BTC_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_BTC_TRACE_LEVEL_WARNING)
  • API (CONFIG_BTC_TRACE_LEVEL_API)
  • EVENT (CONFIG_BTC_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_BTC_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_BTC_TRACE_LEVEL_VERBOSE)
CONFIG_OSI_INITIAL_TRACE_LEVEL

OSI layer

Define BT trace level for OSI layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_OSI_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_OSI_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_OSI_TRACE_LEVEL_WARNING)
  • API (CONFIG_OSI_TRACE_LEVEL_API)
  • EVENT (CONFIG_OSI_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_OSI_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_OSI_TRACE_LEVEL_VERBOSE)
CONFIG_BLUFI_INITIAL_TRACE_LEVEL

BLUFI layer

Define BT trace level for BLUFI layer

Found in
Component config > Bluetooth > Bluedroid Enable > BT DEBUG LOG LEVEL
Available options:
  • NONE (CONFIG_BLUFI_TRACE_LEVEL_NONE)
  • ERROR (CONFIG_BLUFI_TRACE_LEVEL_ERROR)
  • WARNING (CONFIG_BLUFI_TRACE_LEVEL_WARNING)
  • API (CONFIG_BLUFI_TRACE_LEVEL_API)
  • EVENT (CONFIG_BLUFI_TRACE_LEVEL_EVENT)
  • DEBUG (CONFIG_BLUFI_TRACE_LEVEL_DEBUG)
  • VERBOSE (CONFIG_BLUFI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_ACL_CONNECTIONS

BT/BLE MAX ACL CONNECTIONS(1~7)

Maximum BT/BLE connection count

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST

BT/BLE will first malloc the memory from the PSRAM

This select can save the internal RAM if there have the PSRAM

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY

Use dynamic memory allocation in BT/BLE stack

This select can make the allocation of memory will become more flexible

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_HOST_QUEUE_CONGESTION_CHECK

BLE queue congestion check

When scanning and scan duplicate is not enabled, if there are a lot of adv packets around or application layer handling adv packets is slow, it will cause the controller memory to run out. if enabled, adv packets will be lost when host queue is congested.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_SCAN_DUPLICATE

BLE Scan Duplicate Options

This select enables parameters setting of BLE scan duplicate.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_DUPLICATE_SCAN_CACHE_SIZE

Maximum number of devices in scan duplicate filter

Maximum number of devices which can be recorded in scan duplicate filter. When the maximum amount of device in the filter is reached, the cache will be refreshed.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_MESH_SCAN_DUPLICATE_EN

Special duplicate scan mechanism for BLE Mesh scan

This enables the BLE scan duplicate for special BLE Mesh scan.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_MESH_DUPLICATE_SCAN_CACHE_SIZE

Maximum number of Mesh adv packets in scan duplicate filter

Maximum number of adv packets which can be recorded in duplicate scan cache for BLE Mesh. When the maximum amount of device in the filter is reached, the cache will be refreshed.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_ADV_REPORT_FLOW_CONTROL_SUPPORTED

BLE adv report flow control supported

The function is mainly used to enable flow control for advertising reports. When it is enabled, advertising reports will be discarded by the controller if the number of unprocessed advertising reports exceeds the size of BLE adv report flow control.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_ADV_REPORT_FLOW_CONTROL_NUM

BLE adv report flow control number

The number of unprocessed advertising report that Bluedroid can save.If you set BLE_ADV_REPORT_FLOW_CONTROL_NUM to a small value, this may cause adv packets lost. If you set BLE_ADV_REPORT_FLOW_CONTROL_NUM to a large value, Bluedroid may cache a lot of adv packets and this may cause system memory run out. For example, if you set it to 50, the maximum memory consumed by host is 35 * 50 bytes. Please set BLE_ADV_REPORT_FLOW_CONTROL_NUM according to your system free memory and handle adv packets as fast as possible, otherwise it will cause adv packets lost.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_ADV_REPORT_DISCARD_THRSHOLD

BLE adv lost event threshold value

When adv report flow control is enabled, The ADV lost event will be generated when the number of ADV packets lost in the controller reaches this threshold. It is better to set a larger value. If you set BLE_ADV_REPORT_DISCARD_THRSHOLD to a small value or printf every adv lost event, it may cause adv packets lost more.

Found in
Component config > Bluetooth > Bluedroid Enable
CONFIG_BLE_ACTIVE_SCAN_REPORT_ADV_SCAN_RSP_INDIVIDUALLY

Report adv data and scan response individually when BLE active scan

Originally, when doing BLE active scan, Bluedroid will not report adv to application layer until receive scan response. This option is used to disable the behavior. When enable this option, Bluedroid will report adv data or scan response to application layer immediately.

Found in
Component config > Bluetooth > Bluedroid Enable

Timeout of BLE connection establishment

Bluetooth Connection establishment maximum time, if connection time exceeds this value, the connection establishment fails, ESP_GATTC_OPEN_EVT or ESP_GATTS_OPEN_EVT is triggered.

Found in
Component config > Bluetooth > Bluedroid Enable

mbedTLS

CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN

TLS maximum message content length

Maximum TLS message length (in bytes) supported by mbedTLS.

16384 is the default and this value is required to comply fully with TLS standards.

However you can set a lower value in order to save RAM. This is safe if the other end of the connection supports Maximum Fragment Length Negotiation Extension (max_fragment_length, see RFC6066) or you know for certain that it will never send a message longer than a certain number of bytes.

If the value is set too low, symptoms are a failed TLS handshake or a return value of MBEDTLS_ERR_SSL_INVALID_RECORD (-0x7200).

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_DEBUG

Enable mbedTLS debugging

Enable mbedTLS debugging functions at compile time.

If this option is enabled, you can include
“mbedtls/esp_debug.h” and call mbedtls_esp_enable_debug_log() at runtime in order to enable mbedTLS debug output via the ESP log mechanism.
Found in
Component config > mbedTLS
CONFIG_MBEDTLS_HARDWARE_AES

Enable hardware AES acceleration

Enable hardware accelerated AES encryption & decryption.

Note that if the ESP32 CPU is running at 240MHz, hardware AES does not offer any speed boost over software AES.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_HARDWARE_MPI

Enable hardware MPI (bignum) acceleration

Enable hardware accelerated multiple precision integer operations.

Hardware accelerated multiplication, modulo multiplication, and modular exponentiation for up to 4096 bit results.

These operations are used by RSA.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_MPI_USE_INTERRUPT

Use interrupt for MPI operations

Use an interrupt to coordinate MPI operations.

This allows other code to run on the CPU while an MPI operation is pending. Otherwise the CPU busy-waits.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_HARDWARE_SHA

Enable hardware SHA acceleration

Enable hardware accelerated SHA1, SHA256, SHA384 & SHA512 in mbedTLS.

Due to a hardware limitation, hardware acceleration is only guaranteed if SHA digests are calculated one at a time. If more than one SHA digest is calculated at the same time, one will be calculated fully in hardware and the rest will be calculated (at least partially calculated) in software. This happens automatically.

SHA hardware acceleration is faster than software in some situations but slower in others. You should benchmark to find the best setting for you.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_HAVE_TIME

Enable mbedtls time

System has time.h and time(). The time does not need to be correct, only time differences are used,

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_HAVE_TIME_DATE

Enable mbedtls time data

System has time.h and time(), gmtime() and the clock is correct. The time needs to be correct (not necesarily very accurate, but at least the date should be correct). This is used to verify the validity period of X.509 certificates.

It is suggested that you should get the real time by “SNTP”.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_TLS_MODE

TLS Protocol Role

mbedTLS can be compiled with protocol support for the TLS server, TLS client, or both server and client.

Reducing the number of TLS roles supported saves code size.

Found in
Component config > mbedTLS
Available options:
  • Server & Client (CONFIG_MBEDTLS_TLS_SERVER_AND_CLIENT)
  • Server (CONFIG_MBEDTLS_TLS_SERVER_ONLY)
  • Client (CONFIG_MBEDTLS_TLS_CLIENT_ONLY)
  • None (CONFIG_MBEDTLS_TLS_DISABLED)

TLS Key Exchange Methods

CONFIG_MBEDTLS_PSK_MODES

Enable pre-shared-key ciphersuites

Enable to show configuration for different types of pre-shared-key TLS authentatication methods.

Leaving this options disabled will save code size if they are not used.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_PSK

Enable PSK based ciphersuite modes

Enable to support symmetric key PSK (pre-shared-key) TLS key exchange modes.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_PSK

Enable DHE-PSK based ciphersuite modes

Enable to support Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_PSK

Enable ECDHE-PSK based ciphersuite modes

Enable to support Elliptic-Curve-Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_RSA_PSK

Enable RSA-PSK based ciphersuite modes

Enable to support RSA PSK (pre-shared-key) TLS authentication modes.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_RSA

Enable RSA-only based ciphersuite modes

Enable to support ciphersuites with prefix TLS-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_DHE_RSA

Enable DHE-RSA based ciphersuite modes

Enable to support ciphersuites with prefix TLS-DHE-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE

Support Elliptic Curve based ciphersuites

Enable to show Elliptic Curve based ciphersuite mode options.

Disabling all Elliptic Curve ciphersuites saves code size and can give slightly faster TLS handshakes, provided the server supports RSA-only ciphersuite modes.

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_RSA

Enable ECDHE-RSA based ciphersuite modes

Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA

Enable ECDHE-ECDSA based ciphersuite modes

Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA

Enable ECDH-ECDSA based ciphersuite modes

Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_KEY_EXCHANGE_ECDH_RSA

Enable ECDH-RSA based ciphersuite modes

Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-

Found in
Component config > mbedTLS > TLS Key Exchange Methods
CONFIG_MBEDTLS_SSL_RENEGOTIATION

Support TLS renegotiation

The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authentication after the initial handshake. If you don’t need renegotiation, disabling it will save code size and reduce the possibility of abuse/vulnerability.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_PROTO_SSL3

Legacy SSL 3.0 support

Support the legacy SSL 3.0 protocol. Most servers will speak a newer TLS protocol these days.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_PROTO_TLS1

Support TLS 1.0 protocol

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_PROTO_TLS1_1

Support TLS 1.1 protocol

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_PROTO_TLS1_2

Support TLS 1.2 protocol

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_PROTO_DTLS

Support DTLS protocol (all versions)

Requires TLS 1.1 to be enabled for DTLS 1.0 Requires TLS 1.2 to be enabled for DTLS 1.2

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_ALPN

Support ALPN (Application Layer Protocol Negotiation)

Disabling this option will save some code size if it is not needed.

Found in
Component config > mbedTLS
CONFIG_MBEDTLS_SSL_SESSION_TICKETS

TLS: Support RFC 5077 SSL session tickets

Support RFC 5077 session tickets. See mbedTLS documentation for more details.

Disabling this option will save some code size.

Found in
Component config > mbedTLS

Symmetric Ciphers

CONFIG_MBEDTLS_AES_C

AES block cipher

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_CAMELLIA_C

Camellia block cipher

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_DES_C

DES block cipher (legacy, insecure)

Enables the DES block cipher to support 3DES-based TLS ciphersuites.

3DES is vulnerable to the Sweet32 attack and should only be enabled if absolutely necessary.

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_RC4_MODE

RC4 Stream Cipher (legacy, insecure)

ARCFOUR (RC4) stream cipher can be disabled entirely, enabled but not added to default ciphersuites, or enabled completely.

Please consider the security implications before enabling RC4.

Found in
Component config > mbedTLS > Symmetric Ciphers
Available options:
  • Disabled (CONFIG_MBEDTLS_RC4_DISABLED)
  • Enabled, not in default ciphersuites (CONFIG_MBEDTLS_RC4_ENABLED_NO_DEFAULT)
  • Enabled (CONFIG_MBEDTLS_RC4_ENABLED)
CONFIG_MBEDTLS_BLOWFISH_C

Blowfish block cipher (read help)

Enables the Blowfish block cipher (not used for TLS sessions.)

The Blowfish cipher is not used for mbedTLS TLS sessions but can be used for other purposes. Read up on the limitations of Blowfish (including Sweet32) before enabling.

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_XTEA_C

XTEA block cipher

Enables the XTEA block cipher.

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_CCM_C

CCM (Counter with CBC-MAC) block cipher modes

Enable Counter with CBC-MAC (CCM) modes for AES and/or Camellia ciphers.

Disabling this option saves some code size.

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_GCM_C

GCM (Galois/Counter) block cipher modes

Enable Galois/Counter Mode for AES and/or Camellia ciphers.

This option is generally faster than CCM.

Found in
Component config > mbedTLS > Symmetric Ciphers
CONFIG_MBEDTLS_RIPEMD160_C

Enable RIPEMD-160 hash algorithm

Enable the RIPEMD-160 hash algorithm.

Found in
Component config > mbedTLS

Certificates

CONFIG_MBEDTLS_PEM_PARSE_C

Read & Parse PEM formatted certificates

Enable decoding/parsing of PEM formatted certificates.

If your certificates are all in the simpler DER format, disabling this option will save some code size.

Found in
Component config > mbedTLS > Certificates
CONFIG_MBEDTLS_PEM_WRITE_C

Write PEM formatted certificates

Enable writing of PEM formatted certificates.

If writing certificate data only in DER format, disabling this option will save some code size.

Found in
Component config > mbedTLS > Certificates
CONFIG_MBEDTLS_X509_CRL_PARSE_C

X.509 CRL parsing

Support for parsing X.509 Certifificate Revocation Lists.

Found in
Component config > mbedTLS > Certificates
CONFIG_MBEDTLS_X509_CSR_PARSE_C

X.509 CSR parsing

Support for parsing X.509 Certifificate Signing Requests

Found in
Component config > mbedTLS > Certificates
CONFIG_MBEDTLS_ECP_C

Elliptic Curve Ciphers

CONFIG_MBEDTLS_ECDH_C

Elliptic Curve Diffie-Hellman (ECDH)

Enable ECDH. Needed to use ECDHE-xxx TLS ciphersuites.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECDSA_C

Elliptic Curve DSA

Enable ECDSA. Needed to use ECDSA-xxx TLS ciphersuites.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP192R1_ENABLED

Enable SECP192R1 curve

Enable support for SECP192R1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP224R1_ENABLED

Enable SECP224R1 curve

Enable support for SECP224R1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP256R1_ENABLED

Enable SECP256R1 curve

Enable support for SECP256R1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP384R1_ENABLED

Enable SECP384R1 curve

Enable support for SECP384R1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP521R1_ENABLED

Enable SECP521R1 curve

Enable support for SECP521R1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP192K1_ENABLED

Enable SECP192K1 curve

Enable support for SECP192K1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP224K1_ENABLED

Enable SECP224K1 curve

Enable support for SECP224K1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_SECP256K1_ENABLED

Enable SECP256K1 curve

Enable support for SECP256K1 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_BP256R1_ENABLED

Enable BP256R1 curve

support for DP Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_BP384R1_ENABLED

Enable BP384R1 curve

support for DP Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_BP512R1_ENABLED

Enable BP512R1 curve

support for DP Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED

Enable CURVE25519 curve

Enable support for CURVE25519 Elliptic Curve.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers
CONFIG_MBEDTLS_ECP_NIST_OPTIM

NIST ‘modulo p’ optimisations

NIST ‘modulo p’ optimisations increase Elliptic Curve operation performance.

Disabling this option saves some code size.

Found in
Component config > mbedTLS > Elliptic Curve Ciphers

FAT Filesystem support

CONFIG_FATFS_CHOOSE_CODEPAGE

OEM Code Page

OEM code page used for file name encodings.

If “Dynamic” is selected, code page can be chosen at runtime using f_setcp function. Note that choosing this option will increase application size by ~480kB.

Found in
Component config > FAT Filesystem support
Available options:
  • Dynamic (all code pages supported) (CONFIG_FATFS_CODEPAGE_DYNAMIC)
  • US (CP437) (CONFIG_FATFS_CODEPAGE_437)
  • Arabic (CP720) (CONFIG_FATFS_CODEPAGE_720)
  • Greek (CP737) (CONFIG_FATFS_CODEPAGE_737)
  • KBL (CP771) (CONFIG_FATFS_CODEPAGE_771)
  • Baltic (CP775) (CONFIG_FATFS_CODEPAGE_775)
  • Latin 1 (CP850) (CONFIG_FATFS_CODEPAGE_850)
  • Latin 2 (CP852) (CONFIG_FATFS_CODEPAGE_852)
  • Cyrillic (CP855) (CONFIG_FATFS_CODEPAGE_855)
  • Turkish (CP857) (CONFIG_FATFS_CODEPAGE_857)
  • Portugese (CP860) (CONFIG_FATFS_CODEPAGE_860)
  • Icelandic (CP861) (CONFIG_FATFS_CODEPAGE_861)
  • Hebrew (CP862) (CONFIG_FATFS_CODEPAGE_862)
  • Canadian French (CP863) (CONFIG_FATFS_CODEPAGE_863)
  • Arabic (CP864) (CONFIG_FATFS_CODEPAGE_864)
  • Nordic (CP865) (CONFIG_FATFS_CODEPAGE_865)
  • Russian (CP866) (CONFIG_FATFS_CODEPAGE_866)
  • Greek 2 (CP869) (CONFIG_FATFS_CODEPAGE_869)
  • Japanese (DBCS) (CP932) (CONFIG_FATFS_CODEPAGE_932)
  • Simplified Chinese (DBCS) (CP936) (CONFIG_FATFS_CODEPAGE_936)
  • Korean (DBCS) (CP949) (CONFIG_FATFS_CODEPAGE_949)
  • Traditional Chinese (DBCS) (CP950) (CONFIG_FATFS_CODEPAGE_950)
CONFIG_FATFS_LONG_FILENAMES

Long filename support

Support long filenames in FAT. Long filename data increases memory usage. FATFS can be configured to store the buffer for long filename data in stack or heap.

Found in
Component config > FAT Filesystem support
Available options:
  • No long filenames (CONFIG_FATFS_LFN_NONE)
  • Long filename buffer in heap (CONFIG_FATFS_LFN_HEAP)
  • Long filename buffer on stack (CONFIG_FATFS_LFN_STACK)
CONFIG_FATFS_MAX_LFN

Max long filename length

Maximum long filename length. Can be reduced to save RAM.

Found in
Component config > FAT Filesystem support
CONFIG_FATFS_API_ENCODING

API character encoding

Choose encoding for character and string arguments/returns when using FATFS APIs. The encoding of arguments will usually depend on text editor settings.

Found in
Component config > FAT Filesystem support
Available options:
  • API uses ANSI/OEM encoding (CONFIG_FATFS_API_ENCODING_ANSI_OEM)
  • API uses UTF-16 encoding (CONFIG_FATFS_API_ENCODING_UTF_16)
  • API uses UTF-8 encoding (CONFIG_FATFS_API_ENCODING_UTF_8)
CONFIG_FATFS_FS_LOCK

Number of simultaneously open files protected by lock function

This option sets the FATFS configuration value _FS_LOCK. The option _FS_LOCK switches file lock function to control duplicated file open and illegal operation to open objects.

* 0: Disable file lock function. To avoid volume corruption, application
should avoid illegal open, remove and rename to the open objects.
* >0: Enable file lock function. The value defines how many files/sub-directories
can be opened simultaneously under file lock control.

Note that the file lock control is independent of re-entrancy.

Found in
Component config > FAT Filesystem support
CONFIG_FATFS_TIMEOUT_MS

Timeout for acquiring a file lock, ms

This option sets FATFS configuration value _FS_TIMEOUT, scaled to milliseconds. Sets the number of milliseconds FATFS will wait to acquire a mutex when operating on an open file. For example, if one task is performing a lenghty operation, another task will wait for the first task to release the lock, and time out after amount of time set by this option.

Found in
Component config > FAT Filesystem support
CONFIG_FATFS_PER_FILE_CACHE

Use separate cache for each file

This option affects FATFS configuration value _FS_TINY.

If this option is set, _FS_TINY is 0, and each open file has its own cache, size of the cache is equal to the _MAX_SS variable (512 or 4096 bytes). This option uses more RAM if more than 1 file is open, but needs less reads and writes to the storage for some operations.

If this option is not set, _FS_TINY is 1, and single cache is used for all open files, size is also equal to _MAX_SS variable. This reduces the amount of heap used when multiple files are open, but increases the number of read and write operations which FATFS needs to make.

Found in
Component config > FAT Filesystem support

SPIFFS Configuration

CONFIG_SPIFFS_MAX_PARTITIONS

Maximum Number of Partitions

Define maximum number of partitions that can be mounted.

Found in
Component config > SPIFFS Configuration

SPIFFS Cache Configuration

CONFIG_SPIFFS_CACHE

Enable SPIFFS Cache

Enables/disable memory read caching of nucleus file system operations.

Found in
Component config > SPIFFS Configuration > SPIFFS Cache Configuration
CONFIG_SPIFFS_CACHE_WR

Enable SPIFFS Write Caching

Enables memory write caching for file descriptors in hydrogen.

Found in
Component config > SPIFFS Configuration > SPIFFS Cache Configuration
CONFIG_SPIFFS_CACHE_STATS

Enable SPIFFS Cache Statistics

Enable/disable statistics on caching. Debug/test purpose only.

Found in
Component config > SPIFFS Configuration > SPIFFS Cache Configuration
CONFIG_SPIFFS_PAGE_CHECK

Enable SPIFFS Page Check

Always check header of each accessed page to ensure consistent state. If enabled it will increase number of reads from flash, especially if cache is disabled.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_GC_MAX_RUNS

Set Maximum GC Runs

Define maximum number of GC runs to perform to reach desired free pages.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_GC_STATS

Enable SPIFFS GC Statistics

Enable/disable statistics on gc. Debug/test purpose only.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_PAGE_SIZE

SPIFFS logical page size

Logical page size of SPIFFS partition, in bytes. Must be multiple of flash page size (which is usually 256 bytes). Larger page sizes reduce overhead when storing large files, and improve filesystem performance when reading large files. Smaller page sizes reduce overhead when storing small (< page size) files.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_OBJ_NAME_LEN

Set SPIFFS Maximum Name Length

Object name maximum length. Note that this length include the zero-termination character, meaning maximum string of characters can at most be SPIFFS_OBJ_NAME_LEN - 1.

SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE - 64.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_USE_MAGIC

Enable SPIFFS Filesystem Magic

Enable this to have an identifiable spiffs filesystem. This will look for a magic in all sectors to determine if this is a valid spiffs system or not at mount time.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_USE_MAGIC_LENGTH

Enable SPIFFS Filesystem Length Magic

If this option is enabled, the magic will also be dependent on the length of the filesystem. For example, a filesystem configured and formatted for 4 megabytes will not be accepted for mounting with a configuration defining the filesystem as 2 megabytes.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_META_LENGTH

Size of per-file metadata field

This option sets the number of extra bytes stored in the file header. These bytes can be used in an application-specific manner. Set this to at least 4 bytes to enable support for saving file modification time.

SPIFFS_OBJ_NAME_LEN + SPIFFS_META_LENGTH should not exceed SPIFFS_PAGE_SIZE - 64.

Found in
Component config > SPIFFS Configuration
CONFIG_SPIFFS_USE_MTIME

Save file modification time

If enabled, then the first 4 bytes of per-file metadata will be used to store file modification time (mtime), accessible through stat/fstat functions. Modification time is updated when the file is opened.

Found in
Component config > SPIFFS Configuration

Debug Configuration

CONFIG_SPIFFS_DBG

Enable general SPIFFS debug

Enabling this option will print general debug mesages to the console.

Found in
Component config > SPIFFS Configuration > Debug Configuration
CONFIG_SPIFFS_API_DBG

Enable SPIFFS API debug

Enabling this option will print API debug mesages to the console.

Found in
Component config > SPIFFS Configuration > Debug Configuration
CONFIG_SPIFFS_GC_DBG

Enable SPIFFS Garbage Cleaner debug

Enabling this option will print GC debug mesages to the console.

Found in
Component config > SPIFFS Configuration > Debug Configuration
CONFIG_SPIFFS_CACHE_DBG

Enable SPIFFS Cache debug

Enabling this option will print cache debug mesages to the console.

Found in
Component config > SPIFFS Configuration > Debug Configuration
CONFIG_SPIFFS_CHECK_DBG

Enable SPIFFS Filesystem Check debug

Enabling this option will print Filesystem Check debug mesages to the console.

Found in
Component config > SPIFFS Configuration > Debug Configuration
CONFIG_SPIFFS_TEST_VISUALISATION

Enable SPIFFS Filesystem Visualization

Enable this option to enable SPIFFS_vis function in the API.

Found in
Component config > SPIFFS Configuration > Debug Configuration

SPI Flash driver

CONFIG_SPI_FLASH_VERIFY_WRITE

Verify SPI flash writes

If this option is enabled, any time SPI flash is written then the data will be read back and verified. This can catch hardware problems with SPI flash, or flash which was not erased before verification.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_LOG_FAILED_WRITE

Log errors if verification fails

If this option is enabled, if SPI flash write verification fails then a log error line will be written with the address, expected & actual values. This can be useful when debugging hardware SPI flash problems.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE

Log warning if writing zero bits to ones

If this option is enabled, any SPI flash write which tries to set zero bits in the flash to ones will log a warning. Such writes will not result in the requested data appearing identically in flash once written, as SPI NOR flash can only set bits to one when an entire sector is erased. After erasing, individual bits can only be written from one to zero.

Note that some software (such as SPIFFS) which is aware of SPI NOR flash may write one bits as an optimisation, relying on the data in flash becoming a bitwise AND of the new data and any existing data. Such software will log spurious warnings if this option is enabled.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_ENABLE_COUNTERS

Enable operation counters

This option enables the following APIs:

  • spi_flash_reset_counters
  • spi_flash_dump_counters
  • spi_flash_get_counters

These APIs may be used to collect performance data for spi_flash APIs and to help understand behaviour of libraries which use SPI flash.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_ROM_DRIVER_PATCH

Enable SPI flash ROM driver patched functions

Enable this flag to use patched versions of SPI flash ROM driver functions. This option is needed to write to flash on ESP32-D2WD, and any configuration where external SPI flash is connected to non-default pins.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS

Writing to dangerous flash regions

SPI flash APIs can optionally abort or return a failure code if erasing or writing addresses that fall at the beginning of flash (covering the bootloader and partition table) or that overlap the app partition that contains the running app.

It is not recommended to ever write to these regions from an IDF app, and this check prevents logic errors or corrupted firmware memory from damaging these regions.

Note that this feature *does not* check calls to the esp_rom_xxx SPI flash ROM functions. These functions should not be called directly from IDF applications.

Found in
Component config > SPI Flash driver
Available options:
  • Aborts (CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ABORTS)
  • Fails (CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_FAILS)
  • Allowed (CONFIG_SPI_FLASH_WRITING_DANGEROUS_REGIONS_ALLOWED)
CONFIG_SPI_FLASH_YIELD_DURING_ERASE

Enables yield operation during flash erase

This allows to yield the CPUs between erase commands. Prevents starvation of other tasks.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS

Duration of erasing to yield CPUs (ms)

If a duration of one erase command is large then it will yield CPUs after finishing a current command.

Found in
Component config > SPI Flash driver
CONFIG_SPI_FLASH_ERASE_YIELD_TICKS

CPU release time (tick)

Defines how many ticks will be before returning to continue a erasing.

Found in
Component config > SPI Flash driver

Virtual file system

CONFIG_SUPPRESS_SELECT_DEBUG_OUTPUT

Suppress select() related debug outputs

Select() related functions might produce an unconveniently lot of debug outputs when one sets the default log level to DEBUG or higher. It is possible to suppress these debug outputs by enabling this option.

Found in
Component config > Virtual file system

tcpip adapter

CONFIG_IP_LOST_TIMER_INTERVAL

IP Address lost timer interval (seconds)

The value of 0 indicates the IP lost timer is disabled, otherwise the timer is enabled.

The IP address may be lost because of some reasons, e.g. when the station disconnects from soft-AP, or when DHCP IP renew fails etc. If the IP lost timer is enabled, it will be started everytime the IP is lost. Event SYSTEM_EVENT_STA_LOST_IP will be raised if the timer expires. The IP lost timer is stopped if the station get the IP again before the timer expires.

Found in
Component config > tcpip adapter

Customisations

Because IDF builds by default with Warning On Undefined Variables, when the Kconfig tool generates Makefiles (the auto.conf file) its behaviour has been customised. In normal Kconfig, a variable which is set to “no” is undefined. In IDF’s version of Kconfig, this variable is defined in the Makefile but has an empty value.

(Note that ifdef and ifndef can still be used in Makefiles, because they test if a variable is defined and has a non-empty value.)

When generating header files for C & C++, the behaviour is not customised - so #ifdef can be used to test if a boolean config item is set or not.