#21 Using sdkconfig.defaults

What is sdkconfig?

Every ESP32 project has a main configuration file called sdkconfig. This file contains every configuration setting for your project. It is typically not edited by hand although you can do that. It is not recommended. Most users edit the contents of that file using the IDF utility idf.py menuconfig which offers a user interface to navigate all of the settings.

By default the sdkconfig file is located in the root of the project but this can also be changed by altering your CMakeLists.txt file. The format of the file is of key value pairs and looks like this.

#
# Automatically generated file. DO NOT EDIT.
# Espressif IoT Development Framework (ESP-IDF) Project Configuration
#
CONFIG_IDF_CMAKE=y
CONFIG_IDF_TARGET_ARCH_XTENSA=y
CONFIG_IDF_TARGET="esp32"
CONFIG_IDF_TARGET_ESP32=y
CONFIG_IDF_FIRMWARE_CHIP_ID=0x0000
....

What is sdkconfig.defaults?

The sdkconfig.defaults file allows you to specify only those config values that are different from the defaults. Using it allows you to overwrite the defaults in a much smaller file that is easier to digest. It has the exact same format as sdkconfig.

Why use sdkconfig.defaults?

Looking at the sdkconfig file can get tedious as it contains every possible setting for every option you have enabled. It is extremely difficult to know what settings you’ve changes versus what is a default. However, you normally only change a few of the settings and oftentimes you do this across projects once you have dialed in the settings you like. The defaults file allows you to store that changeset in a simple text file.

It’s also a great way to package settings that relate to each other. For example, in the case of enabling BLE provisioning you may need to change 15 or 20 settings and now you want to share those changes with another project. You can add them all to the sdkconfig.defaults file and share that instead of giving menuconfig instructions on how to change each setting by hand.

Your sdkconfig file won’t automatically pick up changes from the sdkconfig.defaults file. You need to delete the sdkconfig file so it is regenerated.

Advanced sdkconfig.[anything]

Target Dependent Defaults

In addition to sdkconfig.defaults there are target-dependent default files that allow you to specify configuration settings that should be applied for a specific target if your project is multi-target capable. This file is only loaded if there is an sdkconfig.defaults file also present in the project and has the form:

sdkconfig.defaults.TARGET

For example, if you wanted to specify a different set of settings for the ESP32-S3 target you could place those changes in a file called sdkconfig.defaults.esp32s3. The build system will pick this file up automatically. Remember, this only works if you already have an sdkconfig.defaults file.

Custom Defaults Files

You can create as many defaults files as you want. For example, you may want to compile without optimizations in dev but with them in prod. An sdkconfig setting for this is CONFIG_COMPILER_OPTIMIZATION_SIZE=y. You could define that in a file called sdkconfig.production which is only used for production builds.

CONFIG_COMPILER_OPTIMIZATION_SIZE=y

You can tell the build system to include this on the command line by modifying your build command

idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.production" build

You can chain as many of these as you want. They are evaluated left to right. So if you have duplicate settings in the defaults files the last one will win.

You could have different default files for things like a testing build, production vs. dev, or device-under-test rigs. They are also helpful if you have multiple versions of a product that build from the same codebase.

Production Pointers

• Use sdkconfig.defaults to specify settings for which you want to override the default value
• Use target-dependent defaults files to specify overrides based on the build target
• Use a custom defaults file for things like production build overrides or CI/CD pipeline builds.

Summary

Using an sdkconfig.defaults file helps with the Maintainable and Deterministic Pillars of Production. It’s easier to maintain a smaller changset of settings that differ from the default but also allows your configuration to be easily reproducible. Instead of having to navigate through lots of menus and submenus in menuconfig to duplicate a certain configuration you just need a single file specifying the changes from default.

Join the community and get the weekly Production ESP32 newsletter. Concise, actionable content right in your inbox.