esp-idf-sys

esp-idf-sys provides raw Rust bindings for the ESP IDF SDK.

Key Features

• Automated Build: The build is cargo driven and automatically downloads and configures the ESP IDF SDK and the necessary C toolchain by default.
• Build Systems: Supports the native ESP IDF build system and PlatformIO.
• Mixed Projects: Can be used in mixed Rust/C projects.

Important Note on Build Progress

Because the build script downloads and builds the ESP IDF SDK, the initial build can take a significant amount of time. To see the progress and detailed build information, run cargo with the -vv (very verbose) flag:

cargo build -vv

Related Type-Safe Wrappers

These raw bindings are low-level. For safer, idiomatic Rust usage, consider:

• esp-idf-svc: Type-safe wrappers for ESP IDF Services.
• esp-idf-hal: Type-safe wrappers for ESP IDF Drivers.

The esp-idf-sys build script provides several Rust cfg flags that allow you to conditionally compile code based on the ESP-IDF configuration and hardware.

Available cfg flags:

• esp_idf_comp_{component}_enabled: Enabled for each component (e.g., esp_idf_comp_espressif__mdns_enabled).
• esp_idf_version="{major}.{minor}"
• esp_idf_version_full="{major}.{minor}.{patch}"
• esp_idf_version_major="{major}"
• esp_idf_version_minor="{minor}"
• esp_idf_version_patch="{patch}"
• esp_idf_{sdkconfig_option}: For any sdkconfig option set to y. The option name is lowercased and prefixed with esp_idf_ (e.g., if CONFIG_ESP_WIFI_ENABLED is set, the flag is esp_idf_wifi_enabled).
• {mcu}: The MCU for which the ESP-IDF is compiled.

Note for upstream crate authors: If your crate needs access to these cfg flags, you must depend on esp-idf-sys and call embuild::espidf::sysenv::output(); in your build.rs.

You can configure how the ESP-IDF framework is compiled using two methods:

1. Environment Variables: Denoted by $VARIABLE. These can be passed via the command line or defined in the [env] section of a .cargo/config.toml file.
2. Cargo.toml Metadata: Using the [package.metadata.esp-idf-sys] section.

Important Rules:

• Precedence: Environment variables always take precedence over Cargo.toml metadata.
• Scope: Configuration must be placed in the root crate's Cargo.toml (the package in the workspace directory). If using a virtual workspace, specify the root crate name using the ESP_IDF_SYS_ROOT_CRATE environment variable.
• Workspace Directory: Relative paths are resolved relative to the workspace directory (the directory containing Cargo.lock). If you have moved your target directory using CARGO_TARGET_DIR, you must explicitly set CARGO_WORKSPACE_DIR in .cargo/config.toml to ensure embuild can locate the crate root and your sdkconfig.defaults.

[env]
CARGO_WORKSPACE_DIR = { value = "", relative = true }

You can instruct esp-idf-sys to compile additional ESP-IDF components and generate Rust bindings for them by adding them to the package.metadata.esp-idf-sys.extra_components array in your Cargo.toml. This works for the root crate and all direct dependencies.

Each entry in the array can specify:

• component_dirs: A list of paths (absolute or relative to the Cargo.toml) to component directories.
• remote_component: Configuration for components managed by the ESP-IDF component manager.
• bindings_header: The path to a C header file used to generate bindings. If this is the only field provided, you are extending the existing bindings from src/include/esp-idf/bindings.h.
• bindings_module: The name of the Rust module where the generated bindings will reside. If omitted, bindings are added to the crate root. If provided, a separate bindgen instance is used.

[[package.metadata.esp-idf-sys.extra_components]]
component_dirs = ["dir1", "dir2"]
bindings_header = "bindings.h"
bindings_module = "name"