Configuration Options¶
Introduction¶
ESP-IDF uses Kconfig system to provide a compile-time configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc.
Applications developers can use make menuconfig
build target to edit components’ configuration. This configuration is saved inside sdkconfig
file in the project root directory. Based on sdkconfig
, application build targets will generate sdkconfig.h
file in the build directory, and will make sdkconfig options available to component makefiles.
Using sdkconfig.defaults¶
When updating ESP-IDF version, it is not uncommon to find that new Kconfig options are introduced. When this happens, application build targets will offer an interactive prompt to select values for the new options. New values are then written into sdkconfig
file. To supress interactive prompts, applications can either define BATCH_BUILD
environment variable, which will cause all prompts to be suppressed. This is the same effect as that of V
or VERBOSE
variables. Alternatively, defconfig
build target can be used to update configuration for all new variables to the default values.
In some cases, such as when sdkconfig
file is under revision control, the fact that sdkconfig
file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of sdkconfig.defaults
file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the sdkconfig
file. Once sdkconfig.defaults
is created, sdkconfig
can be deleted and added to the ignore list of the revision control system (e.g. .gitignore
file for git). Project build targets will automatically create sdkconfig
file, populated with the settings from sdkconfig.defaults
file, and the rest of the settings will be set to their default values. Note that when make defconfig
is used, settings in sdkconfig will be overriden by the ones in sdkconfig.defaults
. For more information, see Custom sdkconfig defaults.
Configuration Options Reference¶
Subsequent sections contain the list of available ESP-IDF options, automatically generated from Kconfig files. Note that depending on the options selected, some options listed here may not be visible by default in the interface of menuconfig.
By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with CONFIG_
. So if an option ENABLE_FOO
is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have CONFIG_ENABLE_FOO
defined. In this reference, option names are also prefixed with CONFIG_
, same as in the source code.
LWIP¶
L2_TO_L3_COPY¶
Enable copy between Layer2 and Layer3 packets
Found in: Component config > LWIP
If this feature is enabled, all traffic from layer2(WIFI Driver) will be copied to a new buffer before sending it to layer3(LWIP stack), freeing the layer2 buffer. Please be notified that the total layer2 receiving buffer is fixed and ESP32 currently supports 25 layer2 receiving buffer, when layer2 buffer runs out of memory, then the incoming packets will be dropped in hardware. The layer3 buffer is allocated from the heap, so the total layer3 receiving buffer depends on the available heap size, when heap runs out of memory, no copy will be sent to layer3 and packet will be dropped in layer2. Please make sure you fully understand the impact of this feature before enabling it.
LWIP_MAX_SOCKETS¶
Max number of open sockets
Found in: Component config > LWIP
Sockets take up a certain amount of memory, and allowing fewer sockets to be open at the same time conserves memory. Specify the maximum amount of sockets here. The valid value is from 1 to 16.
LWIP_SO_REUSE¶
Enable SO_REUSEADDR option
Found in: Component config > LWIP
Enabling this option allows binding to a port which remains in TIME_WAIT.
LWIP_SO_REUSE_RXTOALL¶
SO_REUSEADDR copies broadcast/multicast to all matches
Found in: Component config > LWIP
Enabling this option means that any incoming broadcast or multicast packet will be copied to all of the local sockets that it matches (may be more than one if SO_REUSEADDR is set on the socket.)
This increases memory overhead as the packets need to be copied, however they are only copied per matching socket. You can safely disable it if you don’t plan to receive broadcast or multicast traffic on more than one socket at a time.
LWIP_SO_RCVBUF¶
Enable SO_RCVBUF option
Found in: Component config > LWIP
Enabling this option allows checking for available data on a netconn.
LWIP_DHCP_MAX_NTP_SERVERS¶
Maximum number of NTP servers
Found in: Component config > LWIP
Set maximum number of NTP servers used by LwIP SNTP module. First argument of sntp_setserver/sntp_setservername functions is limited to this value.
LWIP_IP_FRAG¶
Enable fragment outgoing IP packets
Found in: Component config > LWIP
Enabling this option allows fragmenting outgoing IP packets if their size exceeds MTU.
LWIP_IP_REASSEMBLY¶
Enable reassembly incoming fragmented IP packets
Found in: Component config > LWIP
Enabling this option allows reassemblying incoming fragmented IP packets.
LWIP_STATS¶
Enable LWIP statistics
Found in: Component config > LWIP
Enabling this option allows LWIP statistics
LWIP_ETHARP_TRUST_IP_MAC¶
Enable LWIP ARP trust
Found in: Component config > LWIP
Enabling this option allows ARP table to be updated.
If this option is enabled, the incoming IP packets cause the ARP table to be updated with the source MAC and IP addresses supplied in the packet. You may want to disable this if you do not trust LAN peers to have the correct addresses, or as a limited approach to attempt to handle spoofing. If disabled, lwIP will need to make a new ARP request if the peer is not already in the ARP table, adding a little latency. The peer is in the ARP table if it requested our address before. Also notice that this slows down input processing of every IP packet!
- There are two known issues in real application if this feature is enabled:
- The LAN peer may have bug to update the ARP table after the ARP entry is aged out. If the ARP entry on the LAN peer is aged out but failed to be updated, all IP packets sent from LWIP to the LAN peer will be dropped by LAN peer.
- The LAN peer may not be trustful, the LAN peer may send IP packets to LWIP with two different MACs, but the same IP address. If this happens, the LWIP has problem to receive IP packets from LAN peer.
So the recommendation is to disable this option. Here the LAN peer means the other side to which the ESP station or soft-AP is connected.
ESP_GRATUITOUS_ARP¶
Send gratuitous ARP periodically
Found in: Component config > LWIP
Enable this option allows to send gratuitous ARP periodically.
This option solve the compatibility issues.If the ARP table of the AP is old, and the AP doesn’t send ARP request to update it’s ARP table, this will lead to the STA sending IP packet fail. Thus we send gratuitous ARP periodically to let AP update it’s ARP table.
GARP_TMR_INTERVAL¶
GARP timer interval(seconds)
Found in: Component config > LWIP
Set the timer interval for gratuitous ARP. The default value is 60s
TCPIP_RECVMBOX_SIZE¶
TCPIP task receive mail box size
Found in: Component config > LWIP
Set TCPIP task receive mail box size. Generally bigger value means higher throughput but more memory. The value should be bigger than UDP/TCP mail box size.
LWIP_DHCP_DOES_ARP_CHECK¶
DHCP: Perform ARP check on any offered address
Found in: Component config > LWIP
Enabling this option performs a check (via ARP request) if the offered IP address is not already in use by another host on the network.
DHCP server¶
LWIP_DHCPS_LEASE_UNIT¶
Multiplier for lease time, in seconds
Found in: Component config > LWIP > DHCP server
The DHCP server is calculating lease time multiplying the sent and received times by this number of seconds per unit. The default is 60, that equals one minute.
LWIP_DHCPS_MAX_STATION_NUM¶
Maximum number of stations
Found in: Component config > LWIP > DHCP server
The maximum number of DHCP clients that are connected to the server. After this number is exceeded, DHCP server removes of the oldest device from it’s address pool, without notification.
LWIP_AUTOIP¶
Enable IPV4 Link-Local Addressing (AUTOIP)
Found in: Component config > LWIP
Enabling this option allows the device to self-assign an address in the 169.256/16 range if none is assigned statically or via DHCP.
See RFC 3927.
LWIP_AUTOIP_TRIES¶
DHCP Probes before self-assigning IPv4 LL address
Found in: Component config > LWIP
DHCP client will send this many probes before self-assigning a link local address.
From LWIP help: “This can be set as low as 1 to get an AutoIP address very quickly, but you should be prepared to handle a changing IP address when DHCP overrides AutoIP.” (In the case of ESP-IDF, this means multiple SYSTEM_EVENT_STA_GOT_IP events.)
LWIP_AUTOIP_MAX_CONFLICTS¶
Max IP conflicts before rate limiting
Found in: Component config > LWIP
If the AUTOIP functionality detects this many IP conflicts while self-assigning an address, it will go into a rate limited mode.
LWIP_AUTOIP_RATE_LIMIT_INTERVAL¶
Rate limited interval (seconds)
Found in: Component config > LWIP
If rate limiting self-assignment requests, wait this long between each request.
LWIP_NETIF_LOOPBACK¶
Support per-interface loopback
Found in: Component config > LWIP
Enabling this option means that if a packet is sent with a destination address equal to the interface’s own IP address, it will “loop back” and be received by this interface.
LWIP_LOOPBACK_MAX_PBUFS¶
Max queued loopback packets per interface
Found in: Component config > LWIP
Configure the maximum number of packets which can be queued for loopback on a given interface. Reducing this number may cause packets to be dropped, but will avoid filling memory with queued packet data.
TCP¶
LWIP_MAX_ACTIVE_TCP¶
Maximum active TCP Connections
Found in: Component config > LWIP > TCP
The maximum number of simultaneously active TCP connections. The practical maximum limit is determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new TCP connections after the limit is reached.
LWIP_MAX_LISTENING_TCP¶
Maximum listening TCP Connections
Found in: Component config > LWIP > TCP
The maximum number of simultaneously listening TCP connections. The practical maximum limit is determined by available heap memory at runtime.
Changing this value by itself does not substantially change the memory usage of LWIP, except for preventing new listening TCP connections after the limit is reached.
TCP_MAXRTX¶
Maximum number of retransmissions of data segments
Found in: Component config > LWIP > TCP
Set maximum number of retransmissions of data segments.
TCP_SYNMAXRTX¶
Maximum number of retransmissions of SYN segments
Found in: Component config > LWIP > TCP
Set maximum number of retransmissions of SYN segments.
TCP_MSS¶
Maximum Segment Size (MSS)
Found in: Component config > LWIP > TCP
Set maximum segment size for TCP transmission.
Can be set lower to save RAM, the default value 1436 will give best throughput.
TCP_MSL¶
Maximum segment lifetime (MSL)
Found in: Component config > LWIP > TCP
Set maximum segment lifetime in in milliseconds.
TCP_SND_BUF_DEFAULT¶
Default send buffer size
Found in: Component config > LWIP > TCP
Set default send buffer size for new TCP sockets.
Per-socket send buffer size can be changed at runtime with lwip_setsockopt(s, TCP_SNDBUF, …).
This value must be at least 2x the MSS size, and the default is 4x the default MSS size.
Setting a smaller default SNDBUF size can save some RAM, but will decrease performance.
TCP_WND_DEFAULT¶
Default receive window size
Found in: Component config > LWIP > TCP
Set default TCP receive window size for new TCP sockets.
Per-socket receive window size can be changed at runtime with lwip_setsockopt(s, TCP_WINDOW, …).
Setting a smaller default receive window size can save some RAM, but will significantly decrease performance.
TCP_RECVMBOX_SIZE¶
Default TCP receive mail box size
Found in: Component config > LWIP > TCP
Set TCP receive mail box size. Generally bigger value means higher throughput but more memory. The recommended value is: TCP_WND_DEFAULT/TCP_MSS + 2, e.g. if TCP_WND_DEFAULT=14360, TCP_MSS=1436, then the recommended receive mail box size is (14360/1436 + 2) = 12.
TCP receive mail box is a per socket mail box, when the application receives packets from TCP socket, LWIP core firstly posts the packets to TCP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum TCP_RECCVMBOX_SIZE packets for each TCP socket, so the maximum possible cached TCP packets for all TCP sockets is TCP_RECCVMBOX_SIZE multiples the maximum TCP socket number. In other words, the bigger TCP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we need to make sure the TCP receive mail box is big enough to avoid packet drop between LWIP core and application.
TCP_QUEUE_OOSEQ¶
Queue incoming out-of-order segments
Found in: Component config > LWIP > TCP
Queue incoming out-of-order segments for later use.
Disable this option to save some RAM during TCP sessions, at the expense of increased retransmissions if segments arrive out of order.
ESP_TCP_KEEP_CONNECTION_WHEN_IP_CHANGES¶
Keep TCP connections when IP changed
Found in: Component config > LWIP > TCP
This option is enabled when the following scenario happen: network dropped and reconnected, IP changes is like: 192.168.0.2->0.0.0.0->192.168.0.2
Disable this option to keep consistent with the original LWIP code behavior.
TCP_OVERSIZE¶
Pre-allocate transmit PBUF size
Found in: Component config > LWIP > TCP
Allows enabling “oversize” allocation of TCP transmission pbufs ahead of time, which can reduce the length of pbuf chains used for transmission.
This will not make a difference to sockets where Nagle’s algorithm is disabled.
Default value of MSS is fine for most applications, 25% MSS may save some RAM when only transmitting small amounts of data. Disabled will have worst performance and fragmentation characteristics, but uses least RAM overall.
- Available options:
- TCP_OVERSIZE_MSS
- TCP_OVERSIZE_QUARTER_MSS
- TCP_OVERSIZE_DISABLE
UDP¶
LWIP_MAX_UDP_PCBS¶
Maximum active UDP control blocks
Found in: Component config > LWIP > UDP
The maximum number of active UDP “connections” (ie UDP sockets sending/receiving data). The practical maximum limit is determined by available heap memory at runtime.
UDP_RECVMBOX_SIZE¶
Default UDP receive mail box size
Found in: Component config > LWIP > UDP
Set UDP receive mail box size. The recommended value is 6.
UDP receive mail box is a per socket mail box, when the application receives packets from UDP socket, LWIP core firstly posts the packets to UDP receive mail box and the application then fetches the packets from mail box. It means LWIP can caches maximum UDP_RECCVMBOX_SIZE packets for each UDP socket, so the maximum possible cached UDP packets for all UDP sockets is UDP_RECCVMBOX_SIZE multiples the maximum UDP socket number. In other words, the bigger UDP_RECVMBOX_SIZE means more memory. On the other hand, if the receiv mail box is too small, the mail box may be full. If the mail box is full, the LWIP drops the packets. So generally we need to make sure the UDP receive mail box is big enough to avoid packet drop between LWIP core and application.
TCPIP_TASK_STACK_SIZE¶
TCP/IP Task Stack Size
Found in: Component config > LWIP
Configure TCP/IP task stack size, used by LWIP to process multi-threaded TCP/IP operations. Setting this stack too small will result in stack overflow crashes.
PPP_SUPPORT¶
Enable PPP support (new/experimental)
Found in: Component config > LWIP
Enable PPP stack. Now only PPP over serial is possible.
PPP over serial support is experimental and unsupported.
PPP_PAP_SUPPORT¶
Enable PAP support
Found in: Component config > LWIP
Enable Password Authentication Protocol (PAP) support
PPP_CHAP_SUPPORT¶
Enable CHAP support
Found in: Component config > LWIP
Enable Challenge Handshake Authentication Protocol (CHAP) support
PPP_MSCHAP_SUPPORT¶
Enable MSCHAP support
Found in: Component config > LWIP
Enable Microsoft version of the Challenge-Handshake Authentication Protocol (MSCHAP) support
PPP_MPPE_SUPPORT¶
Enable MPPE support
Found in: Component config > LWIP
Enable Microsoft Point-to-Point Encryption (MPPE) support
PPP_DEBUG_ON¶
Enable PPP debug log output
Found in: Component config > LWIP
Enable PPP debug log output
ICMP¶
LWIP_MULTICAST_PING¶
Respond to multicast pings
Found in: Component config > LWIP > ICMP
LWIP_BROADCAST_PING¶
Respond to broadcast pings
Found in: Component config > LWIP > ICMP
LWIP RAW API¶
LWIP_MAX_RAW_PCBS¶
Maximum LWIP RAW PCBs
Found in: Component config > LWIP > LWIP RAW API
The maximum number of simultaneously active LWIP RAW protocol control blocks. The practical maximum limit is determined by available heap memory at runtime.
libsodium¶
LIBSODIUM_USE_MBEDTLS_SHA¶
Use mbedTLS SHA256 & SHA512 implementations
Found in: Component config > libsodium
If this option is enabled, libsodium will use thin wrappers around mbedTLS for SHA256 & SHA512 operations.
This saves some code size if mbedTLS is also used. However it is incompatible with hardware SHA acceleration (due to the way libsodium’s API manages SHA state).
FreeRTOS¶
FREERTOS_UNICORE¶
Run FreeRTOS only on first core
Found in: Component config > FreeRTOS
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.
FREERTOS_CORETIMER¶
Xtensa timer to use as the FreeRTOS tick source
Found in: Component config > FreeRTOS
FreeRTOS needs a timer with an associated interrupt to use as the main tick source to increase counters, run timers and do pre-emptive multitasking with. There are multiple timers available to do this, with different interrupt priorities. Check
- Available options:
- FREERTOS_CORETIMER_0
- FREERTOS_CORETIMER_1
FREERTOS_HZ¶
Tick rate (Hz)
Found in: Component config > FreeRTOS
Select the tick rate at which FreeRTOS does pre-emptive context switching.
FREERTOS_ASSERT_ON_UNTESTED_FUNCTION¶
Halt when an SMP-untested function is called
Found in: Component config > FreeRTOS
Some functions in FreeRTOS have not been thoroughly tested yet when moving to the SMP implementation of FreeRTOS. When this option is enabled, these fuctions will throw an assert().
FREERTOS_CHECK_STACKOVERFLOW¶
Check for stack overflow
Found in: Component config > FreeRTOS
FreeRTOS can check for stack overflows in threads and trigger an user function called vApplicationStackOverflowHook when this happens.
- Available options:
- FREERTOS_CHECK_STACKOVERFLOW_NONE
- FREERTOS_CHECK_STACKOVERFLOW_PTRVAL
- FREERTOS_CHECK_STACKOVERFLOW_CANARY
FREERTOS_WATCHPOINT_END_OF_STACK¶
Set a debug watchpoint as a stack overflow check
Found in: Component config > FreeRTOS
FreeRTOS can check if a stack has overflown its bounds by checking either the value of the stack pointer or by checking the integrity of canary bytes. (See FREERTOS_CHECK_STACKOVERFLOW for more information.) These checks only happen on a context switch, and the situation that caused the stack overflow may already be long gone by then. This option will use the debug memory watchpoint 1 (the second one) to allow breaking into the debugger (or panic’ing) as soon as any of the last 32 bytes on the stack of a task are overwritten. The side effect is that using gdb, you effectively only have one watchpoint; the 2nd one is overwritten as soon as a task switch happens.
This check only triggers if the stack overflow writes within 4 bytes of the end of the stack, rather than overshooting further, so it is worth combining this approach with one of the other stack overflow check methods.
When this watchpoint is hit, gdb will stop with a SIGTRAP message. When no JTAG OCD is attached, esp-idf will panic on an unhandled debug exception.
FREERTOS_INTERRUPT_BACKTRACE¶
Enable backtrace from interrupt to task context
Found in: Component config > FreeRTOS
If this option is enabled, interrupt stack frame will be modified to point to the code of the interrupted task as its return address. This helps the debugger (or the panic handler) show a backtrace from the interrupt to the task which was interrupted. This also works for nested interrupts: higer level interrupt stack can be traced back to the lower level interrupt. This option adds 4 instructions to the interrupt dispatching code.
FREERTOS_THREAD_LOCAL_STORAGE_POINTERS¶
Number of thread local storage pointers
Found in: Component config > FreeRTOS
FreeRTOS has the ability to store per-thread pointers in the task control block. This controls the number of pointers available.
This value must be at least 1. Index 0 is reserved for use by the pthreads API thread-local-storage. Other indexes can be used for any desired purpose.
FREERTOS_ASSERT¶
FreeRTOS assertions
Found in: Component config > FreeRTOS
Failed FreeRTOS configASSERT() assertions can be configured to behave in different ways.
- Available options:
- FREERTOS_ASSERT_FAIL_ABORT
- FREERTOS_ASSERT_FAIL_PRINT_CONTINUE
- FREERTOS_ASSERT_DISABLE
FREERTOS_IDLE_TASK_STACKSIZE¶
Idle Task stack size
Found in: Component config > FreeRTOS
The idle task has its own stack, sized in bytes. The default size is enough for most uses. Size can be reduced to 768 bytes if no (or simple) FreeRTOS idle hooks are used. The stack size may need to be increased above the default if the app installs idle hooks that use a lot of stack memory.
FREERTOS_ISR_STACKSIZE¶
ISR stack size
Found in: Component config > FreeRTOS
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.
FREERTOS_LEGACY_HOOKS¶
Use FreeRTOS legacy hooks
Found in: Component config > FreeRTOS
FreeRTOS offers a number of hooks/callback functions that are called when a timer tick happens, the idle thread runs etc. esp-idf replaces these by runtime registerable hooks using the esp_register_freertos_xxx_hook system, but for legacy reasons the old hooks can also still be enabled. Please enable this only if you have code that for some reason can’t be migrated to the esp_register_freertos_xxx_hook system.
FREERTOS_LEGACY_IDLE_HOOK¶
Enable legacy idle hook
Found in: Component config > FreeRTOS
If enabled, FreeRTOS will call a function called vApplicationIdleHook when the idle thread on a CPU is running. Please make sure your code defines such a function.
FREERTOS_LEGACY_TICK_HOOK¶
Enable legacy tick hook
Found in: Component config > FreeRTOS
If enabled, FreeRTOS will call a function called vApplicationTickHook when a FreeRTOS tick is executed. Please make sure your code defines such a function.
FREERTOS_MAX_TASK_NAME_LEN¶
Maximum task name length
Found in: Component config > FreeRTOS
Changes the maximum task name length. Each task allocated will include this many bytes for a task name. Using a shorter value saves a small amount of RAM, a longer value allows more complex names.
For most uses, the default of 16 is OK.
SUPPORT_STATIC_ALLOCATION¶
Enable FreeRTOS static allocation API
Found in: Component config > FreeRTOS
FreeRTOS gives the application writer the ability to instead provide the memory themselves, allowing the following objects to optionally be created without any memory being allocated dynamically:
- Tasks
- Software Timers (Daemon task is still dynamic. See documentation)
- Queues
- Event Groups
- Binary Semaphores
- Counting Semaphores
- Recursive Semaphores
- Mutexes
Whether it is preferable to use static or dynamic memory allocation is dependent on the application, and the preference of the application writer. Both methods have pros and cons, and both methods can be used within the same RTOS application.
Creating RTOS objects using statically allocated RAM has the benefit of providing the application writer with more control: RTOS objects can be placed at specific memory locations. The maximum RAM footprint can be determined at link time, rather than run time. The application writer does not need to concern themselves with graceful handling of memory allocation failures. It allows the RTOS to be used in applications that simply don’t allow any dynamic memory allocation (although FreeRTOS includes allocation schemes that can overcome most objections).
ENABLE_STATIC_TASK_CLEAN_UP_HOOK¶
Enable static task clean up hook
Found in: Component config > FreeRTOS
Enable this option to make FreeRTOS call the static task clean up hook when a task is deleted.
Bear in mind that if this option is enabled you will need to implement the following function:
void vPortCleanUpTCB ( void *pxTCB ) { // place clean up code here }
TIMER_TASK_PRIORITY¶
FreeRTOS timer task priority
Found in: Component config > FreeRTOS
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the application’s executable binary.
Use this constant to define the priority that the timer task will run at.
TIMER_TASK_STACK_DEPTH¶
FreeRTOS timer task stack size
Found in: Component config > FreeRTOS
The timer service task (primarily) makes use of existing FreeRTOS features, allowing timer functionality to be added to an application with minimal impact on the size of the application’s executable binary.
Use this constant to define the size (in bytes) of the stack allocated for the timer task.
TIMER_QUEUE_LENGTH¶
FreeRTOS timer queue length
Found in: Component config > FreeRTOS
FreeRTOS provides a set of timer related API functions. Many of these functions use a standard FreeRTOS queue to send commands to the timer service task. The queue used for this purpose is called the ‘timer command queue’. The ‘timer command queue’ is private to the FreeRTOS timer implementation, and cannot be accessed directly.
For most uses the default value of 10 is OK.
FREERTOS_QUEUE_REGISTRY_SIZE¶
FreeRTOS queue registry size
Found in: Component config > FreeRTOS
FreeRTOS uses the queue registry as a means for kernel aware debuggers to locate queues, semaphores, and mutexes. The registry allows for a textual name to be associated with a queue for easy identification within a debugging GUI. A value of 0 will disable queue registry functionality, and a value larger than 0 will specify the number of queues/semaphores/mutexes that the registry can hold.
FREERTOS_USE_TRACE_FACILITY¶
Enable FreeRTOS trace facility
Found in: Component config > FreeRTOS
If enabled, configUSE_TRACE_FACILITY will be defined as 1 in FreeRTOS. This will allow the usage of trace facility functions such as uxTaskGetSystemState().
FREERTOS_USE_STATS_FORMATTING_FUNCTIONS¶
Enable FreeRTOS stats formatting functions
Found in: Component config > FreeRTOS
If enabled, configUSE_STATS_FORMATTING_FUNCTIONS will be defined as 1 in FreeRTOS. This will allow the usage of stats formatting functions such as vTaskList().
FREERTOS_GENERATE_RUN_TIME_STATS¶
Enable FreeRTOS to collect run time stats
Found in: Component config > FreeRTOS
If enabled, configGENERATE_RUN_TIME_STATS will be defined as 1 in FreeRTOS. This will allow FreeRTOS to collect information regarding the usage of processor time amongst FreeRTOS tasks. Run time stats are generated using either the ESP Timer or the CPU Clock as the clock source (Note that run time stats are only valid until the clock source overflows). The function vTaskGetRunTimeStats() will also be available if FREERTOS_USE_STATS_FORMATTING_FUNCTIONS and FREERTOS_USE_TRACE_FACILITY are enabled. vTaskGetRunTimeStats() will display the run time of each task as a % of the total run time of all CPUs (task run time / no of CPUs) / (total run time / 100 )
FREERTOS_RUN_TIME_STATS_CLK¶
Choose the clock source for run time stats
Found in: Component config > FreeRTOS
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:
- FREERTOS_RUN_TIME_STATS_USING_ESP_TIMER
- FREERTOS_RUN_TIME_STATS_USING_CPU_CLK
FREERTOS_DEBUG_INTERNALS¶
Debug FreeRTOS internals
Found in: Component config > FreeRTOS
Enable this option to show the menu with internal FreeRTOS debugging features. This option does not change any code by itself, it just shows/hides some options.
FREERTOS_PORTMUX_DEBUG¶
Debug portMUX portENTER_CRITICAL/portEXIT_CRITICAL
Found in: Component config > FreeRTOS
If enabled, debug information (including integrity checks) will be printed to UART for the port-specific MUX implementation.
FREERTOS_PORTMUX_DEBUG_RECURSIVE¶
Debug portMUX Recursion
Found in: Component config > FreeRTOS
If enabled, additional debug information will be printed for recursive portMUX usage.
ADC-Calibration¶
ADC_CAL_EFUSE_TP_ENABLE¶
Use Two Point Values
Found in: Component config > ADC-Calibration
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.
ADC_CAL_EFUSE_VREF_ENABLE¶
Use eFuse Vref
Found in: Component config > ADC-Calibration
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.
ADC_CAL_LUT_ENABLE¶
Use Lookup Tables
Found in: Component config > ADC-Calibration
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.
Wear Levelling¶
WL_SECTOR_SIZE¶
Wear Levelling library sector size
Found in: Component config > Wear Levelling
Sector size used by wear levelling library. You can set default sector size or size that will fit to the flash device sector size.
With sector size set to 4096 bytes, wear levelling library is more efficient. However if FAT filesystem is used on top of wear levelling library, it will need more temporary storage: 4096 bytes for each mounted filesystem and 4096 bytes for each opened file.
With sector size set to 512 bytes, wear levelling library will perform more operations with flash memory, but less RAM will be used by FAT filesystem library (512 bytes for the filesystem and 512 bytes for each file opened).
- Available options:
- WL_SECTOR_SIZE_512
- WL_SECTOR_SIZE_4096
WL_SECTOR_MODE¶
Sector store mode
Found in: Component config > Wear Levelling
Specify the mode to store data into flash:
- In Performance mode a data will be stored to the RAM and then stored back to the flash. Compared to the Safety mode, this operation is faster, but if power will be lost when erase sector operation is in progress, then the data from complete flash device sector will be lost.
- In Safety mode data from complete flash device sector will be read from flash, modified, and then stored back to flash. Compared to the Performance mode, this operation is slower, but if power is lost during erase sector operation, then the data from full flash device sector will not be lost.
- Available options:
- WL_SECTOR_MODE_PERF
- WL_SECTOR_MODE_SAFE
Heap memory debugging¶
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:
- HEAP_POISONING_DISABLED
- HEAP_POISONING_LIGHT
- HEAP_POISONING_COMPREHENSIVE
HEAP_TRACING¶
Enable 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.
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.
Partition Table¶
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. Otherwise it’s possible to create a new custom partition CSV for your application.
- Available options:
- PARTITION_TABLE_SINGLE_APP
- PARTITION_TABLE_TWO_OTA
- PARTITION_TABLE_CUSTOM
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.
PARTITION_TABLE_CUSTOM_APP_BIN_OFFSET¶
Factory app partition offset
Found in: Partition Table
If using a custom partition table, specify the offset in the flash where ‘make flash’ should write the built app.
PARTITION_TABLE_CUSTOM_PHY_DATA_OFFSET¶
PHY data partition offset
Found in: Partition Table
If using a custom partition table, specify the offset in the flash where ‘make flash’ should write the initial PHY data file.
ESP32-specific¶
ESP32_DEFAULT_CPU_FREQ_MHZ¶
CPU frequency
Found in: Component config > ESP32-specific
CPU frequency to be set on application startup.
- Available options:
- ESP32_DEFAULT_CPU_FREQ_80
- ESP32_DEFAULT_CPU_FREQ_160
- ESP32_DEFAULT_CPU_FREQ_240
MEMMAP_SMP¶
Reserve memory for two cores
Found in: Component config > ESP32-specific
The ESP32 contains two cores. If you plan to only use one, you can disable this item to save some memory. (ToDo: Make this automatically depend on unicore support)
SPIRAM_SUPPORT¶
Support for external, SPI-connected RAM
Found in: Component config > ESP32-specific
This enables support for an external SPI RAM chip, connected in parallel with the main SPI flash chip.
SPI RAM config¶
SPIRAM_BOOT_INIT¶
Initialize SPI RAM when booting the ESP32
Found in: Component config > ESP32-specific > 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.
SPIRAM_USE¶
SPI RAM access method
Found in: Component config > ESP32-specific > SPI RAM config
The SPI RAM can be accessed in multiple methods: by just having it available as an unmanaged memory region in the ESP32 memory map, by integrating it in the ESP32s heap as ‘special’ memory needing heap_caps_malloc to allocate, or by fully integrating it making malloc() also able to return SPI RAM pointers.
- Available options:
- SPIRAM_USE_MEMMAP
- SPIRAM_USE_CAPS_ALLOC
- SPIRAM_USE_MALLOC
SPIRAM_TYPE¶
Type of SPI RAM chip in use
Found in: Component config > ESP32-specific > SPI RAM config
- Available options:
- SPIRAM_TYPE_ESPPSRAM32
SPIRAM_SPEED¶
Set RAM clock speed
Found in: Component config > ESP32-specific > 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, the VSPI port will be occupied by the system.
Application code should never touch VSPI hardware in this case. The option to select 80MHz will only be visible if the flash SPI speed is also 80MHz. (ESPTOOLPY_FLASHFREQ_80M is true)
- Available options:
- SPIRAM_SPEED_40M
- SPIRAM_SPEED_80M
SPIRAM_MEMTEST¶
Run memory test on SPI RAM initialization
Found in: Component config > ESP32-specific > SPI RAM config
Runs a rudimentary memory test on initialization. Aborts when memory test fails. Disable this for slightly faster startop.
SPIRAM_CACHE_WORKAROUND¶
Enable workaround for bug in SPI RAM cache for Rev1 ESP32s
Found in: Component config > ESP32-specific > 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 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.
SPIRAM_MALLOC_ALWAYSINTERNAL¶
Maximum malloc() size, in bytes, to always put in internal memory
Found in: Component config > ESP32-specific > 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.
WIFI_LWIP_ALLOCATION_FROM_SPIRAM_FIRST¶
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, allocate internal memory
Found in: Component config > ESP32-specific > SPI RAM config
Try to allocate memories of WiFi and LWIP in SPIRAM firstly. If failed, try to allocate internal memory then.
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 > ESP32-specific > 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.
SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY¶
Allow external memory as an argument to xTaskCreateStatic
Found in: Component config > ESP32-specific > 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 friends always allocate stack in internal memory and xTaskCreateStatic will check if the memory passed to it is in internal memory. If you have a task that needs a large amount of stack and does not call on ROM code in any way (no direct calls, but also no Bluetooth/WiFi), you can try to disable this and use xTaskCreateStatic to create the tasks stack in external memory.
ESP32_TRAX¶
Use TRAX tracing feature
Found in: Component config > ESP32-specific
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.
ESP32_TRAX_TWOBANKS¶
Reserve memory for tracing both pro as well as app cpu execution
Found in: Component config > ESP32-specific
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.
ESP32_COREDUMP_TO_FLASH_OR_UART¶
Core dump destination
Found in: Component config > ESP32-specific
Select place to store core dump: flash, uart or none (to disable core dumps generation).
If core dump is configured to be stored in flash and custom partition table is used add corresponding entry to your CSV. For examples, please see predefined partition table CSV descriptions in the components/partition_table directory.
- Available options:
- ESP32_ENABLE_COREDUMP_TO_FLASH
- ESP32_ENABLE_COREDUMP_TO_UART
- ESP32_ENABLE_COREDUMP_TO_NONE
ESP32_CORE_DUMP_UART_DELAY¶
Core dump print to UART delay
Found in: Component config > ESP32-specific
Config delay (in ms) before printing core dump to UART. Delay can be interrupted by pressing Enter key.
ESP32_CORE_DUMP_LOG_LEVEL¶
Core dump module logging level
Found in: Component config > ESP32-specific
Config core dump module logging level (0-5).
NUMBER_OF_UNIVERSAL_MAC_ADDRESS¶
Number of universally administered (by IEEE) MAC address
Found in: Component config > ESP32-specific
Configure the number of universally administered (by IEEE) MAC addresses. During initialisation, MAC addresses for each network interface are generated or derived from a single base MAC address. If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. If the number of universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet) receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC addresses, respectively. When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
- Available options:
- TWO_UNIVERSAL_MAC_ADDRESS
- FOUR_UNIVERSAL_MAC_ADDRESS
SYSTEM_EVENT_QUEUE_SIZE¶
System event queue size
Found in: Component config > ESP32-specific
Config system event queue size in different application.
SYSTEM_EVENT_TASK_STACK_SIZE¶
Event loop task stack size
Found in: Component config > ESP32-specific
Config system event task stack size in different application.
MAIN_TASK_STACK_SIZE¶
Main task stack size
Found in: Component config > ESP32-specific
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.
IPC_TASK_STACK_SIZE¶
Inter-Processor Call (IPC) task stack size
Found in: Component config > ESP32-specific
Configure the IPC tasks stack size. One IPC task runs on each core (in dual core mode), and allows for cross-core function calls.
See IPC documentation for more details.
The default stack size should be enough for most common use cases. It can be shrunk if you are sure that you do not use any custom IPC functionality.
TIMER_TASK_STACK_SIZE¶
High-resolution timer task stack size
Found in: Component config > ESP32-specific
Configure the stack size of esp_timer/ets_timer task. This task is used to dispatch callbacks of timers created using ets_timer and esp_timer APIs. If you are seing stack overflow errors in timer task, increase this value.
Note that this is not the same as FreeRTOS timer task. To configure FreeRTOS timer task size, see “FreeRTOS timer task stack size” option in “FreeRTOS” menu.
NEWLIB_STDOUT_LINE_ENDING¶
Line ending for UART output
Found in: Component config > ESP32-specific
This option allows configuring the desired line endings sent to UART when a newline (‘n’, LF) appears on stdout. Three options are possible:
CRLF: whenever LF is encountered, prepend it with CR
LF: no modification is applied, stdout is sent as is
CR: each occurence of LF is replaced with CR
This option doesn’t affect behavior of the UART driver (drivers/uart.h).
- Available options:
- NEWLIB_STDOUT_LINE_ENDING_CRLF
- NEWLIB_STDOUT_LINE_ENDING_LF
- NEWLIB_STDOUT_LINE_ENDING_CR
NEWLIB_STDIN_LINE_ENDING¶
Line ending for UART input
Found in: Component config > ESP32-specific
This option allows configuring which input sequence on UART produces a newline (‘n’, LF) on stdin. Three options are possible:
CRLF: CRLF is converted to LF
LF: no modification is applied, input is sent to stdin as is
CR: each occurence of CR is replaced with LF
This option doesn’t affect behavior of the UART driver (drivers/uart.h).
- Available options:
- NEWLIB_STDIN_LINE_ENDING_CRLF
- NEWLIB_STDIN_LINE_ENDING_LF
- NEWLIB_STDIN_LINE_ENDING_CR
NEWLIB_NANO_FORMAT¶
Enable ‘nano’ formatting options for printf/scanf family
Found in: Component config > ESP32-specific
ESP32 ROM contains parts of newlib C library, including printf/scanf family of functions. These functions have been compiled with so-called “nano” formatting option. This option doesn’t support 64-bit integer formats and C99 features, such as positional arguments.
For more details about “nano” formatting option, please see newlib readme file, search for ‘–enable-newlib-nano-formatted-io’: https://sourceware.org/newlib/README
If this option is enabled, build system will use functions available in ROM, reducing the application binary size. Functions available in ROM run faster than functions which run from flash. Functions available in ROM can also run when flash instruction cache is disabled.
If you need 64-bit integer formatting support or C99 features, keep this option disabled.
CONSOLE_UART¶
UART for console output
Found in: Component config > ESP32-specific
Select whether to use UART for console output (through stdout and stderr).
- Default is to use UART0 on pins GPIO1(TX) and GPIO3(RX).
- If “Custom” is selected, UART0 or UART1 can be chosen, and any pins can be selected.
- If “None” is selected, there will be no console output on any UART, except for initial output from ROM bootloader. This output can be further suppressed by bootstrapping GPIO13 pin to low logic level.
- Available options:
- CONSOLE_UART_DEFAULT
- CONSOLE_UART_CUSTOM
- CONSOLE_UART_NONE
CONSOLE_UART_NUM¶
UART peripheral to use for console output (0-1)
Found in: Component config > ESP32-specific
Due of a ROM bug, UART2 is not supported for console output via ets_printf.
- Available options:
- CONSOLE_UART_CUSTOM_NUM_0
- CONSOLE_UART_CUSTOM_NUM_1
CONSOLE_UART_TX_GPIO¶
UART TX on GPIO#
Found in: Component config > ESP32-specific
CONSOLE_UART_RX_GPIO¶
UART RX on GPIO#
Found in: Component config > ESP32-specific
CONSOLE_UART_BAUDRATE¶
UART console baud rate
Found in: Component config > ESP32-specific
ULP_COPROC_ENABLED¶
Enable Ultra Low Power (ULP) Coprocessor
Found in: Component config > ESP32-specific
Set to ‘y’ if you plan to load a firmware for the coprocessor.
If this option is enabled, further coprocessor configuration will appear in the Components menu.
ULP_COPROC_RESERVE_MEM¶
RTC slow memory reserved for coprocessor
Found in: Component config > ESP32-specific
Bytes of memory to reserve for ULP coprocessor firmware & data.
Data is reserved at the beginning of RTC slow memory.
ESP32_PANIC¶
Panic handler behaviour
Found in: Component config > ESP32-specific
If FreeRTOS detects unexpected behaviour or an unhandled exception, the panic handler is invoked. Configure the panic handlers action here.
- Available options:
- ESP32_PANIC_PRINT_HALT
- ESP32_PANIC_PRINT_REBOOT
- ESP32_PANIC_SILENT_REBOOT
- ESP32_PANIC_GDBSTUB
ESP32_DEBUG_OCDAWARE¶
Make exception and panic handlers JTAG/OCD aware
Found in: Component config > ESP32-specific
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.
INT_WDT¶
Interrupt watchdog
Found in: Component config > ESP32-specific
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.
INT_WDT_TIMEOUT_MS¶
Interrupt watchdog timeout (ms)
Found in: Component config > ESP32-specific
The timeout of the watchdog, in miliseconds. Make this higher than the FreeRTOS tick rate.
INT_WDT_CHECK_CPU1¶
Also watch CPU1 tick interrupt
Found in: Component config > ESP32-specific
Also detect if interrupts on CPU 1 are disabled for too long.
TASK_WDT¶
Initialize Task Watchdog Timer on startup
Found in: Component config > ESP32-specific
The Task Watchdog Timer can be used to make sure individual tasks are still running. Enabling this option will cause the Task Watchdog Timer to be initialized automatically at startup. The Task Watchdog timer can be initialized after startup as well (see Task Watchdog Timer API Reference)
TASK_WDT_PANIC¶
Invoke panic handler on Task Watchdog timeout
Found in: Component config > ESP32-specific
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)
TASK_WDT_TIMEOUT_S¶
Task Watchdog timeout period (seconds)
Found in: Component config > ESP32-specific
Timeout period configuration for the Task Watchdog Timer in seconds. This is also configurable at run time (see Task Watchdog Timer API Reference)
TASK_WDT_CHECK_IDLE_TASK_CPU0¶
Watch CPU0 Idle Task
Found in: Component config > ESP32-specific
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.
TASK_WDT_CHECK_IDLE_TASK_CPU1¶
Watch CPU1 Idle Task
Found in: Component config > ESP32-specific
If this option is enabled, the Task Wtachdog Timer will wach the CPU1 Idle Task.
BROWNOUT_DET¶
Hardware brownout detect & reset
Found in: Component config > ESP32-specific
The ESP32 has a built-in brownout detector which can detect if the voltage is lower than a specific value. If this happens, it will reset the chip in order to prevent unintended behaviour.
BROWNOUT_DET_LVL_SEL¶
Brownout voltage level
Found in: Component config > ESP32-specific
The brownout detector will reset the chip when the supply voltage is approximately below this level. Note that there may be some variation of brownout voltage level between each ESP32 chip.
- Available options:
- BROWNOUT_DET_LVL_SEL_0
- BROWNOUT_DET_LVL_SEL_1
- BROWNOUT_DET_LVL_SEL_2
- BROWNOUT_DET_LVL_SEL_3
- BROWNOUT_DET_LVL_SEL_4
- BROWNOUT_DET_LVL_SEL_5
- BROWNOUT_DET_LVL_SEL_6
- BROWNOUT_DET_LVL_SEL_7
ESP32_TIME_SYSCALL¶
Timers used for gettimeofday function
Found in: Component config > ESP32-specific
This setting defines which hardware timers are used to implement ‘gettimeofday’ and ‘time’ functions in C library.
- If both high-resolution and RTC timers are used, timekeeping will continue in deep sleep. Time will be reported at 1 microsecond resolution. This is the default, and the recommended option.
- If only high-resolution timer is used, gettimeofday will provide time at microsecond resolution. Time will not be preserved when going into deep sleep mode.
- If only RTC timer is used, timekeeping will continue in deep sleep, but time will be measured at 6.(6) microsecond resolution. Also the gettimeofday function itself may take longer to run.
- If no timers are used, gettimeofday and time functions return -1 and set errno to ENOSYS.
- When RTC is used for timekeeping, two RTC_STORE registers are used to keep time in deep sleep mode.
- Available options:
- ESP32_TIME_SYSCALL_USE_RTC_FRC1
- ESP32_TIME_SYSCALL_USE_RTC
- ESP32_TIME_SYSCALL_USE_FRC1
- ESP32_TIME_SYSCALL_USE_NONE
ESP32_RTC_CLOCK_SOURCE¶
RTC clock source
Found in: Component config > ESP32-specific
Choose which clock is used as RTC clock source.
- Available options:
- ESP32_RTC_CLOCK_SOURCE_INTERNAL_RC
- ESP32_RTC_CLOCK_SOURCE_EXTERNAL_CRYSTAL
ESP32_RTC_CLK_CAL_CYCLES¶
Number of cycles for RTC_SLOW_CLK calibration
Found in: Component config > ESP32-specific
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
- 32768 Hz if the 32k crystal oscillator is used
ESP32_DEEP_SLEEP_WAKEUP_DELAY¶
Extra delay in deep sleep wake stub (in us)
Found in: Component config > ESP32-specific
When ESP32 exits deep sleep, the CPU and the flash chip are powered on at the same time. CPU will run deep sleep stub first, and then proceed to load code from flash. Some flash chips need sufficient time to pass between power on and first read operation. By default, without any extra delay, this time is approximately 900us, although some flash chip types need more than that.
By default extra delay is set to 2000us. When optimizing startup time for applications which require it, this value may be reduced.
If you are seeing “flash read err, 1000” message printed to the console after deep sleep reset, try increasing this value.
ESP32_XTAL_FREQ_SEL¶
Main XTAL frequency
Found in: Component config > ESP32-specific
ESP32 currently supports the following XTAL frequencies:
- 26 MHz
- 40 MHz
Startup code can automatically estimate XTAL frequency. This feature uses the internal 8MHz oscillator as a reference. Because the internal oscillator frequency is temperature dependent, it is not recommended to use automatic XTAL frequency detection in applications which need to work at high ambient temperatures and use high-temperature qualified chips and modules.
- Available options:
- ESP32_XTAL_FREQ_40
- ESP32_XTAL_FREQ_26
- ESP32_XTAL_FREQ_AUTO
DISABLE_BASIC_ROM_CONSOLE¶
Permanently disable BASIC ROM Console
Found in: Component config > ESP32-specific
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.)
NO_BLOBS¶
No Binary Blobs
Found in: Component config > ESP32-specific
If enabled, this disables the linking of binary libraries in the application build. Note that after enabling this Wi-Fi/Bluetooth will not work.
ESP_TIMER_PROFILING¶
Enable esp_timer profiling features
Found in: Component config > ESP32-specific
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.
COMPATIBLE_PRE_V2_1_BOOTLOADERS¶
App compatible with bootloaders before IDF v2.1
Found in: Component config > ESP32-specific
Bootloaders before IDF v2.1 did less initialisation of the system clock. This setting needs to be enabled to build an app which can be booted by these older bootloaders.
If this setting is enabled, the app can be booted by any bootloader from IDF v1.0 up to the current version.
If this setting is disabled, the app can only be booted by bootloaders from IDF v2.1 or newer.
Enabling this setting adds approximately 1KB to the app’s IRAM usage.
Wi-Fi¶
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.
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.
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.
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:
- ESP32_WIFI_STATIC_TX_BUFFER
- ESP32_WIFI_DYNAMIC_TX_BUFFER
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.
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.
ESP32_WIFI_AMPDU_TX_ENABLED¶
WiFi AMPDU TX
Found in: Component config > Wi-Fi
Select this option to enable AMPDU TX feature
ESP32_WIFI_TX_BA_WIN¶
WiFi AMPDU TX BA window size
Found in: Component config > Wi-Fi
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.
ESP32_WIFI_AMPDU_RX_ENABLED¶
WiFi AMPDU RX
Found in: Component config > Wi-Fi
Select this option to enable AMPDU RX feature
ESP32_WIFI_RX_BA_WIN¶
WiFi AMPDU RX BA window size
Found in: Component config > Wi-Fi
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.
ESP32_WIFI_NVS_ENABLED¶
WiFi NVS flash
Found in: Component config > Wi-Fi
Select this option to enable WiFi NVS flash
PHY¶
ESP32_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’.
ESP32_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’.
ESP32_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.
Power Management¶
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.
PM_DFS_INIT_AUTO¶
Enable dynamic frequency scaling (DFS) at startup
Found in: Component config > Power Management
If enabled, startup code configures dynamic frequency scaling. Max CPU frequency is set to CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ setting, min frequency is set to XTAL frequency. If disabled, DFS will not be active until the application configures it using esp_pm_configure function.
PM_USE_RTC_TIMER_REF¶
Use RTC timer to prevent time drift (EXPERIMENTAL)
Found in: Component config > Power Management
When APB clock frequency changes, high-resolution timer (esp_timer) scale and base value need to be adjusted. Each adjustment may cause small error, and over time such small errors may cause time drift. If this option is enabled, RTC timer will be used as a reference to compensate for the drift. It is recommended that this option is only used if 32k XTAL is selected as RTC clock source.
PM_PROFILING¶
Enable profiling counters for PM locks
Found in: Component config > Power Management
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.
PM_TRACE¶
Enable debug tracing of PM using GPIOs
Found in: Component config > Power Management
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.
Log output¶
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.
Note that this setting limits which log statements are compiled into the program. So setting this to, say, “Warning” would mean that changing log level to “Debug” at runtime will not be possible.
- Available options:
- LOG_DEFAULT_LEVEL_NONE
- LOG_DEFAULT_LEVEL_ERROR
- LOG_DEFAULT_LEVEL_WARN
- LOG_DEFAULT_LEVEL_INFO
- LOG_DEFAULT_LEVEL_DEBUG
- LOG_DEFAULT_LEVEL_VERBOSE
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.
PThreads¶
ESP32_PTHREAD_TASK_PRIO_DEFAULT¶
Default task priority
Found in: Component config > PThreads
Priority used to create new tasks with default pthread parameters.
ESP32_PTHREAD_TASK_STACK_SIZE_DEFAULT¶
Default task stack size
Found in: Component config > PThreads
Stack size used to create new tasks with default pthread parameters.
Application Level Tracing¶
ESP32_APPTRACE_DESTINATION¶
Data Destination
Found in: Component config > Application Level Tracing
Select destination for application trace: trace memory or none (to disable).
- Available options:
- ESP32_APPTRACE_DEST_TRAX
- ESP32_APPTRACE_DEST_NONE
ESP32_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.
ESP32_APPTRACE_POSTMORTEM_FLUSH_TRAX_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.
ESP32_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¶
SYSVIEW_ENABLE¶
SystemView Tracing Enable
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables supporrt for SEGGER SystemView tracing functionality.
SYSVIEW_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:
- SYSVIEW_TS_SOURCE_CCOUNT
- SYSVIEW_TS_SOURCE_TIMER_00
- SYSVIEW_TS_SOURCE_TIMER_01
- SYSVIEW_TS_SOURCE_TIMER_10
- SYSVIEW_TS_SOURCE_TIMER_11
- SYSVIEW_TS_SOURCE_ESP_TIMER
SYSVIEW_EVT_OVERFLOW_ENABLE¶
Trace Buffer Overflow Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Trace Buffer Overflow” event.
SYSVIEW_EVT_ISR_ENTER_ENABLE¶
ISR Enter Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR Enter” event.
SYSVIEW_EVT_ISR_EXIT_ENABLE¶
ISR Exit Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR Exit” event.
SYSVIEW_EVT_ISR_TO_SCHEDULER_ENABLE¶
ISR Exit to Scheduler Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “ISR to Scheduler” event.
SYSVIEW_EVT_TASK_START_EXEC_ENABLE¶
Task Start Execution Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Start Execution” event.
SYSVIEW_EVT_TASK_STOP_EXEC_ENABLE¶
Task Stop Execution Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Stop Execution” event.
SYSVIEW_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.
SYSVIEW_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.
SYSVIEW_EVT_TASK_CREATE_ENABLE¶
Task Create Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Create” event.
SYSVIEW_EVT_TASK_TERMINATE_ENABLE¶
Task Terminate Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Task Terminate” event.
SYSVIEW_EVT_IDLE_ENABLE¶
System Idle Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “System Idle” event.
SYSVIEW_EVT_TIMER_ENTER_ENABLE¶
Timer Enter Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Timer Enter” event.
SYSVIEW_EVT_TIMER_EXIT_ENABLE¶
Timer Exit Event
Found in: Component config > Application Level Tracing > FreeRTOS SystemView Tracing
Enables “Timer Exit” event.
Ethernet¶
DMA_RX_BUF_NUM¶
Number of DMA RX buffers
Found in: Component config > Ethernet
Number of DMA receive buffers. Each buffer is 1600 bytes. Buffers are allocated statically. Larger number of buffers increases throughput. If enable flow ctrl, the num must be above 9 .
DMA_TX_BUF_NUM¶
Number of DMA TX buffers
Found in: Component config > Ethernet
Number of DMA transmit buffers. Each buffer is 1600 bytes. Buffers are allocated statically. Larger number of buffers increases throughput.
EMAC_L2_TO_L3_RX_BUF_MODE¶
Enable copy between Layer2 and Layer3
Found in: Component config > Ethernet
If this options is selected, a copy of each received buffer will be created when passing it from the Ethernet MAC (L2) to the IP stack (L3). Otherwise, IP stack will receive pointers to the DMA buffers used by Ethernet MAC.
When Ethernet MAC doesn’t have any unused buffers left, it will drop incomming packets (flow control may help with this problem, to some extent).
The buffers for the IP stack are allocated from the heap, so the total number of receive buffers is limited by the available heap size, if this option is selected.
If unsure, choose n.
EMAC_TASK_PRIORITY¶
EMAC_TASK_PRIORITY
Found in: Component config > Ethernet
Ethernet MAC task priority.
Bootloader config¶
LOG_BOOTLOADER_LEVEL¶
Bootloader log verbosity
Found in: Bootloader config
Specify how much output to see in bootloader logs.
- Available options:
- LOG_BOOTLOADER_LEVEL_NONE
- LOG_BOOTLOADER_LEVEL_ERROR
- LOG_BOOTLOADER_LEVEL_WARN
- LOG_BOOTLOADER_LEVEL_INFO
- LOG_BOOTLOADER_LEVEL_DEBUG
- LOG_BOOTLOADER_LEVEL_VERBOSE
BOOTLOADER_SPI_WP_PIN¶
SPI Flash WP Pin when customising pins via efuse (read help)
Found in: Bootloader config
This value is ignored unless flash mode is set to QIO or QOUT and the SPI flash pins have been overriden by setting the efuses SPI_PAD_CONFIG_xxx.
When this is the case, the Efuse config only defines 3 of the 4 Quad I/O data pins. The WP pin (aka ESP32 pin “SD_DATA_3” or SPI flash pin “IO2”) is not specified in Efuse. That pin number is compiled into the bootloader instead.
The default value (GPIO 7) is correct for WP pin on ESP32-D2WD integrated flash.
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:
- BOOTLOADER_VDDSDIO_BOOST_1_8V
- BOOTLOADER_VDDSDIO_BOOST_1_9V
Security features¶
SECURE_BOOT_ENABLED¶
Enable 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.
Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
SECURE_BOOTLOADER_MODE¶
Secure bootloader mode
Found in: Security features
- Available options:
- SECURE_BOOTLOADER_ONE_TIME_FLASH
- SECURE_BOOTLOADER_REFLASHABLE
SECURE_BOOT_BUILD_SIGNED_BINARIES¶
Sign binaries during build
Found in: Security features
Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
If enabled, these binary files are signed as part of the build process. The file named in “Secure boot private signing key” will be used to sign the image.
If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py (for example, on a remote signing server.)
SECURE_BOOT_SIGNING_KEY¶
Secure boot private signing key
Found in: Security features
Path to the key file used to sign partition tables and app images for secure boot. Once secure boot is enabled, bootloader will only boot if partition table and app image are signed.
Key file is an ECDSA private key (NIST256p curve) in PEM format.
Path is evaluated relative to the project directory.
You can generate a new signing key by running the following command: espsecure.py generate_signing_key secure_boot_signing_key.pem
See docs/security/secure-boot.rst for details.
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. This key is compiled into the bootloader, and may also be used to verify signatures on OTA images after download.
Key file is in raw binary format, and can be extracted from a PEM formatted private key using the espsecure.py extract_public_key command.
Refer to https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
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 https://esp-idf.readthedocs.io/en/latest/security/secure-boot.html before enabling.
FLASH_ENCRYPTION_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 https://esp-idf.readthedocs.io/en/latest/security/flash-encryption.html before enabling.
FLASH_ENCRYPTION_INSECURE¶
Allow potentially insecure options
Found in: Security features
You can disable some of the default protections offered by flash encryption, in order to enable testing or a custom combination of security features.
Only enable these options if you are very sure.
Refer to docs/security/secure-boot.rst and docs/security/flash-encryption.rst for details.
Potentially insecure options¶
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.
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.
FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_ENCRYPT¶
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.
FLASH_ENCRYPTION_UART_BOOTLOADER_ALLOW_DECRYPT¶
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.
FLASH_ENCRYPTION_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.
SECURE_BOOT_TEST_MODE¶
Secure boot test mode: don’t permanently set any efuses
Found in: Security features > Potentially insecure options
If this option is set, all permanent secure boot changes (via Efuse) are disabled.
Log output will state changes which would be applied, but they will not be.
This option is for testing purposes only - it completely disables secure boot protection.
FLASH_ENCRYPTION_DISABLE_PLAINTEXT¶
Disable serial reflashing of plaintext firmware
Found in: Security features
If this option is enabled, flash encryption is permanently enabled after first boot by write-protecting the FLASH_CRYPT_CNT efuse. This is the recommended configuration for a secure production system.
If this option is disabled, FLASH_CRYPT_CNT is left writeable and up to 4 plaintext re-flashes are allowed. An attacker with physical access will be able to read out encrypted flash contents until all plaintext re-flashes have been used up.
If this option is disabled and hardware Secure Boot is enabled, Secure Boot must be configured in Reflashable mode so that a new Secure Boot digest can be flashed at the same time as plaintext firmware. This combination is not secure and should not be used for a production system.
OpenSSL¶
OPENSSL_DEBUG¶
Enable OpenSSL debugging
Found in: Component config > OpenSSL
Enable OpenSSL debugging function.
If the option is enabled, “SSL_DEBUG” works.
OPENSSL_DEBUG_LEVEL¶
OpenSSL debugging level
Found in: Component config > OpenSSL
OpenSSL debugging level.
Only function whose debugging level is higher than “OPENSSL_DEBUG_LEVEL” works.
- For example:
- If OPENSSL_DEBUG_LEVEL = 2, you use function “SSL_DEBUG(1, “malloc failed”)”. Because 1 < 2, it will not print.
OPENSSL_LOWLEVEL_DEBUG¶
Enable OpenSSL low-level module debugging
Found in: Component config > OpenSSL
If the option is enabled, low-level module debugging function of OpenSSL is enabled, e.g. mbedtls internal debugging function.
OPENSSL_ASSERT¶
Select OpenSSL assert function
Found in: Component config > OpenSSL
OpenSSL function needs “assert” function to check if input parameters are valid.
If you want to use assert debugging function, “OPENSSL_DEBUG” should be enabled.
- Available options:
- OPENSSL_ASSERT_DO_NOTHING
- OPENSSL_ASSERT_EXIT
- OPENSSL_ASSERT_DEBUG
- OPENSSL_ASSERT_DEBUG_EXIT
- OPENSSL_ASSERT_DEBUG_BLOCK
AWS_IOT_SDK¶
Amazon Web Services IoT Platform
Found in: Component config
Select this option to enable support for the AWS IoT platform, via the esp-idf component for the AWS IoT Device C SDK.
AWS_IOT_MQTT_HOST¶
AWS IoT Endpoint Hostname
Found in: Component config
Default endpoint host name to connect to AWS IoT MQTT/S gateway
This is the custom endpoint hostname and is specific to an AWS IoT account. You can find it by logging into your AWS IoT Console and clicking the Settings button. The endpoint hostname is shown under the “Custom Endpoint” heading on this page.
If you need per-device hostnames for different regions or accounts, you can override the default hostname in your app.
AWS_IOT_MQTT_PORT¶
AWS IoT MQTT Port
Found in: Component config
Default port number to connect to AWS IoT MQTT/S gateway
If you need per-device port numbers for different regions, you can override the default port number in your app.
AWS_IOT_MQTT_TX_BUF_LEN¶
MQTT TX Buffer Length
Found in: Component config
Maximum MQTT transmit buffer size. This is the maximum MQTT message length (including protocol overhead) which can be sent.
Sending longer messages will fail.
AWS_IOT_MQTT_RX_BUF_LEN¶
MQTT RX Buffer Length
Found in: Component config
Maximum MQTT receive buffer size. This is the maximum MQTT message length (including protocol overhead) which can be received.
Longer messages are dropped.
AWS_IOT_MQTT_NUM_SUBSCRIBE_HANDLERS¶
Maximum MQTT Topic Filters
Found in: Component config
Maximum number of concurrent MQTT topic filters.
AWS_IOT_MQTT_MIN_RECONNECT_WAIT_INTERVAL¶
Auto reconnect initial interval (ms)
Found in: Component config
Initial delay before making first reconnect attempt, if the AWS IoT connection fails. Client will perform exponential backoff, starting from this value.
AWS_IOT_MQTT_MAX_RECONNECT_WAIT_INTERVAL¶
Auto reconnect maximum interval (ms)
Found in: Component config
Maximum delay between reconnection attempts. If the exponentially increased delay interval reaches this value, the client will stop automatically attempting to reconnect.
Bluetooth¶
BT_ENABLED¶
Bluetooth
Found in: Component config > Bluetooth
Select this option to enable Bluetooth and show the submenu with Bluetooth configuration choices.
BTDM_CONTROLLER_PINNED_TO_CORE_CHOICE¶
The cpu core which bluetooth controller run
Found in: Component config > Bluetooth
Specify the cpu core to run bluetooth controller. Can not specify no-affinity.
- Available options:
- BTDM_CONTROLLER_PINNED_TO_CORE_0
- BTDM_CONTROLLER_PINNED_TO_CORE_1
BTDM_CONTROLLER_HCI_MODE_CHOICE¶
HCI mode
Found in: Component config > Bluetooth
Speicify HCI mode as VHCI or UART(H4)
- Available options:
- BTDM_CONTROLLER_HCI_MODE_VHCI
- BTDM_CONTROLLER_HCI_MODE_UART_H4
HCI UART(H4) Options¶
BT_HCI_UART_NO¶
UART Number for HCI
Found in: Component config > Bluetooth > HCI UART(H4) Options
Uart number for HCI. The available uart is UART1 and UART2.
BT_HCI_UART_BAUDRATE¶
UART Baudrate for HCI
Found in: Component config > Bluetooth > HCI UART(H4) Options
UART Baudrate for HCI. Please use standard baudrate.
BLUEDROID_ENABLED¶
Bluedroid Enable
Found in: Component config > Bluetooth
This enables the default Bluedroid Bluetooth stack
BLUEDROID_PINNED_TO_CORE_CHOICE¶
The cpu core which Bluedroid run
Found in: Component config > Bluetooth
Which the cpu core to run Bluedroid. Can choose core0 and core1. Can not specify no-affinity.
- Available options:
- BLUEDROID_PINNED_TO_CORE_0
- BLUEDROID_PINNED_TO_CORE_1
BTC_TASK_STACK_SIZE¶
Bluetooth event (callback to application) task stack size
Found in: Component config > Bluetooth
This select btc task stack size
BLUEDROID_MEM_DEBUG¶
Bluedroid memory debug
Found in: Component config > Bluetooth
Bluedroid memory debug
CLASSIC_BT_ENABLED¶
Classic Bluetooth
Found in: Component config > Bluetooth
For now this option needs “SMP_ENABLE” to be set to yes
A2DP_SINK_TASK_STACK_SIZE¶
A2DP sink (audio stream decoding) task stack size
Found in: Component config > Bluetooth
This affects the stack size of A2DP sink task which invokes the data callback function.
GATTS_ENABLE¶
Include GATT server module(GATTS)
Found in: Component config > Bluetooth
This option can be disabled when the app work only on gatt client mode
GATTC_ENABLE¶
Include GATT client module(GATTC)
Found in: Component config > Bluetooth
This option can be close when the app work only on gatt server mode
BLE_SMP_ENABLE¶
Include BLE security module(SMP)
Found in: Component config > Bluetooth
This option can be close when the app not used the ble security connect.
BT_STACK_NO_LOG¶
Close the bluedroid bt stack log print
Found in: Component config > Bluetooth
This select can save the rodata code size
BT_ACL_CONNECTIONS¶
BT/BLE MAX ACL CONNECTIONS(1~7)
Found in: Component config > Bluetooth
Maximum BT/BLE connection count
BLE_SCAN_DUPLICATE¶
BLE Scan Duplicate Options
Found in: Component config > Bluetooth
This select enables parameters setting of BLE scan duplicate.
DUPLICATE_SCAN_CACHE_SIZE¶
Maximum number of devices in scan duplicate filter
Found in: Component config > Bluetooth
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.
BLE_MESH_SCAN_DUPLICATE_EN¶
Special duplicate scan mechanism for BLE Mesh scan
Found in: Component config > Bluetooth
This enables the BLE scan duplicate for special BLE Mesh scan.
MESH_DUPLICATE_SCAN_CACHE_SIZE¶
Maximum number of Mesh adv packets in scan duplicate filter
Found in: Component config > Bluetooth
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.
BLE_ACTIVE_SCAN_REPORT_ADV_SCAN_RSP_INDIVIDUALLY¶
Report adv data and scan response individually when BLE active scan
Found in: Component config > Bluetooth
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.
mbedTLS¶
MBEDTLS_SSL_MAX_CONTENT_LEN¶
TLS maximum message content length
Found in: Component config > mbedTLS
Maximum TLS message length (in bytes) supported by mbedTLS.
16384 is the default and this value is required to comply fully with TLS standards.
However you can set a lower value in order to save RAM. This is safe if the other end of the connection supports Maximum Fragment Length Negotiation Extension (max_fragment_length, see RFC6066) or you know for certain that it will never send a message longer than a certain number of bytes.
If the value is set too low, symptoms are a failed TLS handshake or a return value of MBEDTLS_ERR_SSL_INVALID_RECORD (-0x7200).
MBEDTLS_DEBUG¶
Enable mbedTLS debugging
Found in: Component config > mbedTLS
Enable mbedTLS debugging functions at compile time.
- If this option is enabled, you can include
- “mbedtls/esp_debug.h” and call mbedtls_esp_enable_debug_log() at runtime in order to enable mbedTLS debug output via the ESP log mechanism.
MBEDTLS_HARDWARE_AES¶
Enable hardware AES acceleration
Found in: Component config > mbedTLS
Enable hardware accelerated AES encryption & decryption.
Note that if the ESP32 CPU is running at 240MHz, hardware AES does not offer any speed boost over software AES.
MBEDTLS_HARDWARE_MPI¶
Enable hardware MPI (bignum) acceleration
Found in: Component config > mbedTLS
Enable hardware accelerated multiple precision integer operations.
Hardware accelerated multiplication, modulo multiplication, and modular exponentiation for up to 4096 bit results.
These operations are used by RSA.
MBEDTLS_MPI_USE_INTERRUPT¶
Use interrupt for MPI operations
Found in: Component config > mbedTLS
Use an interrupt to coordinate MPI operations.
This allows other code to run on the CPU while an MPI operation is pending. Otherwise the CPU busy-waits.
MBEDTLS_HARDWARE_SHA¶
Enable hardware SHA acceleration
Found in: Component config > mbedTLS
Enable hardware accelerated SHA1, SHA256, SHA384 & SHA512 in mbedTLS.
Due to a hardware limitation, hardware acceleration is only guaranteed if SHA digests are calculated one at a time. If more than one SHA digest is calculated at the same time, one will be calculated fully in hardware and the rest will be calculated (at least partially calculated) in software. This happens automatically.
SHA hardware acceleration is faster than software in some situations but slower in others. You should benchmark to find the best setting for you.
MBEDTLS_HAVE_TIME¶
Enable mbedtls time
Found in: Component config > mbedTLS
System has time.h and time(). The time does not need to be correct, only time differences are used,
MBEDTLS_HAVE_TIME_DATE¶
Enable mbedtls time data
Found in: Component config > mbedTLS
System has time.h and time(), gmtime() and the clock is correct. The time needs to be correct (not necesarily very accurate, but at least the date should be correct). This is used to verify the validity period of X.509 certificates.
It is suggested that you should get the real time by “SNTP”.
MBEDTLS_TLS_MODE¶
TLS Protocol Role
Found in: Component config > mbedTLS
mbedTLS can be compiled with protocol support for the TLS server, TLS client, or both server and client.
Reducing the number of TLS roles supported saves code size.
- Available options:
- MBEDTLS_TLS_SERVER_AND_CLIENT
- MBEDTLS_TLS_SERVER_ONLY
- MBEDTLS_TLS_CLIENT_ONLY
- MBEDTLS_TLS_DISABLED
TLS Key Exchange Methods¶
MBEDTLS_PSK_MODES¶
Enable pre-shared-key ciphersuites
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to show configuration for different types of pre-shared-key TLS authentatication methods.
Leaving this options disabled will save code size if they are not used.
MBEDTLS_KEY_EXCHANGE_PSK¶
Enable PSK based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support symmetric key PSK (pre-shared-key) TLS key exchange modes.
MBEDTLS_KEY_EXCHANGE_DHE_PSK¶
Enable DHE-PSK based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.
MBEDTLS_KEY_EXCHANGE_ECDHE_PSK¶
Enable ECDHE-PSK based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support Elliptic-Curve-Diffie-Hellman PSK (pre-shared-key) TLS authentication modes.
MBEDTLS_KEY_EXCHANGE_RSA_PSK¶
Enable RSA-PSK based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support RSA PSK (pre-shared-key) TLS authentication modes.
MBEDTLS_KEY_EXCHANGE_RSA¶
Enable RSA-only based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-RSA-WITH-
MBEDTLS_KEY_EXCHANGE_DHE_RSA¶
Enable DHE-RSA based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-DHE-RSA-WITH-
MBEDTLS_KEY_EXCHANGE_ELLIPTIC_CURVE¶
Support Elliptic Curve based ciphersuites
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to show Elliptic Curve based ciphersuite mode options.
Disabling all Elliptic Curve ciphersuites saves code size and can give slightly faster TLS handshakes, provided the server supports RSA-only ciphersuite modes.
MBEDTLS_KEY_EXCHANGE_ECDHE_RSA¶
Enable ECDHE-RSA based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-
MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA¶
Enable ECDHE-ECDSA based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-
MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA¶
Enable ECDH-ECDSA based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-
MBEDTLS_KEY_EXCHANGE_ECDH_RSA¶
Enable ECDH-RSA based ciphersuite modes
Found in: Component config > mbedTLS > TLS Key Exchange Methods
Enable to support ciphersuites with prefix TLS-ECDHE-RSA-WITH-
MBEDTLS_SSL_RENEGOTIATION¶
Support TLS renegotiation
Found in: Component config > mbedTLS
The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authentication after the initial handshake. If you don’t need renegotiation, disabling it will save code size and reduce the possibility of abuse/vulnerability.
MBEDTLS_SSL_PROTO_SSL3¶
Legacy SSL 3.0 support
Found in: Component config > mbedTLS
Support the legacy SSL 3.0 protocol. Most servers will speak a newer TLS protocol these days.
MBEDTLS_SSL_PROTO_TLS1¶
Support TLS 1.0 protocol
Found in: Component config > mbedTLS
MBEDTLS_SSL_PROTO_TLS1_1¶
Support TLS 1.1 protocol
Found in: Component config > mbedTLS
MBEDTLS_SSL_PROTO_TLS1_2¶
Support TLS 1.2 protocol
Found in: Component config > mbedTLS
MBEDTLS_SSL_PROTO_DTLS¶
Support DTLS protocol (all versions)
Found in: Component config > mbedTLS
Requires TLS 1.1 to be enabled for DTLS 1.0 Requires TLS 1.2 to be enabled for DTLS 1.2
MBEDTLS_SSL_ALPN¶
Support ALPN (Application Layer Protocol Negotiation)
Found in: Component config > mbedTLS
Disabling this option will save some code size if it is not needed.
MBEDTLS_SSL_SESSION_TICKETS¶
TLS: Support RFC 5077 SSL session tickets
Found in: Component config > mbedTLS
Support RFC 5077 session tickets. See mbedTLS documentation for more details.
Disabling this option will save some code size.
Symmetric Ciphers¶
MBEDTLS_AES_C¶
AES block cipher
Found in: Component config > mbedTLS > Symmetric Ciphers
MBEDTLS_CAMELLIA_C¶
Camellia block cipher
Found in: Component config > mbedTLS > Symmetric Ciphers
MBEDTLS_DES_C¶
DES block cipher (legacy, insecure)
Found in: Component config > mbedTLS > Symmetric Ciphers
Enables the DES block cipher to support 3DES-based TLS ciphersuites.
3DES is vulnerable to the Sweet32 attack and should only be enabled if absolutely necessary.
MBEDTLS_RC4_MODE¶
RC4 Stream Cipher (legacy, insecure)
Found in: Component config > mbedTLS > Symmetric Ciphers
ARCFOUR (RC4) stream cipher can be disabled entirely, enabled but not added to default ciphersuites, or enabled completely.
Please consider the security implications before enabling RC4.
- Available options:
- MBEDTLS_RC4_DISABLED
- MBEDTLS_RC4_ENABLED_NO_DEFAULT
- MBEDTLS_RC4_ENABLED
MBEDTLS_BLOWFISH_C¶
Blowfish block cipher (read help)
Found in: Component config > mbedTLS > Symmetric Ciphers
Enables the Blowfish block cipher (not used for TLS sessions.)
The Blowfish cipher is not used for mbedTLS TLS sessions but can be used for other purposes. Read up on the limitations of Blowfish (including Sweet32) before enabling.
MBEDTLS_XTEA_C¶
XTEA block cipher
Found in: Component config > mbedTLS > Symmetric Ciphers
Enables the XTEA block cipher.
MBEDTLS_CCM_C¶
CCM (Counter with CBC-MAC) block cipher modes
Found in: Component config > mbedTLS > Symmetric Ciphers
Enable Counter with CBC-MAC (CCM) modes for AES and/or Camellia ciphers.
Disabling this option saves some code size.
MBEDTLS_GCM_C¶
GCM (Galois/Counter) block cipher modes
Found in: Component config > mbedTLS > Symmetric Ciphers
Enable Galois/Counter Mode for AES and/or Camellia ciphers.
This option is generally faster than CCM.
MBEDTLS_RIPEMD160_C¶
Enable RIPEMD-160 hash algorithm
Found in: Component config > mbedTLS
Enable the RIPEMD-160 hash algorithm.
Certificates¶
MBEDTLS_PEM_PARSE_C¶
Read & Parse PEM formatted certificates
Found in: Component config > mbedTLS > Certificates
Enable decoding/parsing of PEM formatted certificates.
If your certificates are all in the simpler DER format, disabling this option will save some code size.
MBEDTLS_PEM_WRITE_C¶
Write PEM formatted certificates
Found in: Component config > mbedTLS > Certificates
Enable writing of PEM formatted certificates.
If writing certificate data only in DER format, disabling this option will save some code size.
MBEDTLS_X509_CRL_PARSE_C¶
X.509 CRL parsing
Found in: Component config > mbedTLS > Certificates
Support for parsing X.509 Certifificate Revocation Lists.
MBEDTLS_X509_CSR_PARSE_C¶
X.509 CSR parsing
Found in: Component config > mbedTLS > Certificates
Support for parsing X.509 Certifificate Signing Requests
MBEDTLS_ECP_C¶
Elliptic Curve Ciphers
Found in: Component config > mbedTLS
MBEDTLS_ECDH_C¶
Elliptic Curve Diffie-Hellman (ECDH)
Found in: Component config > mbedTLS
Enable ECDH. Needed to use ECDHE-xxx TLS ciphersuites.
MBEDTLS_ECDSA_C¶
Elliptic Curve DSA
Found in: Component config > mbedTLS
Enable ECDSA. Needed to use ECDSA-xxx TLS ciphersuites.
MBEDTLS_ECP_DP_SECP192R1_ENABLED¶
Enable SECP192R1 curve
Found in: Component config > mbedTLS
Enable support for SECP192R1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP224R1_ENABLED¶
Enable SECP224R1 curve
Found in: Component config > mbedTLS
Enable support for SECP224R1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP256R1_ENABLED¶
Enable SECP256R1 curve
Found in: Component config > mbedTLS
Enable support for SECP256R1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP384R1_ENABLED¶
Enable SECP384R1 curve
Found in: Component config > mbedTLS
Enable support for SECP384R1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP521R1_ENABLED¶
Enable SECP521R1 curve
Found in: Component config > mbedTLS
Enable support for SECP521R1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP192K1_ENABLED¶
Enable SECP192K1 curve
Found in: Component config > mbedTLS
Enable support for SECP192K1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP224K1_ENABLED¶
Enable SECP224K1 curve
Found in: Component config > mbedTLS
Enable support for SECP224K1 Elliptic Curve.
MBEDTLS_ECP_DP_SECP256K1_ENABLED¶
Enable SECP256K1 curve
Found in: Component config > mbedTLS
Enable support for SECP256K1 Elliptic Curve.
MBEDTLS_ECP_DP_BP256R1_ENABLED¶
Enable BP256R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
MBEDTLS_ECP_DP_BP384R1_ENABLED¶
Enable BP384R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
MBEDTLS_ECP_DP_BP512R1_ENABLED¶
Enable BP512R1 curve
Found in: Component config > mbedTLS
support for DP Elliptic Curve.
MBEDTLS_ECP_DP_CURVE25519_ENABLED¶
Enable CURVE25519 curve
Found in: Component config > mbedTLS
Enable support for CURVE25519 Elliptic Curve.
MBEDTLS_ECP_NIST_OPTIM¶
NIST ‘modulo p’ optimisations
Found in: Component config > mbedTLS
NIST ‘modulo p’ optimisations increase Elliptic Curve operation performance.
Disabling this option saves some code size.
FAT Filesystem support¶
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:
- FATFS_CODEPAGE_DYNAMIC
- FATFS_CODEPAGE_437
- FATFS_CODEPAGE_720
- FATFS_CODEPAGE_737
- FATFS_CODEPAGE_771
- FATFS_CODEPAGE_775
- FATFS_CODEPAGE_850
- FATFS_CODEPAGE_852
- FATFS_CODEPAGE_855
- FATFS_CODEPAGE_857
- FATFS_CODEPAGE_860
- FATFS_CODEPAGE_861
- FATFS_CODEPAGE_862
- FATFS_CODEPAGE_863
- FATFS_CODEPAGE_864
- FATFS_CODEPAGE_865
- FATFS_CODEPAGE_866
- FATFS_CODEPAGE_869
- FATFS_CODEPAGE_932
- FATFS_CODEPAGE_936
- FATFS_CODEPAGE_949
- FATFS_CODEPAGE_950
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.
- Available options:
- FATFS_LFN_NONE
- FATFS_LFN_HEAP
- FATFS_LFN_STACK
FATFS_MAX_LFN¶
Max long filename length
Found in: Component config > FAT Filesystem support
Maximum long filename length. Can be reduced to save RAM.
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.
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.
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.
SPIFFS Configuration¶
SPIFFS_MAX_PARTITIONS¶
Maximum Number of Partitions
Found in: Component config > SPIFFS Configuration
Define maximum number of partitions that can be mounted.
SPIFFS Cache Configuration¶
SPIFFS_CACHE¶
Enable SPIFFS Cache
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration
Enables/disable memory read caching of nucleus file system operations.
SPIFFS_CACHE_WR¶
Enable SPIFFS Write Caching
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration
Enables memory write caching for file descriptors in hydrogen.
SPIFFS_CACHE_STATS¶
Enable SPIFFS Cache Statistics
Found in: Component config > SPIFFS Configuration > SPIFFS Cache Configuration
Enable/disable statistics on caching. Debug/test purpose only.
SPIFFS_PAGE_CHECK¶
Enable SPIFFS Page Check
Found in: Component config > SPIFFS Configuration
Always check header of each accessed page to ensure consistent state. If enabled it will increase number of reads, will increase flash.
SPIFFS_GC_MAX_RUNS¶
Set Maximum GC Runs
Found in: Component config > SPIFFS Configuration
Define maximum number of gc runs to perform to reach desired free pages.
SPIFFS_GC_STATS¶
Enable SPIFFS GC Statistics
Found in: Component config > SPIFFS Configuration
Enable/disable statistics on gc. Debug/test purpose only.
SPIFFS_OBJ_NAME_LEN¶
Set SPIFFS Maximum Name Length
Found in: Component config > SPIFFS Configuration
Object name maximum length. Note that this length include the zero-termination character, meaning maximum string of characters can at most be SPIFFS_OBJ_NAME_LEN - 1.
SPIFFS_USE_MAGIC¶
Enable SPIFFS Filesystem Magic
Found in: Component config > SPIFFS Configuration
Enable this to have an identifiable spiffs filesystem. This will look for a magic in all sectors to determine if this is a valid spiffs system or not on mount point.
SPIFFS_USE_MAGIC_LENGTH¶
Enable SPIFFS Filesystem Length Magic
Found in: Component config > SPIFFS Configuration
If this option is enabled, the magic will also be dependent on the length of the filesystem. For example, a filesystem configured and formatted for 4 megabytes will not be accepted for mounting with a configuration defining the filesystem as 2 megabytes.
SPIFFS_META_LENGTH¶
Size of per-file metadata field
Found in: Component config > SPIFFS Configuration
This option sets the number of extra bytes stored in the file header. These bytes can be used in an application-specific manner. Set this to at least 4 bytes to enable support for saving file modification time.
SPIFFS_USE_MTIME¶
Save file modification time
Found in: Component config > SPIFFS Configuration
If enabled, then the first 4 bytes of per-file metadata will be used to store file modification time (mtime), accessible through stat/fstat functions. Modification time is updated when the file is opened.
Debug Configuration¶
SPIFFS_DBG¶
Enable general SPIFFS debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print general debug mesages to the console
SPIFFS_API_DBG¶
Enable SPIFFS API debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print API debug mesages to the console
SPIFFS_GC_DBG¶
Enable SPIFFS Garbage Cleaner debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print GC debug mesages to the console
SPIFFS_CACHE_DBG¶
Enable SPIFFS Cache debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print Cache debug mesages to the console
SPIFFS_CHECK_DBG¶
Enable SPIFFS Filesystem Check debug
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enabling this option will print Filesystem Check debug mesages to the console
SPIFFS_TEST_VISUALISATION¶
Enable SPIFFS Filesystem Visualization
Found in: Component config > SPIFFS Configuration > Debug Configuration
Enable this option to enable SPIFFS_vis function in the api.
SPI Flash driver¶
SPI_FLASH_VERIFY_WRITE¶
Verify SPI flash writes
Found in: Component config > SPI Flash driver
If this option is enabled, any time SPI flash is written then the data will be read back and verified. This can catch hardware problems with SPI flash, or flash which was not erased before verification.
SPI_FLASH_LOG_FAILED_WRITE¶
Log errors if verification fails
Found in: Component config > SPI Flash driver
If this option is enabled, if SPI flash write verification fails then a log error line will be written with the address, expected & actual values. This can be useful when debugging hardware SPI flash problems.
SPI_FLASH_WARN_SETTING_ZERO_TO_ONE¶
Log warning if writing zero bits to ones
Found in: Component config > SPI Flash driver
If this option is enabled, any SPI flash write which tries to set zero bits in the flash to ones will log a warning. Such writes will not result in the requested data appearing identically in flash once written, as SPI NOR flash can only set bits to one when an entire sector is erased. After erasing, individual bits can only be written from one to zero.
Note that some software (such as SPIFFS) which is aware of SPI NOR flash may write one bits as an optimisation, relying on the data in flash becoming a bitwise AND of the new data and any existing data. Such software will log spurious warnings if this option is enabled.
SPI_FLASH_ENABLE_COUNTERS¶
Enable operation counters
Found in: Component config > SPI Flash driver
This option enables the following APIs:
- spi_flash_reset_counters
- spi_flash_dump_counters
- spi_flash_get_counters
These APIs may be used to collect performance data for spi_flash APIs and to help understand behaviour of libraries which use SPI flash.
SPI_FLASH_ROM_DRIVER_PATCH¶
Enable SPI flash ROM driver patched functions
Found in: Component config > SPI Flash driver
Enable this flag to use patched versions of SPI flash ROM driver functions. This option is needed to write to flash on ESP32-D2WD, and any configuration where external SPI flash is connected to non-default pins.
SPI_FLASH_WRITING_DANGEROUS_REGIONS¶
Writing to dangerous flash regions
Found in: Component config > SPI Flash driver
SPI flash APIs can optionally abort or return a failure code if erasing or writing addresses that fall at the beginning of flash (covering the bootloader and partition table) or that overlap the app partition that contains the running app.
It is not recommended to ever write to these regions from an IDF app, and this check prevents logic errors or corrupted firmware memory from damaging these regions.
Note that this feature does not check calls to the esp_rom_xxx SPI flash ROM functions. These functions should not be called directly from IDF applications.
- Available options:
- SPI_FLASH_WRITING_DANGEROUS_REGIONS_ABORTS
- SPI_FLASH_WRITING_DANGEROUS_REGIONS_FAILS
- SPI_FLASH_WRITING_DANGEROUS_REGIONS_ALLOWED
Serial flasher config¶
ESPTOOLPY_PORT¶
Default serial port
Found in: Serial flasher config
The serial port that’s connected to the ESP chip. This can be overridden by setting the ESPPORT environment variable.
ESPTOOLPY_BAUD¶
Default baud rate
Found in: Serial flasher config
Default baud rate to use while communicating with the ESP chip. Can be overridden by setting the ESPBAUD variable.
- Available options:
- ESPTOOLPY_BAUD_115200B
- ESPTOOLPY_BAUD_230400B
- ESPTOOLPY_BAUD_921600B
- ESPTOOLPY_BAUD_2MB
- ESPTOOLPY_BAUD_OTHER
ESPTOOLPY_BAUD_OTHER_VAL¶
Other baud rate value
Found in: Serial flasher config
ESPTOOLPY_COMPRESSED¶
Use compressed upload
Found in: Serial flasher config
The flasher tool can send data compressed using zlib, letting the ROM on the ESP chip decompress it on the fly before flashing it. For most payloads, this should result in a speed increase.
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:
- FLASHMODE_QIO
- FLASHMODE_QOUT
- FLASHMODE_DIO
- FLASHMODE_DOUT
ESPTOOLPY_FLASHFREQ¶
Flash SPI speed
Found in: Serial flasher config
The SPI flash frequency to be used.
- Available options:
- ESPTOOLPY_FLASHFREQ_80M
- ESPTOOLPY_FLASHFREQ_40M
- ESPTOOLPY_FLASHFREQ_26M
- ESPTOOLPY_FLASHFREQ_20M
ESPTOOLPY_FLASHSIZE¶
Flash size
Found in: Serial flasher config
SPI flash size, in megabytes
- Available options:
- ESPTOOLPY_FLASHSIZE_1MB
- ESPTOOLPY_FLASHSIZE_2MB
- ESPTOOLPY_FLASHSIZE_4MB
- ESPTOOLPY_FLASHSIZE_8MB
- ESPTOOLPY_FLASHSIZE_16MB
ESPTOOLPY_FLASHSIZE_DETECT¶
Detect flash size when flashing bootloader
Found in: Serial flasher config
If this option is set, ‘make flash’ targets will automatically detect the flash size and update the bootloader image when flashing.
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:
- ESPTOOLPY_BEFORE_RESET
- ESPTOOLPY_BEFORE_NORESET
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:
- ESPTOOLPY_AFTER_RESET
- ESPTOOLPY_AFTER_NORESET
MONITOR_BAUD¶
‘make monitor’ baud rate
Found in: Serial flasher config
Baud rate to use when running ‘make monitor’ to view serial output from a running chip.
Can override by setting the MONITORBAUD environment variable.
- Available options:
- MONITOR_BAUD_9600B
- MONITOR_BAUD_57600B
- MONITOR_BAUD_115200B
- MONITOR_BAUD_230400B
- MONITOR_BAUD_921600B
- MONITOR_BAUD_2MB
- MONITOR_BAUD_OTHER
MONITOR_BAUD_OTHER_VAL¶
Custom baud rate value
Found in: Serial flasher config
tcpip adapter¶
IP_LOST_TIMER_INTERVAL¶
IP Address lost timer interval (seconds)
Found in: Component config > tcpip 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.
Customisations¶
Because IDF builds by default with Warning On Undefined Variables, when the Kconfig tool generates Makefiles (the auto.conf
file) its behaviour has been customised. In normal Kconfig, a variable which is set to “no” is undefined. In IDF’s version of Kconfig, this variable is defined in the Makefile but has an empty value.
(Note that ifdef
and ifndef
can still be used in Makefiles, because they test if a variable is defined and has a non-empty value.)
When generating header files for C & C++, the behaviour is not customised - so #ifdef
can be used to test if a boolean config item is set or not.