ESP-IDF Kconfig Tooling

3.7.0 · active · verified Sun Apr 12

esp-idf-kconfig is a Python library that provides Kconfig tooling for the Espressif IoT Development Framework (ESP-IDF). It enables project configuration using the Kconfig language, offers IDE support for configuration, and facilitates documentation generation. As of version 3.7.0, it is actively developed and forms a core part of the ESP-IDF 6.x ecosystem. Its release cadence aligns with ESP-IDF updates.

Warnings

breaking Migration from esp-idf-kconfig v2.x to v3.x involved significant breaking changes to the Kconfig language syntax. Removed `---help---` keyword, `def_<type>` options, and restricted `config` and `choice` names to uppercase, numbers, and underscores. Preprocessor macros are also limited.
Fix: Review the official migration guide from v2.x to v3.x and update Kconfig files to comply with the new syntax and rules, including replacing `---help---` with proper indented help blocks. Use `sdkconfig.rename` files for backward compatibility of renamed options.
gotcha Specific versions of the `pyparsing` library are often required for compatibility, and mismatches can lead to parsing errors. For example, `esp-idf-kconfig v3.4.2` required updates to comply with `pyparsing 3.3.1`.
Fix: Ensure that the installed `pyparsing` version is compatible with your `esp-idf-kconfig` version, especially when updating ESP-IDF or `esp-idf-kconfig`. Check ESP-IDF's `requirements.txt` for recommended `pyparsing` version ranges.
gotcha On Windows, the terminal-based `menuconfig` interface may fail to launch or function correctly if the `windows-curses` package is not installed.
Fix: Install `windows-curses` explicitly via `pip install windows-curses` in your Python environment if you are using `idf.py menuconfig` on Windows.
gotcha Unexpected behavior with default values and invisible choices has been observed and fixed in various releases. This can manifest as crashes or incorrect configuration reports when certain options are not visible or dependencies are not correctly respected.
Fix: Update to the latest `esp-idf-kconfig` version to benefit from bug fixes related to Kconfig parsing and default value handling. Ensure Kconfig dependencies are correctly defined.
deprecated Older Kconfig option names that change across ESP-IDF versions are managed through `sdkconfig.rename` files. While these files provide backward compatibility, relying heavily on deprecated options can lead to maintainability issues and make upgrades more complex.
Fix: Regularly update your project's `sdkconfig` to use the latest Kconfig option names. Consult `sdkconfig.rename` files to understand mappings but strive to eliminate reliance on deprecated options in your Kconfig definitions.

Install

pip install esp-idf-kconfig Latest stable version

Imports

Kconfig
```
from kconfiglib import Kconfig
```
The `esp-idf-kconfig` package integrates and extends `kconfiglib`. For programmatic interaction with Kconfig objects (e.g., parsing files, accessing symbols), import `Kconfig` directly from `kconfiglib`.
KconfServer
```
from esp_idf_kconfig.kconfserver import KconfServer
```
Used for providing Kconfig configuration server functionality, typically for IDE integration.
KconfigGen
```
from esp_idf_kconfig.kconfgen import KconfigGen
```
Used for advanced Kconfig file manipulation and generation tasks.

Quickstart

This quickstart demonstrates how to programmatically interact with Kconfig files using the underlying `kconfiglib` module, which is integrated into `esp-idf-kconfig`. It shows how to load a Kconfig definition, access configuration symbols, and simulate loading a configuration from an `sdkconfig` file. Most users will interact with Kconfig via the `idf.py menuconfig` command-line tool within an ESP-IDF project environment.

import os
from kconfiglib import Kconfig

# Create a dummy Kconfig file for demonstration
with open('Kconfig.example', 'w') as f:
    f.write('config MY_OPTION\n')
    f.write('    bool "My boolean option"\n')
    f.write('    default y\n')
    f.write('\n')
    f.write('config MY_STRING_OPTION\n')
    f.write('    string "My string option"\n')
    f.write('    default "hello"\n')

# Load the Kconfig file
try:
    # Path to the Kconfig file (can be Kconfig or Kconfig.projbuild)
    kconf = Kconfig('Kconfig.example')

    # Access a symbol
    my_option = kconf.syms['MY_OPTION']
    print(f"MY_OPTION: {my_option.str_value}")

    my_string_option = kconf.syms['MY_STRING_OPTION']
    print(f"MY_STRING_OPTION: '{my_string_option.str_value}'")

    # Simulate loading an sdkconfig file (empty for defaults)
    # In a real scenario, this would load a previously saved config
    with open('sdkconfig.temp', 'w') as f:
        f.write('# CONFIG_MY_OPTION is not set\n')
        f.write('CONFIG_MY_STRING_OPTION="world"\n')

    kconf.load_config('sdkconfig.temp')

    print(f"MY_OPTION after loading sdkconfig: {kconf.syms['MY_OPTION'].str_value}")
    print(f"MY_STRING_OPTION after loading sdkconfig: '{kconf.syms['MY_STRING_OPTION'].str_value}'")

finally:
    # Clean up dummy files
    if os.path.exists('Kconfig.example'):
        os.remove('Kconfig.example')
    if os.path.exists('sdkconfig.temp'):
        os.remove('sdkconfig.temp')

view raw JSON →