Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Rust bindings for ESP-IDF (Espressif's IoT Development Framework)
The ESP-IDF API in Rust, with support for each ESP chip (ESP32, ESP32S2, ESP32C3 etc.) based on the Rust target.
- To build this crate, please follow all the build requirements specified in the ESP-IDF Rust Hello World template crate
- The relevant Espressif toolchain, as well as the ESP-IDF framework itself are all automatically downloaded during the build:
- Check the ESP-IDF Rust Hello World template crate for a "Hello, world!" Rust template demonstrating how to use and build this crate.
- Check the demo crate for a more comprehensive example in terms of capabilities.
pio builder installs all needed tools to compile this crate as well as the ESP-IDF framework itself.
(PIO builder only) Using cargo-pio to interactively modify ESP-IDF's
To enable Bluetooth, or do other configurations to the ESP-IDF sdkconfig you might take advantage of the cargo-pio Cargo subcommand:
- To install it, issue
cargo install cargo-pio --git https://github.com/ivmarkov/cargo-pio
- To open the ESP-IDF interactive menuconfig system, issue
cargo pio espidf menuconfigin the root of your binary crate project
- To use the generated/updated
sdkconfigfile, follow the steps described in the "Bluetooth Support" section
This is an experimental feature for downloading all tools and building the ESP-IDF framework using the framework's "native" (own) tooling. It will become the default in the near future. It also relies on build and installation utilities available in the embuild crate.
Similarly to the
pio builder, the
native builder also automatically installs all needed tools to compile this crate as well as the ESP-IDF framework itself.
(Native builder only) Using cargo-idf to interactively modify ESP-IDF's
Environment variables are used to configure how the ESP-IDF framework is compiled.
Note that instead of / in addition to specifying those on the command line, you can also put these in a
.config/cargo.toml file inside your crate directory
(or a parent directory of your crate) by using the recently stabilized Cargo configurable-env feature.
The following environment variables are used by the build script:
;-separated list of paths to
sdkconfig.defaultsfiles to be used as base values for the
sdkconfig. If such a path is relative, it will be relative to the cargo workspace directory (i.e. the directory that contains the
sdkconfig.defaultsis used as default.
For each defaults file in this list more specific version will also be searched and used. This happens with the following patterns and order (least to most specific):
<profile>is the current cargo profile used (
<mcu>specifies the mcu for which this is currently compiled for (see the
MCUconfiguration option below).
Also note that a setting contained in a more specific defaults file will override the same setting specified in a less specific one.
The base-path to the
sdkconfigfile used to configure the
esp-idf. If this is a relative path, it is relative to the cargo workspace directory.
sdkconfigis used as default.
Similar to the
sdkconfig.defaults-file a more specific
sdkconfig-file will be selected if available. This happens with the following patterns and precedence:
Note (native builder only):
The cargo optimization options (
opt-level) are used by default to determine the compiler optimizations of the
esp-idf, however if the compiler optimization options are already set in the
sdkconfigthey will be used instead.
The location where the ESP-IDF framework tooling is assumed to be/will be installed. The framework tooling is either PlatformIO (when the
piobuilder is used), or the ESP-IDF native toolset (when the
nativebuilder is used).
This variable can take one of the following values:
workspace(default) - the tooling will be installed/used in
out- the tooling will be installed/used inside the crate's build output directory, and will be deleted when
cargo cleanis invoked;
global- the tooling will be installed/used in its standard directory (
~/.platformiofor PlatformIO, and
~./espressiffor the native ESP-IDF toolset);
custom:<dir>- the tooling will be installed/used in the directory specified by
<dir>. If this directory is a relative location, it is assumed to be relative to the crate's workspace dir.
ATTENTION: Please be extra careful with the
custom:<dir>setting when switching from
nativeand the other way around, because the builder will install the tooling in
<dir>without using any additional
espressifsubdirectories, so if you are not careful, you might end up with both PlatformIO, as well as the ESP-IDF native tooling intermingled together in a single folder.
Note that both builders (
pio) clone the ESP-IDF GIT repository inside the tooling directory as well. This restriction might be lifted soon for the
nativebuilder, whereas the user would be able to point the build to a custom ESP-IDF repository location.
ESP_IDF_VERSION(native builder only):
The version used for the
esp-idfcan be one of the following:
commit:<hash>: Uses the commit
esp-idfrepository. Note that this will clone the whole
esp-idfnot just one commit.
tag:<tag>: Uses the tag
branch:<branch>: Uses the branch
<major>.<minor>: Uses the tag
<branch>: Uses the branch
It defaults to
ESP_IDF_REPOSITORY(native builder only):
The URL to the git repository of the
esp-idf, defaults to https://github.com/espressif/esp-idf.git.
Note that when the
piobuilder is used, it is possible to achieve something similar to
ESP_IDF_REPOSITORYby using the
platform_packagesPlatformIO option as follows:
ESP_IDF_PIO_CONF="platform_packages = framework-espidf @ <git-url> [@ <git-branch>]"
- The above approach however has the restriction that PlatformIO will always use the ESP-IDF build tooling from its own ESP-IDF distribution, so the user-provided ESP-IDF branch may or may not compile. The current PlatformIO tooling is suitable for compiling ESP-IDF branches derived from versions 4.3.X .
A pair of environment variable prefixes that enable copying files and directory trees that match a certain glob mask into the native C project used for building the ESP-IDF framework:
ESP_IDF_GLOB[_XXX]_BASEspecifies the base directory which will be glob-ed for resources to be copied
ESP_IDF_GLOB[_XXX]_BASE_YYYspecifies one or more environment variables that represent the glob masks of resources to be searched for and copied, using the directory designated by the
ESP_IDF_GLOB[_XXX]_BASEenvironment variable as the root. For example, if the follwing variables are specified:
ESP_IDF_GLOB_HOMEDIR_BAR=bar*... then all files and directories matching 'foo*' or 'bar*' from the home directory of the user will be copied in theESP-IDF C project.
Note also that
_HOMEDIRin the above example is optional, and is just a mechanism allowing the user to specify more than base directory and its glob patterns.
ESP_IDF_PIO_CONF_XXX(pio builder only):
A PlatformIO setting (or multiple settings separated by a newline) that will be passed as-is to the
platformio.inifile of the C project that compiles the ESP-IDF.
- Check the PlatformIO documentation for more information as to what settings you can pass via this variable.
- Note also that this is not one variable - but rather - a family of variables all starting with
ESP_IDF_PIO_CONF_. I.e., passing
ESP_IDF_PIO_CONF_1as well as
ESP_IDF_PIO_CONF_FOOis valid and all such variables will be honored
The MCU name (i.e.
If not set this will be automatically detected from the cargo target.
If you are interested how it all works under the hood, check the build.rs build script of this crate.