Project Configuration
Introduction
ESP-IDF uses kconfiglib which is a Python-based extension to the Kconfig system which provides a compile-time project 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.
For the complete list of available features please see Kconfig and kconfiglib extentions.
Using sdkconfig.defaults
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 can be created manually or automatically. It can contain all the options which matter for the given application and are different from the default ones. The format is the same as that of the sdkconfig
file. sdkconfig.defaults
can be created manually when one remembers all the changed configurations. Otherwise, the file can be generated automatically by running the idf.py save-defconfig
command.
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 the build process will not override settings that are already in sdkconfig
by ones from sdkconfig.defaults
. For more information, see Custom sdkconfig defaults.
Kconfig Formatting Rules
The following attributes of Kconfig
files are standardized:
Within any menu, option names should have a consistent prefix. The prefix length is currently set to at least 3 characters.
The indentation style is 4 characters created by spaces. All sub-items belonging to a parent item are indented by one level deeper. For example,
menu
is indented by 0 characters, theconfig
inside of the menu by 4 characters, the help of theconfig
by 8 characters and the text of thehelp
by 12 characters.No trailing spaces are allowed at the end of the lines.
The maximum length of options is set to 40 characters.
The maximum length of lines is set to 120 characters.
Format checker
tools/check_kconfigs.py
is provided for checking the Kconfig
formatting rules. The checker checks all Kconfig
and Kconfig.projbuild
files in the ESP-IDF directory and generates a new file with suffix .new
with some recommendations how to fix issues (if there are any). Please note that the checker cannot correct all rules and the responsibility of the developer is to check and make final corrections in order to pass the tests. For example, indentations will be corrected if there isn’t some misleading previous formatting but it cannot come up with a common prefix for options inside a menu.
Backward Compatibility of Kconfig Options
The standard Kconfig tools ignore unknown options in sdkconfig
. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
confgen.py
is used by the tool chain to pre-processsdkconfig
files before anything else, for examplemenuconfig
, would read them. As the consequence, the settings for old options will be kept and not ignored.confgen.py
recursively finds allsdkconfig.rename
files in ESP-IDF directory which contain old and newKconfig
option names. Old options are replaced by new ones in thesdkconfig
file. Renames that should only appear for a single target can be placed in a target specific rename file: sdkconfig.rename.TARGET, where TARGET is the target name, e.g. sdkconfig.rename.esp32s2.confgen.py
post-processessdkconfig
files and generates all build outputs (sdkconfig.h
,sdkconfig.cmake
,auto.conf
) by adding a list of compatibility statements, i.e. value of the old option is set the value of the new option (after modification). This is done in order to not break customer codes where old option might still be used.Deprecated options and their replacements are automatically generated by
confgen.py
.
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.
Build type
Contains:
CONFIG_APP_BUILD_TYPE
Application build type
Found in: Build type
Select the way the application is built.
By default, the application is built as a binary file in a format compatible with the ESP-IDF bootloader. In addition to this application, 2nd stage bootloader is also built. Application and bootloader binaries can be written into flash and loaded/executed from there.
Another option, useful for only very small and limited applications, is to only link the .elf file of the application, such that it can be loaded directly into RAM over JTAG. Note that since IRAM and DRAM sizes are very limited, it is not possible to build any complex application this way. However for kinds of testing and debugging, this option may provide faster iterations, since the application does not need to be written into flash. Note that at the moment, ESP-IDF does not contain all the startup code required to initialize the CPUs and ROM memory (data/bss). Therefore it is necessary to execute a bit of ROM code prior to executing the application. A gdbinit file may look as follows (for ESP32):
# Connect to a running instance of OpenOCD target remote :3333 # Reset and halt the target mon reset halt # Run to a specific point in ROM code, # where most of initialization is complete. thb *0x40007d54 c # Load the application into RAM load # Run till app_main tb app_main c
Execute this gdbinit file as follows:
xtensa-esp32-elf-gdb build/app-name.elf -x gdbinit
Example gdbinit files for other targets can be found in tools/test_apps/system/gdb_loadable_elf/
Recommended sdkconfig.defaults for building loadable ELF files is as follows. CONFIG_APP_BUILD_TYPE_ELF_RAM is required, other options help reduce application memory footprint.
CONFIG_APP_BUILD_TYPE_ELF_RAM=y CONFIG_VFS_SUPPORT_TERMIOS= CONFIG_NEWLIB_NANO_FORMAT=y CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y CONFIG_ESP_DEBUG_STUBS_ENABLE= CONFIG_ESP_ERR_TO_NAME_LOOKUP=
- Available options:
Default (binary application + 2nd stage bootloader) (APP_BUILD_TYPE_APP_2NDBOOT)
ELF file, loadable into RAM (EXPERIMENTAL)) (APP_BUILD_TYPE_ELF_RAM)
CONFIG_APP_REPRODUCIBLE_BUILD
Enable reproducible build
Found in: Build type
If enabled, all date, time, and path information would be eliminated. A .gdbinit file would be create automatically. (or will be append if you have one already)
- Default value:
No (disabled)
CONFIG_APP_NO_BLOBS
No Binary Blobs
Found in: Build type
If enabled, this disables the linking of binary libraries in the application build. Note that after enabling this Wi-Fi/Bluetooth will not work.
- Default value:
No (disabled)
CONFIG_APP_COMPATIBLE_PRE_V2_1_BOOTLOADERS
App compatible with bootloaders before ESP-IDF v2.1
Found in: Build type
Bootloaders before ESP-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.
- Default value:
No (disabled)
CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS
App compatible with bootloader and partition table before ESP-IDF v3.1
Found in: Build type
Partition tables before ESP-IDF V3.1 do not contain an MD5 checksum field, and the bootloader before ESP-IDF v3.1 cannot read a partition table that contains an MD5 checksum field.
Enable this option only if your app needs to boot on a bootloader and/or partition table that was generated from a version *before* ESP-IDF v3.1.
If this option and Flash Encryption are enabled at the same time, and any data partitions in the partition table are marked Encrypted, then the partition encrypted flag should be manually verified in the app before accessing the partition (see CVE-2021-27926).
- Default value:
No (disabled)
Bootloader config
Contains:
CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION
Bootloader optimization Level
Found in: Bootloader config
This option sets compiler optimization level (gcc -O argument) for the bootloader.
The default “Size” setting will add the -0s flag to CFLAGS.
The “Debug” setting will add the -Og flag to CFLAGS.
The “Performance” setting will add the -O2 flag to CFLAGS.
The “None” setting will add the -O0 flag to CFLAGS.
Note that custom optimization levels may be unsupported.
- Available options:
Size (-Os) (BOOTLOADER_COMPILER_OPTIMIZATION_SIZE)
Debug (-Og) (BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG)
Optimize for performance (-O2) (BOOTLOADER_COMPILER_OPTIMIZATION_PERF)
Debug without optimization (-O0) (BOOTLOADER_COMPILER_OPTIMIZATION_NONE)
CONFIG_BOOTLOADER_LOG_LEVEL
Bootloader log verbosity
Found in: Bootloader config
Specify how much output to see in bootloader logs.
- Available options:
No output (BOOTLOADER_LOG_LEVEL_NONE)
Error (BOOTLOADER_LOG_LEVEL_ERROR)
Warning (BOOTLOADER_LOG_LEVEL_WARN)
Info (BOOTLOADER_LOG_LEVEL_INFO)
Debug (BOOTLOADER_LOG_LEVEL_DEBUG)
Verbose (BOOTLOADER_LOG_LEVEL_VERBOSE)
CONFIG_BOOTLOADER_SPI_CUSTOM_WP_PIN
Use custom SPI Flash WP Pin when flash pins set in eFuse (read help)
Found in: Bootloader config
This setting is only used if the SPI flash pins have been overridden by setting the eFuses SPI_PAD_CONFIG_xxx, and the SPI flash mode is QIO or QOUT.
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. The same pin is also used for external SPIRAM if it is enabled.
If this config item is set to N (default), the correct WP pin will be automatically used for any Espressif chip or module with integrated flash. If a custom setting is needed, set this config item to Y and specify the GPIO number connected to the WP.
- Default value:
No (disabled) if ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT
CONFIG_BOOTLOADER_SPI_WP_PIN
Custom SPI Flash WP Pin
Found in: Bootloader config
The option “Use custom SPI Flash WP Pin” must be set or this value is ignored
If burning a customized set of SPI flash pins in eFuse and using QIO or QOUT mode for flash, set this value to the GPIO number of the SPI flash WP pin.
- Range:
from 0 to 33 if ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT
- Default value:
7 if ESPTOOLPY_FLASHMODE_QIO || ESPTOOLPY_FLASHMODE_QOUT
CONFIG_BOOTLOADER_VDDSDIO_BOOST
VDDSDIO LDO voltage
Found in: Bootloader config
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.
- Available options:
1.8V (BOOTLOADER_VDDSDIO_BOOST_1_8V)
1.9V (BOOTLOADER_VDDSDIO_BOOST_1_9V)
CONFIG_BOOTLOADER_FACTORY_RESET
GPIO triggers factory reset
Found in: Bootloader config
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 held at the configured level while device starts up. See settings below.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET
Number of the GPIO input for factory reset
Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET
The selected GPIO will be configured as an input with internal pull-up enabled (note that on some SoCs. not all pins have an internal pull-up, consult the hardware datasheet for details.) To trigger a factory reset, this GPIO must be held high or low (as configured) on startup.
- Range:
from 0 to 39 if CONFIG_BOOTLOADER_FACTORY_RESET
- Default value:
CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL
Factory reset GPIO level
Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET
Pin level for factory reset, can be triggered on low or high.
- Available options:
Reset on GPIO low (BOOTLOADER_FACTORY_RESET_PIN_LOW)
Reset on GPIO high (BOOTLOADER_FACTORY_RESET_PIN_HIGH)
CONFIG_BOOTLOADER_OTA_DATA_ERASE
Clear OTA data on factory reset (select factory partition)
Found in: Bootloader config > CONFIG_BOOTLOADER_FACTORY_RESET
The device will boot from “factory” partition (or OTA slot 0 if no factory partition is present) after a factory reset.
CONFIG_BOOTLOADER_DATA_FACTORY_RESET
Comma-separated names of partitions to clear on factory reset
Found in: Bootloader config > CONFIG_BOOTLOADER_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.
- Default value:
“nvs” if CONFIG_BOOTLOADER_FACTORY_RESET
CONFIG_BOOTLOADER_APP_TEST
GPIO triggers boot from test app partition
Found in: Bootloader config
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.
- Default value:
No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_NUM_PIN_APP_TEST
Number of the GPIO input to boot TEST partition
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_TEST
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.
- Range:
from 0 to 39 if CONFIG_BOOTLOADER_APP_TEST
- Default value:
CONFIG_BOOTLOADER_APP_TEST_PIN_LEVEL
App test GPIO level
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_TEST
Pin level for app test, can be triggered on low or high.
- Available options:
Enter test app on GPIO low (BOOTLOADER_APP_TEST_PIN_LOW)
Enter test app on GPIO high (BOOTLOADER_APP_TEST_PIN_HIGH)
CONFIG_BOOTLOADER_HOLD_TIME_GPIO
Hold time of GPIO for reset/test mode (seconds)
Found in: Bootloader config
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.
- Default value:
CONFIG_BOOTLOADER_REGION_PROTECTION_ENABLE
Enable protection for unmapped memory regions
Found in: Bootloader config
Protects the unmapped memory regions of the entire address space from unintended accesses. This will ensure that an exception will be triggered whenever the CPU performs a memory operation on unmapped regions of the address space.
- Default value:
Yes (enabled)
CONFIG_BOOTLOADER_WDT_ENABLE
Use RTC watchdog in start code
Found in: Bootloader config
Tracks the execution time of startup code. If the execution time is exceeded, the RTC_WDT will restart system. It is also useful to prevent a lock up in start code caused by an unstable power source. NOTE: Tracks the execution time starts from the bootloader code - re-set timeout, while selecting the source for slow_clk - and ends calling app_main. Re-set timeout is needed due to WDT uses a SLOW_CLK clock source. After changing a frequency slow_clk a time of WDT needs to re-set for new frequency. slow_clk depends on RTC_CLK_SRC (INTERNAL_RC or EXTERNAL_CRYSTAL).
- Default value:
Yes (enabled)
CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE
Allows RTC watchdog disable in user code
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
If this option is set, the ESP-IDF app must explicitly reset, feed, or disable the rtc_wdt in the app’s own code. If this option is not set (default), then rtc_wdt will be disabled by ESP-IDF before calling the app_main() function.
Use function rtc_wdt_feed() for resetting counter of rtc_wdt. Use function rtc_wdt_disable() for disabling rtc_wdt.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_WDT_TIME_MS
Timeout for RTC watchdog (ms)
Found in: Bootloader config > CONFIG_BOOTLOADER_WDT_ENABLE
Verify that this parameter is correct and more then the execution time. Pay attention to options such as reset to factory, trigger test partition and encryption on boot - these options can increase the execution time. Note: RTC_WDT will reset while encryption operations will be performed.
- Range:
from 0 to 120000
- Default value:
9000
CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
Enable app rollback support
Found in: Bootloader config
After updating the app, the bootloader runs a new app with the “ESP_OTA_IMG_PENDING_VERIFY” state set. This state prevents the re-run of this app. After the first boot of the new app in the user code, the function should be called to confirm the operability of the app or vice versa about its non-operability. If the app is working, then it is marked as valid. Otherwise, it is marked as not valid and rolls back to the previous working app. A reboot is performed, and the app is booted before the software update. Note: If during the first boot a new app the power goes out or the WDT works, then roll back will happen. Rollback is possible only between the apps with the same security versions.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
Enable app anti-rollback support
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
This option prevents rollback to previous firmware/application image with lower security version.
- Default value:
No (disabled) if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE
CONFIG_BOOTLOADER_APP_SECURE_VERSION
eFuse secure version of app
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
The secure version is the sequence number stored in the header of each firmware. The security version is set in the bootloader, version is recorded in the eFuse field as the number of set ones. The allocated number of bits in the efuse field for storing the security version is limited (see BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD option).
Bootloader: When bootloader selects an app to boot, an app is selected that has a security version greater or equal that recorded in eFuse field. The app is booted with a higher (or equal) secure version.
The security version is worth increasing if in previous versions there is a significant vulnerability and their use is not acceptable.
Your partition table should has a scheme with ota_0 + ota_1 (without factory).
- Default value:
CONFIG_BOOTLOADER_APP_SEC_VER_SIZE_EFUSE_FIELD
Size of the efuse secure version field
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
The size of the efuse secure version field. Its length is limited to 32 bits for ESP32 and 16 bits for ESP32-S2. This determines how many times the security version can be increased.
- Range:
from 1 to 32 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
from 1 to 16 if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
- Default value:
CONFIG_BOOTLOADER_EFUSE_SECURE_VERSION_EMULATE
Emulate operations with efuse secure version(only test)
Found in: Bootloader config > CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE > CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
This option allows to emulate read/write operations with all eFuses and efuse secure version. It allows to test anti-rollback implemention without permanent write eFuse bits. There should be an entry in partition table with following details: emul_efuse, data, efuse, , 0x2000.
This option enables: EFUSE_VIRTUAL and EFUSE_VIRTUAL_KEEP_IN_FLASH.
- Default value:
No (disabled) if CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK
CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP
Skip image validation when exiting deep sleep
Found in: Bootloader config
This option disables the normal validation of an image coming out of deep sleep (checksums, SHA256, and signature). This is a trade-off between wakeup performance from deep sleep, and image integrity checks.
Only enable this if you know what you are doing. It should not be used in conjunction with using deep_sleep() entry and changing the active OTA partition as this would skip the validation upon first load of the new OTA partition.
It is possible to enable this option with Secure Boot if “allow insecure options” is enabled, however it’s strongly recommended to NOT enable it as it may allow a Secure Boot bypass.
- Default value:
No (disabled) if (CONFIG_SECURE_BOOT && CONFIG_SECURE_BOOT_INSECURE) || CONFIG_SECURE_BOOT
CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON
Skip image validation from power on reset (READ HELP FIRST)
Found in: Bootloader config
Some applications need to boot very quickly from power on. By default, the entire app binary is read from flash and verified which takes up a significant portion of the boot time.
Enabling this option will skip validation of the app when the SoC boots from power on. Note that in this case it’s not possible for the bootloader to detect if an app image is corrupted in the flash, therefore it’s not possible to safely fall back to a different app partition. Flash corruption of this kind is unlikely but can happen if there is a serious firmware bug or physical damage.
Following other reset types, the bootloader will still validate the app image. This increases the chances that flash corruption resulting in a crash can be detected following soft reset, and the bootloader will fall back to a valid app image. To increase the chances of successfully recovering from a flash corruption event, keep the option BOOTLOADER_WDT_ENABLE enabled and consider also enabling BOOTLOADER_WDT_DISABLE_IN_USER_CODE - then manually disable the RTC Watchdog once the app is running. In addition, enable both the Task and Interrupt watchdog timers with reset options set.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS
Skip image validation always (READ HELP FIRST)
Found in: Bootloader config
Selecting this option prevents the bootloader from ever validating the app image before booting it. Any flash corruption of the selected app partition will make the entire SoC unbootable.
Although flash corruption is a very rare case, it is not recommended to select this option. Consider selecting “Skip image validation from power on reset” instead. However, if boot time is the only important factor then it can be enabled.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
Reserve RTC FAST memory for custom purposes
Found in: Bootloader config
This option allows the customer to place data in the RTC FAST memory, this area remains valid when rebooted, except for power loss. This memory is located at a fixed address and is available for both the bootloader and the application. (The application and bootoloader must be compiled with the same option). The RTC FAST memory has access only through PRO_CPU.
- Default value:
No (disabled)
CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC_SIZE
Size in bytes for custom purposes
Found in: Bootloader config > CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC
This option reserves in RTC FAST memory the area for custom purposes. If you want to create your own bootloader and save more information in this area of memory, you can increase it. It must be a multiple of 4 bytes. This area (rtc_retain_mem_t) is reserved and has access from the bootloader and an application.
- Default value:
CONFIG_BOOTLOADER_FLASH_XMC_SUPPORT
Enable the support for flash chips of XMC (READ HELP FIRST)
Found in: Bootloader config
Perform the startup flow recommended by XMC. Please consult XMC for the details of this flow. XMC chips will be forbidden to be used, when this option is disabled.
DON’T DISABLE THIS UNLESS YOU KNOW WHAT YOU ARE DOING.
- Default value:
Yes (enabled)
Security features
Contains:
CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
Require signed app images
Found in: Security features
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.
CONFIG_SECURE_SIGNED_APPS_SCHEME
App Signing Scheme
Found in: Security features
Select the Secure App signing scheme. Depends on the Chip Revision. There are two secure boot versions:
- Secure boot V1
Legacy custom secure boot scheme. Supported in ESP32 SoC.
- Secure boot V2
RSA based secure boot scheme. Supported in ESP32-ECO3 (ESP32 Chip Revision 3 onwards), ESP32-S2, ESP32-C3, ESP32-S3 SoCs.
ECDSA based secure boot scheme. Supported in ESP32-C2 SoC.
- Available options:
ECDSA (SECURE_SIGNED_APPS_ECDSA_SCHEME)
Embeds the ECDSA public key in the bootloader and signs the application with an ECDSA key. Refer to the documentation before enabling.
RSA (SECURE_SIGNED_APPS_RSA_SCHEME)
Appends the RSA-3072 based Signature block to the application. Refer to <Secure Boot Version 2 documentation link> before enabling.
ECDSA (V2) (SECURE_SIGNED_APPS_ECDSA_V2_SCHEME)
For Secure boot V2 (e.g., ESP32-C2 SoC), appends ECDSA based signature block to the application. Refer to documentation before enabling.
CONFIG_SECURE_BOOT_ECDSA_KEY_LEN_SIZE
ECDSA key size
Found in: Security features
Select the ECDSA key size. Two key sizes are supported
192 bit key using NISTP192 curve
256 bit key using NISTP256 curve (Recommended)
The advantage of using 256 bit key is the extra randomness which makes it difficult to be bruteforced compared to 192 bit key. At present, both key sizes are practically implausible to bruteforce.
- Available options:
Using ECC curve NISTP192 (SECURE_BOOT_ECDSA_KEY_LEN_192_BITS)
Using ECC curve NISTP256 (Recommended) (SECURE_BOOT_ECDSA_KEY_LEN_256_BITS)
CONFIG_SECURE_SIGNED_ON_BOOT_NO_SECURE_BOOT
Bootloader verifies app signatures
Found in: Security features
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.
- Default value:
No (disabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT && SECURE_SIGNED_APPS_ECDSA_SCHEME
CONFIG_SECURE_SIGNED_ON_UPDATE_NO_SECURE_BOOT
Verify app signature on update
Found in: Security features
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.
- Default value:
Yes (enabled) if CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT
CONFIG_SECURE_BOOT
Enable hardware Secure Boot in bootloader (READ DOCS FIRST)
Found in: Security features
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.
- Default value:
No (disabled)
CONFIG_SECURE_BOOT_VERSION
Select secure boot version
Found in: Security features > CONFIG_SECURE_BOOT
Select the Secure Boot Version. Depends on the Chip Revision. Secure Boot V2 is the new RSA / ECDSA based secure boot scheme.
RSA based scheme is supported in ESP32 (Revision 3 onwards), ESP32-S2, ESP32-C3 (ECO3), ESP32-S3.
ECDSA based scheme is supported in ESP32-C2 SoC.
Please note that, RSA or ECDSA secure boot is property of specific SoC based on its HW design, supported crypto accelerators, die-size, cost and similar parameters. Please note that RSA scheme has requirement for bigger key sizes but at the same time it is comparatively faster than ECDSA verification.
Secure Boot V1 is the AES based (custom) secure boot scheme supported in ESP32 SoC.
- Available options:
Enable Secure Boot version 1 (SECURE_BOOT_V1_ENABLED)
Build a bootloader which enables secure boot version 1 on first boot. Refer to the Secure Boot section of the ESP-IDF Programmer’s Guide for this version before enabling.
Enable Secure Boot version 2 (SECURE_BOOT_V2_ENABLED)
Build a bootloader which enables Secure Boot version 2 on first boot. Refer to Secure Boot V2 section of the ESP-IDF Programmer’s Guide for this version before enabling.
CONFIG_SECURE_BOOTLOADER_MODE
Secure bootloader mode
Found in: Security features
- Available options:
One-time flash (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 (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
Found in: Security features
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. Version 1 to enable ECDSA Based Secure Boot and Version 2 to enable RSA based Secure Boot. (for example, on a remote signing server.)
CONFIG_SECURE_BOOT_SIGNING_KEY
Secure boot private signing key
Found in: Security features > CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
Path to the key file used to sign app images.
Key file is an ECDSA private key (NIST256p curve) in PEM format for Secure Boot V1. Key file is an RSA private key in PEM format for Secure Boot V2.
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 the Secure Boot section of the ESP-IDF Programmer’s Guide for this version for details.
- Default value:
“secure_boot_signing_key.pem” if CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
CONFIG_SECURE_BOOT_VERIFICATION_KEY
Secure boot public signature verification key
Found in: Security features
Path to a public key file used to verify signed images. Secure Boot V1: This ECDSA public key is compiled into the bootloader and/or app, to verify app images. Secure Boot V2: This RSA public key is compiled into the signature block at the end of the bootloader/app.
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 the Secure Boot section of the ESP-IDF Programmer’s Guide for this version before enabling.
CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE
Enable Aggressive key revoke strategy
Found in: Security features
If this option is set, ROM bootloader will revoke the public key digest burned in efuse block if it fails to verify the signature of software bootloader with it. Revocation of keys does not happen when enabling secure boot. Once secure boot is enabled, key revocation checks will be done on subsequent boot-up, while verifying the software bootloader
This feature provides a strong resistance against physical attacks on the device.
NOTE: Once a digest slot is revoked, it can never be used again to verify an image This can lead to permanent bricking of the device, in case all keys are revoked because of signature verification failure.
- Default value:
No (disabled) if CONFIG_SECURE_BOOT && SOC_SUPPORT_SECURE_BOOT_REVOKE_KEY
CONFIG_SECURE_BOOTLOADER_KEY_ENCODING
Hardware Key Encoding
Found in: Security features
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.
- Available options:
No encoding (256 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_256BIT)
3/4 encoding (192 bit key) (SECURE_BOOTLOADER_KEY_ENCODING_192BIT)
CONFIG_SECURE_BOOT_INSECURE
Allow potentially insecure options
Found in: Security features
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 the Secure Boot section of the ESP-IDF Programmer’s Guide for this version before enabling.
- Default value:
No (disabled) if CONFIG_SECURE_BOOT
CONFIG_SECURE_FLASH_ENC_ENABLED
Enable flash encryption on boot (READ DOCS FIRST)
Found in: Security features
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 Flash Encryption before enabling.
- Default value:
No (disabled)
CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE
Size of generated AES-XTS key
Found in: Security features > CONFIG_SECURE_FLASH_ENC_ENABLED
Size of generated AES-XTS key.
AES-128 uses a 256-bit key (32 bytes) derived from 128 bits (16 bytes) burned in half Efuse key block. Internally, it calculates SHA256(128 bits)
AES-128 uses a 256-bit key (32 bytes) which occupies one Efuse key block.
AES-256 uses a 512-bit key (64 bytes) which occupies two Efuse key blocks.
This setting is ignored if either type of key is already burned to Efuse before the first boot. In this case, the pre-burned key is used and no new key is generated.
- Available options:
AES-128 key derived from 128 bits (SHA256(128 bits)) (SECURE_FLASH_ENCRYPTION_AES128_DERIVED)
AES-128 (256-bit key) (SECURE_FLASH_ENCRYPTION_AES128)
AES-256 (512-bit key) (SECURE_FLASH_ENCRYPTION_AES256)
CONFIG_SECURE_FLASH_ENCRYPTION_MODE
Enable usage mode
Found in: Security features > CONFIG_SECURE_FLASH_ENC_ENABLED
By default Development mode is enabled which allows ROM download mode to perform flash encryption operations (plaintext is sent to the device, and it encrypts it internally and writes ciphertext to flash.) This mode is not secure, it’s possible for an attacker to write their own chosen plaintext to flash.
Release mode should always be selected for production or manufacturing. Once enabled it’s no longer possible for the device in ROM Download Mode to use the flash encryption hardware.
Refer to the Flash Encryption section of the ESP-IDF Programmer’s Guide for details.
- Available options:
Development (NOT SECURE) (SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT)
Release (SECURE_FLASH_ENCRYPTION_MODE_RELEASE)
Potentially insecure options
Contains:
CONFIG_SECURE_BOOT_ALLOW_ROM_BASIC
Leave ROM BASIC Interpreter available on reset
Found in: Security features > Potentially insecure options
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.
- Default value:
No (disabled) if CONFIG_SECURE_BOOT_INSECURE || SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_BOOT_ALLOW_JTAG
Allow JTAG Debugging
Found in: Security features > Potentially insecure options
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.
- Default value:
No (disabled) if CONFIG_SECURE_BOOT_INSECURE || SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_BOOT_ALLOW_SHORT_APP_PARTITION
Allow app partition length not 64KB aligned
Found in: Security features > Potentially insecure options
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.
CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
Allow additional read protecting of efuses
Found in: Security features > Potentially insecure options
If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS efuse when Secure Boot is enabled. This prevents any more efuses from being read protected.
If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure Boot is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and BLOCK4-BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the public key digest, causing an immediate denial of service and possibly allowing an additional fault injection attack to bypass the signature protection.
NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block
NOTE: If “UART ROM download mode (Permanently disabled (recommended))” or “UART ROM download mode (Permanently switch to Secure mode (recommended))” is set, then it is __NOT__ possible to read/write efuses using espefuse.py utility. However, efuse can be read/written from the application
CONFIG_SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS
Leave unused digest slots available (not revoke)
Found in: Security features > Potentially insecure options
If not set (default), during startup in the app all unused digest slots will be revoked. To revoke unused slot will be called esp_efuse_set_digest_revoke(num_digest) for each digest. Revoking unused digest slots makes ensures that no trusted keys can be added later by an attacker. If set, it means that you have a plan to use unused digests slots later.
- Default value:
No (disabled) if CONFIG_SECURE_BOOT_INSECURE && SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC
Leave UART bootloader encryption enabled
Found in: Security features > Potentially insecure options
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.
- Default value:
No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC
Leave UART bootloader decryption enabled
Found in: Security features > Potentially insecure options
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.
- Default value:
No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE
Leave UART bootloader flash cache enabled
Found in: Security features > Potentially insecure options
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.
- Default value:
No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED
Require flash encryption to be already enabled
Found in: Security features > Potentially insecure options
If not set (default), and flash encryption is not yet enabled in eFuses, the 2nd stage bootloader will enable flash encryption: generate the flash encryption key and program eFuses. If this option is set, and flash encryption is not yet enabled, the bootloader will error out and reboot. If flash encryption is enabled in eFuses, this option does not change the bootloader behavior.
Only use this option in testing environments, to avoid accidentally enabling flash encryption on the wrong device. The device needs to have flash encryption already enabled using espefuse.py.
- Default value:
No (disabled) if SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP
Check Flash Encryption enabled on app startup
Found in: Security features
If set (default), in an app during startup code, there is a check of the flash encryption eFuse bit is on (as the bootloader should already have set it). The app requires this bit is on to continue work otherwise abort.
If not set, the app does not care if the flash encryption eFuse bit is set or not.
- Default value:
Yes (enabled) if CONFIG_SECURE_FLASH_ENC_ENABLED
CONFIG_SECURE_UART_ROM_DL_MODE
UART ROM download mode
Found in: Security features
- Available options:
UART ROM download mode (Permanently disabled (recommended)) (SECURE_DISABLE_ROM_DL_MODE)
If set, during startup the app will burn an eFuse bit to permanently disable the UART ROM Download Mode. This prevents any future use of esptool.py, espefuse.py and similar tools.
Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode then an error is printed instead.
It is recommended to enable this option in any production application where Flash Encryption and/or Secure Boot is enabled and access to Download Mode is not required.
It is also possible to permanently disable Download Mode by calling esp_efuse_disable_rom_download_mode() at runtime.
UART ROM download mode (Permanently switch to Secure mode (recommended)) (SECURE_ENABLE_SECURE_ROM_DL_MODE)
If set, during startup the app will burn an eFuse bit to permanently switch the UART ROM Download Mode into a separate Secure Download mode. This option can only work if Download Mode is not already disabled by eFuse.
Secure Download mode limits the use of Download Mode functions to update SPI config, changing baud rate, basic flash write and a command to return a summary of currently enabled security features (get_security_info).
Secure Download mode is not compatible with the esptool.py flasher stub feature, espefuse.py, read/writing memory or registers, encrypted download, or any other features that interact with unsupported Download Mode commands.
Secure Download mode should be enabled in any application where Flash Encryption and/or Secure Boot is enabled. Disabling this option does not immediately cancel the benefits of the security features, but it increases the potential “attack surface” for an attacker to try and bypass them with a successful physical attack.
It is also possible to enable secure download mode at runtime by calling esp_efuse_enable_rom_secure_download_mode()
Note: Secure Download mode is not available for ESP32 (includes revisions till ECO3).
UART ROM download mode (Enabled (not recommended)) (SECURE_INSECURE_ALLOW_DL_MODE)
This is a potentially insecure option. Enabling this option will allow the full UART download mode to stay enabled. This option SHOULD NOT BE ENABLED for production use cases.
Application manager
Contains:
CONFIG_APP_COMPILE_TIME_DATE
Use time/date stamp for app
Found in: Application manager
If set, then the app will be built with the current time/date stamp. It is stored in the app description structure. If not set, time/date stamp will be excluded from app image. This can be useful for getting the same binary image files made from the same source, but at different times.
- Default value:
Yes (enabled)
CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
Exclude PROJECT_VER from firmware image
Found in: Application manager
The PROJECT_VER variable from the build system will not affect the firmware image. This value will not be contained in the esp_app_desc structure.
- Default value:
No (disabled)
CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
Exclude PROJECT_NAME from firmware image
Found in: Application manager
The PROJECT_NAME variable from the build system will not affect the firmware image. This value will not be contained in the esp_app_desc structure.
- Default value:
No (disabled)
CONFIG_APP_PROJECT_VER_FROM_CONFIG
Get the project version from Kconfig
Found in: Application manager
If this is enabled, then config item APP_PROJECT_VER will be used for the variable PROJECT_VER. Other ways to set PROJECT_VER will be ignored.
- Default value:
No (disabled)
CONFIG_APP_PROJECT_VER
Project version
Found in: Application manager > CONFIG_APP_PROJECT_VER_FROM_CONFIG
Project version
- Default value:
CONFIG_APP_RETRIEVE_LEN_ELF_SHA
The length of APP ELF SHA is stored in RAM(chars)
Found in: Application manager
At startup, the app will read this many hex characters from the embedded APP ELF SHA-256 hash value and store it in static RAM. This ensures the app ELF SHA-256 value is always available if it needs to be printed by the panic handler code. Changing this value will change the size of a static buffer, in bytes.
- Range:
from 8 to 64
- Default value:
16
Serial flasher config
Contains:
CONFIG_ESPTOOLPY_NO_STUB
Disable download stub
Found in: Serial flasher config
The flasher tool sends a precompiled download stub first by default. That stub allows things like compressed downloads and more. Usually you should not need to disable that feature
- Default value:
No (disabled)
CONFIG_ESPTOOLPY_FLASHMODE
Flash SPI mode
Found in: Serial flasher config
Mode the flash chip is flashed in, as well as the default mode for the binary to run in.
- Available options:
QIO (ESPTOOLPY_FLASHMODE_QIO)
QOUT (ESPTOOLPY_FLASHMODE_QOUT)
DIO (ESPTOOLPY_FLASHMODE_DIO)
DOUT (ESPTOOLPY_FLASHMODE_DOUT)
OPI (ESPTOOLPY_FLASHMODE_OPI)
CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE
Flash Sampling Mode
Found in: Serial flasher config
- Available options:
STR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_STR)
DTR Mode (ESPTOOLPY_FLASH_SAMPLE_MODE_DTR)
CONFIG_ESPTOOLPY_FLASHFREQ
Flash SPI speed
Found in: Serial flasher config
- Available options:
120 MHz (ESPTOOLPY_FLASHFREQ_120M)
80 MHz (ESPTOOLPY_FLASHFREQ_80M)
60 MHz (ESPTOOLPY_FLASHFREQ_60M)
48 MHz (ESPTOOLPY_FLASHFREQ_48M)
40 MHz (ESPTOOLPY_FLASHFREQ_40M)
30 MHz (ESPTOOLPY_FLASHFREQ_30M)
26 MHz (ESPTOOLPY_FLASHFREQ_26M)
24 MHz (ESPTOOLPY_FLASHFREQ_24M)
20 MHz (ESPTOOLPY_FLASHFREQ_20M)
15 MHz (ESPTOOLPY_FLASHFREQ_15M)
CONFIG_ESPTOOLPY_FLASHSIZE
Flash size
Found in: Serial flasher config
SPI flash size, in megabytes
- Available options:
1 MB (ESPTOOLPY_FLASHSIZE_1MB)
2 MB (ESPTOOLPY_FLASHSIZE_2MB)
4 MB (ESPTOOLPY_FLASHSIZE_4MB)
8 MB (ESPTOOLPY_FLASHSIZE_8MB)
16 MB (ESPTOOLPY_FLASHSIZE_16MB)
32 MB (ESPTOOLPY_FLASHSIZE_32MB)
64 MB (ESPTOOLPY_FLASHSIZE_64MB)
128 MB (ESPTOOLPY_FLASHSIZE_128MB)
CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE
Detect flash size when flashing bootloader
Found in: Serial flasher config
If this option is set, flashing the project will automatically detect the flash size of the target chip and update the bootloader image before it is flashed.
Enabling this option turns off the image protection against corruption by a SHA256 digest. Updating the bootloader image before flashing would invalidate the digest.
- Default value:
No (disabled)
CONFIG_ESPTOOLPY_BEFORE
Before flashing
Found in: Serial flasher config
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.
- Available options:
Reset to bootloader (ESPTOOLPY_BEFORE_RESET)
No reset (ESPTOOLPY_BEFORE_NORESET)
CONFIG_ESPTOOLPY_AFTER
After flashing
Found in: Serial flasher config
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.
- Available options:
Reset after flashing (ESPTOOLPY_AFTER_RESET)
Stay in bootloader (ESPTOOLPY_AFTER_NORESET)
Partition Table
Contains:
CONFIG_PARTITION_TABLE_TYPE
Partition Table
Found in: 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. These are mostly intended for example and development use, it’s expect that for production use you will copy one of these CSV files and create a custom partition CSV for your application.
- Available options:
Single factory app, no OTA (PARTITION_TABLE_SINGLE_APP)
This is the default partition table, designed to fit into a 2MB or larger flash with a single 1MB app partition.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp.csv
This partition table is not suitable for an app that needs OTA (over the air update) capability.
Single factory app (large), no OTA (PARTITION_TABLE_SINGLE_APP_LARGE)
This is a variation of the default partition table, that expands the 1MB app partition size to 1.5MB to fit more code.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp_large.csv
This partition table is not suitable for an app that needs OTA (over the air update) capability.
Factory app, two OTA definitions (PARTITION_TABLE_TWO_OTA)
This is a basic OTA-enabled partition table with a factory app partition plus two OTA app partitions. All are 1MB, so this partition table requires 4MB or larger flash size.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_two_ota.csv
Custom partition table CSV (PARTITION_TABLE_CUSTOM)
Specify the path to the partition table CSV to use for your project.
Consult the Partition Table section in the ESP-IDF Programmers Guide for more information.
Single factory app, no OTA, encrypted NVS (PARTITION_TABLE_SINGLE_APP_ENCRYPTED_NVS)
This is a variation of the default “Single factory app, no OTA” partition table that supports encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF Programmers Guide for more information.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp_encr_nvs.csv
Single factory app (large), no OTA, encrypted NVS (PARTITION_TABLE_SINGLE_APP_LARGE_ENC_NVS)
This is a variation of the “Single factory app (large), no OTA” partition table that supports encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF Programmers Guide for more information.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_singleapp_large_encr_nvs.csv
Factory app, two OTA definitions, encrypted NVS (PARTITION_TABLE_TWO_OTA_ENCRYPTED_NVS)
This is a variation of the “Factory app, two OTA definitions” partition table that supports encrypted NVS when using flash encryption. See the Flash Encryption section in the ESP-IDF Programmers Guide for more information.
The corresponding CSV file in the IDF directory is components/partition_table/partitions_two_ota_encr_nvs.csv
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME
Custom partition CSV file
Found in: Partition Table
Name of the custom partition CSV filename. This path is evaluated relative to the project root directory.
- Default value:
“partitions.csv”
CONFIG_PARTITION_TABLE_OFFSET
Offset of partition table
Found in: 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.
This number should be a multiple of 0x1000.
Note that partition offsets in the partition table CSV file may need to be changed if this value is set to a higher value. To have each partition offset adapt to the configured partition table offset, leave all partition offsets blank in the CSV file.
- Default value:
“0x8000”
CONFIG_PARTITION_TABLE_MD5
Generate an MD5 checksum for the partition table
Found in: 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.
- Default value:
Yes (enabled) if CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS
Compiler options
Contains:
CONFIG_COMPILER_OPTIMIZATION
Optimization Level
Found in: Compiler options
This option sets compiler optimization level (gcc -O argument) for the app.
The “Default” setting will add the -0g flag to CFLAGS.
The “Size” setting will add the -0s flag to CFLAGS.
The “Performance” setting will add the -O2 flag to CFLAGS.
The “None” setting will add the -O0 flag to CFLAGS.
The “Size” setting cause the compiled code to be smaller and faster, but may lead to difficulties of correlating code addresses to source file lines when debugging.
The “Performance” setting causes the compiled code to be larger and faster, but will be easier to correlated code addresses to source file lines.
“None” with -O0 produces compiled code without optimization.
Note that custom optimization levels may be unsupported.
Compiler optimization for the IDF bootloader is set separately, see the BOOTLOADER_COMPILER_OPTIMIZATION setting.
- Available options:
Debug (-Og) (COMPILER_OPTIMIZATION_DEFAULT)
Optimize for size (-Os) (COMPILER_OPTIMIZATION_SIZE)
Optimize for performance (-O2) (COMPILER_OPTIMIZATION_PERF)
Debug without optimization (-O0) (COMPILER_OPTIMIZATION_NONE)
CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL
Assertion level
Found in: Compiler options
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.
- Available options:
Enabled (COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE)
Enable assertions. Assertion content and line number will be printed on failure.
Silent (saves code size) (COMPILER_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) (COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE)
If assertions are disabled, -DNDEBUG is added to CPPFLAGS.
CONFIG_COMPILER_FLOAT_LIB_FROM
Compiler float lib source
Found in: Compiler options
In the soft-fp part of libgcc, riscv version is written in C, and handles all edge cases in IEEE754, which makes it larger and performance is slow.
RVfplib is an optimized RISC-V library for FP arithmetic on 32-bit integer processors, for single and double-precision FP. RVfplib is “fast”, but it has a few exceptions from IEEE 754 compliance.
- Available options:
libgcc (COMPILER_FLOAT_LIB_FROM_GCCLIB)
librvfp (COMPILER_FLOAT_LIB_FROM_RVFPLIB)
CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT
Disable messages in ESP_RETURN_ON_* and ESP_EXIT_ON_* macros
Found in: Compiler options
If enabled, the error messages will be discarded in following check macros: - ESP_RETURN_ON_ERROR - ESP_EXIT_ON_ERROR - ESP_RETURN_ON_FALSE - ESP_EXIT_ON_FALSE
- Default value:
No (disabled)
CONFIG_COMPILER_HIDE_PATHS_MACROS
Replace ESP-IDF and project paths in binaries
Found in: Compiler options
When expanding the __FILE__ and __BASE_FILE__ macros, replace paths inside ESP-IDF with paths relative to the placeholder string “IDF”, and convert paths inside the project directory to relative paths.
This allows building the project with assertions or other code that embeds file paths, without the binary containing the exact path to the IDF or project directories.
This option passes -fmacro-prefix-map options to the GCC command line. To replace additional paths in your binaries, modify the project CMakeLists.txt file to pass custom -fmacro-prefix-map or -ffile-prefix-map arguments.
- Default value:
Yes (enabled)
CONFIG_COMPILER_CXX_EXCEPTIONS
Enable C++ exceptions
Found in: Compiler options
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.
- Default value:
No (disabled)
Contains:
CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE
Emergency Pool Size
Found in: Compiler options > CONFIG_COMPILER_CXX_EXCEPTIONS
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.
- Default value:
CONFIG_COMPILER_CXX_RTTI
Enable C++ run-time type info (RTTI)
Found in: Compiler options
Enabling this option compiles all C++ files with RTTI support enabled. This increases binary size (typically by tens of kB) but allows using dynamic_cast conversion and typeid operator.
- Default value:
No (disabled)
CONFIG_COMPILER_STACK_CHECK_MODE
Stack smashing protection mode
Found in: Compiler options
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
The performance impact includes increasing the amount of stack memory required for each task.
- Available options:
None (COMPILER_STACK_CHECK_MODE_NONE)
Normal (COMPILER_STACK_CHECK_MODE_NORM)
Strong (COMPILER_STACK_CHECK_MODE_STRONG)
Overall (COMPILER_STACK_CHECK_MODE_ALL)
CONFIG_COMPILER_WARN_WRITE_STRINGS
Enable -Wwrite-strings warning flag
Found in: Compiler options
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-constchar \*
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 \*
.
- Default value:
No (disabled)
CONFIG_COMPILER_DUMP_RTL_FILES
Dump RTL files during compilation
Found in: Compiler options
If enabled, RTL files will be produced during compilation. These files can be used by other tools, for example to calculate call graphs.
Component config
Contains:
Application Level Tracing
Contains:
CONFIG_APPTRACE_DESTINATION1
Data Destination 1
Found in: Component config > Application Level Tracing
Select destination for application trace: JTAG or none (to disable).
- Available options:
JTAG (APPTRACE_DEST_JTAG)
None (APPTRACE_DEST_NONE)
CONFIG_APPTRACE_DESTINATION2
Data Destination 2
Found in: Component config > Application Level Tracing
Select destination for application trace: UART(XX) or none (to disable).
- Available options:
UART0 (APPTRACE_DEST_UART0)
UART1 (APPTRACE_DEST_UART1)
UART2 (APPTRACE_DEST_UART2)
USB_CDC (APPTRACE_DEST_USB_CDC)
None (APPTRACE_DEST_UART_NONE)
CONFIG_APPTRACE_UART_TX_GPIO
UART TX on GPIO#
Found in: Component config > Application Level Tracing
This GPIO is used for UART TX pin.
CONFIG_APPTRACE_UART_RX_GPIO
UART RX on GPIO#
Found in: Component config > Application Level Tracing
This GPIO is used for UART RX pin.
CONFIG_APPTRACE_UART_BAUDRATE
UART baud rate
Found in: Component config > Application Level Tracing
This baud rate is used for UART.
The app’s maximum baud rate depends on the UART clock source. If Power Management is disabled, the UART clock source is the APB clock and all baud rates in the available range will be sufficiently accurate. If Power Management is enabled, REF_TICK clock source is used so the baud rate is divided from 1MHz. Baud rates above 1Mbps are not possible and values between 500Kbps and 1Mbps may not be accurate.
CONFIG_APPTRACE_UART_RX_BUFF_SIZE
UART RX ring buffer size
Found in: Component config > Application Level Tracing
Size of the UART input ring buffer. This size related to the baudrate, system tick frequency and amount of data to transfer. The data placed to this buffer before sent out to the interface.
CONFIG_APPTRACE_UART_TX_BUFF_SIZE
UART TX ring buffer size
Found in: Component config > Application Level Tracing
Size of the UART output ring buffer. This size related to the baudrate, system tick frequency and amount of data to transfer.
CONFIG_APPTRACE_UART_TX_MSG_SIZE
UART TX message size
Found in: Component config > Application Level Tracing
Maximum size of the single message to transfer.
CONFIG_APPTRACE_UART_TASK_PRIO
UART Task Priority
Found in: Component config > Application Level Tracing
UART task priority. In case of high events rate, this parameter could be changed up to (configMAX_PRIORITIES-1).
- Range:
from 1 to 32
- Default value:
1
CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO
Timeout for flushing last trace data to host on panic
Found in: Component config > Application Level Tracing
Timeout for flushing last trace data to host in case of panic. In ms. Use -1 to disable timeout and wait forever.
CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH
Threshold for flushing last trace data to host on panic
Found in: Component config > Application Level Tracing
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.
CONFIG_APPTRACE_BUF_SIZE
Size of the apptrace buffer
Found in: Component config > Application Level Tracing
Size of the memory buffer for trace data in bytes.
CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX
Size of the pending data buffer
Found in: Component config > Application Level Tracing
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.
FreeRTOS SystemView Tracing
Contains:
CONFIG_APPTRACE_SV_ENABLE
SystemView Tracing Enable
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables supporrt for SEGGER SystemView tracing functionality.
CONFIG_APPTRACE_SV_DEST
SystemView destination
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing > CONFIG_APPTRACE_SV_ENABLE
SystemView witt transfer data trough defined interface.
- Available options:
Data destination JTAG (APPTRACE_SV_DEST_JTAG)
Send SEGGER SystemView events through JTAG interface.
Data destination UART (APPTRACE_SV_DEST_UART)
Send SEGGER SystemView events through UART interface.
CONFIG_APPTRACE_SV_CPU
CPU to trace
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Define the CPU to trace by SystemView.
- Available options:
CPU0 (APPTRACE_SV_DEST_CPU_0)
Send SEGGER SystemView events for Pro CPU.
CPU1 (APPTRACE_SV_DEST_CPU_1)
Send SEGGER SystemView events for App CPU.
CONFIG_APPTRACE_SV_TS_SOURCE
Timer to use as timestamp source
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
SystemView needs to use a hardware timer as the source of timestamps when tracing. This option selects the timer for it.
- Available options:
CPU cycle counter (CCOUNT) (APPTRACE_SV_TS_SOURCE_CCOUNT)
General Purpose Timer (Timer Group) (APPTRACE_SV_TS_SOURCE_GPTIMER)
esp_timer high resolution timer (APPTRACE_SV_TS_SOURCE_ESP_TIMER)
CONFIG_APPTRACE_SV_MAX_TASKS
Maximum supported tasks
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Configures maximum supported tasks in sysview debug
CONFIG_APPTRACE_SV_BUF_WAIT_TMO
Trace buffer wait timeout
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Configures timeout (in us) to wait for free space in trace buffer. Set to -1 to wait forever and avoid lost events.
CONFIG_APPTRACE_SV_EVT_OVERFLOW_ENABLE
Trace Buffer Overflow Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Trace Buffer Overflow” event.
CONFIG_APPTRACE_SV_EVT_ISR_ENTER_ENABLE
ISR Enter Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR Enter” event.
CONFIG_APPTRACE_SV_EVT_ISR_EXIT_ENABLE
ISR Exit Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR Exit” event.
CONFIG_APPTRACE_SV_EVT_ISR_TO_SCHED_ENABLE
ISR Exit to Scheduler Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR to Scheduler” event.
CONFIG_APPTRACE_SV_EVT_TASK_START_EXEC_ENABLE
Task Start Execution Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Start Execution” event.
CONFIG_APPTRACE_SV_EVT_TASK_STOP_EXEC_ENABLE
Task Stop Execution Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Stop Execution” event.
CONFIG_APPTRACE_SV_EVT_TASK_START_READY_ENABLE
Task Start Ready State Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Start Ready State” event.
CONFIG_APPTRACE_SV_EVT_TASK_STOP_READY_ENABLE
Task Stop Ready State Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Stop Ready State” event.
CONFIG_APPTRACE_SV_EVT_TASK_CREATE_ENABLE
Task Create Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Create” event.
CONFIG_APPTRACE_SV_EVT_TASK_TERMINATE_ENABLE
Task Terminate Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Terminate” event.
CONFIG_APPTRACE_SV_EVT_IDLE_ENABLE
System Idle Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “System Idle” event.
CONFIG_APPTRACE_SV_EVT_TIMER_ENTER_ENABLE
Timer Enter Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Timer Enter” event.
CONFIG_APPTRACE_SV_EVT_TIMER_EXIT_ENABLE
Timer Exit Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Timer Exit” event.
CONFIG_APPTRACE_GCOV_ENABLE
GCOV to Host Enable
Found in: Component config > Application Level Tracing
Enables support for GCOV data transfer to host.
Bluetooth
Contains:
CONFIG_BT_ENABLED
Bluetooth
Found in: Component config > Bluetooth
Select this option to enable Bluetooth and show the submenu with Bluetooth configuration choices.
CONFIG_BT_HOST
Host
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED
This helps to choose Bluetooth host stack
- Available options:
Bluedroid - Dual-mode (BT_BLUEDROID_ENABLED)
This option is recommended for classic Bluetooth or for dual-mode usecases
NimBLE - BLE only (BT_NIMBLE_ENABLED)
This option is recommended for BLE only usecases to save on memory
Disabled (BT_CONTROLLER_ONLY)
This option is recommended when you want to communicate directly with the controller (without any host) or when you are using any other host stack not supported by Espressif (not mentioned here).
CONFIG_BT_CONTROLLER
Controller
Found in: Component config > Bluetooth > CONFIG_BT_ENABLED
This helps to choose Bluetooth controller stack
- Available options:
Enabled (BT_CONTROLLER_ENABLED)
This option is recommended for Bluetooth controller usecases
Disabled (BT_CONTROLLER_DISABLED)
This option is recommended for Bluetooth Host only usecases
Bluedroid Options
Contains:
CONFIG_BT_BTC_TASK_STACK_SIZE
Bluetooth event (callback to application) task stack size
Found in: Component config > Bluetooth > Bluedroid Options
This select btc task stack size
- Default value:
3072 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE
The cpu core which Bluedroid run
Found in: Component config > Bluetooth > Bluedroid Options
Which the cpu core to run Bluedroid. Can choose core0 and core1. Can not specify no-affinity.
- Available options:
Core 0 (PRO CPU) (BT_BLUEDROID_PINNED_TO_CORE_0)
Core 1 (APP CPU) (BT_BLUEDROID_PINNED_TO_CORE_1)
CONFIG_BT_BTU_TASK_STACK_SIZE
Bluetooth Bluedroid Host Stack task stack size
Found in: Component config > Bluetooth > Bluedroid Options
This select btu task stack size
- Default value:
4096 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLUEDROID_MEM_DEBUG
Bluedroid memory debug
Found in: Component config > Bluetooth > Bluedroid Options
Bluedroid memory debug
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_CLASSIC_ENABLED
Classic Bluetooth
Found in: Component config > Bluetooth > Bluedroid Options
For now this option needs “SMP_ENABLE” to be set to yes
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_A2DP_ENABLE
A2DP
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED
Advanced Audio Distrubution Profile
- Default value:
No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_SPP_ENABLED
SPP
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED
This enables the Serial Port Profile
- Default value:
No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_L2CAP_ENABLED
BT L2CAP
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED
This enables the Logical Link Control and Adaptation Layer Protocol. Only supported classic bluetooth.
- Default value:
No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_HFP_ENABLE
Hands Free/Handset Profile
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED
- Default value:
No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_HFP_ROLE
Hands-free Profile Role configuration
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED > CONFIG_BT_HFP_ENABLE
- Available options:
Hands Free Unit (BT_HFP_CLIENT_ENABLE)
Audio Gateway (BT_HFP_AG_ENABLE)
CONFIG_BT_HFP_AUDIO_DATA_PATH
audio(SCO) data path
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_CLASSIC_ENABLED > CONFIG_BT_HFP_ENABLE
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.
- Available options:
PCM (BT_HFP_AUDIO_DATA_PATH_PCM)
HCI (BT_HFP_AUDIO_DATA_PATH_HCI)
CONFIG_BT_HFP_WBS_ENABLE
Wide Band Speech
Found in: Component config > Bluetooth > Bluedroid Options
This enables Wide Band Speech. Should disable it when SCO data path is PCM. Otherwise there will be no data transmited via GPIOs.
- Default value:
Yes (enabled) if BT_HFP_AUDIO_DATA_PATH_HCI && BT_BLUEDROID_ENABLED
CONFIG_BT_HID_ENABLED
Classic BT HID
Found in: Component config > Bluetooth > Bluedroid Options
This enables the BT HID Host
- Default value:
No (disabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_HID_ROLE
Profile Role configuration
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_HID_ENABLED
- Available options:
Classic BT HID Host (BT_HID_HOST_ENABLED)
This enables the BT HID Host
Classic BT HID Device (BT_HID_DEVICE_ENABLED)
This enables the BT HID Device
CONFIG_BT_SSP_ENABLED
Secure Simple Pairing
Found in: Component config > Bluetooth > Bluedroid Options
This enables the Secure Simple Pairing. If disable this option, Bluedroid will only support Legacy Pairing
- Default value:
Yes (enabled) if CONFIG_BT_CLASSIC_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ENABLED
Bluetooth Low Energy
Found in: Component config > Bluetooth > Bluedroid Options
This enables Bluetooth Low Energy
- Default value:
Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_ENABLE
Include GATT server module(GATTS)
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED
This option can be disabled when the app work only on gatt client mode
- Default value:
Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_PPCP_CHAR_GAP
Enable Peripheral Preferred Connection Parameters characteristic in GAP service
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE
This enables “Peripheral Preferred Connection Parameters” characteristic (UUID: 0x2A04) in GAP service that has connection parameters like min/max connection interval, slave latency and supervision timeout multiplier
- Default value:
No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_BLUFI_ENABLE
Include blufi function
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE
This option can be close when the app does not require blufi function.
- Default value:
No (disabled) if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATT_MAX_SR_PROFILES
Max GATT Server Profiles
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE
Maximum GATT Server Profiles Count
- Range:
from 1 to 32 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
- Default value:
8 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATT_MAX_SR_ATTRIBUTES
Max GATT Service Attributes
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE
Maximum GATT Service Attributes Count
- Range:
from 1 to 500 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
- Default value:
100 if CONFIG_BT_GATTS_ENABLE && BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTS_SEND_SERVICE_CHANGE_MODE
GATTS Service Change Mode
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTS_ENABLE
Service change indication mode for GATT Server.
- Available options:
GATTS manually send service change indication (BT_GATTS_SEND_SERVICE_CHANGE_MANUAL)
Manually send service change indication through API esp_ble_gatts_send_service_change_indication()
GATTS automatically send service change indication (BT_GATTS_SEND_SERVICE_CHANGE_AUTO)
Let Bluedroid handle the service change indication internally
CONFIG_BT_GATTC_ENABLE
Include GATT client module(GATTC)
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED
This option can be close when the app work only on gatt server mode
- Default value:
Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTC_MAX_CACHE_CHAR
Max gattc cache characteristic for discover
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTC_ENABLE
Maximum GATTC cache characteristic count
- Range:
from 1 to 500 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
- Default value:
40 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTC_CACHE_NVS_FLASH
Save gattc cache data to nvs flash
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTC_ENABLE
This select can save gattc cache data to nvs flash
- Default value:
No (disabled) if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_GATTC_CONNECT_RETRY_COUNT
The number of attempts to reconnect if the connection establishment failed
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_GATTC_ENABLE
The number of attempts to reconnect if the connection establishment failed
- Range:
from 0 to 7 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
- Default value:
3 if CONFIG_BT_GATTC_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_SMP_ENABLE
Include BLE security module(SMP)
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED
This option can be close when the app not used the ble security connect.
- Default value:
Yes (enabled) if CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_SMP_SLAVE_CON_PARAMS_UPD_ENABLE
Slave enable connection parameters update during pairing
Found in: Component config > Bluetooth > Bluedroid Options > CONFIG_BT_BLE_ENABLED > CONFIG_BT_BLE_SMP_ENABLE
In order to reduce the pairing time, slave actively initiates connection parameters update during pairing.
- Default value:
No (disabled) if CONFIG_BT_BLE_SMP_ENABLE && BT_BLUEDROID_ENABLED
CONFIG_BT_STACK_NO_LOG
Disable BT debug logs (minimize bin size)
Found in: Component config > Bluetooth > Bluedroid Options
This select can save the rodata code size
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
BT DEBUG LOG LEVEL
Contains:
CONFIG_BT_LOG_HCI_TRACE_LEVEL
HCI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for HCI layer
- Available options:
NONE (BT_LOG_HCI_TRACE_LEVEL_NONE)
ERROR (BT_LOG_HCI_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_HCI_TRACE_LEVEL_WARNING)
API (BT_LOG_HCI_TRACE_LEVEL_API)
EVENT (BT_LOG_HCI_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_HCI_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_HCI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTM_TRACE_LEVEL
BTM layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTM layer
- Available options:
NONE (BT_LOG_BTM_TRACE_LEVEL_NONE)
ERROR (BT_LOG_BTM_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_BTM_TRACE_LEVEL_WARNING)
API (BT_LOG_BTM_TRACE_LEVEL_API)
EVENT (BT_LOG_BTM_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_BTM_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_BTM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_L2CAP_TRACE_LEVEL
L2CAP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for L2CAP layer
- Available options:
NONE (BT_LOG_L2CAP_TRACE_LEVEL_NONE)
ERROR (BT_LOG_L2CAP_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_L2CAP_TRACE_LEVEL_WARNING)
API (BT_LOG_L2CAP_TRACE_LEVEL_API)
EVENT (BT_LOG_L2CAP_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_L2CAP_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_L2CAP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_RFCOMM_TRACE_LEVEL
RFCOMM layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for RFCOMM layer
- Available options:
NONE (BT_LOG_RFCOMM_TRACE_LEVEL_NONE)
ERROR (BT_LOG_RFCOMM_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_RFCOMM_TRACE_LEVEL_WARNING)
API (BT_LOG_RFCOMM_TRACE_LEVEL_API)
EVENT (BT_LOG_RFCOMM_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_RFCOMM_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_RFCOMM_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SDP_TRACE_LEVEL
SDP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for SDP layer
- Available options:
NONE (BT_LOG_SDP_TRACE_LEVEL_NONE)
ERROR (BT_LOG_SDP_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_SDP_TRACE_LEVEL_WARNING)
API (BT_LOG_SDP_TRACE_LEVEL_API)
EVENT (BT_LOG_SDP_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_SDP_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_SDP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GAP_TRACE_LEVEL
GAP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for GAP layer
- Available options:
NONE (BT_LOG_GAP_TRACE_LEVEL_NONE)
ERROR (BT_LOG_GAP_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_GAP_TRACE_LEVEL_WARNING)
API (BT_LOG_GAP_TRACE_LEVEL_API)
EVENT (BT_LOG_GAP_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_GAP_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_GAP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BNEP_TRACE_LEVEL
BNEP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BNEP layer
- Available options:
NONE (BT_LOG_BNEP_TRACE_LEVEL_NONE)
ERROR (BT_LOG_BNEP_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_BNEP_TRACE_LEVEL_WARNING)
API (BT_LOG_BNEP_TRACE_LEVEL_API)
EVENT (BT_LOG_BNEP_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_BNEP_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_BNEP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_PAN_TRACE_LEVEL
PAN layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for PAN layer
- Available options:
NONE (BT_LOG_PAN_TRACE_LEVEL_NONE)
ERROR (BT_LOG_PAN_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_PAN_TRACE_LEVEL_WARNING)
API (BT_LOG_PAN_TRACE_LEVEL_API)
EVENT (BT_LOG_PAN_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_PAN_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_PAN_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_A2D_TRACE_LEVEL
A2D layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for A2D layer
- Available options:
NONE (BT_LOG_A2D_TRACE_LEVEL_NONE)
ERROR (BT_LOG_A2D_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_A2D_TRACE_LEVEL_WARNING)
API (BT_LOG_A2D_TRACE_LEVEL_API)
EVENT (BT_LOG_A2D_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_A2D_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_A2D_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVDT_TRACE_LEVEL
AVDT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVDT layer
- Available options:
NONE (BT_LOG_AVDT_TRACE_LEVEL_NONE)
ERROR (BT_LOG_AVDT_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_AVDT_TRACE_LEVEL_WARNING)
API (BT_LOG_AVDT_TRACE_LEVEL_API)
EVENT (BT_LOG_AVDT_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_AVDT_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_AVDT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVCT_TRACE_LEVEL
AVCT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVCT layer
- Available options:
NONE (BT_LOG_AVCT_TRACE_LEVEL_NONE)
ERROR (BT_LOG_AVCT_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_AVCT_TRACE_LEVEL_WARNING)
API (BT_LOG_AVCT_TRACE_LEVEL_API)
EVENT (BT_LOG_AVCT_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_AVCT_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_AVCT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_AVRC_TRACE_LEVEL
AVRC layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for AVRC layer
- Available options:
NONE (BT_LOG_AVRC_TRACE_LEVEL_NONE)
ERROR (BT_LOG_AVRC_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_AVRC_TRACE_LEVEL_WARNING)
API (BT_LOG_AVRC_TRACE_LEVEL_API)
EVENT (BT_LOG_AVRC_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_AVRC_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_AVRC_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_MCA_TRACE_LEVEL
MCA layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for MCA layer
- Available options:
NONE (BT_LOG_MCA_TRACE_LEVEL_NONE)
ERROR (BT_LOG_MCA_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_MCA_TRACE_LEVEL_WARNING)
API (BT_LOG_MCA_TRACE_LEVEL_API)
EVENT (BT_LOG_MCA_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_MCA_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_MCA_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_HID_TRACE_LEVEL
HID layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for HID layer
- Available options:
NONE (BT_LOG_HID_TRACE_LEVEL_NONE)
ERROR (BT_LOG_HID_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_HID_TRACE_LEVEL_WARNING)
API (BT_LOG_HID_TRACE_LEVEL_API)
EVENT (BT_LOG_HID_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_HID_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_HID_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_APPL_TRACE_LEVEL
APPL layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for APPL layer
- Available options:
NONE (BT_LOG_APPL_TRACE_LEVEL_NONE)
ERROR (BT_LOG_APPL_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_APPL_TRACE_LEVEL_WARNING)
API (BT_LOG_APPL_TRACE_LEVEL_API)
EVENT (BT_LOG_APPL_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_APPL_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_APPL_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_GATT_TRACE_LEVEL
GATT layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for GATT layer
- Available options:
NONE (BT_LOG_GATT_TRACE_LEVEL_NONE)
ERROR (BT_LOG_GATT_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_GATT_TRACE_LEVEL_WARNING)
API (BT_LOG_GATT_TRACE_LEVEL_API)
EVENT (BT_LOG_GATT_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_GATT_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_GATT_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_SMP_TRACE_LEVEL
SMP layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for SMP layer
- Available options:
NONE (BT_LOG_SMP_TRACE_LEVEL_NONE)
ERROR (BT_LOG_SMP_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_SMP_TRACE_LEVEL_WARNING)
API (BT_LOG_SMP_TRACE_LEVEL_API)
EVENT (BT_LOG_SMP_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_SMP_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_SMP_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTIF_TRACE_LEVEL
BTIF layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTIF layer
- Available options:
NONE (BT_LOG_BTIF_TRACE_LEVEL_NONE)
ERROR (BT_LOG_BTIF_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_BTIF_TRACE_LEVEL_WARNING)
API (BT_LOG_BTIF_TRACE_LEVEL_API)
EVENT (BT_LOG_BTIF_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_BTIF_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_BTIF_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BTC_TRACE_LEVEL
BTC layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BTC layer
- Available options:
NONE (BT_LOG_BTC_TRACE_LEVEL_NONE)
ERROR (BT_LOG_BTC_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_BTC_TRACE_LEVEL_WARNING)
API (BT_LOG_BTC_TRACE_LEVEL_API)
EVENT (BT_LOG_BTC_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_BTC_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_BTC_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_OSI_TRACE_LEVEL
OSI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for OSI layer
- Available options:
NONE (BT_LOG_OSI_TRACE_LEVEL_NONE)
ERROR (BT_LOG_OSI_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_OSI_TRACE_LEVEL_WARNING)
API (BT_LOG_OSI_TRACE_LEVEL_API)
EVENT (BT_LOG_OSI_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_OSI_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_OSI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_LOG_BLUFI_TRACE_LEVEL
BLUFI layer
Found in: Component config > Bluetooth > Bluedroid Options > BT DEBUG LOG LEVEL
Define BT trace level for BLUFI layer
- Available options:
NONE (BT_LOG_BLUFI_TRACE_LEVEL_NONE)
ERROR (BT_LOG_BLUFI_TRACE_LEVEL_ERROR)
WARNING (BT_LOG_BLUFI_TRACE_LEVEL_WARNING)
API (BT_LOG_BLUFI_TRACE_LEVEL_API)
EVENT (BT_LOG_BLUFI_TRACE_LEVEL_EVENT)
DEBUG (BT_LOG_BLUFI_TRACE_LEVEL_DEBUG)
VERBOSE (BT_LOG_BLUFI_TRACE_LEVEL_VERBOSE)
CONFIG_BT_ACL_CONNECTIONS
BT/BLE MAX ACL CONNECTIONS(1~9)
Found in: Component config > Bluetooth > Bluedroid Options
Maximum BT/BLE connection count. The ESP32-C3/S3 chip supports a maximum of 10 instances, including ADV, SCAN and connections. The ESP32-C3/S3 chip can connect up to 9 devices if ADV or SCAN uses only one. If ADV and SCAN are both used, The ESP32-C3/S3 chip is connected to a maximum of 8 devices. Because Bluetooth cannot reclaim used instances once ADV or SCAN is used.
- Range:
from 1 to 9 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
- Default value:
4 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_MULTI_CONNECTION_ENBALE
Enable BLE multi-conections
Found in: Component config > Bluetooth > Bluedroid Options
Enable this option if there are multiple connections
- Default value:
Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST
BT/BLE will first malloc the memory from the PSRAM
Found in: Component config > Bluetooth > Bluedroid Options
This select can save the internal RAM if there have the PSRAM
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY
Use dynamic memory allocation in BT/BLE stack
Found in: Component config > Bluetooth > Bluedroid Options
This select can make the allocation of memory will become more flexible
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_HOST_QUEUE_CONG_CHECK
BLE queue congestion check
Found in: Component config > Bluetooth > Bluedroid Options
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.
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ACT_SCAN_REP_ADV_SCAN
Report adv data and scan response individually when BLE active scan
Found in: Component config > Bluetooth > Bluedroid Options
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.
# Memory reserved at start of DRAM for Bluetooth stack
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && CONFIG_BT_BLE_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_ESTAB_LINK_CONN_TOUT
Timeout of BLE connection establishment
Found in: Component config > Bluetooth > Bluedroid Options
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.
- Range:
from 1 to 60 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
- Default value:
30 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_MAX_DEVICE_NAME_LEN
length of bluetooth device name
Found in: Component config > Bluetooth > Bluedroid Options
Bluetooth Device name length shall be no larger than 248 octets, If the broadcast data cannot contain the complete device name, then only the shortname will be displayed, the rest parts that can’t fit in will be truncated.
- Range:
from 32 to 248 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
- Default value:
32 if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_RPA_SUPPORTED
Update RPA to Controller
Found in: Component config > Bluetooth > Bluedroid Options
This enables controller RPA list function. For ESP32, ESP32 only support network privacy mode. If this option is enabled, ESP32 will only accept advertising packets from peer devices that contain private address, HW will not receive the advertising packets contain identity address after IRK changed. If this option is disabled, address resolution will be performed in the host, so the functions that require controller to resolve address in the white list cannot be used. This option is disabled by default on ESP32, please enable or disable this option according to your own needs.
For ESP32C3, ESP32S3, ESP32H2 and ESP32C2, devices support network privacy mode and device privacy mode, users can switch the two modes according to their own needs. So this option is enabled by default.
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
Yes (enabled) if BT_BLUEDROID_ENABLED && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_50_FEATURES_SUPPORTED
Enable BLE 5.0 features
Found in: Component config > Bluetooth > Bluedroid Options
This enables BLE 5.0 features, this option only support esp32c3/esp32s3 chip
- Default value:
Yes (enabled) if BT_BLUEDROID_ENABLED && SOC_ESP_NIMBLE_CONTROLLER && BT_BLUEDROID_ENABLED
CONFIG_BT_BLE_42_FEATURES_SUPPORTED
Enable BLE 4.2 features
Found in: Component config > Bluetooth > Bluedroid Options
This enables BLE 4.2 features.
- Default value:
No (disabled) if BT_BLUEDROID_ENABLED && SOC_ESP_NIMBLE_CONTROLLER && BT_BLUEDROID_ENABLED
NimBLE Options
Contains:
CONFIG_BT_NIMBLE_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > Bluetooth > NimBLE Options
Allocation strategy for NimBLE host stack, essentially provides ability to allocate all required dynamic allocations from,
Internal DRAM memory only
External SPIRAM memory only
Either internal or external memory based on default malloc() behavior in ESP-IDF
Internal IRAM memory wherever applicable else internal DRAM
- Available options:
Internal memory (BT_NIMBLE_MEM_ALLOC_MODE_INTERNAL)
External SPIRAM (BT_NIMBLE_MEM_ALLOC_MODE_EXTERNAL)
Default alloc mode (BT_NIMBLE_MEM_ALLOC_MODE_DEFAULT)
Internal IRAM (BT_NIMBLE_MEM_ALLOC_MODE_IRAM_8BIT)
Allows to use IRAM memory region as 8bit accessible region.
Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned read/write.
CONFIG_BT_NIMBLE_LOG_LEVEL
NimBLE Host log verbosity
Found in: Component config > Bluetooth > NimBLE Options
Select NimBLE log level. Please make a note that the selected NimBLE log verbosity can not exceed the level set in “Component config –> Log output –> Default log verbosity”.
- Available options:
No logs (BT_NIMBLE_LOG_LEVEL_NONE)
Error logs (BT_NIMBLE_LOG_LEVEL_ERROR)
Warning logs (BT_NIMBLE_LOG_LEVEL_WARNING)
Info logs (BT_NIMBLE_LOG_LEVEL_INFO)
Debug logs (BT_NIMBLE_LOG_LEVEL_DEBUG)
CONFIG_BT_NIMBLE_MAX_CONNECTIONS
Maximum number of concurrent connections
Found in: Component config > Bluetooth > NimBLE Options
Defines maximum number of concurrent BLE connections. For ESP32, user is expected to configure BTDM_CTRL_BLE_MAX_CONN from controller menu along with this option. Similarly for ESP32-C3 or ESP32-S3, user is expected to configure BT_CTRL_BLE_MAX_ACT from controller menu. For ESP32C2, ESP32C6 and ESP32H2, each connection will take about 1k DRAM.
- Range:
from 1 to 8 if IDF_TARGET_ESP32H4 && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
from 1 to 9 if SOC_ESP_NIMBLE_CONTROLLER && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
- Default value:
3 if IDF_TARGET_ESP32H4 && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_BONDS
Maximum number of bonds to save across reboots
Found in: Component config > Bluetooth > NimBLE Options
Defines maximum number of bonds to save for peer security and our security
- Default value:
3 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_CCCDS
Maximum number of CCC descriptors to save across reboots
Found in: Component config > Bluetooth > NimBLE Options
Defines maximum number of CCC descriptors to save
- Default value:
8 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_L2CAP_COC_MAX_NUM
Maximum number of connection oriented channels
Found in: Component config > Bluetooth > NimBLE Options
Defines maximum number of BLE Connection Oriented Channels. When set to (0), BLE COC is not compiled in
- Range:
from 0 to 9 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
- Default value:
0 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE
The CPU core on which NimBLE host will run
Found in: Component config > Bluetooth > NimBLE Options
The CPU core on which NimBLE host will run. You can choose Core 0 or Core 1. Cannot specify no-affinity
- Available options:
Core 0 (PRO CPU) (BT_NIMBLE_PINNED_TO_CORE_0)
Core 1 (APP CPU) (BT_NIMBLE_PINNED_TO_CORE_1)
CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE
NimBLE Host task stack size
Found in: Component config > Bluetooth > NimBLE Options
This configures stack size of NimBLE host task
- Default value:
5120 if CONFIG_BLE_MESH && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
4096 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_CENTRAL
Enable BLE Central role
Found in: Component config > Bluetooth > NimBLE Options
Enables central role
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_PERIPHERAL
Enable BLE Peripheral role
Found in: Component config > Bluetooth > NimBLE Options
Enable peripheral role
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_BROADCASTER
Enable BLE Broadcaster role
Found in: Component config > Bluetooth > NimBLE Options
Enables broadcaster role
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ROLE_OBSERVER
Enable BLE Observer role
Found in: Component config > Bluetooth > NimBLE Options
Enables observer role
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_NVS_PERSIST
Persist the BLE Bonding keys in NVS
Found in: Component config > Bluetooth > NimBLE Options
Enable this flag to make bonding persistent across device reboots
- Default value:
No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SECURITY_ENABLE
Enable BLE SM feature
Found in: Component config > Bluetooth > NimBLE Options
Enable BLE sm feature
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Contains:
CONFIG_BT_NIMBLE_SM_LEGACY
Security manager legacy pairing
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_SECURITY_ENABLE
Enable security manager legacy pairing
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_SECURITY_ENABLE && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SM_SC
Security manager secure connections (4.2)
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_SECURITY_ENABLE
Enable security manager secure connections
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_SECURITY_ENABLE && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SM_SC_DEBUG_KEYS
Use predefined public-private key pair
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_SECURITY_ENABLE > CONFIG_BT_NIMBLE_SM_SC
If this option is enabled, SM uses predefined DH key pair as described in Core Specification, Vol. 3, Part H, 2.3.5.6.1. This allows to decrypt air traffic easily and thus should only be used for debugging.
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_SECURITY_ENABLE && CONFIG_BT_NIMBLE_SM_SC && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_ENCRYPTION
Enable LE encryption
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_SECURITY_ENABLE
Enable encryption connection
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_SECURITY_ENABLE && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_DEBUG
Enable extra runtime asserts and host debugging
Found in: Component config > Bluetooth > NimBLE Options
This enables extra runtime asserts and host debugging
- Default value:
No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SVC_GAP_DEVICE_NAME
BLE GAP default device name
Found in: Component config > Bluetooth > NimBLE Options
The Device Name characteristic shall contain the name of the device as an UTF-8 string. This name can be changed by using API ble_svc_gap_device_name_set()
- Default value:
“nimble” if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_GAP_DEVICE_NAME_MAX_LEN
Maximum length of BLE device name in octets
Found in: Component config > Bluetooth > NimBLE Options
Device Name characteristic value shall be 0 to 248 octets in length
- Default value:
31 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU
Preferred MTU size in octets
Found in: Component config > Bluetooth > NimBLE Options
This is the default value of ATT MTU indicated by the device during an ATT MTU exchange. This value can be changed using API ble_att_set_preferred_mtu()
- Default value:
256 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_SVC_GAP_APPEARANCE
External appearance of the device
Found in: Component config > Bluetooth > NimBLE Options
Standard BLE GAP Appearance value in HEX format e.g. 0x02C0
- Default value:
0 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Memory Settings
Contains:
CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT
MSYS_1 Block Count
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
MSYS is a system level mbuf registry. For prepare write & prepare responses MBUFs are allocated out of msys_1 pool. For NIMBLE_MESH enabled cases, this block count is increased by 8 than user defined count.
- Default value:
24 if SOC_ESP_NIMBLE_CONTROLLER && BT_NIMBLE_ENABLED
12 if SOC_ESP_NIMBLE_CONTROLLER && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE
MSYS_1 Block Size
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
Dynamic memory size of block 1
- Default value:
128 if SOC_ESP_NIMBLE_CONTROLLER && BT_NIMBLE_ENABLED
256 if SOC_ESP_NIMBLE_CONTROLLER && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT
MSYS_2 Block Count
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
Dynamic memory count
- Default value:
24 if BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MSYS_2_BLOCK_SIZE
MSYS_2 Block Size
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
Dynamic memory size of block 2
- Default value:
320 if BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ACL_BUF_COUNT
ACL Buffer count
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
The number of ACL data buffers.
- Default value:
24 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ACL_BUF_SIZE
ACL Buffer size
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
This is the maximum size of the data portion of HCI ACL data packets. It does not include the HCI data header (of 4 bytes)
- Default value:
255 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HCI_EVT_BUF_SIZE
HCI Event Buffer size
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
This is the size of each HCI event buffer in bytes. In case of extended advertising, packets can be fragmented. 257 bytes is the maximum size of a packet.
- Default value:
257 if CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
70 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT
High Priority HCI Event Buffer count
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
This is the high priority HCI events’ buffer size. High-priority event buffers are for everything except advertising reports. If there are no free high-priority event buffers then host will try to allocate a low-priority buffer instead
- Default value:
30 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT
Low Priority HCI Event Buffer count
Found in: Component config > Bluetooth > NimBLE Options > Memory Settings
This is the low priority HCI events’ buffer size. Low-priority event buffers are only used for advertising reports. If there are no free low-priority event buffers, then an incoming advertising report will get dropped
- Default value:
8 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_GATT_MAX_PROCS
Maximum number of GATT client procedures
Found in: Component config > Bluetooth > NimBLE Options
Maximum number of GATT client procedures that can be executed.
- Default value:
4 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Enable Host Flow control
Found in: Component config > Bluetooth > NimBLE Options
Enable Host Flow control
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_ITVL
Host Flow control interval
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Host flow control interval in msecs
- Default value:
1000 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_THRESH
Host Flow control threshold
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Host flow control threshold, if the number of free buffers are at or below this threshold, send an immediate number-of-completed-packets event
- Default value:
2 if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_FLOW_CTRL_TX_ON_DISCONNECT
Host Flow control on disconnect
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_HS_FLOW_CTRL
Enable this option to send number-of-completed-packets event to controller after disconnection
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_HS_FLOW_CTRL && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_RPA_TIMEOUT
RPA timeout in seconds
Found in: Component config > Bluetooth > NimBLE Options
Time interval between RPA address change. This is applicable in case of Host based RPA
- Range:
from 1 to 41400 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
- Default value:
900 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH
Enable BLE mesh functionality
Found in: Component config > Bluetooth > NimBLE Options
Enable BLE Mesh example present in upstream mynewt-nimble and not maintained by Espressif.
IDF maintains ESP-BLE-MESH as the official Mesh solution. Please refer to ESP-BLE-MESH guide at: :doc:../esp32/api-guides/esp-ble-mesh/ble-mesh-index``
- Default value:
No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Contains:
CONFIG_BT_NIMBLE_MESH_PROXY
Enable mesh proxy functionality
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable proxy. This is automatically set whenever NIMBLE_MESH_PB_GATT or NIMBLE_MESH_GATT_PROXY is set
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PROV
Enable BLE mesh provisioning
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable mesh provisioning
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_ADV
Enable mesh provisioning over advertising bearer
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CONFIG_BT_NIMBLE_MESH_PROV
Enable this option to allow the device to be provisioned over the advertising bearer
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PB_GATT
Enable mesh provisioning over GATT bearer
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH > CONFIG_BT_NIMBLE_MESH_PROV
Enable this option to allow the device to be provisioned over the GATT bearer
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_MESH_PROV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_GATT_PROXY
Enable GATT Proxy functionality
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
This option enables support for the Mesh GATT Proxy Service, i.e. the ability to act as a proxy between a Mesh GATT Client and a Mesh network
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_RELAY
Enable mesh relay functionality
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Support for acting as a Mesh Relay Node
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_LOW_POWER
Enable mesh low power mode
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable this option to be able to act as a Low Power Node
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_FRIEND
Enable mesh friend functionality
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable this option to be able to act as a Friend Node
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_DEVICE_NAME
Set mesh device name
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
This value defines Bluetooth Mesh device/node name
- Default value:
“nimble-mesh-node” if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_NODE_COUNT
Set mesh node count
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Defines mesh node count.
- Default value:
1 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MESH_PROVISIONER
Enable BLE mesh provisioner
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_MESH
Enable mesh provisioner.
- Default value:
0 if CONFIG_BT_NIMBLE_MESH && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_CRYPTO_STACK_MBEDTLS
Override TinyCrypt with mbedTLS for crypto computations
Found in: Component config > Bluetooth > NimBLE Options
Enable this option to choose mbedTLS instead of TinyCrypt for crypto computations.
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_HS_STOP_TIMEOUT_MS
BLE host stop timeout in msec
Found in: Component config > Bluetooth > NimBLE Options
BLE Host stop procedure timeout in milliseconds.
- Default value:
2000 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
Enable connection reattempts on connection establishment error
Found in: Component config > Bluetooth > NimBLE Options
Enable to make the NimBLE host to reattempt GAP connection on connection establishment failure.
- Default value:
No (disabled) if BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_CONN_REATTEMPT
Maximum number connection reattempts
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT
Defines maximum number of connection reattempts.
- Range:
from 1 to 7 if BT_NIMBLE_ENABLED && CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT && BT_NIMBLE_ENABLED
- Default value:
3 if BT_NIMBLE_ENABLED && CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT
Enable BLE 5 feature
Found in: Component config > Bluetooth > NimBLE Options
Enable BLE 5 feature
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
Contains:
CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_2M_PHY
Enable 2M Phy
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT
Enable 2M-PHY
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_LL_CFG_FEAT_LE_CODED_PHY
Enable coded Phy
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT
Enable coded-PHY
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_EXT_ADV
Enable extended advertising
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT
Enable this option to do extended advertising. Extended advertising will be supported from BLE 5.0 onwards.
- Default value:
No (disabled) if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_EXT_ADV_INSTANCES
Maximum number of extended advertising instances.
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT > CONFIG_BT_NIMBLE_EXT_ADV
Change this option to set maximum number of extended advertising instances. Minimum there is always one instance of advertising. Enter how many more advertising instances you want. For ESP32C2, ESP32C6 and ESP32H2, each extended advertising instance will take about 0.5k DRAM.
- Range:
from 0 to 4 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
- Default value:
1 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
0 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_EXT_ADV_MAX_SIZE
Maximum length of the advertising data.
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT > CONFIG_BT_NIMBLE_EXT_ADV
Defines the length of the extended adv data. The value should not exceed 1650.
- Range:
from 0 to 1650 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
- Default value:
1650 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
0 if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV
Enable periodic advertisement.
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT > CONFIG_BT_NIMBLE_EXT_ADV
Enable this option to start periodic advertisement.
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_EXT_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_PERIODIC_ADV_SYNC_TRANSFER
Enable Transer Sync Events
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT > CONFIG_BT_NIMBLE_EXT_ADV > CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV
This enables controller transfer periodic sync events to host
- Default value:
Yes (enabled) if CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV && CONFIG_BT_NIMBLE_EXT_ADV && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_MAX_PERIODIC_SYNCS
Maximum number of periodic advertising syncs
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT
Set this option to set the upper limit for number of periodic sync connections. This should be less than maximum connections allowed by controller.
- Range:
from 0 to 8 if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
- Default value:
1 if CONFIG_BT_NIMBLE_ENABLE_PERIODIC_ADV && CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
0 if CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_53_FEATURE_SUPPORT
Enable BLE 5.3 feature
Found in: Component config > Bluetooth > NimBLE Options
Enable BLE 5.3 feature
Contains:
CONFIG_BT_NIMBLE_SUBRATE
Connection Subrate
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_53_FEATURE_SUPPORT
Enable support for Connection Subrate
CONFIG_BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM
Coexistence: limit on MAX Tx/Rx time for coded-PHY connection
Found in: Component config > Bluetooth > NimBLE Options
When using PHY-Coded in BLE connection, limitation on max tx/rx time can be applied to better avoid dramatic performance deterioration of Wi-Fi.
- Available options:
Force Enable (BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM_EN)
Always enable the limitation on max tx/rx time for Coded-PHY connection
Force Disable (BT_NIMBLE_COEX_PHY_CODED_TX_RX_TLIM_DIS)
Disable the limitation on max tx/rx time for Coded-PHY connection
CONFIG_BT_NIMBLE_52_FEATURE_SUPPORT
Enable BLE 5.2 Feature
Found in: Component config > Bluetooth > NimBLE Options
Enable this option to select 5.2 features
Contains:
CONFIG_BT_NIMBLE_BLE_POWER_CONTROL
Enable support for BLE Power Control
Found in: Component config > Bluetooth > NimBLE Options > CONFIG_BT_NIMBLE_52_FEATURE_SUPPORT
Set this option to enable the Power Control feature
CONFIG_BT_NIMBLE_WHITELIST_SIZE
BLE white list size
Found in: Component config > Bluetooth > NimBLE Options
BLE list size
- Range:
from 1 to 15 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
- Default value:
12 if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_TEST_THROUGHPUT_TEST
Throughput Test Mode enable
Found in: Component config > Bluetooth > NimBLE Options
Enable the throughput test mode
- Default value:
No (disabled) if BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_BLUFI_ENABLE
Enable blufi functionality
Found in: Component config > Bluetooth > NimBLE Options
Set this option to enable blufi functionality.
- Default value:
No (disabled) if BT_NIMBLE_ENABLED && BT_NIMBLE_ENABLED
CONFIG_BT_NIMBLE_USE_ESP_TIMER
Enable Esp Timer for Nimble
Found in: Component config > Bluetooth > NimBLE Options
Set this option to use Esp Timer which has higher priority timer instead of FreeRTOS timer
- Default value:
Yes (enabled) if BT_NIMBLE_ENABLED
Controller Options
Contains:
CONFIG_BTDM_CTRL_MODE
Bluetooth controller mode (BR/EDR/BLE/DUALMODE)
Found in: Component config > Bluetooth > Controller Options
Specify the bluetooth controller mode (BR/EDR, BLE or dual mode).
- Available options:
BLE Only (BTDM_CTRL_MODE_BLE_ONLY)
BR/EDR Only (BTDM_CTRL_MODE_BR_EDR_ONLY)
Bluetooth Dual Mode (BTDM_CTRL_MODE_BTDM)
CONFIG_BTDM_CTRL_BLE_MAX_CONN
BLE Max Connections
Found in: Component config > Bluetooth > Controller Options
BLE maximum connections of bluetooth controller. Each connection uses 1KB static DRAM whenever the BT controller is enabled.
- Range:
from 1 to 9 if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
- Default value:
3 if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN
BR/EDR ACL Max Connections
Found in: Component config > Bluetooth > Controller Options
BR/EDR ACL maximum connections of bluetooth controller. Each connection uses 1.2 KB DRAM whenever the BT controller is enabled.
- Range:
from 1 to 7 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
- Default value:
2 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_BR_EDR_MAX_SYNC_CONN
BR/EDR Sync(SCO/eSCO) Max Connections
Found in: Component config > Bluetooth > Controller Options
BR/EDR Synchronize maximum connections of bluetooth controller. Each connection uses 2 KB DRAM whenever the BT controller is enabled.
- Range:
from 0 to 3 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
- Default value:
0 if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_BR_EDR_SCO_DATA_PATH
BR/EDR Sync(SCO/eSCO) default data path
Found in: Component config > Bluetooth > Controller Options
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”
- Available options:
HCI (BTDM_CTRL_BR_EDR_SCO_DATA_PATH_HCI)
PCM (BTDM_CTRL_BR_EDR_SCO_DATA_PATH_PCM)
CONFIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM Signal Config (Role and Polar)
Found in: Component config > Bluetooth > Controller Options
- Default value:
Yes (enabled) if BTDM_CTRL_BR_EDR_SCO_DATA_PATH_PCM && BT_CONTROLLER_ENABLED
Contains:
CONFIG_BTDM_CTRL_PCM_ROLE
PCM Role
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM role can be configured as PCM master or PCM slave
- Available options:
PCM Master (BTDM_CTRL_PCM_ROLE_MASTER)
PCM Slave (BTDM_CTRL_PCM_ROLE_SLAVE)
CONFIG_BTDM_CTRL_PCM_POLAR
PCM Polar
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_CTRL_PCM_ROLE_EDGE_CONFIG
PCM polarity can be configured as Falling Edge or Rising Edge
- Available options:
Falling Edge (BTDM_CTRL_PCM_POLAR_FALLING_EDGE)
Rising Edge (BTDM_CTRL_PCM_POLAR_RISING_EDGE)
CONFIG_BTDM_CTRL_AUTO_LATENCY
Auto latency
Found in: Component config > Bluetooth > Controller Options
BLE auto latency, used to enhance classic BT performance while classic BT and BLE are enabled at the same time.
- Default value:
No (disabled) if BTDM_CTRL_MODE_BTDM && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT
Legacy Authentication Vendor Specific Event Enable
Found in: Component config > Bluetooth > Controller Options
To protect from BIAS attack during Legacy authentication, Legacy authentication Vendor specific event should be enabled
- Default value:
Yes (enabled) if (BTDM_CTRL_MODE_BR_EDR_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE
The cpu core which bluetooth controller run
Found in: Component config > Bluetooth > Controller Options
Specify the cpu core to run bluetooth controller. Can not specify no-affinity.
- Available options:
Core 0 (PRO CPU) (BTDM_CTRL_PINNED_TO_CORE_0)
Core 1 (APP CPU) (BTDM_CTRL_PINNED_TO_CORE_1)
CONFIG_BTDM_CTRL_HCI_MODE_CHOICE
HCI mode
Found in: Component config > Bluetooth > Controller Options
Speicify HCI mode as VHCI or UART(H4)
- Available options:
VHCI (BTDM_CTRL_HCI_MODE_VHCI)
Normal option. Mostly, choose this VHCI when bluetooth host run on ESP32, too.
UART(H4) (BTDM_CTRL_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
Contains:
CONFIG_BTDM_CTRL_HCI_UART_NO
UART Number for HCI
Found in: Component config > Bluetooth > Controller Options > HCI UART(H4) Options
Uart number for HCI. The available uart is UART1 and UART2.
- Range:
from 1 to 2 if BTDM_CTRL_HCI_MODE_UART_H4 && BT_CONTROLLER_ENABLED
- Default value:
1 if BTDM_CTRL_HCI_MODE_UART_H4 && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE
UART Baudrate for HCI
Found in: Component config > Bluetooth > Controller Options > HCI UART(H4) Options
UART Baudrate for HCI. Please use standard baudrate.
- Range:
from 115200 to 921600 if BTDM_CTRL_HCI_MODE_UART_H4 && BT_CONTROLLER_ENABLED
- Default value:
921600 if BTDM_CTRL_HCI_MODE_UART_H4 && BT_CONTROLLER_ENABLED
MODEM SLEEP Options
Contains:
CONFIG_BTDM_CTRL_MODEM_SLEEP
Bluetooth modem sleep
Found in: Component config > Bluetooth > Controller Options > MODEM SLEEP Options
Enable/disable bluetooth controller low power mode.
- Default value:
Yes (enabled) if BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_MODEM_SLEEP_MODE
Bluetooth Modem sleep mode
Found in: Component config > Bluetooth > Controller Options > MODEM SLEEP Options > CONFIG_BTDM_CTRL_MODEM_SLEEP
To select which strategy to use for modem sleep
- Available options:
ORIG Mode(sleep with low power clock) (BTDM_CTRL_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) (BTDM_CTRL_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_CTRL_LOW_POWER_CLOCK
Bluetooth low power clock
Found in: Component config > Bluetooth > Controller Options > MODEM SLEEP Options
Select the low power clock source for bluetooth controller. Bluetooth low power clock is the clock source to maintain time in sleep mode.
“Main crystal” option provides good accuracy and can support Dynamic Frequency Scaling to be used with Bluetooth modem sleep. Light sleep is not supported.
“External 32kHz crystal” option allows user to use a 32.768kHz crystal as Bluetooth low power clock. This option is allowed as long as External 32kHz crystal is configured as the system RTC clock source. This option provides good accuracy and supports Bluetooth modem sleep to be used alongside Dynamic Frequency Scaling or light sleep.
- Available options:
Main crystal (BTDM_CTRL_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 good performance in accuracy as the bluetooth low power clock source.
External 32kHz crystal (BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL)
External 32kHz crystal has a nominal frequency of 32.768kHz and provides good frequency stability. If used as Bluetooth low power clock, External 32kHz can support Bluetooth modem sleep to be used with both DFS and light sleep.
CONFIG_BTDM_BLE_SLEEP_CLOCK_ACCURACY
BLE Sleep Clock Accuracy
Found in: Component config > Bluetooth > Controller Options
BLE Sleep Clock Accuracy(SCA) for the local device is used to estimate window widening in BLE connection events. With a lower level of clock accuracy(e.g. 500ppm over 250ppm), the slave needs a larger RX window to synchronize with master in each anchor point, thus resulting in an increase of power consumption but a higher level of robustness in keeping connected. According to the requirements of Bluetooth Core specification 4.2, the worst-case accuracy of Classic Bluetooth low power oscialltor(LPO) is +/-250ppm in STANDBY and in low power modes such as sniff. For BLE the worst-case SCA is +/-500ppm.
“151ppm to 250ppm” option is the default value for Bluetooth Dual mode
- “251ppm to 500ppm” option can be used in BLE only mode when using external 32kHz crystal as
low power clock. This option is provided in case that BLE sleep clock has a lower level of accuracy, or other error sources contribute to the inaccurate timing during sleep.
- Available options:
251ppm to 500ppm (BTDM_BLE_DEFAULT_SCA_500PPM)
151ppm to 250ppm (BTDM_BLE_DEFAULT_SCA_250PPM)
CONFIG_BTDM_BLE_SCAN_DUPL
BLE Scan Duplicate Options
Found in: Component config > Bluetooth > Controller Options
This select enables parameters setting of BLE scan duplicate.
- Default value:
Yes (enabled) if (BTDM_CTRL_MODE_BTDM || BTDM_CTRL_MODE_BLE_ONLY) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_SCAN_DUPL_TYPE
Scan Duplicate Type
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_SCAN_DUPL
Scan duplicate have three ways. one is “Scan Duplicate By Device Address”, This way is to use advertiser address filtering. The adv packet of the same address is only allowed to be reported once. Another way is “Scan Duplicate By Device Address And Advertising Data”. This way is to use advertising data and device address filtering. All different adv packets with the same address are allowed to be reported. The last way is “Scan Duplicate By Advertising Data”. This way is to use advertising data filtering. All same advertising data only allow to be reported once even though they are from different devices.
- Available options:
Scan Duplicate By Device Address (BTDM_SCAN_DUPL_TYPE_DEVICE)
This way is to use advertiser address filtering. The adv packet of the same address is only allowed to be reported once
Scan Duplicate By Advertising Data (BTDM_SCAN_DUPL_TYPE_DATA)
This way is to use advertising data filtering. All same advertising data only allow to be reported once even though they are from different devices.
Scan Duplicate By Device Address And Advertising Data (BTDM_SCAN_DUPL_TYPE_DATA_DEVICE)
This way is to use advertising data and device address filtering. All different adv packets with the same address are allowed to be reported.
CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE
Maximum number of devices in scan duplicate filter
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_SCAN_DUPL
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.
- Range:
from 10 to 1000 if CONFIG_BTDM_BLE_SCAN_DUPL && BT_CONTROLLER_ENABLED
- Default value:
100 if CONFIG_BTDM_BLE_SCAN_DUPL && BT_CONTROLLER_ENABLED
CONFIG_BTDM_SCAN_DUPL_CACHE_REFRESH_PERIOD
Duplicate scan list refresh period (seconds)
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_SCAN_DUPL
If the period value is non-zero, the controller will periodically clear the device information stored in the scan duuplicate filter. If it is 0, the scan duuplicate filter will not be cleared until the scanning is disabled. Duplicate advertisements for this period should not be sent to the Host in advertising report events. There are two scenarios where the ADV packet will be repeatedly reported: 1. The duplicate scan cache is full, the controller will delete the oldest device information and add new device information. 2. When the refresh period is up, the controller will clear all device information and start filtering again.
- Range:
from 0 to 1000 if CONFIG_BTDM_BLE_SCAN_DUPL && BT_CONTROLLER_ENABLED
- Default value:
0 if CONFIG_BTDM_BLE_SCAN_DUPL && BT_CONTROLLER_ENABLED
CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN
Special duplicate scan mechanism for BLE Mesh scan
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_SCAN_DUPL
This enables the BLE scan duplicate for special BLE Mesh scan.
- Default value:
No (disabled) if CONFIG_BTDM_BLE_SCAN_DUPL && BT_CONTROLLER_ENABLED
CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE
Maximum number of Mesh adv packets in scan duplicate filter
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_SCAN_DUPL > CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN
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.
- Range:
from 10 to 1000 if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN && BT_CONTROLLER_ENABLED
- Default value:
100 if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED
BLE full scan feature supported
Found in: Component config > Bluetooth > Controller Options
The full scan function is mainly used to provide BLE scan performance. This is required for scenes with high scan performance requirements, such as BLE Mesh scenes.
- Default value:
Yes (enabled) if (BTDM_CTRL_MODE_BLE_ONLY || BTDM_CTRL_MODE_BTDM) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
BLE adv report flow control supported
Found in: Component config > Bluetooth > Controller Options
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.
- Default value:
Yes (enabled) if (BTDM_CTRL_MODE_BTDM || BTDM_CTRL_MODE_BLE_ONLY) && BT_CONTROLLER_ENABLED
CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM
BLE adv report flow control number
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
The number of unprocessed advertising report that Bluedroid can save.If you set BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM to a small value, this may cause adv packets lost. If you set BTDM_BLE_ADV_REPORT_FLOW_CTRL_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 BTDM_BLE_ADV_REPORT_FLOW_CTRL_NUM according to your system free memory and handle adv packets as fast as possible, otherwise it will cause adv packets lost.
- Range:
from 50 to 1000 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && BT_CONTROLLER_ENABLED
- Default value:
100 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && BT_CONTROLLER_ENABLED
CONFIG_BTDM_BLE_ADV_REPORT_DISCARD_THRSHOLD
BLE adv lost event threshold value
Found in: Component config > Bluetooth > Controller Options > CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP
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 BTDM_BLE_ADV_REPORT_DISCARD_THRSHOLD to a small value or printf every adv lost event, it may cause adv packets lost more.
- Range:
from 1 to 1000 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && BT_CONTROLLER_ENABLED
- Default value:
20 if CONFIG_BTDM_BLE_ADV_REPORT_FLOW_CTRL_SUPP && BT_CONTROLLER_ENABLED
CONFIG_BTDM_CTRL_HLI
High level interrupt
Found in: Component config > Bluetooth > Controller Options
Using Level 4 interrupt for Bluetooth.
- Default value:
Yes (enabled) if CONFIG_BT_ENABLED && BT_CONTROLLER_ENABLED
CONFIG_BLE_MESH
ESP BLE Mesh Support
Found in: Component config
This option enables ESP BLE Mesh support. The specific features that are available may depend on other features that have been enabled in the stack, such as Bluetooth Support, Bluedroid Support & GATT support.
Contains:
CONFIG_BLE_MESH_HCI_5_0
Support sending 20ms non-connectable adv packets
Found in: Component config > CONFIG_BLE_MESH
It is a temporary solution and needs further modifications.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_USE_DUPLICATE_SCAN
Support Duplicate Scan in BLE Mesh
Found in: Component config > CONFIG_BLE_MESH
Enable this option to allow using specific duplicate scan filter in BLE Mesh, and Scan Duplicate Type must be set by choosing the option in the Bluetooth Controller section in menuconfig, which is “Scan Duplicate By Device Address and Advertising Data”.
- Default value:
Yes (enabled) if BT_BLUEDROID_ENABLED && CONFIG_BLE_MESH
CONFIG_BLE_MESH_MEM_ALLOC_MODE
Memory allocation strategy
Found in: Component config > CONFIG_BLE_MESH
Allocation strategy for BLE Mesh stack, essentially provides ability to allocate all required dynamic allocations from,
Internal DRAM memory only
External SPIRAM memory only
Either internal or external memory based on default malloc() behavior in ESP-IDF
Internal IRAM memory wherever applicable else internal DRAM
Recommended mode here is always internal (*), since that is most preferred from security perspective. But if application requirement does not allow sufficient free internal memory then alternate mode can be selected.
(*) In case of ESP32-S2/ESP32-S3, hardware allows encryption of external SPIRAM contents provided hardware flash encryption feature is enabled. In that case, using external SPIRAM allocation strategy is also safe choice from security perspective.
- Available options:
Internal DRAM (BLE_MESH_MEM_ALLOC_MODE_INTERNAL)
External SPIRAM (BLE_MESH_MEM_ALLOC_MODE_EXTERNAL)
Default alloc mode (BLE_MESH_MEM_ALLOC_MODE_DEFAULT)
Enable this option to use the default memory allocation strategy when external SPIRAM is enabled. See the SPIRAM options for more details.
Internal IRAM (BLE_MESH_MEM_ALLOC_MODE_IRAM_8BIT)
Allows to use IRAM memory region as 8bit accessible region. Every unaligned (8bit or 16bit) access will result in an exception and incur penalty of certain clock cycles per unaligned read/write.
CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC
Enable FreeRTOS static allocation
Found in: Component config > CONFIG_BLE_MESH
Enable this option to use FreeRTOS static allocation APIs for BLE Mesh, which provides the ability to use different dynamic memory (i.e. SPIRAM or IRAM) for FreeRTOS objects. If this option is disabled, the FreeRTOS static allocation APIs will not be used, and internal DRAM will be allocated for FreeRTOS objects.
- Default value:
No (disabled) if (CONFIG_SPIRAM || CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY) && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC_MODE
Memory allocation for FreeRTOS objects
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FREERTOS_STATIC_ALLOC
Choose the memory to be used for FreeRTOS objects.
- Available options:
External SPIRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_EXTERNAL)
If enabled, BLE Mesh allocates dynamic memory from external SPIRAM for FreeRTOS objects, i.e. mutex, queue, and task stack. External SPIRAM can only be used for task stack when SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY is enabled. See the SPIRAM options for more details.
Internal IRAM (BLE_MESH_FREERTOS_STATIC_ALLOC_IRAM_8BIT)
If enabled, BLE Mesh allocates dynamic memory from internal IRAM for FreeRTOS objects, i.e. mutex, queue. Note: IRAM region cannot be used as task stack.
CONFIG_BLE_MESH_DEINIT
Support de-initialize BLE Mesh stack
Found in: Component config > CONFIG_BLE_MESH
If enabled, users can use the function esp_ble_mesh_deinit() to de-initialize the whole BLE Mesh stack.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
BLE Mesh and BLE coexistence support
Contains:
CONFIG_BLE_MESH_SUPPORT_BLE_ADV
Support sending normal BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support
When selected, users can send normal BLE advertising packets with specific API.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_BLE_ADV_BUF_COUNT
Number of advertising buffers for BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support > CONFIG_BLE_MESH_SUPPORT_BLE_ADV
Number of advertising buffers for BLE packets available.
- Range:
from 1 to 255 if CONFIG_BLE_MESH_SUPPORT_BLE_ADV && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_SUPPORT_BLE_SCAN
Support scanning normal BLE advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh and BLE coexistence support
When selected, users can register a callback and receive normal BLE advertising packets in the application layer.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_FAST_PROV
Enable BLE Mesh Fast Provisioning
Found in: Component config > CONFIG_BLE_MESH
Enable this option to allow BLE Mesh fast provisioning solution to be used. When there are multiple unprovisioned devices around, fast provisioning can greatly reduce the time consumption of the whole provisioning process. When this option is enabled, and after an unprovisioned device is provisioned into a node successfully, it can be changed to a temporary Provisioner.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_NODE
Support for BLE Mesh Node
Found in: Component config > CONFIG_BLE_MESH
Enable the device to be provisioned into a node. This option should be enabled when an unprovisioned device is going to be provisioned into a node and communicate with other nodes in the BLE Mesh network.
CONFIG_BLE_MESH_PROVISIONER
Support for BLE Mesh Provisioner
Found in: Component config > CONFIG_BLE_MESH
Enable the device to be a Provisioner. The option should be enabled when a device is going to act as a Provisioner and provision unprovisioned devices into the BLE Mesh network.
CONFIG_BLE_MESH_WAIT_FOR_PROV_MAX_DEV_NUM
Maximum number of unprovisioned devices that can be added to device queue
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many unprovisioned devices can be added to device queue for provisioning. Users can use this option to define the size of the queue in the bottom layer which is used to store unprovisioned device information (e.g. Device UUID, address).
- Range:
from 1 to 100 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_MAX_PROV_NODES
Maximum number of devices that can be provisioned by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned by a Provisioner. This value indicates the maximum number of unprovisioned devices which can be provisioned by a Provisioner. For instance, if the value is 6, it means the Provisioner can provision up to 6 unprovisioned devices. Theoretically a Provisioner without the limitation of its memory can provision up to 32766 unprovisioned devices, here we limit the maximum number to 100 just to limit the memory used by a Provisioner. The bigger the value is, the more memory it will cost by a Provisioner to store the information of nodes.
- Range:
from 1 to 1000 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PBA_SAME_TIME
Maximum number of PB-ADV running at the same time by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned at the same time using PB-ADV. For examples, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-ADV at the same time.
- Range:
from 1 to 10 if CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PBG_SAME_TIME
Maximum number of PB-GATT running at the same time by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many devices can be provisioned at the same time using PB-GATT. For example, if the value is 2, it means a Provisioner can provision two unprovisioned devices with PB-GATT at the same time.
- Range:
from 1 to 5 if CONFIG_BLE_MESH_PB_GATT && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PROVISIONER_SUBNET_COUNT
Maximum number of mesh subnets that can be created by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many subnets per network a Provisioner can create. Indeed, this value decides the number of network keys which can be added by a Provisioner.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PROVISIONER_APP_KEY_COUNT
Maximum number of application keys that can be owned by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
This option specifies how many application keys the Provisioner can have. Indeed, this value decides the number of the application keys which can be added by a Provisioner.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PROVISIONER_RECV_HB
Support receiving Heartbeat messages
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER
When this option is enabled, Provisioner can call specific functions to enable or disable receiving Heartbeat messages and notify them to the application layer.
- Default value:
No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PROVISIONER_RECV_HB_FILTER_SIZE
Maximum number of filter entries for receiving Heartbeat messages
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PROVISIONER > CONFIG_BLE_MESH_PROVISIONER_RECV_HB
This option specifies how many heartbeat filter entries Provisioner supports. The heartbeat filter (acceptlist or rejectlist) entries are used to store a list of SRC and DST which can be used to decide if a heartbeat message will be processed and notified to the application layer by Provisioner. Note: The filter is an empty rejectlist by default.
- Range:
from 1 to 1000 if CONFIG_BLE_MESH_PROVISIONER_RECV_HB && CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PROV
BLE Mesh Provisioning support
Found in: Component config > CONFIG_BLE_MESH
Enable this option to support BLE Mesh Provisioning functionality. For BLE Mesh, this option should be always enabled.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_PB_ADV
Provisioning support using the advertising bearer (PB-ADV)
Found in: Component config > CONFIG_BLE_MESH
Enable this option to allow the device to be provisioned over the advertising bearer. This option should be enabled if PB-ADV is going to be used during provisioning procedure.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_UNPROVISIONED_BEACON_INTERVAL
Interval between two consecutive Unprovisioned Device Beacon
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_PB_ADV
This option specifies the interval of sending two consecutive unprovisioned device beacon, users can use this option to change the frequency of sending unprovisioned device beacon. For example, if the value is 5, it means the unprovisioned device beacon will send every 5 seconds. When the option of BLE_MESH_FAST_PROV is selected, the value is better to be 3 seconds, or less.
- Range:
from 1 to 100 if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_PB_ADV && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PB_GATT
Provisioning support using GATT (PB-GATT)
Found in: Component config > CONFIG_BLE_MESH
Enable this option to allow the device to be provisioned over GATT. This option should be enabled if PB-GATT is going to be used during provisioning procedure.
# Virtual option enabled whenever any Proxy protocol is needed
CONFIG_BLE_MESH_PROXY
BLE Mesh Proxy protocol support
Found in: Component config > CONFIG_BLE_MESH
Enable this option to support BLE Mesh Proxy protocol used by PB-GATT and other proxy pdu transmission.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_GATT_PROXY_SERVER
BLE Mesh GATT Proxy Server
Found in: Component config > CONFIG_BLE_MESH
This option enables support for Mesh GATT Proxy Service, i.e. the ability to act as a proxy between a Mesh GATT Client and a Mesh network. This option should be enabled if a node is going to be a Proxy Server.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH
CONFIG_BLE_MESH_NODE_ID_TIMEOUT
Node Identity advertising timeout
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER
This option determines for how long the local node advertises using Node Identity. The given value is in seconds. The specification limits this to 60 seconds and lists it as the recommended value as well. So leaving the default value is the safest option. When an unprovisioned device is provisioned successfully and becomes a node, it will start to advertise using Node Identity during the time set by this option. And after that, Network ID will be advertised.
- Range:
from 1 to 60 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_PROXY_FILTER_SIZE
Maximum number of filter entries per Proxy Client
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_GATT_PROXY_SERVER
This option specifies how many Proxy Filter entries the local node supports. The entries of Proxy filter (whitelist or blacklist) are used to store a list of addresses which can be used to decide which messages will be forwarded to the Proxy Client by the Proxy Server.
- Range:
from 1 to 32767 if CONFIG_BLE_MESH_GATT_PROXY_SERVER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_GATT_PROXY_CLIENT
BLE Mesh GATT Proxy Client
Found in: Component config > CONFIG_BLE_MESH
This option enables support for Mesh GATT Proxy Client. The Proxy Client can use the GATT bearer to send mesh messages to a node that supports the advertising bearer.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_SETTINGS
Store BLE Mesh configuration persistently
Found in: Component config > CONFIG_BLE_MESH
When selected, the BLE Mesh stack will take care of storing/restoring the BLE Mesh configuration persistently in flash. If the device is a BLE Mesh node, when this option is enabled, the configuration of the device will be stored persistently, including unicast address, NetKey, AppKey, etc. And if the device is a BLE Mesh Provisioner, the information of the device will be stored persistently, including the information of provisioned nodes, NetKey, AppKey, etc.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_STORE_TIMEOUT
Delay (in seconds) before storing anything persistently
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines in seconds how soon any pending changes are actually written into persistent storage (flash) after a change occurs. The option allows nodes to delay a certain period of time to save proper information to flash. The default value is 0, which means information will be stored immediately once there are updates.
- Range:
from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_SEQ_STORE_RATE
How often the sequence number gets updated in storage
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines how often the local sequence number gets updated in persistent storage (i.e. flash). e.g. a value of 100 means that the sequence number will be stored to flash on every 100th increment. If the node sends messages very frequently a higher value makes more sense, whereas if the node sends infrequently a value as low as 0 (update storage for every increment) can make sense. When the stack gets initialized it will add sequence number to the last stored one, so that it starts off with a value that’s guaranteed to be larger than the last one used before power off.
- Range:
from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_RPL_STORE_TIMEOUT
Minimum frequency that the RPL gets updated in storage
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This value defines in seconds how soon the RPL (Replay Protection List) gets written to persistent storage after a change occurs. If the node receives messages frequently, then a large value is recommended. If the node receives messages rarely, then the value can be as low as 0 (which means the RPL is written into the storage immediately). Note that if the node operates in a security-sensitive case, and there is a risk of sudden power-off, then a value of 0 is strongly recommended. Otherwise, a power loss before RPL being written into the storage may introduce message replay attacks and system security will be in a vulnerable state.
- Range:
from 0 to 1000000 if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_SETTINGS_BACKWARD_COMPATIBILITY
A specific option for settings backward compatibility
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
This option is created to solve the issue of failure in recovering node information after mesh stack updates. In the old version mesh stack, there is no key of “mesh/role” in nvs. In the new version mesh stack, key of “mesh/role” is added in nvs, recovering node information needs to check “mesh/role” key in nvs and implements selective recovery of mesh node information. Therefore, there may be failure in recovering node information during node restarting after OTA.
The new version mesh stack adds the option of “mesh/role” because we have added the support of storing Provisioner information, while the old version only supports storing node information.
If users are updating their nodes from old version to new version, we recommend enabling this option, so that system could set the flag in advance before recovering node information and make sure the node information recovering could work as expected.
- Default value:
No (disabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SPECIFIC_PARTITION
Use a specific NVS partition for BLE Mesh
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
When selected, the mesh stack will use a specified NVS partition instead of default NVS partition. Note that the specified partition must be registered with NVS using nvs_flash_init_partition() API, and the partition must exists in the csv file. When Provisioner needs to store a large amount of nodes’ information in the flash (e.g. more than 20), this option is recommended to be enabled.
- Default value:
No (disabled) if CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_PARTITION_NAME
Name of the NVS partition for BLE Mesh
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CONFIG_BLE_MESH_SPECIFIC_PARTITION
This value defines the name of the specified NVS partition used by the mesh stack.
- Default value:
“ble_mesh” if CONFIG_BLE_MESH_SPECIFIC_PARTITION && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
Support using multiple NVS namespaces by Provisioner
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS
When selected, Provisioner can use different NVS namespaces to store different instances of mesh information. For example, if in the first room, Provisioner uses NetKey A, AppKey A and provisions three devices, these information will be treated as mesh information instance A. When the Provisioner moves to the second room, it uses NetKey B, AppKey B and provisions two devices, then the information will be treated as mesh information instance B. Here instance A and instance B will be stored in different namespaces. With this option enabled, Provisioner needs to use specific functions to open the corresponding NVS namespace, restore the mesh information, release the mesh information or erase the mesh information.
- Default value:
No (disabled) if CONFIG_BLE_MESH_PROVISIONER && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
CONFIG_BLE_MESH_MAX_NVS_NAMESPACE
Maximum number of NVS namespaces
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_SETTINGS > CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE
This option specifies the maximum NVS namespaces supported by Provisioner.
- Range:
from 1 to 255 if CONFIG_BLE_MESH_USE_MULTIPLE_NAMESPACE && CONFIG_BLE_MESH_SETTINGS && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_SUBNET_COUNT
Maximum number of mesh subnets per network
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many subnets a Mesh network can have at the same time. Indeed, this value decides the number of the network keys which can be owned by a node.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH
- Default value:
3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_APP_KEY_COUNT
Maximum number of application keys per network
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many application keys the device can store per network. Indeed, this value decides the number of the application keys which can be owned by a node.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH
- Default value:
3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_MODEL_KEY_COUNT
Maximum number of application keys per model
Found in: Component config > CONFIG_BLE_MESH
This option specifies the maximum number of application keys to which each model can be bound.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH
- Default value:
3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_MODEL_GROUP_COUNT
Maximum number of group address subscriptions per model
Found in: Component config > CONFIG_BLE_MESH
This option specifies the maximum number of addresses to which each model can be subscribed.
- Range:
from 1 to 4096 if CONFIG_BLE_MESH
- Default value:
3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_LABEL_COUNT
Maximum number of Label UUIDs used for Virtual Addresses
Found in: Component config > CONFIG_BLE_MESH
This option specifies how many Label UUIDs can be stored. Indeed, this value decides the number of the Virtual Addresses can be supported by a node.
- Range:
from 0 to 4096 if CONFIG_BLE_MESH
- Default value:
3 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_CRPL
Maximum capacity of the replay protection list
Found in: Component config > CONFIG_BLE_MESH
This option specifies the maximum capacity of the replay protection list. It is similar to Network message cache size, but has a different purpose. The replay protection list is used to prevent a node from replay attack, which will store the source address and sequence number of the received mesh messages. For Provisioner, the replay protection list size should not be smaller than the maximum number of nodes whose information can be stored. And the element number of each node should also be taken into consideration. For example, if Provisioner can provision up to 20 nodes and each node contains two elements, then the replay protection list size of Provisioner should be at least 40.
- Range:
from 2 to 65535 if CONFIG_BLE_MESH
- Default value:
10 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_MSG_CACHE_SIZE
Network message cache size
Found in: Component config > CONFIG_BLE_MESH
Number of messages that are cached for the network. This helps prevent unnecessary decryption operations and unnecessary relays. This option is similar to Replay protection list, but has a different purpose. A node is not required to cache the entire Network PDU and may cache only part of it for tracking, such as values for SRC/SEQ or others.
- Range:
from 2 to 65535 if CONFIG_BLE_MESH
- Default value:
10 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_ADV_BUF_COUNT
Number of advertising buffers
Found in: Component config > CONFIG_BLE_MESH
Number of advertising buffers available. The transport layer reserves ADV_BUF_COUNT - 3 buffers for outgoing segments. The maximum outgoing SDU size is 12 times this value (out of which 4 or 8 bytes are used for the Transport Layer MIC). For example, 5 segments means the maximum SDU size is 60 bytes, which leaves 56 bytes for application layer data using a 4-byte MIC, or 52 bytes using an 8-byte MIC.
- Range:
from 6 to 256 if CONFIG_BLE_MESH
- Default value:
60 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_IVU_DIVIDER
Divider for IV Update state refresh timer
Found in: Component config > CONFIG_BLE_MESH
When the IV Update state enters Normal operation or IV Update in Progress, we need to keep track of how many hours has passed in the state, since the specification requires us to remain in the state at least for 96 hours (Update in Progress has an additional upper limit of 144 hours).
In order to fulfill the above requirement, even if the node might be powered off once in a while, we need to store persistently how many hours the node has been in the state. This doesn’t necessarily need to happen every hour (thanks to the flexible duration range). The exact cadence will depend a lot on the ways that the node will be used and what kind of power source it has.
Since there is no single optimal answer, this configuration option allows specifying a divider, i.e. how many intervals the 96 hour minimum gets split into. After each interval the duration that the node has been in the current state gets stored to flash. E.g. the default value of 4 means that the state is saved every 24 hours (96 / 4).
- Range:
from 2 to 96 if CONFIG_BLE_MESH
- Default value:
4 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_IVU_RECOVERY_IVI
Recovery the IV index when the latest whole IV update procedure is missed
Found in: Component config > CONFIG_BLE_MESH
According to Section 3.10.5 of Mesh Specification v1.0.1. If a node in Normal Operation receives a Secure Network beacon with an IV index equal to the last known IV index+1 and the IV Update Flag set to 0, the node may update its IV without going to the IV Update in Progress state, or it may initiate an IV Index Recovery procedure (Section 3.10.6), or it may ignore the Secure Network beacon. The node makes the choice depending on the time since last IV update and the likelihood that the node has missed the Secure Network beacons with the IV update Flag. When the above situation is encountered, this option can be used to decide whether to perform the IV index recovery procedure.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TX_SEG_MSG_COUNT
Maximum number of simultaneous outgoing segmented messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of simultaneous outgoing multi-segment and/or reliable messages. The default value is 1, which means the device can only send one segmented message at a time. And if another segmented message is going to be sent, it should wait for the completion of the previous one. If users are going to send multiple segmented messages at the same time, this value should be configured properly.
- Range:
from 1 to if CONFIG_BLE_MESH
- Default value:
1 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_RX_SEG_MSG_COUNT
Maximum number of simultaneous incoming segmented messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of simultaneous incoming multi-segment and/or reliable messages. The default value is 1, which means the device can only receive one segmented message at a time. And if another segmented message is going to be received, it should wait for the completion of the previous one. If users are going to receive multiple segmented messages at the same time, this value should be configured properly.
- Range:
from 1 to 255 if CONFIG_BLE_MESH
- Default value:
1 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_RX_SDU_MAX
Maximum incoming Upper Transport Access PDU length
Found in: Component config > CONFIG_BLE_MESH
Maximum incoming Upper Transport Access PDU length. Leave this to the default value, unless you really need to optimize memory usage.
- Range:
from 36 to 384 if CONFIG_BLE_MESH
- Default value:
384 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TX_SEG_MAX
Maximum number of segments in outgoing messages
Found in: Component config > CONFIG_BLE_MESH
Maximum number of segments supported for outgoing messages. This value should typically be fine-tuned based on what models the local node supports, i.e. what’s the largest message payload that the node needs to be able to send. This value affects memory and call stack consumption, which is why the default is lower than the maximum that the specification would allow (32 segments).
The maximum outgoing SDU size is 12 times this number (out of which 4 or 8 bytes is used for the Transport Layer MIC). For example, 5 segments means the maximum SDU size is 60 bytes, which leaves 56 bytes for application layer data using a 4-byte MIC and 52 bytes using an 8-byte MIC.
Be sure to specify a sufficient number of advertising buffers when setting this option to a higher value. There must be at least three more advertising buffers (BLE_MESH_ADV_BUF_COUNT) as there are outgoing segments.
- Range:
from 2 to 32 if CONFIG_BLE_MESH
- Default value:
32 if CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY
Relay support
Found in: Component config > CONFIG_BLE_MESH
Support for acting as a Mesh Relay Node. Enabling this option will allow a node to support the Relay feature, and the Relay feature can still be enabled or disabled by proper configuration messages. Disabling this option will let a node not support the Relay feature.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH_NODE && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF
Use separate advertising buffers for relay packets
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY
When selected, self-send packets will be put in a high-priority queue and relay packets will be put in a low-priority queue.
- Default value:
No (disabled) if CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
CONFIG_BLE_MESH_RELAY_ADV_BUF_COUNT
Number of advertising buffers for relay packets
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_RELAY > CONFIG_BLE_MESH_RELAY_ADV_BUF
Number of advertising buffers for relay packets available.
- Range:
from 6 to 256 if CONFIG_BLE_MESH_RELAY_ADV_BUF && CONFIG_BLE_MESH_RELAY && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LOW_POWER
Support for Low Power features
Found in: Component config > CONFIG_BLE_MESH
Enable this option to operate as a Low Power Node. If low power consumption is required by a node, this option should be enabled. And once the node enters the mesh network, it will try to find a Friend node and establish a friendship.
CONFIG_BLE_MESH_LPN_ESTABLISHMENT
Perform Friendship establishment using low power
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Perform the Friendship establishment using low power with the help of a reduced scan duty cycle. The downside of this is that the node may miss out on messages intended for it until it has successfully set up Friendship with a Friend node. When this option is enabled, the node will stop scanning for a period of time after a Friend Request or Friend Poll is sent, so as to reduce more power consumption.
- Default value:
No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_AUTO
Automatically start looking for Friend nodes once provisioned
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Once provisioned, automatically enable LPN functionality and start looking for Friend nodes. If this option is disabled LPN mode needs to be manually enabled by calling bt_mesh_lpn_set(true). When an unprovisioned device is provisioned successfully and becomes a node, enabling this option will trigger the node starts to send Friend Request at a certain period until it finds a proper Friend node.
- Default value:
No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_AUTO_TIMEOUT
Time from last received message before going to LPN mode
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER > CONFIG_BLE_MESH_LPN_AUTO
Time in seconds from the last received message, that the node waits out before starting to look for Friend nodes.
- Range:
from 0 to 3600 if CONFIG_BLE_MESH_LPN_AUTO && CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_RETRY_TIMEOUT
Retry timeout for Friend requests
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Time in seconds between Friend Requests, if a previous Friend Request did not yield any acceptable Friend Offers.
- Range:
from 1 to 3600 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_RSSI_FACTOR
RSSIFactor, used in Friend Offer Delay calculation
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The contribution of the RSSI, measured by the Friend node, used in Friend Offer Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5. RSSIFactor, one of the parameters carried by Friend Request sent by Low Power node, which is used to calculate the Friend Offer Delay.
- Range:
from 0 to 3 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_RECV_WIN_FACTOR
ReceiveWindowFactor, used in Friend Offer Delay calculation
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The contribution of the supported Receive Window used in Friend Offer Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5. ReceiveWindowFactor, one of the parameters carried by Friend Request sent by Low Power node, which is used to calculate the Friend Offer Delay.
- Range:
from 0 to 3 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_MIN_QUEUE_SIZE
Minimum size of the acceptable friend queue (MinQueueSizeLog)
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The MinQueueSizeLog field is defined as log_2(N), where N is the minimum number of maximum size Lower Transport PDUs that the Friend node can store in its Friend Queue. As an example, MinQueueSizeLog value 1 gives N = 2, and value 7 gives N = 128.
- Range:
from 1 to 7 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_RECV_DELAY
Receive delay requested by the local node
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The ReceiveDelay is the time between the Low Power node sending a request and listening for a response. This delay allows the Friend node time to prepare the response. The value is in units of milliseconds.
- Range:
from 10 to 255 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
100 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_POLL_TIMEOUT
The value of the PollTimeout timer
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
PollTimeout timer is used to measure time between two consecutive requests sent by a Low Power node. If no requests are received the Friend node before the PollTimeout timer expires, then the friendship is considered terminated. The value is in units of 100 milliseconds, so e.g. a value of 300 means 30 seconds. The smaller the value, the faster the Low Power node tries to get messages from corresponding Friend node and vice versa.
- Range:
from 10 to 244735 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
300 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_INIT_POLL_TIMEOUT
The starting value of the PollTimeout timer
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
The initial value of the PollTimeout timer when Friendship is to be established for the first time. After this, the timeout gradually grows toward the actual PollTimeout, doubling in value for each iteration. The value is in units of 100 milliseconds, so e.g. a value of 300 means 30 seconds.
- Range:
from 10 to if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_SCAN_LATENCY
Latency for enabling scanning
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Latency (in milliseconds) is the time it takes to enable scanning. In practice, it means how much time in advance of the Receive Window, the request to enable scanning is made.
- Range:
from 0 to 50 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
10 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_LPN_GROUPS
Number of groups the LPN can subscribe to
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Maximum number of groups to which the LPN can subscribe.
- Range:
from 0 to 16384 if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_LPN_SUB_ALL_NODES_ADDR
Automatically subscribe all nodes address
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_LOW_POWER
Automatically subscribe all nodes address when friendship established.
- Default value:
No (disabled) if CONFIG_BLE_MESH_LOW_POWER && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND
Support for Friend feature
Found in: Component config > CONFIG_BLE_MESH
Enable this option to be able to act as a Friend Node.
CONFIG_BLE_MESH_FRIEND_RECV_WIN
Friend Receive Window
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Receive Window in milliseconds supported by the Friend node.
- Range:
from 1 to 255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
- Default value:
255 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_QUEUE_SIZE
Minimum number of buffers supported per Friend Queue
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Minimum number of buffers available to be stored for each local Friend Queue. This option decides the size of each buffer which can be used by a Friend node to store messages for each Low Power node.
- Range:
from 2 to 65536 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
- Default value:
16 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
CONFIG_BLE_MESH_FRIEND_SUB_LIST_SIZE
Friend Subscription List Size
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Size of the Subscription List that can be supported by a Friend node for a Low Power node. And Low Power node can send Friend Subscription List Add or Friend Subscription List Remove messages to the Friend node to add or remove subscription addresses.
- Range:
from 0 to 1023 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_FRIEND_LPN_COUNT
Number of supported LPN nodes
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Number of Low Power Nodes with which a Friend can have Friendship simultaneously. A Friend node can have friendship with multiple Low Power nodes at the same time, while a Low Power node can only establish friendship with only one Friend node at the same time.
- Range:
from 1 to 1000 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_FRIEND_SEG_RX
Number of incomplete segment lists per LPN
Found in: Component config > CONFIG_BLE_MESH > CONFIG_BLE_MESH_FRIEND
Number of incomplete segment lists tracked for each Friends’ LPN. In other words, this determines from how many elements can segmented messages destined for the Friend queue be received simultaneously.
- Range:
from 1 to 1000 if CONFIG_BLE_MESH_FRIEND && CONFIG_BLE_MESH
- Default value:
CONFIG_BLE_MESH_NO_LOG
Disable BLE Mesh debug logs (minimize bin size)
Found in: Component config > CONFIG_BLE_MESH
Select this to save the BLE Mesh related rodata code size. Enabling this option will disable the output of BLE Mesh debug log.
- Default value:
No (disabled) if CONFIG_BLE_MESH && CONFIG_BLE_MESH
BLE Mesh STACK DEBUG LOG LEVEL
Contains:
CONFIG_BLE_MESH_STACK_TRACE_LEVEL
BLE_MESH_STACK
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh STACK DEBUG LOG LEVEL
Define BLE Mesh trace level for BLE Mesh stack.
- Available options:
NONE (BLE_MESH_TRACE_LEVEL_NONE)
ERROR (BLE_MESH_TRACE_LEVEL_ERROR)
WARNING (BLE_MESH_TRACE_LEVEL_WARNING)
INFO (BLE_MESH_TRACE_LEVEL_INFO)
DEBUG (BLE_MESH_TRACE_LEVEL_DEBUG)
VERBOSE (BLE_MESH_TRACE_LEVEL_VERBOSE)
BLE Mesh NET BUF DEBUG LOG LEVEL
Contains:
CONFIG_BLE_MESH_NET_BUF_TRACE_LEVEL
BLE_MESH_NET_BUF
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh NET BUF DEBUG LOG LEVEL
Define BLE Mesh trace level for BLE Mesh net buffer.
- Available options:
NONE (BLE_MESH_NET_BUF_TRACE_LEVEL_NONE)
ERROR (BLE_MESH_NET_BUF_TRACE_LEVEL_ERROR)
WARNING (BLE_MESH_NET_BUF_TRACE_LEVEL_WARNING)
INFO (BLE_MESH_NET_BUF_TRACE_LEVEL_INFO)
DEBUG (BLE_MESH_NET_BUF_TRACE_LEVEL_DEBUG)
VERBOSE (BLE_MESH_NET_BUF_TRACE_LEVEL_VERBOSE)
CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT
Timeout(ms) for client message response
Found in: Component config > CONFIG_BLE_MESH
Timeout value used by the node to get response of the acknowledged message which is sent by the client model. This value indicates the maximum time that a client model waits for the response of the sent acknowledged messages. If a client model uses 0 as the timeout value when sending acknowledged messages, then the default value will be used which is four seconds.
- Range:
from 100 to 1200000 if CONFIG_BLE_MESH
- Default value:
4000 if CONFIG_BLE_MESH
Support for BLE Mesh Foundation models
Contains:
CONFIG_BLE_MESH_CFG_CLI
Configuration Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models
Enable support for Configuration Client model.
CONFIG_BLE_MESH_HEALTH_CLI
Health Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models
Enable support for Health Client model.
CONFIG_BLE_MESH_HEALTH_SRV
Health Server model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Foundation models
Enable support for Health Server model.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
Support for BLE Mesh Client/Server models
Contains:
CONFIG_BLE_MESH_GENERIC_ONOFF_CLI
Generic OnOff Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic OnOff Client model.
CONFIG_BLE_MESH_GENERIC_LEVEL_CLI
Generic Level Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Level Client model.
CONFIG_BLE_MESH_GENERIC_DEF_TRANS_TIME_CLI
Generic Default Transition Time Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Default Transition Time Client model.
CONFIG_BLE_MESH_GENERIC_POWER_ONOFF_CLI
Generic Power OnOff Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Power OnOff Client model.
CONFIG_BLE_MESH_GENERIC_POWER_LEVEL_CLI
Generic Power Level Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Power Level Client model.
CONFIG_BLE_MESH_GENERIC_BATTERY_CLI
Generic Battery Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Battery Client model.
CONFIG_BLE_MESH_GENERIC_LOCATION_CLI
Generic Location Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Location Client model.
CONFIG_BLE_MESH_GENERIC_PROPERTY_CLI
Generic Property Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic Property Client model.
CONFIG_BLE_MESH_SENSOR_CLI
Sensor Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Sensor Client model.
CONFIG_BLE_MESH_TIME_CLI
Time Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Time Client model.
CONFIG_BLE_MESH_SCENE_CLI
Scene Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Scene Client model.
CONFIG_BLE_MESH_SCHEDULER_CLI
Scheduler Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Scheduler Client model.
CONFIG_BLE_MESH_LIGHT_LIGHTNESS_CLI
Light Lightness Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Light Lightness Client model.
CONFIG_BLE_MESH_LIGHT_CTL_CLI
Light CTL Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Light CTL Client model.
CONFIG_BLE_MESH_LIGHT_HSL_CLI
Light HSL Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Light HSL Client model.
CONFIG_BLE_MESH_LIGHT_XYL_CLI
Light XYL Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Light XYL Client model.
CONFIG_BLE_MESH_LIGHT_LC_CLI
Light LC Client model
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Light LC Client model.
CONFIG_BLE_MESH_GENERIC_SERVER
Generic server models
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Generic server models.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_SENSOR_SERVER
Sensor server models
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Sensor server models.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TIME_SCENE_SERVER
Time and Scenes server models
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Time and Scenes server models.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_LIGHTING_SERVER
Lighting server models
Found in: Component config > CONFIG_BLE_MESH > Support for BLE Mesh Client/Server models
Enable support for Lighting server models.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_IV_UPDATE_TEST
Test the IV Update Procedure
Found in: Component config > CONFIG_BLE_MESH
This option removes the 96 hour limit of the IV Update Procedure and lets the state to be changed at any time. If IV Update test mode is going to be used, this option should be enabled.
- Default value:
No (disabled) if CONFIG_BLE_MESH
BLE Mesh specific test option
Contains:
CONFIG_BLE_MESH_SELF_TEST
Perform BLE Mesh self-tests
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option
This option adds extra self-tests which are run every time BLE Mesh networking is initialized.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_TEST_AUTO_ENTER_NETWORK
Unprovisioned device enters mesh network automatically
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_SELF_TEST
With this option enabled, an unprovisioned device can automatically enters mesh network using a specific test function without the pro- visioning procedure. And on the Provisioner side, a test function needs to be invoked to add the node information into the mesh stack.
- Default value:
Yes (enabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_TEST_USE_WHITE_LIST
Use white list to filter mesh advertising packets
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_SELF_TEST
With this option enabled, users can use white list to filter mesh advertising packets while scanning.
- Default value:
No (disabled) if CONFIG_BLE_MESH_SELF_TEST && CONFIG_BLE_MESH
CONFIG_BLE_MESH_SHELL
Enable BLE Mesh shell
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option
Activate shell module that provides BLE Mesh commands to the console.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_DEBUG
Enable BLE Mesh debug logs
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option
Enable debug logs for the BLE Mesh functionality.
- Default value:
No (disabled) if CONFIG_BLE_MESH
CONFIG_BLE_MESH_DEBUG_NET
Network layer debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Network layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_TRANS
Transport layer debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Transport layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_BEACON
Beacon debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Beacon-related debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_CRYPTO
Crypto debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable cryptographic debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROV
Provisioning debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Provisioning debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_ACCESS
Access layer debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Access layer debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_MODEL
Foundation model debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Foundation Models debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_ADV
Advertising debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable advertising debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_LOW_POWER
Low Power debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Low Power debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_FRIEND
Friend debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Friend debug logs for the BLE Mesh functionality.
CONFIG_BLE_MESH_DEBUG_PROXY
Proxy debug
Found in: Component config > CONFIG_BLE_MESH > BLE Mesh specific test option > CONFIG_BLE_MESH_DEBUG
Enable Proxy protocol debug logs for the BLE Mesh functionality.
Driver Configurations
Contains:
Legacy ADC Configuration
Contains:
CONFIG_ADC_DISABLE_DAC
Disable DAC when ADC2 is used on GPIO 25 and 26
Found in: Component config > Driver Configurations > Legacy ADC Configuration
If this is set, the ADC2 driver will disable 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.
- Default value:
Yes (enabled)
CONFIG_ADC_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > Legacy ADC Configuration
Wether to suppress the deprecation warnings when using legacy adc driver (driver/adc.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
Legacy ADC Calibration Configuration
Contains:
CONFIG_ADC_CAL_EFUSE_TP_ENABLE
Use Two Point Values
Found in: Component config > Driver Configurations > Legacy ADC Configuration > Legacy ADC Calibration Configuration
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.
- Default value:
Yes (enabled)
CONFIG_ADC_CAL_EFUSE_VREF_ENABLE
Use eFuse Vref
Found in: Component config > Driver Configurations > Legacy ADC Configuration > Legacy ADC Calibration Configuration
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.
- Default value:
Yes (enabled)
CONFIG_ADC_CAL_LUT_ENABLE
Use Lookup Tables
Found in: Component config > Driver Configurations > Legacy ADC Configuration > Legacy ADC Calibration Configuration
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.
- Default value:
Yes (enabled)
CONFIG_ADC_CALI_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > Legacy ADC Configuration > Legacy ADC Calibration Configuration
Wether to suppress the deprecation warnings when using legacy adc calibration driver (esp_adc_cal.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
SPI Configuration
Contains:
CONFIG_SPI_MASTER_IN_IRAM
Place transmitting functions of SPI master into IRAM
Found in: Component config > Driver Configurations > SPI Configuration
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
andtransmit
functions into the IRAM to avoid possible cache miss.During unit test, this is enabled to measure the ideal case of api.
- Default value:
No (disabled)
CONFIG_SPI_MASTER_ISR_IN_IRAM
Place SPI master ISR function into IRAM
Found in: Component config > Driver Configurations > SPI Configuration
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.
- Default value:
Yes (enabled)
CONFIG_SPI_SLAVE_IN_IRAM
Place transmitting functions of SPI slave into IRAM
Found in: Component config > Driver Configurations > SPI Configuration
Normally only the ISR of SPI slave 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
andtransmit
functions into the IRAM to avoid possible cache miss.
- Default value:
No (disabled)
CONFIG_SPI_SLAVE_ISR_IN_IRAM
Place SPI slave ISR function into IRAM
Found in: Component config > Driver Configurations > SPI Configuration
Place the SPI slave 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.
- Default value:
Yes (enabled)
TWAI Configuration
Contains:
CONFIG_TWAI_ISR_IN_IRAM
Place TWAI ISR function into IRAM
Found in: Component config > Driver Configurations > TWAI Configuration
Place the TWAI ISR in to IRAM. This will allow the ISR to avoid cache misses, and also be able to run whilst the cache is disabled (such as when writing to SPI Flash). Note that if this option is enabled: - Users should also set the ESP_INTR_FLAG_IRAM in the driver configuration structure when installing the driver (see docs for specifics). - Alert logging (i.e., setting of the TWAI_ALERT_AND_LOG flag) will have no effect.
- Default value:
No (disabled)
CONFIG_TWAI_ERRATA_FIX_BUS_OFF_REC
Add SW workaround for REC change during bus-off
Found in: Component config > Driver Configurations > TWAI Configuration
When the bus-off condition is reached, the REC should be reset to 0 and frozen (via LOM) by the driver’s ISR. However on the ESP32, there is an edge case where the REC will increase before the driver’s ISR can respond in time (e.g., due to the rapid occurrence of bus errors), thus causing the REC to be non-zero after bus-off. A non-zero REC can prevent bus-off recovery as the bus-off recovery condition is that both TEC and REC become 0. Enabling this option will add a workaround in the driver to forcibly reset REC to zero on reaching bus-off.
- Default value:
Yes (enabled)
CONFIG_TWAI_ERRATA_FIX_TX_INTR_LOST
Add SW workaround for TX interrupt lost errata
Found in: Component config > Driver Configurations > TWAI Configuration
On the ESP32, when a transmit interrupt occurs, and interrupt register is read on the same APB clock cycle, the transmit interrupt could be lost. Enabling this option will add a workaround that checks the transmit buffer status bit to recover any lost transmit interrupt.
- Default value:
Yes (enabled)
CONFIG_TWAI_ERRATA_FIX_RX_FRAME_INVALID
Add SW workaround for invalid RX frame errata
Found in: Component config > Driver Configurations > TWAI Configuration
On the ESP32, when receiving a data or remote frame, if a bus error occurs in the data or CRC field, the data of the next received frame could be invalid. Enabling this option will add a workaround that will reset the peripheral on detection of this errata condition. Note that if a frame is transmitted on the bus whilst the reset is ongoing, the message will not be receive by the peripheral sent on the bus during the reset, the message will be lost.
- Default value:
Yes (enabled)
CONFIG_TWAI_ERRATA_FIX_RX_FIFO_CORRUPT
Add SW workaround for RX FIFO corruption errata
Found in: Component config > Driver Configurations > TWAI Configuration
On the ESP32, when the RX FIFO overruns and the RX message counter maxes out at 64 messages, the entire RX FIFO is no longer recoverable. Enabling this option will add a workaround that resets the peripheral on detection of this errata condition. Note that if a frame is being sent on the bus during the reset bus during the reset, the message will be lost.
- Default value:
Yes (enabled)
Temperature sensor Configuration
Contains:
CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > Temperature sensor Configuration
Wether to suppress the deprecation warnings when using legacy temperature sensor driver (driver/temp_sensor.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled) if SOC_TEMP_SENSOR_SUPPORTED
CONFIG_TEMP_SENSOR_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > Temperature sensor Configuration
Wether to enable the debug log message for temperature sensor driver. Note that, this option only controls the temperature sensor driver log, won’t affect other drivers.
- Default value:
No (disabled) if SOC_TEMP_SENSOR_SUPPORTED
UART Configuration
Contains:
CONFIG_UART_ISR_IN_IRAM
Place UART ISR function into IRAM
Found in: Component config > Driver Configurations > UART Configuration
If this option is not selected, UART interrupt will be disabled for a long time and may cause data lost when doing spi flash operation.
- Default value:
No (disabled) if CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH
GPIO Configuration
Contains:
CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL
Support light sleep GPIO pullup/pulldown configuration for ESP32
Found in: Component config > Driver Configurations > GPIO Configuration
This option is intended to fix the bug that ESP32 is not able to switch to configured pullup/pulldown mode in sleep. If this option is selected, chip will automatically emulate the behaviour of switching, and about 450B of source codes would be placed into IRAM.
CONFIG_GPIO_CTRL_FUNC_IN_IRAM
Place GPIO control functions into IRAM
Found in: Component config > Driver Configurations > GPIO Configuration
Place GPIO control functions (like intr_disable/set_level) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context.
- Default value:
No (disabled)
Sigma Delta Modulator Configuration
Contains:
CONFIG_SDM_CTRL_FUNC_IN_IRAM
Place SDM control functions into IRAM
Found in: Component config > Driver Configurations > Sigma Delta Modulator Configuration
Place SDM control functions (like set_duty) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well.
- Default value:
No (disabled)
CONFIG_SDM_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > Sigma Delta Modulator Configuration
Wether to suppress the deprecation warnings when using legacy sigma delta driver. If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
CONFIG_SDM_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > Sigma Delta Modulator Configuration
Wether to enable the debug log message for SDM driver. Note that, this option only controls the SDM driver log, won’t affect other drivers.
- Default value:
No (disabled)
GPTimer Configuration
Contains:
CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM
Place GPTimer control functions into IRAM
Found in: Component config > Driver Configurations > GPTimer Configuration
Place GPTimer control functions (like start/stop) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well.
- Default value:
No (disabled)
CONFIG_GPTIMER_ISR_IRAM_SAFE
GPTimer ISR IRAM-Safe
Found in: Component config > Driver Configurations > GPTimer Configuration
Ensure the GPTimer interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write).
- Default value:
No (disabled)
CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > GPTimer Configuration
Wether to suppress the deprecation warnings when using legacy timer group driver (driver/timer.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
CONFIG_GPTIMER_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > GPTimer Configuration
Wether to enable the debug log message for GPTimer driver. Note that, this option only controls the GPTimer driver log, won’t affect other drivers.
- Default value:
No (disabled)
PCNT Configuration
Contains:
CONFIG_PCNT_CTRL_FUNC_IN_IRAM
Place PCNT control functions into IRAM
Found in: Component config > Driver Configurations > PCNT Configuration
Place PCNT control functions (like start/stop) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well.
- Default value:
No (disabled)
CONFIG_PCNT_ISR_IRAM_SAFE
PCNT ISR IRAM-Safe
Found in: Component config > Driver Configurations > PCNT Configuration
Ensure the PCNT interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write).
- Default value:
No (disabled)
CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > PCNT Configuration
Wether to suppress the deprecation warnings when using legacy PCNT driver (driver/pcnt.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
CONFIG_PCNT_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > PCNT Configuration
Wether to enable the debug log message for PCNT driver. Note that, this option only controls the PCNT driver log, won’t affect other drivers.
- Default value:
No (disabled)
RMT Configuration
Contains:
CONFIG_RMT_ISR_IRAM_SAFE
RMT ISR IRAM-Safe
Found in: Component config > Driver Configurations > RMT Configuration
Ensure the RMT interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write).
- Default value:
No (disabled)
CONFIG_RMT_SUPPRESS_DEPRECATE_WARN
Suppress legacy driver deprecated warning
Found in: Component config > Driver Configurations > RMT Configuration
Wether to suppress the deprecation warnings when using legacy rmt driver (driver/rmt.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
CONFIG_RMT_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > RMT Configuration
Wether to enable the debug log message for RMT driver. Note that, this option only controls the RMT driver log, won’t affect other drivers.
- Default value:
No (disabled)
MCPWM Configuration
Contains:
CONFIG_MCPWM_ISR_IRAM_SAFE
Place MCPWM ISR function into IRAM
Found in: Component config > Driver Configurations > MCPWM Configuration
This will ensure the MCPWM interrupt handle is IRAM-Safe, allow to avoid flash cache misses, and also be able to run whilst the cache is disabled. (e.g. SPI Flash write)
- Default value:
No (disabled)
CONFIG_MCPWM_CTRL_FUNC_IN_IRAM
Place MCPWM control functions into IRAM
Found in: Component config > Driver Configurations > MCPWM Configuration
Place MCPWM control functions (like set_compare_value) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well.
- Default value:
No (disabled)
CONFIG_MCPWM_SUPPRESS_DEPRECATE_WARN
Suppress leagcy driver deprecated warning
Found in: Component config > Driver Configurations > MCPWM Configuration
Wether to suppress the deprecation warnings when using legacy MCPWM driver (driver/mcpwm.h). If you want to continue using the legacy driver, and don’t want to see related deprecation warnings, you can enable this option.
- Default value:
No (disabled)
CONFIG_MCPWM_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > Driver Configurations > MCPWM Configuration
Wether to enable the debug log message for MCPWM driver. Note that, this option only controls the MCPWM driver log, won’t affect other drivers.
- Default value:
No (disabled)
I2S Configuration
Contains:
CONFIG_I2S_ISR_IRAM_SAFE
I2S ISR IRAM-Safe
Found in: Component config > Driver Configurations > I2S Configuration
Ensure the I2S interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write).
- Default value:
No (disabled)
CONFIG_I2S_SUPPRESS_DEPRECATE_WARN
Suppress leagcy driver deprecated warning
Found in: Component config > Driver Configurations > I2S Configuration
Enable this option will suppress the deprecation warnings of using APIs in legacy I2S driver.
- Default value:
No (disabled)
CONFIG_I2S_ENABLE_DEBUG_LOG
Enable I2S debug log
Found in: Component config > Driver Configurations > I2S Configuration
Wether to enable the debug log message for I2S driver. Note that, this option only controls the I2S driver log, will not affect other drivers.
- Default value:
No (disabled)
eFuse Bit Manager
Contains:
CONFIG_EFUSE_CUSTOM_TABLE
Use custom eFuse table
Found in: Component config > eFuse Bit Manager
Allows to generate a structure for eFuse from the CSV file.
- Default value:
No (disabled)
CONFIG_EFUSE_CUSTOM_TABLE_FILENAME
Custom eFuse CSV file
Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_CUSTOM_TABLE
Name of the custom eFuse CSV filename. This path is evaluated relative to the project root directory.
- Default value:
“main/esp_efuse_custom_table.csv” if CONFIG_EFUSE_CUSTOM_TABLE
CONFIG_EFUSE_VIRTUAL
Simulate eFuse operations in RAM
Found in: Component config > eFuse Bit Manager
If “n” - No virtual mode. All eFuse operations are real and use eFuse registers. If “y” - The virtual mode is enabled and all eFuse operations (read and write) are redirected to RAM instead of eFuse registers, all permanent changes (via eFuse) are disabled. Log output will state changes that would be applied, but they will not be.
During startup, the eFuses are copied into RAM. This mode is useful for fast tests.
- Default value:
No (disabled)
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
Keep eFuses in flash
Found in: Component config > eFuse Bit Manager > CONFIG_EFUSE_VIRTUAL
In addition to the “Simulate eFuse operations in RAM” option, this option just adds a feature to keep eFuses after reboots in flash memory. To use this mode the partition_table should have the efuse partition. partition.csv: “efuse_em, data, efuse, , 0x2000,”
During startup, the eFuses are copied from flash or, in case if flash is empty, from real eFuse to RAM and then update flash. This mode is useful when need to keep changes after reboot (testing secure_boot and flash_encryption).
CONFIG_EFUSE_CODE_SCHEME_SELECTOR
Coding Scheme Compatibility
Found in: Component config > eFuse Bit Manager
Selector eFuse code scheme.
- Available options:
None Only (EFUSE_CODE_SCHEME_COMPAT_NONE)
3/4 and None (EFUSE_CODE_SCHEME_COMPAT_3_4)
Repeat, 3/4 and None (common table does not support it) (EFUSE_CODE_SCHEME_COMPAT_REPEAT)
ESP-TLS
Contains:
CONFIG_ESP_TLS_LIBRARY_CHOOSE
Choose SSL/TLS library for ESP-TLS (See help for more Info)
Found in: Component config > ESP-TLS
The ESP-TLS APIs support multiple backend TLS libraries. Currently mbedTLS and WolfSSL are supported. Different TLS libraries may support different features and have different resource usage. Consult the ESP-TLS documentation in ESP-IDF Programming guide for more details.
- Available options:
mbedTLS (ESP_TLS_USING_MBEDTLS)
wolfSSL (License info in wolfSSL directory README) (ESP_TLS_USING_WOLFSSL)
CONFIG_ESP_TLS_USE_SECURE_ELEMENT
Use Secure Element (ATECC608A) with ESP-TLS
Found in: Component config > ESP-TLS
Enable use of Secure Element for ESP-TLS, this enables internal support for ATECC608A peripheral on ESPWROOM32SE, which can be used for TLS connection.
CONFIG_ESP_TLS_USE_DS_PERIPHERAL
Use Digital Signature (DS) Peripheral with ESP-TLS
Found in: Component config > ESP-TLS
Enable use of the Digital Signature Peripheral for ESP-TLS.The DS peripheral can only be used when it is appropriately configured for TLS. Consult the ESP-TLS documentation in ESP-IDF Programming Guide for more details.
- Default value:
Yes (enabled) if ESP_TLS_USING_MBEDTLS && SOC_DIG_SIGN_SUPPORTED
CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS
Enable client session tickets
Found in: Component config > ESP-TLS
Enable session ticket support as specified in RFC5077.
CONFIG_ESP_TLS_SERVER
Enable ESP-TLS Server
Found in: Component config > ESP-TLS
Enable support for creating server side SSL/TLS session, available for mbedTLS as well as wolfSSL TLS library.
CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
Enable server session tickets
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER
Enable session ticket support as specified in RFC5077
CONFIG_ESP_TLS_SERVER_SESSION_TICKET_TIMEOUT
Server session ticket timeout in seconds
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER > CONFIG_ESP_TLS_SERVER_SESSION_TICKETS
Sets the session ticket timeout used in the tls server.
- Default value:
CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK
Certificate selection hook
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER
Ability to configure and use a certificate selection callback during server handshake, to select a certificate to present to the client based on the TLS extensions supplied in the client hello (alpn, sni, etc).
CONFIG_ESP_TLS_SERVER_MIN_AUTH_MODE_OPTIONAL
ESP-TLS Server: Set minimum Certificate Verification mode to Optional
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_SERVER
When this option is enabled, the peer (here, the client) certificate is checked by the server, however the handshake continues even if verification failed. By default, the peer certificate is not checked and ignored by the server.
mbedtls_ssl_get_verify_result() can be called after the handshake is complete to retrieve status of verification.
CONFIG_ESP_TLS_PSK_VERIFICATION
Enable PSK verification
Found in: Component config > ESP-TLS
Enable support for pre shared key ciphers, supported for both mbedTLS as well as wolfSSL TLS library.
CONFIG_ESP_TLS_INSECURE
Allow potentially insecure options
Found in: Component config > ESP-TLS
You can enable some potentially insecure options. These options should only be used for testing pusposes. Only enable these options if you are very sure.
CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY
Skip server certificate verification by default (WARNING: ONLY FOR TESTING PURPOSE, READ HELP)
Found in: Component config > ESP-TLS > CONFIG_ESP_TLS_INSECURE
After enabling this option the esp-tls client will skip the server certificate verification by default. Note that this option will only modify the default behaviour of esp-tls client regarding server cert verification. The default behaviour should only be applicable when no other option regarding the server cert verification is opted in the esp-tls config (e.g. crt_bundle_attach, use_global_ca_store etc.). WARNING : Enabling this option comes with a potential risk of establishing a TLS connection with a server which has a fake identity, provided that the server certificate is not provided either through API or other mechanism like ca_store etc.
CONFIG_ESP_WOLFSSL_SMALL_CERT_VERIFY
Enable SMALL_CERT_VERIFY
Found in: Component config > ESP-TLS
Enables server verification with Intermediate CA cert, does not authenticate full chain of trust upto the root CA cert (After Enabling this option client only needs to have Intermediate CA certificate of the server to authenticate server, root CA cert is not necessary).
- Default value:
Yes (enabled) if ESP_TLS_USING_WOLFSSL
CONFIG_ESP_DEBUG_WOLFSSL
Enable debug logs for wolfSSL
Found in: Component config > ESP-TLS
Enable detailed debug prints for wolfSSL SSL library.
ADC and ADC Calibration
Contains:
CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM
Place ISR version ADC oneshot mode read function into IRAM
Found in: Component config > ADC and ADC Calibration
Place ISR version ADC oneshot mode read function into IRAM.
- Default value:
No (disabled)
CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE
ADC continuous mode driver ISR IRAM-Safe
Found in: Component config > ADC and ADC Calibration
Ensure the ADC continuous mode ISR is IRAM-Safe. When enabled, the ISR handler will be available when the cache is disabled.
- Default value:
No (disabled)
ADC Calibration Configurations
Contains:
CONFIG_ADC_CALI_EFUSE_TP_ENABLE
Use Two Point Values
Found in: Component config > ADC and ADC Calibration > ADC Calibration Configurations
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.
- Default value:
Yes (enabled)
CONFIG_ADC_CALI_EFUSE_VREF_ENABLE
Use eFuse Vref
Found in: Component config > ADC and ADC Calibration > ADC Calibration Configurations
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.
- Default value:
Yes (enabled)
CONFIG_ADC_CALI_LUT_ENABLE
Use Lookup Tables
Found in: Component config > ADC and ADC Calibration > ADC Calibration Configurations
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.
- Default value:
Yes (enabled)
CONFIG_ADC_DISABLE_DAC_OUTPUT
Disable DAC when ADC2 is in use
Found in: Component config > ADC and ADC Calibration
By default, this is set. The ADC oneshot driver will disable the output of the corresponding DAC channels: ESP32: IO25 and IO26 ESP32S2: IO17 and IO18
Disable this option so as to measure the output of DAC by internal ADC, for test usage.
- Default value:
Yes (enabled)
Ethernet
Contains:
CONFIG_ETH_USE_ESP32_EMAC
Support ESP32 internal EMAC controller
Found in: Component config > Ethernet
ESP32 integrates a 10/100M Ethernet MAC controller.
- Default value:
Yes (enabled)
Contains:
CONFIG_ETH_PHY_INTERFACE
PHY interface
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Select the communication interface between MAC and PHY chip.
- Available options:
Reduced Media Independent Interface (RMII) (ETH_PHY_INTERFACE_RMII)
CONFIG_ETH_RMII_CLK_MODE
RMII clock mode
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Select external or internal RMII clock.
- Available options:
Input RMII clock from external (ETH_RMII_CLK_INPUT)
MAC will get RMII clock from outside. Note that ESP32 only supports GPIO0 to input the RMII clock.
Output RMII clock from internal (ETH_RMII_CLK_OUTPUT)
ESP32 can generate RMII clock by internal APLL. This clock can be routed to the external PHY device. ESP32 supports to route the RMII clock to GPIO0/16/17.
CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0
Output RMII clock from GPIO0 (Experimental!)
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
GPIO0 can be set to output a pre-divided PLL clock (test only!). Enabling this option will configure GPIO0 to output a 50MHz clock. In fact this clock doesn’t have directly relationship with EMAC peripheral. Sometimes this clock won’t work well with your PHY chip. You might need to add some extra devices after GPIO0 (e.g. inverter). Note that outputting RMII clock on GPIO0 is an experimental practice. If you want the Ethernet to work with WiFi, don’t select GPIO0 output mode for stability.
- Default value:
No (disabled) if ETH_RMII_CLK_OUTPUT && CONFIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_RMII_CLK_OUT_GPIO
RMII clock GPIO number
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Set the GPIO number to output RMII Clock.
- Range:
from 16 to 17 if CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 && ETH_RMII_CLK_OUTPUT && CONFIG_ETH_USE_ESP32_EMAC
- Default value:
17 if CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 && ETH_RMII_CLK_OUTPUT && CONFIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_DMA_BUFFER_SIZE
Ethernet DMA buffer size (Byte)
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Set the size of each buffer used by Ethernet MAC DMA.
- Range:
from 256 to 1600
- Default value:
512
CONFIG_ETH_DMA_RX_BUFFER_NUM
Amount of Ethernet DMA Rx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Number of DMA receive buffers. Each buffer’s size is ETH_DMA_BUFFER_SIZE. Larger number of buffers could increase throughput somehow.
- Range:
from 3 to 30
- Default value:
10
CONFIG_ETH_DMA_TX_BUFFER_NUM
Amount of Ethernet DMA Tx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Number of DMA transmit buffers. Each buffer’s size is ETH_DMA_BUFFER_SIZE. Larger number of buffers could increase throughput somehow.
- Range:
from 3 to 30
- Default value:
10
CONFIG_ETH_SOFT_FLOW_CONTROL
Enable software flow control
Found in: Component config > Ethernet > CONFIG_ETH_USE_ESP32_EMAC
Ethernet MAC engine on ESP32 doesn’t feature a flow control logic. The MAC driver can perform a software flow control if you enable this option. Note that, if the RX buffer number is small, enabling software flow control will cause obvious performance loss.
- Default value:
No (disabled) if CONFIG_ETH_DMA_RX_BUFFER_NUM > 15 && CONFIG_ETH_USE_ESP32_EMAC
CONFIG_ETH_USE_SPI_ETHERNET
Support SPI to Ethernet Module
Found in: Component config > Ethernet
ESP-IDF can also support some SPI-Ethernet modules.
- Default value:
Yes (enabled)
Contains:
CONFIG_ETH_SPI_ETHERNET_DM9051
Use DM9051
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
DM9051 is a fast Ethernet controller with an SPI interface. It’s also integrated with a 10/100M PHY and MAC. Select this to enable DM9051 driver.
CONFIG_ETH_SPI_ETHERNET_W5500
Use W5500 (MAC RAW)
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
W5500 is a HW TCP/IP embedded Ethernet controller. TCP/IP stack, 10/100 Ethernet MAC and PHY are embedded in a single chip. However the driver in ESP-IDF only enables the RAW MAC mode, making it compatible with the software TCP/IP stack. Say yes to enable W5500 driver.
CONFIG_ETH_SPI_ETHERNET_KSZ8851SNL
Use KSZ8851SNL
Found in: Component config > Ethernet > CONFIG_ETH_USE_SPI_ETHERNET
The KSZ8851SNL is a single-chip Fast Ethernet controller consisting of a 10/100 physical layer transceiver (PHY), a MAC, and a Serial Peripheral Interface (SPI). Select this to enable KSZ8851SNL driver.
CONFIG_ETH_USE_OPENETH
Support OpenCores Ethernet MAC (for use with QEMU)
Found in: Component config > Ethernet
OpenCores Ethernet MAC driver can be used when an ESP-IDF application is executed in QEMU. This driver is not supported when running on a real chip.
- Default value:
No (disabled)
Contains:
CONFIG_ETH_OPENETH_DMA_RX_BUFFER_NUM
Number of Ethernet DMA Rx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH
Number of DMA receive buffers, each buffer is 1600 bytes.
- Range:
from 1 to 64 if CONFIG_ETH_USE_OPENETH
- Default value:
CONFIG_ETH_OPENETH_DMA_TX_BUFFER_NUM
Number of Ethernet DMA Tx buffers
Found in: Component config > Ethernet > CONFIG_ETH_USE_OPENETH
Number of DMA transmit buffers, each buffer is 1600 bytes.
- Range:
from 1 to 64 if CONFIG_ETH_USE_OPENETH
- Default value:
CONFIG_ETH_TRANSMIT_MUTEX
Enable Transmit Mutex
Found in: Component config > Ethernet
Prevents multiple accesses when Ethernet interface is used as shared resource and multiple functionalities might try to access it at a time.
- Default value:
No (disabled)
Event Loop Library
Contains:
CONFIG_ESP_EVENT_LOOP_PROFILING
Enable event loop profiling
Found in: Component config > Event Loop Library
Enables collections of statistics in the event loop library such as the number of events posted to/recieved by an event loop, number of callbacks involved, number of events dropped to to a full event loop queue, run time of event handlers, and number of times/run time of each event handler.
- Default value:
No (disabled)
CONFIG_ESP_EVENT_POST_FROM_ISR
Support posting events from ISRs
Found in: Component config > Event Loop Library
Enable posting events from interrupt handlers.
- Default value:
Yes (enabled)
CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR
Support posting events from ISRs placed in IRAM
Found in: Component config > Event Loop Library > CONFIG_ESP_EVENT_POST_FROM_ISR
Enable posting events from interrupt handlers placed in IRAM. Enabling this option places API functions esp_event_post and esp_event_post_to in IRAM.
- Default value:
Yes (enabled)
GDB Stub
Contains:
CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
Enable listing FreeRTOS tasks through GDB Stub
Found in: Component config > GDB Stub
If enabled, GDBStub can supply the list of FreeRTOS tasks to GDB. Thread list can be queried from GDB using ‘info threads’ command. Note that if GDB task lists were corrupted, this feature may not work. If GDBStub fails, try disabling this feature.
CONFIG_ESP_GDBSTUB_MAX_TASKS
Maximum number of tasks supported by GDB Stub
Found in: Component config > GDB Stub > CONFIG_ESP_GDBSTUB_SUPPORT_TASKS
Set the number of tasks which GDB Stub will support.
- Default value:
ESP HTTP client
Contains:
CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS
Enable https
Found in: Component config > ESP HTTP client
This option will enable https protocol by linking esp-tls library and initializing SSL transport
- Default value:
Yes (enabled)
CONFIG_ESP_HTTP_CLIENT_ENABLE_BASIC_AUTH
Enable HTTP Basic Authentication
Found in: Component config > ESP HTTP client
This option will enable HTTP Basic Authentication. It is disabled by default as Basic auth uses unencrypted encoding, so it introduces a vulnerability when not using TLS
- Default value:
No (disabled)
CONFIG_ESP_HTTP_CLIENT_ENABLE_DIGEST_AUTH
Enable HTTP Digest Authentication
Found in: Component config > ESP HTTP client
This option will enable HTTP Digest Authentication. It is enabled by default, but use of this configuration is not recommended as the password can be derived from the exchange, so it introduces a vulnerability when not using TLS
- Default value:
No (disabled)
HTTP Server
Contains:
CONFIG_HTTPD_MAX_REQ_HDR_LEN
Max HTTP Request Header Length
Found in: Component config > HTTP Server
This sets the maximum supported size of headers section in HTTP request packet to be processed by the server
- Default value:
512
CONFIG_HTTPD_MAX_URI_LEN
Max HTTP URI Length
Found in: Component config > HTTP Server
This sets the maximum supported size of HTTP request URI to be processed by the server
- Default value:
512
CONFIG_HTTPD_ERR_RESP_NO_DELAY
Use TCP_NODELAY socket option when sending HTTP error responses
Found in: Component config > HTTP Server
Using TCP_NODEALY socket option ensures that HTTP error response reaches the client before the underlying socket is closed. Please note that turning this off may cause multiple test failures
- Default value:
Yes (enabled)
CONFIG_HTTPD_PURGE_BUF_LEN
Length of temporary buffer for purging data
Found in: Component config > HTTP Server
This sets the size of the temporary buffer used to receive and discard any remaining data that is received from the HTTP client in the request, but not processed as part of the server HTTP request handler.
If the remaining data is larger than the available buffer size, the buffer will be filled in multiple iterations. The buffer should be small enough to fit on the stack, but large enough to avoid excessive iterations.
- Default value:
32
CONFIG_HTTPD_LOG_PURGE_DATA
Log purged content data at Debug level
Found in: Component config > HTTP Server
Enabling this will log discarded binary HTTP request data at Debug level. For large content data this may not be desirable as it will clutter the log.
- Default value:
No (disabled)
CONFIG_HTTPD_WS_SUPPORT
WebSocket server support
Found in: Component config > HTTP Server
This sets the WebSocket server support.
- Default value:
No (disabled)
CONFIG_HTTPD_QUEUE_WORK_BLOCKING
httpd_queue_work as blocking API
Found in: Component config > HTTP Server
This makes httpd_queue_work() API to wait until a message space is available on UDP control socket. It internally uses a counting semaphore with count set to LWIP_UDP_RECVMBOX_SIZE to achieve this. This config will slightly change API behavior to block until message gets delivered on control socket.
ESP HTTPS OTA
Contains:
CONFIG_ESP_HTTPS_OTA_DECRYPT_CB
Provide decryption callback
Found in: Component config > ESP HTTPS OTA
Exposes an additional callback whereby firmware data could be decrypted before being processed by OTA update component. This can help to integrate external encryption related format and removal of such encapsulation layer from firmware image.
- Default value:
No (disabled)
CONFIG_ESP_HTTPS_OTA_ALLOW_HTTP
Allow HTTP for OTA (WARNING: ONLY FOR TESTING PURPOSE, READ HELP)
Found in: Component config > ESP HTTPS OTA
It is highly recommended to keep HTTPS (along with server certificate validation) enabled. Enabling this option comes with potential risk of: - Non-encrypted communication channel with server - Accepting firmware upgrade image from server with fake identity
- Default value:
No (disabled)
ESP HTTPS server
Contains:
CONFIG_ESP_HTTPS_SERVER_ENABLE
Enable ESP_HTTPS_SERVER component
Found in: Component config > ESP HTTPS server
Enable ESP HTTPS server component
Hardware Settings
Contains:
Chip revision
Contains:
CONFIG_ESP32_REV_MIN
Minimum Supported ESP32 Revision
Found in: Component config > Hardware Settings > Chip revision
Required minimum chip revision. ESP-IDF will check for it and reject to boot if the chip revision fails the check. This ensures the chip used will have some modifications (features, or bugfixes).
The complied binary will only support chips above this revision, this will also help to reduce binary size.
- Available options:
Rev v0.0 (ECO0) (ESP32_REV_MIN_0)
Rev v1.0 (ECO1) (ESP32_REV_MIN_1)
Rev v1.1 (ECO1.1) (ESP32_REV_MIN_1_1)
Rev v2.0 (ECO2) (ESP32_REV_MIN_2)
Rev v3.0 (ECO3) (ESP32_REV_MIN_3)
Rev v3.1 (ECO4) (ESP32_REV_MIN_3_1)
MAC Config
Contains:
CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES
Number of universally administered (by IEEE) MAC address
Found in: Component config > Hardware Settings > MAC Config
Configure the number of universally administered (by IEEE) MAC addresses. During initialization, 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.)
- Available options:
Two (ESP32_UNIVERSAL_MAC_ADDRESSES_TWO)
Four (ESP32_UNIVERSAL_MAC_ADDRESSES_FOUR)
Sleep Config
Contains:
CONFIG_ESP_SLEEP_POWER_DOWN_FLASH
Power down flash in light sleep when there is no SPIRAM
Found in: Component config > Hardware Settings > Sleep Config
If enabled, chip will try to power down flash as part of esp_light_sleep_start(), which costs more time when chip wakes up. Can only be enabled if there is no SPIRAM configured.
This option will power down flash under a strict but relatively safe condition. Also, it is possible to power down flash under a relaxed condition by using esp_sleep_pd_config() to set ESP_PD_DOMAIN_VDDSDIO to ESP_PD_OPTION_OFF. It should be noted that there is a risk in powering down flash, you can refer ESP-IDF Programming Guide/API Reference/System API/Sleep Modes/Power-down of Flash for more details.
- Default value:
No (disabled) if CONFIG_SPIRAM
CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND
light sleep GPIO reset workaround
Found in: Component config > Hardware Settings > Sleep Config
esp32c2, esp32c3 and esp32s3 will reset at wake-up if GPIO is received a small electrostatic pulse during light sleep, with specific condition
GPIO needs to be configured as input-mode only
The pin receives a small electrostatic pulse, and reset occurs when the pulse voltage is higher than 6 V
For GPIO set to input mode only, it is not a good practice to leave it open/floating, The hardware design needs to controlled it with determined supply or ground voltage is necessary.
This option provides a software workaround for this issue. Configure to isolate all GPIO pins in sleep state.
CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND
PSRAM leakage current workaround in light sleep
Found in: Component config > Hardware Settings > Sleep Config
When the CS pin of SPIRAM is not pulled up, the sleep current will increase during light sleep. If the CS pin of SPIRAM has an external pull-up, you do not need to select this option, otherwise, you should enable this option.
- Default value:
Yes (enabled) if CONFIG_SPIRAM
CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND
Flash leakage current workaround in light sleep
Found in: Component config > Hardware Settings > Sleep Config
When the CS pin of Flash is not pulled up, the sleep current will increase during light sleep. If the CS pin of Flash has an external pull-up, you do not need to select this option, otherwise, you should enable this option.
- Default value:
Yes (enabled)
CONFIG_ESP_SLEEP_MSPI_NEED_ALL_IO_PU
All pins of mspi need pull up
Found in: Component config > Hardware Settings > Sleep Config
To reduce leakage current, some types of SPI Flash/RAM only need to pull up the CS pin during light sleep. But there are also some kinds of SPI Flash/RAM that need to pull up all pins. It depends on the SPI Flash/RAM chip used.
CONFIG_ESP_SLEEP_DEEP_SLEEP_WAKEUP_DELAY
Extra delay in deep sleep wake stub (in us)
Found in: Component config > Hardware Settings > Sleep Config
When the chip 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.
- Range:
from 0 to 5000
- Default value:
2000
RTC Clock Config
Contains:
CONFIG_RTC_CLK_SRC
RTC clock source
Found in: Component config > Hardware Settings > RTC Clock Config
Choose which clock is used as RTC clock source.
- “Internal 150kHz oscillator” option provides lowest deep sleep current
consumption, and does not require extra external components. However frequency stability with respect to temperature is poor, so time may drift in deep/light sleep modes.
- “External 32kHz crystal” provides better frequency stability, at the
expense of slightly higher (1uA) deep sleep current consumption.
- “External 32kHz oscillator” allows using 32kHz clock generated by an
external circuit. In this case, external clock signal must be connected to 32K_XN pin. Amplitude should be <1.2V in case of sine wave signal, and <1V in case of square wave signal. Common mode voltage should be 0.1 < Vcm < 0.5Vamp, where Vamp is the signal amplitude. Additionally, 1nF capacitor must be connected between 32K_XP pin and ground. 32K_XP pin can not be used as a GPIO in this case.
- “Internal 8.5MHz oscillator divided by 256” option results in higher
deep sleep current (by 5uA) but has better frequency stability than the internal 150kHz oscillator. It does not require external components.
- Available options:
Internal 150kHz RC oscillator (RTC_CLK_SRC_INT_RC)
External 32kHz crystal (RTC_CLK_SRC_EXT_CRYS)
External 32kHz oscillator at 32K_XN pin (RTC_CLK_SRC_EXT_OSC)
Internal 8.5MHz oscillator, divided by 256 (~33kHz) (RTC_CLK_SRC_INT_8MD256)
CONFIG_RTC_EXT_CRYST_ADDIT_CURRENT_METHOD
Additional current for external 32kHz crystal
Found in: Component config > Hardware Settings > RTC Clock Config
With some 32kHz crystal configurations, the X32N and X32P pins may not have enough drive strength to keep the crystal oscillating. Choose the method to provide additional current from touchpad 9 to the external 32kHz crystal. Note that the deep sleep current is slightly high (4-5uA) and the touchpad and the wakeup sources of both touchpad and ULP are not available in method 1 and method 2.
This problem is fixed in ESP32 ECO 3, so this workaround is not needed. Setting the project configuration to minimum revision ECO3 will disable this option, , allow all wakeup sources, and save some code size.
“None” option will not provide additional current to external crystal
- “Method 1” option can’t ensure 100% to solve the external 32k crystal start failed
issue, but the touchpad can work in this method.
- “Method 2” option can solve the external 32k issue, but the touchpad can’t work
in this method.
- Available options:
None (RTC_EXT_CRYST_ADDIT_CURRENT_NONE)
Method 1 (RTC_EXT_CRYST_ADDIT_CURRENT)
Method 2 (RTC_EXT_CRYST_ADDIT_CURRENT_V2)
CONFIG_RTC_CLK_CAL_CYCLES
Number of cycles for RTC_SLOW_CLK calibration
Found in: Component config > Hardware Settings > RTC Clock Config
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.
- Range:
from 0 to 27000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC || RTC_CLK_SRC_INT_8MD256
from 0 to 32766
- Default value:
3000 if RTC_CLK_SRC_EXT_CRYS || RTC_CLK_SRC_EXT_OSC || RTC_CLK_SRC_INT_8MD256
1024
CONFIG_RTC_XTAL_CAL_RETRY
Number of attempts to repeat 32k XTAL calibration
Found in: Component config > Hardware Settings > RTC Clock Config
Number of attempts to repeat 32k XTAL calibration before giving up and switching to the internal RC. Increase this option if the 32k crystal oscillator does not start and switches to internal RC.
- Default value:
1 if RTC_CLK_SRC_EXT_CRYS
Peripheral Control
Contains:
CONFIG_PERIPH_CTRL_FUNC_IN_IRAM
Place peripheral control functions into IRAM
Found in: Component config > Hardware Settings > Peripheral Control
Place peripheral control functions (e.g. periph_module_reset) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context.
- Default value:
No (disabled)
MMU Config
GDMA Configuration
Contains:
CONFIG_GDMA_CTRL_FUNC_IN_IRAM
Place GDMA control functions into IRAM
Found in: Component config > Hardware Settings > GDMA Configuration
Place GDMA control functions (like start/stop/append/reset) into IRAM, so that these functions can be IRAM-safe and able to be called in the other IRAM interrupt context. Enabling this option can improve driver performance as well.
- Default value:
No (disabled) if SOC_GDMA_SUPPORTED
CONFIG_GDMA_ISR_IRAM_SAFE
GDMA ISR IRAM-Safe
Found in: Component config > Hardware Settings > GDMA Configuration
This will ensure the GDMA interrupt handler is IRAM-Safe, allow to avoid flash cache misses, and also be able to run whilst the cache is disabled. (e.g. SPI Flash write).
- Default value:
No (disabled) if SOC_GDMA_SUPPORTED
Main XTAL Config
Contains:
CONFIG_XTAL_FREQ_SEL
Main XTAL frequency
Found in: Component config > Hardware Settings > Main XTAL Config
This option selects the operating frequency of the XTAL (crystal) clock used to drive the ESP target. The selected value MUST reflect the frequency of the given hardware.
Note: The XTAL_FREQ_AUTO option allows the ESP target to automatically estimating XTAL clock’s operating frequency. However, this feature is only supported on the ESP32. The ESP32 uses the internal 8MHZ as a reference when estimating. Due to the internal oscillator’s frequency being temperature dependent, usage of the XTAL_FREQ_AUTO is not recommended in applications that operate in high ambient temperatures or use high-temperature qualified chips and modules.
- Available options:
24 MHz (XTAL_FREQ_24)
26 MHz (XTAL_FREQ_26)
32 MHz (XTAL_FREQ_32)
40 MHz (XTAL_FREQ_40)
Autodetect (XTAL_FREQ_AUTO)
LCD and Touch Panel
Contains:
LCD Peripheral Configuration
Contains:
CONFIG_LCD_PANEL_IO_FORMAT_BUF_SIZE
LCD panel io format buffer size
Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration
LCD driver allocates an internal buffer to transform the data into a proper format, because of the endian order mismatch. This option is to set the size of the buffer, in bytes.
- Default value:
32
CONFIG_LCD_ENABLE_DEBUG_LOG
Enable debug log
Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration
Wether to enable the debug log message for LCD driver. Note that, this option only controls the LCD driver log, won’t affect other drivers.
- Default value:
No (disabled)
CONFIG_LCD_RGB_ISR_IRAM_SAFE
RGB LCD ISR IRAM-Safe
Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration
Ensure the LCD interrupt is IRAM-Safe by allowing the interrupt handler to be executable when the cache is disabled (e.g. SPI Flash write). If you want the LCD driver to keep flushing the screen even when cache ops disabled, you can enable this option. Note, this will also increase the IRAM usage.
- Default value:
No (disabled) if SOC_LCD_RGB_SUPPORTED
CONFIG_LCD_RGB_RESTART_IN_VSYNC
Restart transmission in VSYNC
Found in: Component config > LCD and Touch Panel > LCD Peripheral Configuration
Reset the GDMA channel every VBlank to stop permanent desyncs from happening. Only need to enable it when in your application, the DMA can’t deliver data as fast as the LCD consumes it.
- Default value:
No (disabled) if SOC_LCD_RGB_SUPPORTED
ESP NETIF Adapter
Contains:
CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL
IP Address lost timer interval (seconds)
Found in: Component config > ESP NETIF Adapter
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.
- Range:
from 0 to 65535
- Default value:
120
CONFIG_ESP_NETIF_USE_TCPIP_STACK_LIB
TCP/IP Stack Library
Found in: Component config > ESP NETIF Adapter
Choose the TCP/IP Stack to work, for example, LwIP, uIP, etc.
- Available options:
LwIP (ESP_NETIF_TCPIP_LWIP)
lwIP is a small independent implementation of the TCP/IP protocol suite.
Loopback (ESP_NETIF_LOOPBACK)
Dummy implementation of esp-netif functionality which connects driver transmit to receive function. This option is for testing purpose only
CONFIG_ESP_NETIF_L2_TAP
Enable netif L2 TAP support
Found in: Component config > ESP NETIF Adapter
A user program can read/write link layer (L2) frames from/to ESP TAP device. The ESP TAP device can be currently associated only with Ethernet physical interfaces.
CONFIG_ESP_NETIF_L2_TAP_MAX_FDS
Maximum number of opened L2 TAP File descriptors
Found in: Component config > ESP NETIF Adapter > CONFIG_ESP_NETIF_L2_TAP
Maximum number of opened File descriptors (FD’s) associated with ESP TAP device. ESP TAP FD’s take up a certain amount of memory, and allowing fewer FD’s to be opened at the same time conserves memory.
- Range:
from 1 to 10 if CONFIG_ESP_NETIF_L2_TAP
- Default value:
CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE
Size of L2 TAP Rx queue
Found in: Component config > ESP NETIF Adapter > CONFIG_ESP_NETIF_L2_TAP
Maximum number of frames queued in opened File descriptor. Once the queue is full, the newly arriving frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).
- Range:
from 1 to 100 if CONFIG_ESP_NETIF_L2_TAP
- Default value:
20 if CONFIG_ESP_NETIF_L2_TAP
CONFIG_ESP_NETIF_BRIDGE_EN
Enable LwIP IEEE 802.1D bridge
Found in: Component config > ESP NETIF Adapter
Enable LwIP IEEE 802.1D bridge support in ESP-NETIF. Note that “Number of clients store data in netif” (LWIP_NUM_NETIF_CLIENT_DATA) option needs to be properly configured to be LwIP bridge avaiable!
- Default value:
No (disabled)
PHY
Contains:
CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE
Store phy calibration data in NVS
Found in: Component config > PHY
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’.
- Default value:
Yes (enabled)
CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
Use a partition to store PHY init data
Found in: Component config > PHY
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’.
- Default value:
No (disabled)
Contains:
CONFIG_ESP_PHY_DEFAULT_INIT_IF_INVALID
Reset default PHY init data if invalid
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
If enabled, PHY init data will be restored to default if it cannot be verified successfully to avoid endless bootloops.
If unsure, choose ‘n’.
- Default value:
No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
Support multiple PHY init data bin
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
If enabled, the corresponding PHY init data type can be automatically switched according to the country code. China’s PHY init data bin is used by default. Can be modified by country information in API esp_wifi_set_country(). The priority of switching the PHY init data type is: 1. Country configured by API esp_wifi_set_country() and the parameter policy is WIFI_COUNTRY_POLICY_MANUAL. 2. Country notified by the connected AP. 3. Country configured by API esp_wifi_set_country() and the parameter policy is WIFI_COUNTRY_POLICY_AUTO.
- Default value:
No (disabled) if CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN_EMBED
Support embedded multiple phy init data bin to app bin
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
If enabled, multiple phy init data bin will embedded into app bin If not enabled, multiple phy init data bin will still leave alone, and need to be flashed by users.
- Default value:
No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_INIT_DATA_ERROR
Terminate operation when PHY init data error
Found in: Component config > PHY > CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION > CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN
If enabled, when an error occurs while the PHY init data is updated, the program will terminate and restart. If not enabled, the PHY init data will not be updated when an error occurs.
- Default value:
No (disabled) if CONFIG_ESP_PHY_MULTIPLE_INIT_DATA_BIN && CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION
CONFIG_ESP_PHY_MAX_WIFI_TX_POWER
Max WiFi TX power (dBm)
Found in: Component config > PHY
Set maximum transmit power for WiFi radio. Actual transmit power for high data rates may be lower than this setting.
- Range:
from 10 to 20
- Default value:
20
CONFIG_ESP_PHY_REDUCE_TX_POWER
Reduce PHY TX power when brownout reset
Found in: Component config > PHY
When brownout reset occurs, reduce PHY TX power to keep the code running.
- Default value:
Yes (enabled)
Power Management
Contains:
CONFIG_PM_ENABLE
Support for power management
Found in: Component config > 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.
- Default value:
No (disabled) if CONFIG_FREERTOS_SMP
CONFIG_PM_DFS_INIT_AUTO
Enable dynamic frequency scaling (DFS) at startup
Found in: Component config > Power Management > CONFIG_PM_ENABLE
If enabled, startup code configures dynamic frequency scaling. Max CPU frequency is set to 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.
- Default value:
No (disabled) if CONFIG_PM_ENABLE
CONFIG_PM_PROFILING
Enable profiling counters for PM locks
Found in: Component config > Power Management > CONFIG_PM_ENABLE
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.
- Default value:
No (disabled) if CONFIG_PM_ENABLE
CONFIG_PM_TRACE
Enable debug tracing of PM using GPIOs
Found in: Component config > Power Management > CONFIG_PM_ENABLE
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.
- Default value:
No (disabled) if CONFIG_PM_ENABLE
CONFIG_PM_SLP_IRAM_OPT
Put lightsleep related codes in internal RAM
Found in: Component config > Power Management
If enabled, about 1.8KB of lightsleep related source code would be in IRAM and chip would sleep longer for 760us at most each time. This feature is intended to be used when lower power consumption is needed while there is enough place in IRAM to place source code.
CONFIG_PM_RTOS_IDLE_OPT
Put RTOS IDLE related codes in internal RAM
Found in: Component config > Power Management
If enabled, about 260B of RTOS_IDLE related source code would be in IRAM and chip would sleep longer for 40us at most each time. This feature is intended to be used when lower power consumption is needed while there is enough place in IRAM to place source code.
CONFIG_PM_SLP_DISABLE_GPIO
Disable all GPIO when chip at sleep
Found in: Component config > Power Management
This feature is intended to disable all GPIO pins at automantic sleep to get a lower power mode. If enabled, chips will disable all GPIO pins at automantic sleep to reduce about 200~300 uA current. If you want to specifically use some pins normally as chip wakes when chip sleeps, you can call ‘gpio_sleep_sel_dis’ to disable this feature on those pins. You can also keep this feature on and call ‘gpio_sleep_set_direction’ and ‘gpio_sleep_set_pull_mode’ to have a different GPIO configuration at sleep. Waring: If you want to enable this option on ESP32, you should enable GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL at first, otherwise you will not be able to switch pullup/pulldown mode.
ESP PSRAM
Contains:
CONFIG_SPIRAM
Support for external, SPI-connected RAM
Found in: Component config > ESP PSRAM
This enables support for an external SPI RAM chip, connected in parallel with the main SPI flash chip.
- Default value:
No (disabled)
SPI RAM config
Contains:
CONFIG_SPIRAM_TYPE
Type of SPI RAM chip in use
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
- Available options:
Auto-detect (SPIRAM_TYPE_AUTO)
ESP-PSRAM16 or APS1604 (SPIRAM_TYPE_ESPPSRAM16)
ESP-PSRAM32 (SPIRAM_TYPE_ESPPSRAM32)
ESP-PSRAM64 or LY68L6400 (SPIRAM_TYPE_ESPPSRAM64)
CONFIG_SPIRAM_SPEED
Set RAM clock speed
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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:
Flash SPI running at 40Mhz and RAM SPI running at 40Mhz
Flash SPI running at 80Mhz and RAM SPI running at 40Mhz
Flash SPI running at 80Mhz and RAM SPI running at 80Mhz
Note: If the third mode(80Mhz+80Mhz) is enabled for SPI RAM of type 32MBit, one of the HSPI/VSPI host will be occupied by the system. Which SPI host to use can be selected by the config item SPIRAM_OCCUPY_SPI_HOST. Application code should never touch HSPI/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)
- Available options:
40MHz clock speed (SPIRAM_SPEED_40M)
80MHz clock speed (SPIRAM_SPEED_80M)
CONFIG_SPIRAM_BOOT_INIT
Initialize SPI RAM during startup
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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.
- Default value:
Yes (enabled) if CONFIG_SPIRAM
CONFIG_SPIRAM_IGNORE_NOTFOUND
Ignore PSRAM when not found
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > CONFIG_SPIRAM_BOOT_INIT
Normally, if psram initialization is enabled during compile time but not found at runtime, it is seen as an error making the CPU panic. If this is enabled, booting will complete but no PSRAM will be available.
- Default value:
No (disabled) if CONFIG_SPIRAM_BOOT_INIT && CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY && CONFIG_SPIRAM
CONFIG_SPIRAM_USE
SPI RAM access method
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
The SPI RAM can be accessed in multiple methods: by just having it available as an unmanaged memory region in the CPU’s memory map, by integrating it in the heap as ‘special’ memory needing heap_caps_malloc to allocate, or by fully integrating it making malloc() also able to return SPI RAM pointers.
- Available options:
Integrate RAM into memory map (SPIRAM_USE_MEMMAP)
Make RAM allocatable using heap_caps_malloc(…, MALLOC_CAP_SPIRAM) (SPIRAM_USE_CAPS_ALLOC)
Make RAM allocatable using malloc() as well (SPIRAM_USE_MALLOC)
CONFIG_SPIRAM_MEMTEST
Run memory test on SPI RAM initialization
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
Runs a rudimentary memory test on initialization. Aborts when memory test fails. Disable this for slightly faster startup.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_BOOT_INIT && CONFIG_SPIRAM
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL
Maximum malloc() size, in bytes, to always put in internal memory
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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.
- Range:
from 0 to 131072 if SPIRAM_USE_MALLOC && CONFIG_SPIRAM
- Default value:
16384 if SPIRAM_USE_MALLOC && CONFIG_SPIRAM
CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, allocate internal memory
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, try to allocate internal memory then.
- Default value:
No (disabled) if (SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC) && CONFIG_SPIRAM
CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL
Reserve this amount of bytes for data that specifically needs to be in DMA or internal memory
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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.
Note also that the DMA reserved pool may not be one single contiguous memory region, depending on the configured size and the static memory usage of the app.
- Range:
from 0 to 262144 if SPIRAM_USE_MALLOC && CONFIG_SPIRAM
- Default value:
32768 if SPIRAM_USE_MALLOC && CONFIG_SPIRAM
CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY
Allow .bss segment placed in external memory
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
If enabled, variables with EXT_RAM_BSS_ATTR attribute will be placed in SPIRAM instead of internal DRAM. BSS section of lwip, net80211, pp, bt libraries will be automatically placed in SPIRAM. BSS sections from other object files and libraries can also be placed in SPIRAM through linker fragment scheme extram_bss.
Note that the variables placed in SPIRAM using EXT_RAM_BSS_ATTR will be zero initialized.
- Default value:
No (disabled) if CONFIG_SPIRAM && CONFIG_SPIRAM
CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY
Allow .noinit segment placed in external memory
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
If enabled, noinit variables can be placed in PSRAM using EXT_RAM_NOINIT_ATTR.
Note the values placed into this section will not be initialized at startup and should keep its value after software restart.
- Default value:
No (disabled) if CONFIG_SPIRAM && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_WORKAROUND
Enable workaround for bug in SPI RAM cache for Rev1 ESP32s
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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.
The workaround is not required for ESP32 revision 3 and above.
- Default value:
Yes (enabled) if (SPIRAM_USE_MEMMAP || SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC) && CONFIG_SPIRAM
SPIRAM cache workaround debugging
Contains:
CONFIG_SPIRAM_CACHE_WORKAROUND_STRATEGY
Workaround strategy
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM cache workaround debugging
Select the workaround strategy. Note that the strategy for precompiled libraries (libgcc, newlib, bt, wifi) is not affected by this selection.
Unless you know you need a different strategy, it’s suggested you stay with the default MEMW strategy. Note that DUPLDST can interfere with hardware encryption and this will be automatically disabled if this workaround is selected. ‘Insert nops’ is the workaround that was used in older esp-idf versions. This workaround still can cause faulty data transfers from/to SPI RAM in some situation.
- Available options:
Insert memw after vulnerable instructions (default) (SPIRAM_CACHE_WORKAROUND_STRATEGY_MEMW)
Duplicate LD/ST for 32-bit, memw for 8/16 bit (SPIRAM_CACHE_WORKAROUND_STRATEGY_DUPLDST)
Insert nops between vulnerable loads/stores (old strategy, obsolete) (SPIRAM_CACHE_WORKAROUND_STRATEGY_NOPS)
SPIRAM workaround libraries placement
Contains:
CONFIG_SPIRAM_CACHE_LIBJMP_IN_IRAM
Put libc’s jump related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: longjmp and setjmp. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBMATH_IN_IRAM
Put libc’s math related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: abs, div, labs, ldiv, quorem, fpclassify, and nan. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBNUMPARSER_IN_IRAM
Put libc’s number parsing related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: utoa, itoa, atoi, atol, strtol, and strtoul. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBIO_IN_IRAM
Put libc’s I/O related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: wcrtomb, fvwrite, wbuf, wsetup, fputwc, wctomb_r, ungetc, makebuf, fflush, refill, and sccl. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBTIME_IN_IRAM
Put libc’s time related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: asctime, asctime_r, ctime, ctime_r, lcltime, lcltime_r, gmtime, gmtime_r, strftime, mktime, tzset_r, tzset, time, gettzinfo, systimes, month_lengths, timelocal, tzvars, tzlock, tzcalc_limits, and strptime. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBCHAR_IN_IRAM
Put libc’s characters related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: ctype_, toupper, tolower, toascii, strupr, bzero, isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, and isupper. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBMEM_IN_IRAM
Put libc’s memory related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: memccpy, memchr memmove, and memrchr. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBSTR_IN_IRAM
Put libc’s string related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: strcasecmp, strcasestr, strchr, strcoll, strcpy, strcspn, strdup, strdup_r, strlcat, strlcpy, strlen, strlwr, strncasecmp, strncat, strncmp, strncpy, strndup, strndup_r, strrchr, strsep, strspn, strstr, strtok_r, and strupr. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBRAND_IN_IRAM
Put libc’s random related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: srand, rand, and rand_r. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBENV_IN_IRAM
Put libc’s environment related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: environ, envlock, and getenv_r. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBFILE_IN_IRAM
Put libc’s file related functions in IRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: lock, isatty, fclose, open, close, creat, read, rshift, sbrk, stdio, syssbrk, sysclose, sysopen, creat, sysread, syswrite, impure, fwalk, and findfp. Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_CACHE_LIBMISC_IN_IRAM
Put libc’s miscellaneous functions in IRAM, see help
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > SPIRAM workaround libraries placement
The functions affected by this option are: raise and system Putting these function in IRAM will allow them to be called when flash cache is disabled but it will also reduce the available size of free IRAM for the user application.
- Default value:
Yes (enabled) if CONFIG_SPIRAM_CACHE_WORKAROUND && CONFIG_SPIRAM
CONFIG_SPIRAM_BANKSWITCH_ENABLE
Enable bank switching for >4MiB external RAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
The ESP32 only supports 4MiB of external RAM in its address space. The hardware does support larger memories, but these have to be bank-switched in and out of this address space. Enabling this allows you to reserve some MMU pages for this, which allows the use of the esp_himem api to manage these banks.
#Note that this is limited to 62 banks, as esp_psram_extram_writeback_cache needs some kind of mapping of #some banks below that mark to work. We cannot at this moment guarantee this to exist when himem is #enabled.
If spiram 2T mode is enabled, the size of 64Mbit psram will be changed as 32Mbit, so himem will be unusable.
- Default value:
Yes (enabled) if (SPIRAM_USE_MEMMAP || SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC) && CONFIG_SPIRAM
CONFIG_SPIRAM_BANKSWITCH_RESERVE
Amount of 32K pages to reserve for bank switching
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > CONFIG_SPIRAM_BANKSWITCH_ENABLE
Select the amount of banks reserved for bank switching. Note that the amount of RAM allocatable with malloc/esp_heap_alloc_caps will decrease by 32K for each page reserved here.
Note that this reservation is only actually done if your program actually uses the himem API. Without any himem calls, the reservation is not done and the original amount of memory will be available to malloc/esp_heap_alloc_caps.
- Range:
from 1 to 62 if CONFIG_SPIRAM_BANKSWITCH_ENABLE && CONFIG_SPIRAM
- Default value:
CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY
Allow external memory as an argument to xTaskCreateStatic
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
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 related task creaton functions) 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 enable this to cause xTaskCreateStatic to allow tasks stack in external memory.
- Default value:
No (disabled) if SPIRAM_USE_MALLOC && CONFIG_SPIRAM
CONFIG_SPIRAM_OCCUPY_SPI_HOST
SPI host to use for 32MBit PSRAM
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
When both flash and PSRAM is working under 80MHz, and the PSRAM is of type 32MBit, one of the HSPI/VSPI host will be used to output the clock. Select which one to use here.
- Available options:
HSPI host (SPI2) (SPIRAM_OCCUPY_HSPI_HOST)
VSPI host (SPI3) (SPIRAM_OCCUPY_VSPI_HOST)
Will not try to use any host, will abort if not able to use the PSRAM (SPIRAM_OCCUPY_NO_HOST)
PSRAM clock and cs IO for ESP32-DOWD
Contains:
CONFIG_D0WD_PSRAM_CLK_IO
PSRAM CLK IO number
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > PSRAM clock and cs IO for ESP32-DOWD
The PSRAM CLOCK IO can be any unused GPIO, user can config it based on hardware design. If user use 1.8V flash and 1.8V psram, this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
- Range:
from 0 to 33 if CONFIG_SPIRAM && CONFIG_SPIRAM
- Default value:
17 if CONFIG_SPIRAM && CONFIG_SPIRAM
CONFIG_D0WD_PSRAM_CS_IO
PSRAM CS IO number
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > PSRAM clock and cs IO for ESP32-DOWD
The PSRAM CS IO can be any unused GPIO, user can config it based on hardware design. If user use 1.8V flash and 1.8V psram, this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
- Range:
from 0 to 33 if CONFIG_SPIRAM && CONFIG_SPIRAM
- Default value:
16 if CONFIG_SPIRAM && CONFIG_SPIRAM
PSRAM clock and cs IO for ESP32-D2WD
Contains:
CONFIG_D2WD_PSRAM_CLK_IO
PSRAM CLK IO number
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > PSRAM clock and cs IO for ESP32-D2WD
User can config it based on hardware design. For ESP32-D2WD chip, the psram can only be 1.8V psram, so this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
- Range:
from 0 to 33 if CONFIG_SPIRAM && CONFIG_SPIRAM
- Default value:
9 if CONFIG_SPIRAM && CONFIG_SPIRAM
CONFIG_D2WD_PSRAM_CS_IO
PSRAM CS IO number
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > PSRAM clock and cs IO for ESP32-D2WD
User can config it based on hardware design. For ESP32-D2WD chip, the psram can only be 1.8V psram, so this value can only be one of 6, 7, 8, 9, 10, 11, 16, 17.
- Range:
from 0 to 33 if CONFIG_SPIRAM && CONFIG_SPIRAM
- Default value:
10 if CONFIG_SPIRAM && CONFIG_SPIRAM
PSRAM clock and cs IO for ESP32-PICO
Contains:
CONFIG_PICO_PSRAM_CS_IO
PSRAM CS IO number
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config > PSRAM clock and cs IO for ESP32-PICO
The PSRAM CS IO can be any unused GPIO, user can config it based on hardware design.
For ESP32-PICO chip, the psram share clock with flash, so user do not need to configure the clock IO. For the reference hardware design, please refer to https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf
- Range:
from 0 to 33 if CONFIG_SPIRAM && CONFIG_SPIRAM
- Default value:
10 if CONFIG_SPIRAM && CONFIG_SPIRAM
CONFIG_SPIRAM_CUSTOM_SPIWP_SD3_PIN
Use custom SPI PSRAM WP(SD3) Pin when flash pins set in eFuse (read help)
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
This setting is only used if the SPI flash pins have been overridden by setting the eFuses SPI_PAD_CONFIG_xxx, and the SPI flash mode is DIO or DOUT.
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. The psram only has QPI mode, so a WP pin setting is necessary.
If this config item is set to N (default), the correct WP pin will be automatically used for any Espressif chip or module with integrated flash. If a custom setting is needed, set this config item to Y and specify the GPIO number connected to the WP pin.
When flash mode is set to QIO or QOUT, the PSRAM WP pin will be set the same as the SPI Flash WP pin configured in the bootloader.
- Default value:
No (disabled) if (ESPTOOLPY_FLASHMODE_DIO || ESPTOOLPY_FLASHMODE_DOUT) && CONFIG_SPIRAM
CONFIG_SPIRAM_SPIWP_SD3_PIN
Custom SPI PSRAM WP(SD3) Pin
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
The option “Use custom SPI PSRAM WP(SD3) pin” must be set or this value is ignored
If burning a customized set of SPI flash pins in eFuse and using DIO or DOUT mode for flash, set this value to the GPIO number of the SPIRAM WP pin.
- Range:
from 0 to 33 if (ESPTOOLPY_FLASHMODE_DIO || ESPTOOLPY_FLASHMODE_DOUT) && CONFIG_SPIRAM
- Default value:
7 if (ESPTOOLPY_FLASHMODE_DIO || ESPTOOLPY_FLASHMODE_DOUT) && CONFIG_SPIRAM
CONFIG_SPIRAM_2T_MODE
Enable SPI PSRAM 2T mode
Found in: Component config > ESP PSRAM > CONFIG_SPIRAM > SPI RAM config
Enable this option to fix single bit errors inside 64Mbit PSRAM.
Some 64Mbit PSRAM chips have a hardware issue in the RAM which causes bit errors at multiple fixed bit positions.
Note: If this option is enabled, the 64Mbit PSRAM chip will appear to be 32Mbit in size. Applications will not be affected unless the use the esp_himem APIs, which are not supported in 2T mode.
- Default value:
No (disabled) if CONFIG_SPIRAM && CONFIG_SPIRAM
ESP Ringbuf
Contains:
CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH
Place non-ISR ringbuf functions into flash
Found in: Component config > ESP Ringbuf
Place non-ISR ringbuf functions (like xRingbufferCreate/xRingbufferSend) into flash. This frees up IRAM, but the functions can no longer be called when the cache is disabled.
- Default value:
No (disabled)
CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH
Place ISR ringbuf functions into flash
Found in: Component config > ESP Ringbuf
Place non-ISR ringbuf functions (like xRingbufferSendFromISR/xRingbufferReceiveFromISR) into flash. This frees up IRAM, but the functions can no longer be called when the cache is disabled or from an IRAM interrupt context.
This option is not compatible with ESP-IDF drivers which is configured to run the ISR from an IRAM context, e.g. CONFIG_UART_ISR_IN_IRAM.
- Default value:
No (disabled)
ESP System Settings
Contains:
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ
CPU frequency
Found in: Component config > ESP System Settings
CPU frequency to be set on application startup.
- Available options:
40 MHz (ESP_DEFAULT_CPU_FREQ_MHZ_40)
80 MHz (ESP_DEFAULT_CPU_FREQ_MHZ_80)
160 MHz (ESP_DEFAULT_CPU_FREQ_MHZ_160)
240 MHz (ESP_DEFAULT_CPU_FREQ_MHZ_240)
Memory
Contains:
CONFIG_ESP32_RTCDATA_IN_FAST_MEM
Place RTC_DATA_ATTR and RTC_RODATA_ATTR variables into RTC fast memory segment
Found in: Component config > ESP System Settings > Memory
This option allows to place .rtc_data and .rtc_rodata sections into RTC fast memory segment to free the slow memory region for ULP programs. This option depends on the CONFIG_FREERTOS_UNICORE option because RTC fast memory can be accessed only by PRO_CPU core.
- Default value:
No (disabled) if CONFIG_FREERTOS_UNICORE
CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
Use fixed static RAM size
Found in: Component config > ESP System Settings > Memory
If this option is disabled, the DRAM part of the heap starts right after the .bss section, within the dram0_0 region. As a result, adding or removing some static variables will change the available heap size.
If this option is enabled, the DRAM part of the heap starts right after the dram0_0 region, where its length is set with ESP32_FIXED_STATIC_RAM_SIZE
- Default value:
No (disabled)
CONFIG_ESP32_FIXED_STATIC_RAM_SIZE
Fixed Static RAM size
Found in: Component config > ESP System Settings > Memory > CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
RAM size dedicated for static variables (.data & .bss sections). Please note that the actual length will be reduced by BTDM_RESERVE_DRAM if Bluetooth controller is enabled.
- Range:
from 0 to 0x2c200 if CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
- Default value:
“0x1E000” if CONFIG_ESP32_USE_FIXED_STATIC_RAM_SIZE
CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY
Enable IRAM as 8 bit accessible memory
Found in: Component config > ESP System Settings > Memory
If enabled, application can use IRAM as byte accessible region for storing data (Note: IRAM region cannot be used as task stack)
This is possible due to handling of exceptions LoadStoreError (3) and LoadStoreAlignmentError (9) Each unaligned read/write access will incur a penalty of maximum of 167 CPU cycles.
Trace memory
Contains:
CONFIG_ESP32_TRAX
Use TRAX tracing feature
Found in: Component config > ESP System Settings > Trace memory
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.
- Default value:
No (disabled)
CONFIG_ESP32_TRAX_TWOBANKS
Reserve memory for tracing both pro as well as app cpu execution
Found in: Component config > ESP System Settings > Trace memory > CONFIG_ESP32_TRAX
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.
# Memory to reverse for trace, used in linker script
- Default value:
No (disabled) if CONFIG_ESP32_TRAX && CONFIG_FREERTOS_UNICORE
CONFIG_ESP_SYSTEM_PANIC
Panic handler behaviour
Found in: Component config > ESP System Settings
If FreeRTOS detects unexpected behaviour or an unhandled exception, the panic handler is invoked. Configure the panic handler’s action here.
- Available options:
Print registers and halt (ESP_SYSTEM_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 (ESP_SYSTEM_PANIC_PRINT_REBOOT)
Outputs the relevant registers over the serial port and immediately reset the processor.
Silent reboot (ESP_SYSTEM_PANIC_SILENT_REBOOT)
Just resets the processor without outputting anything
GDBStub on panic (ESP_SYSTEM_PANIC_GDBSTUB)
Invoke gdbstub on the serial port, allowing for gdb to attach to it to do a postmortem of the crash.
GDBStub at runtime (ESP_SYSTEM_GDBSTUB_RUNTIME)
Invoke gdbstub on the serial port, allowing for gdb to attach to it and to do a debug on runtime.
CONFIG_ESP_SYSTEM_RTC_EXT_XTAL_BOOTSTRAP_CYCLES
Bootstrap cycles for external 32kHz crystal
Found in: Component config > ESP System Settings
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).
CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP
Enable RTC fast memory for dynamic allocations
Found in: Component config > ESP System Settings
This config option allows to add RTC fast memory region to system heap with capability similar to that of DRAM region but without DMA. This memory will be consumed first per heap initialization order by early startup services and scheduler related code. Speed wise RTC fast memory operates on APB clock and hence does not have much performance impact.
Memory protection
Contains:
CONFIG_ESP_SYSTEM_PMP_IDRAM_SPLIT
Enable IRAM/DRAM split protection
Found in: Component config > ESP System Settings > Memory protection
If enabled, the CPU watches all the memory access and raises an exception in case of any memory violation. This feature automatically splits the SRAM memory, using PMP, into data and instruction segments and sets Read/Execute permissions for the instruction part (below given splitting address) and Read/Write permissions for the data part (above the splitting address). The memory protection is effective on all access through the IRAM0 and DRAM0 buses.
- Default value:
Yes (enabled) if SOC_CPU_IDRAM_SPLIT_USING_PMP
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
Enable memory protection
Found in: Component config > ESP System Settings > Memory protection
If enabled, the permission control module watches all the memory access and fires the panic handler if a permission violation is detected. This feature automatically splits the SRAM memory into data and instruction segments and sets Read/Execute permissions for the instruction part (below given splitting address) and Read/Write permissions for the data part (above the splitting address). The memory protection is effective on all access through the IRAM0 and DRAM0 buses.
- Default value:
Yes (enabled) if SOC_MEMPROT_SUPPORTED
CONFIG_ESP_SYSTEM_MEMPROT_FEATURE_LOCK
Lock memory protection settings
Found in: Component config > ESP System Settings > Memory protection > CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
Once locked, memory protection settings cannot be changed anymore. The lock is reset only on the chip startup.
- Default value:
Yes (enabled) if CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE
System event queue size
Found in: Component config > ESP System Settings
Config system event queue size in different application.
- Default value:
32
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE
Event loop task stack size
Found in: Component config > ESP System Settings
Config system event task stack size in different application.
- Default value:
2304
CONFIG_ESP_MAIN_TASK_STACK_SIZE
Main task stack size
Found in: Component config > ESP System Settings
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.
- Default value:
3584
CONFIG_ESP_MAIN_TASK_AFFINITY
Main task core affinity
Found in: Component config > ESP System Settings
Configure the “main task” core affinity. This is the used core of the task which calls app_main(). If app_main() returns then this task is deleted.
- Available options:
CPU0 (ESP_MAIN_TASK_AFFINITY_CPU0)
CPU1 (ESP_MAIN_TASK_AFFINITY_CPU1)
No affinity (ESP_MAIN_TASK_AFFINITY_NO_AFFINITY)
CONFIG_ESP_CONSOLE_UART
Channel for console output
Found in: Component config > ESP System Settings
Select where to send console output (through stdout and stderr).
Default is to use UART0 on pre-defined GPIOs.
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 ROM output can be suppressed by GPIO strapping or EFUSE, refer to chip datasheet for details.
On chips with USB OTG peripheral, “USB CDC” option redirects output to the CDC port. This option uses the CDC driver in the chip ROM. This option is incompatible with TinyUSB stack.
On chips with an USB serial/JTAG debug controller, selecting the option for that redirects output to the CDC/ACM (serial port emulation) component of that device.
- Available options:
Default: UART0 (ESP_CONSOLE_UART_DEFAULT)
USB CDC (ESP_CONSOLE_USB_CDC)
USB Serial/JTAG Controller (ESP_CONSOLE_USB_SERIAL_JTAG)
Custom UART (ESP_CONSOLE_UART_CUSTOM)
None (ESP_CONSOLE_NONE)
CONFIG_ESP_CONSOLE_UART_NUM
UART peripheral to use for console output (0-1)
Found in: Component config > ESP System Settings
This UART peripheral is used for console output from the ESP-IDF Bootloader and the app.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
Due to an ESP32 ROM bug, UART2 is not supported for console output via esp_rom_printf.
- Available options:
UART0 (ESP_CONSOLE_UART_CUSTOM_NUM_0)
UART1 (ESP_CONSOLE_UART_CUSTOM_NUM_1)
CONFIG_ESP_CONSOLE_UART_TX_GPIO
UART TX on GPIO#
Found in: Component config > ESP System Settings
This GPIO is used for console UART TX output in the ESP-IDF Bootloader and the app (including boot log output and default standard output and standard error of the app).
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
- Range:
from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
- Default value:
1 if ESP_CONSOLE_UART_CUSTOM
43 if ESP_CONSOLE_UART_CUSTOM
CONFIG_ESP_CONSOLE_UART_RX_GPIO
UART RX on GPIO#
Found in: Component config > ESP System Settings
This GPIO is used for UART RX input in the ESP-IDF Bootloader and the app (including default default standard input of the app).
Note: The default ESP-IDF Bootloader configures this pin but doesn’t read anything from the UART.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
- Range:
from 0 to 46 if ESP_CONSOLE_UART_CUSTOM
- Default value:
3 if ESP_CONSOLE_UART_CUSTOM
44 if ESP_CONSOLE_UART_CUSTOM
CONFIG_ESP_CONSOLE_UART_BAUDRATE
UART console baud rate
Found in: Component config > ESP System Settings
This baud rate is used by both the ESP-IDF Bootloader and the app (including boot log output and default standard input/output/error of the app).
The app’s maximum baud rate depends on the UART clock source. If Power Management is disabled, the UART clock source is the APB clock and all baud rates in the available range will be sufficiently accurate. If Power Management is enabled, REF_TICK clock source is used so the baud rate is divided from 1MHz. Baud rates above 1Mbps are not possible and values between 500Kbps and 1Mbps may not be accurate.
If the configuration is different in the Bootloader binary compared to the app binary, UART is reconfigured after the bootloader exits and the app starts.
- Range:
from 1200 to 4000000 if CONFIG_PM_ENABLE
from 1200 to 1000000 if CONFIG_PM_ENABLE
- Default value:
115200
CONFIG_ESP_INT_WDT
Interrupt watchdog
Found in: Component config > ESP System Settings
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.
- Default value:
Yes (enabled)
CONFIG_ESP_INT_WDT_TIMEOUT_MS
Interrupt watchdog timeout (ms)
Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT
The timeout of the watchdog, in miliseconds. Make this higher than the FreeRTOS tick rate.
- Range:
from 10 to 10000
- Default value:
300 if CONFIG_SPIRAM && CONFIG_ESP_INT_WDT
800 if CONFIG_SPIRAM && CONFIG_ESP_INT_WDT
CONFIG_ESP_INT_WDT_CHECK_CPU1
Also watch CPU1 tick interrupt
Found in: Component config > ESP System Settings > CONFIG_ESP_INT_WDT
Also detect if interrupts on CPU 1 are disabled for too long.
- Default value:
Yes (enabled) if CONFIG_ESP_INT_WDT && CONFIG_FREERTOS_UNICORE
CONFIG_ESP_TASK_WDT_EN
Enable Task Watchdog Timer
Found in: Component config > ESP System Settings
The Task Watchdog Timer can be used to make sure individual tasks are still running. Enabling this option will enable the Task Watchdog Timer. It can be either initialized automatically at startup or initialized after startup (see Task Watchdog Timer API Reference)
- Default value:
Yes (enabled)
CONFIG_ESP_TASK_WDT_INIT
Initialize Task Watchdog Timer on startup
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT_EN
Enabling this option will cause the Task Watchdog Timer to be initialized automatically at startup.
- Default value:
Yes (enabled)
CONFIG_ESP_TASK_WDT_PANIC
Invoke panic handler on Task Watchdog timeout
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT_EN > CONFIG_ESP_TASK_WDT_INIT
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)
- Default value:
No (disabled)
CONFIG_ESP_TASK_WDT_TIMEOUT_S
Task Watchdog timeout period (seconds)
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT_EN > CONFIG_ESP_TASK_WDT_INIT
Timeout period configuration for the Task Watchdog Timer in seconds. This is also configurable at run time (see Task Watchdog Timer API Reference)
- Range:
from 1 to 60
- Default value:
5
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0
Watch CPU0 Idle Task
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT_EN > CONFIG_ESP_TASK_WDT_INIT
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.
- Default value:
Yes (enabled)
CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1
Watch CPU1 Idle Task
Found in: Component config > ESP System Settings > CONFIG_ESP_TASK_WDT_EN > CONFIG_ESP_TASK_WDT_INIT
If this option is enabled, the Task Watchdog Timer will wach the CPU1 Idle Task.
- Default value:
Yes (enabled) if CONFIG_ESP_TASK_WDT_INIT && CONFIG_FREERTOS_UNICORE
CONFIG_ESP_PANIC_HANDLER_IRAM
Place panic handler code in IRAM
Found in: Component config > ESP System Settings
If this option is disabled (default), the panic handler code is placed in flash not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
- Default value:
No (disabled)
CONFIG_ESP_DEBUG_STUBS_ENABLE
OpenOCD debug stubs
Found in: Component config > ESP System Settings
Debug stubs are used by OpenOCD to execute pre-compiled onboard code which does some useful debugging stuff, e.g. GCOV data dump.
- Default value:
“COMPILER_OPTIMIZATION_LEVEL_DEBUG” if CONFIG_ESP32_TRAX && ESP32S2_TRAX && ESP32S3_TRAX
CONFIG_ESP_DEBUG_OCDAWARE
Make exception and panic handlers JTAG/OCD aware
Found in: Component config > ESP System Settings
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.
- Default value:
Yes (enabled)
CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL
Interrupt level to use for Interrupt Watchdog and other system checks
Found in: Component config > ESP System Settings
Interrupt level to use for Interrupt Watchdog and other system checks.
- Available options:
Level 5 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_5)
Using level 5 interrupt for Interrupt Watchdog and other system checks.
Level 4 interrupt (ESP_SYSTEM_CHECK_INT_LEVEL_4)
Using level 4 interrupt for Interrupt Watchdog and other system checks.
Brownout Detector
Contains:
CONFIG_ESP_BROWNOUT_DET
Hardware brownout detect & reset
Found in: Component config > ESP System Settings > Brownout Detector
The ESP 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.
- Default value:
Yes (enabled)
CONFIG_ESP_BROWNOUT_DET_LVL_SEL
Brownout voltage level
Found in: Component config > ESP System Settings > Brownout Detector > CONFIG_ESP_BROWNOUT_DET
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 ESP chip.
#The voltage levels here are estimates, more work needs to be done to figure out the exact voltages #of the brownout threshold levels.
- Available options:
2.43V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_0)
2.48V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_1)
2.58V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_2)
2.62V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_3)
2.67V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_4)
2.70V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_5)
2.77V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_6)
2.80V +/- 0.05 (ESP_BROWNOUT_DET_LVL_SEL_7)
CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE
Permanently disable BASIC ROM Console
Found in: Component config > ESP System Settings
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.)
- Default value:
No (disabled)
IPC (Inter-Processor Call)
Contains:
CONFIG_ESP_IPC_TASK_STACK_SIZE
Inter-Processor Call (IPC) task stack size
Found in: Component config > IPC (Inter-Processor Call)
Configure the IPC tasks stack size. An 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 IPC stack size should be enough for most common simple use cases. However, users can increase/decrease the stack size to their needs.
- Range:
from 512 to 65536
- Default value:
1024
CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
IPC runs at caller’s priority
Found in: Component config > IPC (Inter-Processor Call)
If this option is not enabled then the IPC task will keep behavior same as prior to that of ESP-IDF v4.0, hence IPC task will run at (configMAX_PRIORITIES - 1) priority.
- Default value:
Yes (enabled) if CONFIG_FREERTOS_UNICORE
High resolution timer (esp_timer)
Contains:
CONFIG_ESP_TIMER_PROFILING
Enable esp_timer profiling features
Found in: Component config > High resolution timer (esp_timer)
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.
- Default value:
No (disabled)
CONFIG_ESP_TIMER_TASK_STACK_SIZE
High-resolution timer task stack size
Found in: Component config > High resolution timer (esp_timer)
Configure the stack size of “timer_task” 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.
- Range:
from 2048 to 65536
- Default value:
3584
CONFIG_ESP_TIMER_INTERRUPT_LEVEL
Interrupt level
Found in: Component config > High resolution timer (esp_timer)
It sets the interrupt level for esp_timer ISR in range 1..3. A higher level (3) helps to decrease the ISR esp_timer latency.
- Range:
from 1 to 3
from 1 to 1
- Default value:
1
CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD
Support ISR dispatch method
Found in: Component config > High resolution timer (esp_timer)
Allows using ESP_TIMER_ISR dispatch method (ESP_TIMER_TASK dispatch method is also avalible). - ESP_TIMER_TASK - Timer callbacks are dispatched from a high-priority esp_timer task. - ESP_TIMER_ISR - Timer callbacks are dispatched directly from the timer interrupt handler. The ISR dispatch can be used, in some cases, when a callback is very simple or need a lower-latency.
- Default value:
No (disabled)
Wi-Fi
Contains:
CONFIG_ESP32_WIFI_SW_COEXIST_ENABLE
Software controls WiFi/Bluetooth coexistence
Found in: Component config > Wi-Fi
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. If only Bluetooth is used, it is recommended to disable this option to reduce binary file size.
- Default value:
Yes (enabled) if CONFIG_BT_ENABLED
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM
Max number of WiFi static RX buffers
Found in: Component config > Wi-Fi
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.
- Range:
from 2 to 25
- Default value:
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM
Max number of WiFi dynamic RX buffers
Found in: Component config > Wi-Fi
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.
- Range:
from 0 to 128 if CONFIG_LWIP_WND_SCALE
from 0 to 1024 if CONFIG_LWIP_WND_SCALE
- Default value:
32
CONFIG_ESP32_WIFI_TX_BUFFER
Type of WiFi TX buffers
Found in: Component config > Wi-Fi
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.
- Available options:
Static (ESP32_WIFI_STATIC_TX_BUFFER)
Dynamic (ESP32_WIFI_DYNAMIC_TX_BUFFER)
CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM
Max number of WiFi static TX buffers
Found in: Component config > Wi-Fi
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.
- Range:
from 1 to 64 if ESP32_WIFI_STATIC_TX_BUFFER
- Default value:
16 if ESP32_WIFI_STATIC_TX_BUFFER
CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM
Max number of WiFi cache TX buffers
Found in: Component config > Wi-Fi
Set the number of WiFi cache TX buffer number.
For each TX packet from uplayer, such as LWIP etc, WiFi driver needs to allocate a static TX buffer and makes a copy of uplayer packet. If WiFi driver fails to allocate the static TX buffer, it caches the uplayer packets to a dedicated buffer queue, this option is used to configure the size of the cached TX queue.
- Range:
from 16 to 128 if CONFIG_SPIRAM
- Default value:
32 if CONFIG_SPIRAM
CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM
Max number of WiFi dynamic TX buffers
Found in: Component config > Wi-Fi
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.
- Range:
from 1 to 128
- Default value:
32
CONFIG_ESP32_WIFI_CSI_ENABLED
WiFi CSI(Channel State Information)
Found in: Component config > Wi-Fi
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.
- Default value:
No (disabled)
CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
WiFi AMPDU TX
Found in: Component config > Wi-Fi
Select this option to enable AMPDU TX feature
- Default value:
Yes (enabled)
CONFIG_ESP32_WIFI_TX_BA_WIN
WiFi AMPDU TX BA window size
Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED
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.
- Range:
from 2 to 32
- Default value:
6
CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED
WiFi AMPDU RX
Found in: Component config > Wi-Fi
Select this option to enable AMPDU RX feature
- Default value:
Yes (enabled)
CONFIG_ESP32_WIFI_RX_BA_WIN
WiFi AMPDU RX BA window size
Found in: Component config > Wi-Fi > CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED
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.
- Range:
from 2 to 32
- Default value:
CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED
WiFi AMSDU TX
Found in: Component config > Wi-Fi
Select this option to enable AMSDU TX feature
- Default value:
No (disabled) if CONFIG_SPIRAM
CONFIG_ESP32_WIFI_NVS_ENABLED
WiFi NVS flash
Found in: Component config > Wi-Fi
Select this option to enable WiFi NVS flash
- Default value:
Yes (enabled)
CONFIG_ESP32_WIFI_TASK_CORE_ID
WiFi Task Core ID
Found in: Component config > Wi-Fi
Pinned WiFi task to core 0 or core 1.
- Available options:
Core 0 (ESP32_WIFI_TASK_PINNED_TO_CORE_0)
Core 1 (ESP32_WIFI_TASK_PINNED_TO_CORE_1)
CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN
Max length of WiFi SoftAP Beacon
Found in: Component config > Wi-Fi
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.
- Range:
from 752 to 1256
- Default value:
752
CONFIG_ESP32_WIFI_MGMT_SBUF_NUM
WiFi mgmt short buffer number
Found in: Component config > Wi-Fi
Set the number of WiFi management short buffer.
- Range:
from 6 to 32
- Default value:
32
CONFIG_ESP32_WIFI_IRAM_OPT
WiFi IRAM speed optimization
Found in: Component config > Wi-Fi
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.
- Default value:
No (disabled) if CONFIG_BT_ENABLED && CONFIG_SPIRAM
Yes (enabled)
CONFIG_ESP32_WIFI_RX_IRAM_OPT
WiFi RX IRAM speed optimization
Found in: Component config > Wi-Fi
Select this option to place frequently called Wi-Fi library RX functions in IRAM. When this option is disabled, more than 17Kbytes of IRAM memory will be saved but Wi-Fi performance will be reduced.
- Default value:
No (disabled) if CONFIG_BT_ENABLED && CONFIG_SPIRAM
Yes (enabled)
CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE
Enable WPA3-Personal
Found in: Component config > Wi-Fi
Select this option to allow the device to establish a WPA3-Personal connection with eligible AP’s. PMF (Protected Management Frames) is a prerequisite feature for a WPA3 connection, it needs to be explicitly configured before attempting connection. Please refer to the Wi-Fi Driver API Guide for details.
- Default value:
Yes (enabled)
CONFIG_ESP32_WIFI_ENABLE_WPA3_OWE_STA
Enable OWE STA
Found in: Component config > Wi-Fi
Select this option to allow the device to establish OWE connection with eligible AP’s. PMF (Protected Management Frames) is a prerequisite feature for a WPA3 connection, it needs to be explicitly configured before attempting connection. Please refer to the Wi-Fi Driver API Guide for details.
- Default value:
Yes (enabled)
CONFIG_ESP_WIFI_SLP_IRAM_OPT
WiFi SLP IRAM speed optimization
Found in: Component config > Wi-Fi
Select this option to place called Wi-Fi library TBTT process and receive beacon functions in IRAM. Some functions can be put in IRAM either by ESP32_WIFI_IRAM_OPT and ESP32_WIFI_RX_IRAM_OPT, or this one. If already enabled ESP32_WIFI_IRAM_OPT, the other 7.3KB IRAM memory would be taken by this option. If already enabled ESP32_WIFI_RX_IRAM_OPT, the other 1.3KB IRAM memory would be taken by this option. If neither of them are enabled, the other 7.4KB IRAM memory would be taken by this option. Wi-Fi power-save mode average current would be reduced if this option is enabled.
CONFIG_ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME
Minimum active time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The minimum timeout for waiting to receive data, unit: milliseconds.
- Range:
from 8 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
- Default value:
CONFIG_ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME
Maximum keep alive time
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_IRAM_OPT
The maximum time that wifi keep alive, unit: seconds.
- Range:
from 10 to 60 if CONFIG_ESP_WIFI_SLP_IRAM_OPT
- Default value:
CONFIG_ESP_WIFI_FTM_ENABLE
WiFi FTM
Found in: Component config > Wi-Fi
Enable feature Fine Timing Measurement for calculating WiFi Round-Trip-Time (RTT).
CONFIG_ESP_WIFI_FTM_INITIATOR_SUPPORT
FTM Initiator support
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_FTM_ENABLE
- Default value:
Yes (enabled) if CONFIG_ESP_WIFI_FTM_ENABLE
CONFIG_ESP_WIFI_FTM_RESPONDER_SUPPORT
FTM Responder support
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_FTM_ENABLE
- Default value:
Yes (enabled) if CONFIG_ESP_WIFI_FTM_ENABLE
CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE
Power Management for station at disconnected
Found in: Component config > Wi-Fi
Select this option to enable power_management for station when disconnected. Chip will do modem-sleep when rf module is not in use any more.
- Default value:
Yes (enabled)
CONFIG_ESP_WIFI_GCMP_SUPPORT
WiFi GCMP Support(GCMP128 and GCMP256)
Found in: Component config > Wi-Fi
Select this option to enable GCMP support. GCMP support is compulsory for WiFi Suite-B support.
CONFIG_ESP_WIFI_GMAC_SUPPORT
WiFi GMAC Support(GMAC128 and GMAC256)
Found in: Component config > Wi-Fi
Select this option to enable GMAC support. GMAC support is compulsory for WiFi 192 bit certification.
- Default value:
No (disabled)
CONFIG_ESP_WIFI_SOFTAP_SUPPORT
WiFi SoftAP Support
Found in: Component config > Wi-Fi
WiFi module can be compiled without SoftAP to save code size.
- Default value:
Yes (enabled)
CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
Wifi sleep optimize when beacon lost
Found in: Component config > Wi-Fi
Enable wifi sleep optimization when beacon loss occurs and immediately enter sleep mode when the WiFi module detects beacon loss.
CONFIG_ESP_WIFI_SLP_BEACON_LOST_TIMEOUT
Beacon loss timeout
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
Timeout time for close rf phy when beacon loss occurs, Unit: 1024 microsecond.
- Range:
from 5 to 100 if CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
- Default value:
CONFIG_ESP_WIFI_SLP_BEACON_LOST_THRESHOLD
Maximum number of consecutive lost beacons allowed
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
Maximum number of consecutive lost beacons allowed, WiFi keeps Rx state when the number of consecutive beacons lost is greater than the given threshold.
- Range:
from 0 to 8 if CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
- Default value:
CONFIG_ESP_WIFI_SLP_PHY_ON_DELTA_EARLY_TIME
Delta early time for RF PHY on
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
Delta early time for rf phy on, When the beacon is lost, the next rf phy on will be earlier the time specified by the configuration item, Unit: 32 microsecond.
- Range:
from 0 to 100 if CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
- Default value:
CONFIG_ESP_WIFI_SLP_PHY_OFF_DELTA_TIMEOUT_TIME
Delta timeout time for RF PHY off
Found in: Component config > Wi-Fi > CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
Delta timeout time for rf phy off, When the beacon is lost, the next rf phy off will be delayed for the time specified by the configuration item. Unit: 1024 microsecond.
- Range:
from 0 to 8 if CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT
- Default value:
CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM
Maximum espnow encrypt peers number
Found in: Component config > Wi-Fi
Maximum number of encrypted peers supported by espnow. The number of hardware keys for encryption is fixed. And the espnow and SoftAP share the same hardware keys. So this configuration will affect the maximum connection number of SoftAP. Maximum espnow encrypted peers number + maximum number of connections of SoftAP = Max hardware keys number.
When using ESP mesh, this value should be set to a maximum of 6.
- Range:
from 0 to 17
- Default value:
7
Core dump
Contains:
CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART
Data destination
Found in: Component config > Core dump
Select place to store core dump: flash, uart or none (to disable core dumps generation).
Core dumps to Flash are not available if PSRAM is used for task stacks.
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.
- Available options:
Flash (ESP_COREDUMP_ENABLE_TO_FLASH)
UART (ESP_COREDUMP_ENABLE_TO_UART)
None (ESP_COREDUMP_ENABLE_TO_NONE)
CONFIG_ESP_COREDUMP_DATA_FORMAT
Core dump data format
Found in: Component config > Core dump
Select the data format for core dump.
- Available options:
Binary format (ESP_COREDUMP_DATA_FORMAT_BIN)
ELF format (ESP_COREDUMP_DATA_FORMAT_ELF)
CONFIG_ESP_COREDUMP_CHECKSUM
Core dump data integrity check
Found in: Component config > Core dump
Select the integrity check for the core dump.
- Available options:
Use CRC32 for integrity verification (ESP_COREDUMP_CHECKSUM_CRC32)
Use SHA256 for integrity verification (ESP_COREDUMP_CHECKSUM_SHA256)
CONFIG_ESP_COREDUMP_CHECK_BOOT
Check core dump data integrity on boot
Found in: Component config > Core dump
When enabled, if any data are found on the flash core dump partition, they will be checked by calculating their checksum.
- Default value:
Yes (enabled) if ESP_COREDUMP_ENABLE_TO_FLASH
CONFIG_ESP_COREDUMP_MAX_TASKS_NUM
Maximum number of tasks
Found in: Component config > Core dump
Maximum number of tasks snapshots in core dump.
CONFIG_ESP_COREDUMP_UART_DELAY
Delay before print to UART
Found in: Component config > Core dump
Config delay (in ms) before printing core dump to UART. Delay can be interrupted by pressing Enter key.
- Default value:
0 if ESP_COREDUMP_ENABLE_TO_UART
CONFIG_ESP_COREDUMP_STACK_SIZE
Reserved stack size
Found in: Component config > Core dump
Size of the memory to be reserved for core dump stack. If 0 core dump process will run on the stack of crashed task/ISR, otherwise special stack will be allocated. To ensure that core dump itself will not overflow task/ISR stack set this to the value above 800. NOTE: It eats DRAM.
CONFIG_ESP_COREDUMP_DECODE
Handling of UART core dumps in IDF Monitor
Found in: Component config > Core dump
- Available options:
Decode and show summary (info_corefile) (ESP_COREDUMP_DECODE_INFO)
Don’t decode (ESP_COREDUMP_DECODE_DISABLE)
FAT Filesystem support
Contains:
CONFIG_FATFS_VOLUME_COUNT
Number of volumes
Found in: Component config > FAT Filesystem support
Number of volumes (logical drives) to use.
- Range:
from 1 to 10
- Default value:
2
CONFIG_FATFS_SECTOR_SIZE
Sector size
Found in: Component config > FAT Filesystem support
Specify the size of the sector in bytes for FATFS partition generator.
- Available options:
512 (FATFS_SECTOR_512)
1024 (FATFS_SECTOR_1024)
2048 (FATFS_SECTOR_2048)
4096 (FATFS_SECTOR_4096)
CONFIG_FATFS_SECTORS_PER_CLUSTER
Sectors per cluster
Found in: Component config > FAT Filesystem support
This value specifies how many sectors there are in one cluster.
- Available options:
1 (FATFS_SECTORS_PER_CLUSTER_1)
2 (FATFS_SECTORS_PER_CLUSTER_2)
4 (FATFS_SECTORS_PER_CLUSTER_4)
8 (FATFS_SECTORS_PER_CLUSTER_8)
16 (FATFS_SECTORS_PER_CLUSTER_16)
32 (FATFS_SECTORS_PER_CLUSTER_32)
64 (FATFS_SECTORS_PER_CLUSTER_64)
128 (FATFS_SECTORS_PER_CLUSTER_128)
CONFIG_FATFS_CHOOSE_CODEPAGE
OEM Code Page
Found in: Component config > FAT Filesystem support
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.
- Available options:
Dynamic (all code pages supported) (FATFS_CODEPAGE_DYNAMIC)
US (CP437) (FATFS_CODEPAGE_437)
Arabic (CP720) (FATFS_CODEPAGE_720)
Greek (CP737) (FATFS_CODEPAGE_737)
KBL (CP771) (FATFS_CODEPAGE_771)
Baltic (CP775) (FATFS_CODEPAGE_775)
Latin 1 (CP850) (FATFS_CODEPAGE_850)
Latin 2 (CP852) (FATFS_CODEPAGE_852)
Cyrillic (CP855) (FATFS_CODEPAGE_855)
Turkish (CP857) (FATFS_CODEPAGE_857)
Portugese (CP860) (FATFS_CODEPAGE_860)
Icelandic (CP861) (FATFS_CODEPAGE_861)
Hebrew (CP862) (FATFS_CODEPAGE_862)
Canadian French (CP863) (FATFS_CODEPAGE_863)
Arabic (CP864) (FATFS_CODEPAGE_864)
Nordic (CP865) (FATFS_CODEPAGE_865)
Russian (CP866) (FATFS_CODEPAGE_866)
Greek 2 (CP869) (FATFS_CODEPAGE_869)
Japanese (DBCS) (CP932) (FATFS_CODEPAGE_932)
Simplified Chinese (DBCS) (CP936) (FATFS_CODEPAGE_936)
Korean (DBCS) (CP949) (FATFS_CODEPAGE_949)
Traditional Chinese (DBCS) (CP950) (FATFS_CODEPAGE_950)
CONFIG_FATFS_CHOOSE_TYPE
FAT type
Found in: Component config > FAT Filesystem support
If user specifies automatic detection of the FAT type, the FATFS generator will determine the type by the size.
- Available options:
Select a suitable FATFS type automatically. (FATFS_AUTO_TYPE)
FAT12 (FATFS_FAT12)
FAT16 (FATFS_FAT16)
CONFIG_FATFS_LONG_FILENAMES
Long filename support
Found in: Component config > FAT Filesystem 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 (Currently not supported by FATFS partition generator).
- Available options:
No long filenames (FATFS_LFN_NONE)
Long filename buffer in heap (FATFS_LFN_HEAP)
Long filename buffer on stack (FATFS_LFN_STACK)
CONFIG_FATFS_MAX_LFN
Max long filename length
Found in: Component config > FAT Filesystem support
Maximum long filename length. Can be reduced to save RAM.
- Range:
from 12 to 255
- Default value:
255
CONFIG_FATFS_API_ENCODING
API character encoding
Found in: Component config > FAT Filesystem support
Choose encoding for character and string arguments/returns when using FATFS APIs. The encoding of arguments will usually depend on text editor settings.
- Available options:
API uses ANSI/OEM encoding (FATFS_API_ENCODING_ANSI_OEM)
API uses UTF-8 encoding (FATFS_API_ENCODING_UTF_8)
CONFIG_FATFS_FS_LOCK
Number of simultaneously open files protected by lock function
Found in: Component config > FAT Filesystem support
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.
- Range:
from 0 to 65535
- Default value:
0
CONFIG_FATFS_TIMEOUT_MS
Timeout for acquiring a file lock, ms
Found in: Component config > FAT Filesystem support
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.
- Default value:
10000
CONFIG_FATFS_PER_FILE_CACHE
Use separate cache for each file
Found in: Component config > FAT Filesystem support
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.
- Default value:
Yes (enabled)
CONFIG_FATFS_ALLOC_PREFER_EXTRAM
Perfer external RAM when allocating FATFS buffers
Found in: Component config > FAT Filesystem support
When the option is enabled, internal buffers used by FATFS will be allocated from external RAM. If the allocation from external RAM fails, the buffer will be allocated from the internal RAM. Disable this option if optimizing for performance. Enable this option if optimizing for internal memory size.
- Default value:
Yes (enabled) if SPIRAM_USE_CAPS_ALLOC || SPIRAM_USE_MALLOC
CONFIG_FATFS_USE_FASTSEEK
Enable fast seek algorithm when using lseek function through VFS FAT
Found in: Component config > FAT Filesystem support
The fast seek feature enables fast backward/long seek operations without FAT access by using an in-memory CLMT (cluster link map table). Please note, fast-seek is only allowed for read-mode files, if a file is opened in write-mode, the seek mechanism will automatically fallback to the default implementation.
- Default value:
No (disabled)
CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE
Fast seek CLMT buffer size
Found in: Component config > FAT Filesystem support > CONFIG_FATFS_USE_FASTSEEK
If fast seek algorithm is enabled, this defines the size of CLMT buffer used by this algorithm in 32-bit word units. This value should be chosen based on prior knowledge of maximum elements of each file entry would store.
- Default value:
FreeRTOS
Contains:
Kernel
Contains:
CONFIG_FREERTOS_SMP
Run the SMP FreeRTOS kernel instead (FEATURE UNDER DEVELOPMENT)
Found in: Component config > FreeRTOS > Kernel
This will cause the FreeRTOS component to compile with the SMP FreeRTOS kernel instead. THIS FEATURE IS UNDER ACTIVE DEVELOPMENT, users use this at their own risk.
- Default value:
No (disabled)
CONFIG_FREERTOS_UNICORE
Run FreeRTOS only on first core
Found in: Component config > FreeRTOS > Kernel
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.
CONFIG_FREERTOS_HZ
configTICK_RATE_HZ
Found in: Component config > FreeRTOS > Kernel
Sets the FreeRTOS tick interrupt frequency in Hz (see configTICK_RATE_HZ documentation for more details).
- Range:
from 1 to 1000
- Default value:
100
CONFIG_FREERTOS_OPTIMIZED_SCHEDULER
configUSE_PORT_OPTIMISED_TASK_SELECTION
Found in: Component config > FreeRTOS > Kernel
Enables port specific task selection method. This option can will speed up the search of ready tasks when scheduling (see configUSE_PORT_OPTIMISED_TASK_SELECTION documentation for more details).
- Default value:
Yes (enabled) if CONFIG_FREERTOS_UNICORE
CONFIG_FREERTOS_CHECK_STACKOVERFLOW
configCHECK_FOR_STACK_OVERFLOW
Found in: Component config > FreeRTOS > Kernel
Enables FreeRTOS to check for stack overflows (see configCHECK_FOR_STACK_OVERFLOW documentation for more details).
Note: If users do not provide their own
vApplicationStackOverflowHook()
function, a default function will be provided by ESP-IDF.
- Available options:
No checking (FREERTOS_CHECK_STACKOVERFLOW_NONE)
Do not check for stack overflows (configCHECK_FOR_STACK_OVERFLOW = 0)
Check by stack pointer value (Method 1) (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 (Method 2) (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_THREAD_LOCAL_STORAGE_POINTERS
configNUM_THREAD_LOCAL_STORAGE_POINTERS
Found in: Component config > FreeRTOS > Kernel
Set the number of thread local storage pointers in each task (see configNUM_THREAD_LOCAL_STORAGE_POINTERS documentation for more details).
Note: In ESP-IDF, 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.
- Range:
from 1 to 256
- Default value:
1
CONFIG_FREERTOS_IDLE_TASK_STACKSIZE
configMINIMAL_STACK_SIZE (Idle task stack size)
Found in: Component config > FreeRTOS > Kernel
Sets the idle task stack size in bytes (see configMINIMAL_STACK_SIZE documentation for more details).
Note:
ESP-IDF specifies stack sizes in bytes instead of words.
The default size is enough for most use cases.
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.
Conversely, the stack size can be reduced to the minimum if non of the idle features are used.
- Range:
from 768 to 32768
- Default value:
1536
CONFIG_FREERTOS_USE_IDLE_HOOK
configUSE_IDLE_HOOK
Found in: Component config > FreeRTOS > Kernel
Enables the idle task application hook (see configUSE_IDLE_HOOK documentation for more details).
Note:
The application must provide the hook function
void vApplicationIdleHook( void );
vApplicationIdleHook()
is called from FreeRTOS idle task(s)The FreeRTOS idle hook is NOT the same as the ESP-IDF Idle Hook, but both can be enabled simultaneously.
- Default value:
No (disabled)
CONFIG_FREERTOS_USE_MINIMAL_IDLE_HOOK
Use FreeRTOS minimal idle hook
Found in: Component config > FreeRTOS > Kernel
Enables the minimal idle task application hook (see configUSE_IDLE_HOOK documentation for more details).
Note:
The application must provide the hook function
void vApplicationMinimalIdleHook( void );
vApplicationMinimalIdleHook()
is called from FreeRTOS minimal idle task(s)
- Default value:
No (disabled) if CONFIG_FREERTOS_SMP
CONFIG_FREERTOS_USE_TICK_HOOK
configUSE_TICK_HOOK
Found in: Component config > FreeRTOS > Kernel
Enables the tick hook (see configUSE_TICK_HOOK documentation for more details).
Note:
The application must provide the hook function
void vApplicationTickHook( void );
vApplicationTickHook()
is called from FreeRTOS’s tick handling functionxTaskIncrementTick()
The FreeRTOS tick hook is NOT the same as the ESP-IDF Tick Interrupt Hook, but both can be enabled simultaneously.
- Default value:
No (disabled)
CONFIG_FREERTOS_MAX_TASK_NAME_LEN
configMAX_TASK_NAME_LEN
Found in: Component config > FreeRTOS > Kernel
Sets the maximum number of characters for task names (see configMAX_TASK_NAME_LEN documentation for more details).
Note: For most uses, the default of 16 characters is sufficient.
- Range:
from 1 to 256
- Default value:
16
CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY
configENABLE_BACKWARD_COMPATIBILITY
Found in: Component config > FreeRTOS > Kernel
Enable backward compatibility with APIs prior to FreeRTOS v8.0.0. (see configENABLE_BACKWARD_COMPATIBILITY documentation for more details).
- Default value:
No (disabled)
CONFIG_FREERTOS_TIMER_TASK_PRIORITY
configTIMER_TASK_PRIORITY
Found in: Component config > FreeRTOS > Kernel
Sets the timer task’s priority (see configTIMER_TASK_PRIORITY documentation for more details).
- Range:
from 1 to 25
- Default value:
1
CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH
configTIMER_TASK_STACK_DEPTH
Found in: Component config > FreeRTOS > Kernel
Set the timer task’s stack size (see configTIMER_TASK_STACK_DEPTH documentation for more details).
- Range:
from 1536 to 32768
- Default value:
2048
CONFIG_FREERTOS_TIMER_QUEUE_LENGTH
configTIMER_QUEUE_LENGTH
Found in: Component config > FreeRTOS > Kernel
Set the timer task’s command queue length (see configTIMER_QUEUE_LENGTH documentation for more details).
- Range:
from 5 to 20
- Default value:
10
CONFIG_FREERTOS_QUEUE_REGISTRY_SIZE
configQUEUE_REGISTRY_SIZE
Found in: Component config > FreeRTOS > Kernel
Set the size of the queue registry (see configQUEUE_REGISTRY_SIZE documentation for more details).
Note: A value of 0 will disable queue registry functionality
- Range:
from 0 to 20
- Default value:
0
CONFIG_FREERTOS_USE_TRACE_FACILITY
configUSE_TRACE_FACILITY
Found in: Component config > FreeRTOS > Kernel
Enables additional structure members and functions to assist with execution visualization and tracing (see configUSE_TRACE_FACILITY documentation for more details).
- Default value:
No (disabled)
CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
configUSE_STATS_FORMATTING_FUNCTIONS
Found in: Component config > FreeRTOS > Kernel > CONFIG_FREERTOS_USE_TRACE_FACILITY
Set configUSE_TRACE_FACILITY and configUSE_STATS_FORMATTING_FUNCTIONS to 1 to include the
vTaskList()
andvTaskGetRunTimeStats()
functions in the build (see configUSE_STATS_FORMATTING_FUNCTIONS documentation for more details).
- Default value:
No (disabled) if CONFIG_FREERTOS_USE_TRACE_FACILITY
CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID
Enable display of xCoreID in vTaskList
Found in: Component config > FreeRTOS > Kernel > CONFIG_FREERTOS_USE_TRACE_FACILITY > CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
If enabled, this will include an extra column when vTaskList is called to display the CoreID the task is pinned to (0,1) or -1 if not pinned.
- Default value:
No (disabled) if CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS
CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS
configGENERATE_RUN_TIME_STATS
Found in: Component config > FreeRTOS > Kernel
Enables collection of run time statistics for each task (see configGENERATE_RUN_TIME_STATS documentation for more details).
Note: The clock used for run time statistics can be configured in FREERTOS_RUN_TIME_STATS_CLK.
- Default value:
No (disabled)
CONFIG_FREERTOS_USE_TICKLESS_IDLE
configUSE_TICKLESS_IDLE
Found in: Component config > FreeRTOS > Kernel
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. To skip unnecessary wake-up initialize a timer with the “skip_unhandled_events” option as true.
If disabled, automatic light sleep support will be disabled.
- Default value:
No (disabled) if CONFIG_PM_ENABLE
CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP
configEXPECTED_IDLE_TIME_BEFORE_SLEEP
Found in: Component config > FreeRTOS > Kernel > CONFIG_FREERTOS_USE_TICKLESS_IDLE
FreeRTOS will enter light sleep mode if no tasks need to run for this number of ticks.
- Range:
from 2 to 4294967295 if CONFIG_FREERTOS_USE_TICKLESS_IDLE
- Default value:
Port
Contains:
CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER
Wrap task functions
Found in: Component config > FreeRTOS > Port
If enabled, all FreeRTOS task functions will be enclosed in a wrapper function. If a task function mistakenly returns (i.e. does not delete), the call flow will return to the wrapper function. The wrapper function will then log an error and abort the application. This option is also required for GDB backtraces and C++ exceptions to work correctly inside top-level task functions.
- Default value:
Yes (enabled)
CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK
Enable stack overflow debug watchpoint
Found in: Component config > FreeRTOS > Port
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 last debug memory watchpoint 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 have one hardware watchpoint less because the last one is overwritten as soon as a task switch happens.
Another consequence is that due to alignment requirements of the watchpoint, the usable stack size decreases by up to 60 bytes. This is because the watchpoint region has to be aligned to its size and the size for the stack watchpoint in IDF is 32 bytes.
This check only triggers if the stack overflow writes within 32 bytes near 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.
- Default value:
No (disabled)
CONFIG_FREERTOS_TLSP_DELETION_CALLBACKS
Enable thread local storage pointers deletion callbacks
Found in: Component config > FreeRTOS > Port
ESP-IDF provides users with the ability to free TLSP memory by registering TLSP deletion callbacks. These callbacks are automatically called by FreeRTOS when a task is deleted. When this option is turned on, the memory reserved for TLSPs in the TCB is doubled to make space for storing the deletion callbacks. If the user does not wish to use TLSP deletion callbacks then this option could be turned off to save space in the TCB memory.
- Default value:
Yes (enabled) if CONFIG_FREERTOS_SMP && CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS > 0
CONFIG_FREERTOS_ENABLE_STATIC_TASK_CLEAN_UP
Enable static task clean up hook
Found in: Component config > FreeRTOS > Port
Enable this option to make FreeRTOS call the static task clean up hook when a task is deleted.
Note: Users will need to provide a
void vPortCleanUpTCB ( void \*pxTCB )
callback
- Default value:
No (disabled) if CONFIG_FREERTOS_SMP
CONFIG_FREERTOS_CHECK_MUTEX_GIVEN_BY_OWNER
Check that mutex semaphore is given by owner task
Found in: Component config > FreeRTOS > Port
If enabled, assert that when a mutex semaphore is given, the task giving the semaphore is the task which is currently holding the mutex.
- Default value:
Yes (enabled)
CONFIG_FREERTOS_ISR_STACKSIZE
ISR stack size
Found in: Component config > FreeRTOS > Port
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.
- Range:
from 2096 to 32768 if ESP_COREDUMP_DATA_FORMAT_ELF
from 1536 to 32768
- Default value:
2096 if ESP_COREDUMP_DATA_FORMAT_ELF
1536
CONFIG_FREERTOS_INTERRUPT_BACKTRACE
Enable backtrace from interrupt to task context
Found in: Component config > FreeRTOS > Port
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: higher level interrupt stack can be traced back to the lower level interrupt. This option adds 4 instructions to the interrupt dispatching code.
- Default value:
Yes (enabled)
CONFIG_FREERTOS_FPU_IN_ISR
Use float in Level 1 ISR
Found in: Component config > FreeRTOS > Port
When enabled, the usage of float type is allowed inside Level 1 ISRs. Note that usage of float types in higher level interrupts is still not permitted.
- Default value:
No (disabled)
CONFIG_FREERTOS_CORETIMER
Tick timer source (Xtensa Only)
Found in: Component config > FreeRTOS > Port
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.
- Available options:
Timer 0 (int 6, level 1) (FREERTOS_CORETIMER_0)
Select this to use timer 0
Timer 1 (int 15, level 3) (FREERTOS_CORETIMER_1)
Select this to use timer 1
SYSTIMER 0 (level 1) (FREERTOS_CORETIMER_SYSTIMER_LVL1)
Select this to use systimer with the 1 interrupt priority.
SYSTIMER 0 (level 3) (FREERTOS_CORETIMER_SYSTIMER_LVL3)
Select this to use systimer with the 3 interrupt priority.
CONFIG_FREERTOS_RUN_TIME_STATS_CLK
Choose the clock source for run time stats
Found in: Component config > FreeRTOS > Port
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.
- Available options:
Use ESP TIMER for run time stats (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 (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 ESP_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_PLACE_FUNCTIONS_INTO_FLASH
Place FreeRTOS functions into Flash
Found in: Component config > FreeRTOS > Port
When enabled the selected Non-ISR FreeRTOS functions will be placed into Flash memory instead of IRAM. This saves up to 8KB of IRAM depending on which functions are used.
- Default value:
No (disabled)
CONFIG_FREERTOS_PLACE_SNAPSHOT_FUNS_INTO_FLASH
Place task snapshot functions into flash
Found in: Component config > FreeRTOS > Port
When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, will be placed in flash. Note that if enabled, these functions cannot be called when cache is disabled.
- Default value:
No (disabled) if CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT && CONFIG_ESP_PANIC_HANDLER_IRAM
CONFIG_FREERTOS_CHECK_PORT_CRITICAL_COMPLIANCE
Tests compliance with Vanilla FreeRTOS port*_CRITICAL calls
Found in: Component config > FreeRTOS > Port
If enabled, context of port*_CRITICAL calls (ISR or Non-ISR) would be checked to be in compliance with Vanilla FreeRTOS. e.g Calling port*_CRITICAL from ISR context would cause assert failure
- Default value:
No (disabled)
CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION
Halt when an SMP-untested function is called
Found in: Component config > FreeRTOS > Port
Some functions in FreeRTOS have not been thoroughly tested yet when moving to the SMP implementation of FreeRTOS. When this option is enabled, these functions will throw an
assert()
.
- Default value:
Yes (enabled)
CONFIG_FREERTOS_ENABLE_TASK_SNAPSHOT
Enable task snapshot functions
Found in: Component config > FreeRTOS > Port
When enabled, the functions related to snapshots, such as vTaskGetSnapshot or uxTaskGetSnapshotAll, are compiled and linked. Task snapshots are used by Task Watchdog (TWDT), GDB Stub and Core dump.
- Default value:
Yes (enabled)
Hardware Abstraction Layer (HAL) and Low Level (LL)
Contains:
CONFIG_HAL_DEFAULT_ASSERTION_LEVEL
Default HAL assertion level
Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL)
Set the assert behavior / level for HAL component. HAL component assert level can be set separately, but the level can’t exceed the system assertion level. e.g. If the system assertion is disabled, then the HAL assertion can’t be enabled either. If the system assertion is enable, then the HAL assertion can still be disabled by this Kconfig option.
- Available options:
Same as system assertion level (HAL_ASSERTION_EQUALS_SYSTEM)
Disabled (HAL_ASSERTION_DISABLE)
Silent (HAL_ASSERTION_SILENT)
Enabled (HAL_ASSERTION_ENABLE)
CONFIG_HAL_LOG_LEVEL
HAL layer log verbosity
Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL)
Specify how much output to see in HAL logs.
- Available options:
No output (HAL_LOG_LEVEL_NONE)
Error (HAL_LOG_LEVEL_ERROR)
Warning (HAL_LOG_LEVEL_WARN)
Info (HAL_LOG_LEVEL_INFO)
Debug (HAL_LOG_LEVEL_DEBUG)
Verbose (HAL_LOG_LEVEL_VERBOSE)
CONFIG_HAL_SYSTIMER_USE_ROM_IMPL
Use ROM implementation of SysTimer HAL driver
Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL)
Enable this flag to use HAL functions from ROM instead of ESP-IDF.
If keeping this as “n” in your project, you will have less free IRAM. If making this as “y” in your project, you will increase free IRAM, but you will lose the possibility to debug this module, and some new features will be added and bugs will be fixed in the IDF source but cannot be synced to ROM.
- Default value:
Yes (enabled) if ESP_ROM_HAS_HAL_SYSTIMER
CONFIG_HAL_WDT_USE_ROM_IMPL
Use ROM implementation of WDT HAL driver
Found in: Component config > Hardware Abstraction Layer (HAL) and Low Level (LL)
Enable this flag to use HAL functions from ROM instead of ESP-IDF.
If keeping this as “n” in your project, you will have less free IRAM. If making this as “y” in your project, you will increase free IRAM, but you will lose the possibility to debug this module, and some new features will be added and bugs will be fixed in the IDF source but cannot be synced to ROM.
- Default value:
Yes (enabled) if ESP_ROM_HAS_HAL_WDT
Heap memory debugging
Contains:
CONFIG_HEAP_CORRUPTION_DETECTION
Heap corruption detection
Found in: Component config > Heap memory debugging
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.
- Available options:
Basic (no poisoning) (HEAP_POISONING_DISABLED)
Light impact (HEAP_POISONING_LIGHT)
Comprehensive (HEAP_POISONING_COMPREHENSIVE)
CONFIG_HEAP_TRACING_DEST
Heap tracing
Found in: Component config > Heap memory debugging
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.
- Available options:
Disabled (HEAP_TRACING_OFF)
Standalone (HEAP_TRACING_STANDALONE)
Host-based (HEAP_TRACING_TOHOST)
CONFIG_HEAP_TRACING_STACK_DEPTH
Heap tracing stack depth
Found in: Component config > Heap memory debugging
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.
CONFIG_HEAP_TASK_TRACKING
Enable heap task tracking
Found in: Component config > Heap memory debugging
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.
CONFIG_HEAP_ABORT_WHEN_ALLOCATION_FAILS
Abort if memory allocation fails
Found in: Component config > Heap memory debugging
When enabled, if a memory allocation operation fails it will cause a system abort.
- Default value:
No (disabled)
CONFIG_HEAP_TLSF_USE_ROM_IMPL
Use ROM implementation of heap tlsf library
Found in: Component config > Heap memory debugging
Enable this flag to use heap functions from ROM instead of ESP-IDF.
If keeping this as “n” in your project, you will have less free IRAM. If making this as “y” in your project, you will increase free IRAM, but you will lose the possibility to debug this module, and some new features will be added and bugs will be fixed in the IDF source but cannot be synced to ROM.
- Default value:
Yes (enabled) if ESP_ROM_HAS_HEAP_TLSF
Log output
Contains:
CONFIG_LOG_DEFAULT_LEVEL
Default log verbosity
Found in: Component config > Log output
Specify how much output to see in logs by default. You can set lower verbosity level at runtime using esp_log_level_set function.
By default, this setting limits which log statements are compiled into the program. For example, selecting “Warning” would mean that changing log level to “Debug” at runtime will not be possible. To allow increasing log level above the default at runtime, see the next option.
- Available options:
No output (LOG_DEFAULT_LEVEL_NONE)
Error (LOG_DEFAULT_LEVEL_ERROR)
Warning (LOG_DEFAULT_LEVEL_WARN)
Info (LOG_DEFAULT_LEVEL_INFO)
Debug (LOG_DEFAULT_LEVEL_DEBUG)
Verbose (LOG_DEFAULT_LEVEL_VERBOSE)
CONFIG_LOG_MAXIMUM_LEVEL
Maximum log verbosity
Found in: Component config > Log output
This config option sets the highest log verbosity that it’s possible to select at runtime by calling esp_log_level_set(). This level may be higher than the default verbosity level which is set when the app starts up.
This can be used enable debugging output only at a critical point, for a particular tag, or to minimize startup time but then enable more logs once the firmware has loaded.
Note that increasing the maximum available log level will increase the firmware binary size.
This option only applies to logging from the app, the bootloader log level is fixed at compile time to the separate “Bootloader log verbosity” setting.
- Available options:
Same as default (LOG_MAXIMUM_EQUALS_DEFAULT)
Error (LOG_MAXIMUM_LEVEL_ERROR)
Warning (LOG_MAXIMUM_LEVEL_WARN)
Info (LOG_MAXIMUM_LEVEL_INFO)
Debug (LOG_MAXIMUM_LEVEL_DEBUG)
Verbose (LOG_MAXIMUM_LEVEL_VERBOSE)
CONFIG_LOG_COLORS
Use ANSI terminal colors in log output
Found in: Component config > Log output
Enable ANSI terminal color codes in bootloader output.
In order to view these, your terminal program must support ANSI color codes.
- Default value:
Yes (enabled)
CONFIG_LOG_TIMESTAMP_SOURCE
Log Timestamps
Found in: Component config > Log output
Choose what sort of timestamp is displayed in the log output:
Milliseconds since boot is calulated from the RTOS tick count multiplied by the tick period. This time will reset after a software reboot. e.g. (90000)
System time is taken from POSIX time functions which use the chip’s RTC and high resoultion timers to maintain an accurate time. The system time is initialized to 0 on startup, it can be set with an SNTP sync, or with POSIX time functions. This time will not reset after a software reboot. e.g. (00:01:30.000)
NOTE: Currently this will not get used in logging from binary blobs (i.e WiFi & Bluetooth libraries), these will always print milliseconds since boot.
- Available options:
Milliseconds Since Boot (LOG_TIMESTAMP_SOURCE_RTOS)
System Time (LOG_TIMESTAMP_SOURCE_SYSTEM)
LWIP
Contains: