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)
Background
The ESP-IDF API in Rust, with support for each ESP chip (ESP32, ESP32S2, ESP32C3 etc.) based on the Rust target
Build
- The build requires the Rust ESP32 STD compiler fork to be configured and installed as per the instructions there.
- The relevant Espressif toolchain, as well as the
esp-idf
itself are all automatically downloaded during the build by- with the feature
pio
(default): utilizing platformio (via the embuild crate) or - with the feature
native
(experimental): utilizing nativeesp-idf
tooling.
- with the feature
- Check the mini 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
Feature pio
This is currently the default for installing all build tools and building the ESP-IDF framework. It uses PlatformIO via the embuild crate.
Feature native
This is an experimental feature for downloading all tools and building the ESP-IDF framework using the framerosk'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.
Currently, this build script installs all needed tools to compile the esp-idf
as well as
the esp-idf
itself using embuild::espidf::Installer
. There are two locations where
the esp-idf
source and tools are detected and installed:
~/.espressif
$ESP_IDF_INSTALL_DIR
or<crate workspace-dir>/.embuild/espressif
Bluetooth Support
In order to enable Bluetooth support with either Bluedroid or NimBLE, there is some additional work:
- Go to the root of your binary crate project (e.g., the "Hello, World" demo)
- Create a
.cargo/config.toml
file if it does not exist there yet. You can copy it from the "Hello, World" demo - Include in it the following:
[]
...
= { = "/sdkconfig" }
- Next, create a file
sdkconfig
at the root of binary crate your project. This could be generated withcargo pio espidf menuconfig
if you installcargo-pio
(see below) but a minimal manual example follows:
CONFIG_BT_ENABLED=y
CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y
CONFIG_BTDM_CTRL_MODE_BR_EDR_ONLY=n
CONFIG_BTDM_CTRL_MODE_BTDM=n
// Uncomment whichever of these you need
//CONFIG_BT_BLUEDROID_ENABLED=y
//CONFIG_BT_NIMBLE_ENABLED=y
Using cargo-pio to interactively modify ESP-IDF's sdkconfig
file
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 menuconfig
in the root of your binary crate project - To use the generated/updated
sdkconfig
file, follow the steps described in the "Bluetooth Support" section
More info
If you are interested how it all works under the hood, check the build.rs build script of this crate.
Requirements
- If using chips other than
esp32c3
: python >= 3.7
Configuration
Environment variables are used to configure how the esp-idf
is compiled.
The following environment variables are used by the build script:
-
ESP_IDF_INSTALL_DIR
:The path to the directory where all esp-idf tools are installed. If it is set to a relative path, it is relative to the crate workspace-dir.
If not set, when
ESP_IDF_GLOBAL_INSTALL
is set to1
it defaults to the global install dir~/.espressif
, otherwise it defaults to the local install dir<crate workspace-dir>/.embuild/espressif
. -
ESP_IDF_GLOBAL_INSTALL
If set to
1
,true
,y
oryes
uses the global install directory only whenESP_IDF_INSTALL_DIR
is not specified. -
ESP_IDF_VERSION
: The version used for theesp-idf
can be one of the following:commit:<hash>
: Uses the commit<hash>
of theesp-idf
repository. Note that this will clone the wholeesp-idf
not just one commit.tag:<tag>
: Uses the tag<tag>
of theesp-idf
repository.branch:<branch>
: Uses the branch<branch>
of theesp-idf
repository.v<major>.<minor>
or<major>.<minor>
: Uses the tagv<major>.<minor>
of theesp-idf
repository.<branch>
: Uses the branch<branch>
of theesp-idf
repository.
It defaults to
v4.3
. -
ESP_IDF_REPOSITORY
: The URL to the git repository of theesp-idf
, defaults to https://github.com/espressif/esp-idf.git. -
ESP_IDF_SDKCONFIG_DEFAULTS
: A;
-separated list of paths tosdkconfig.default
files to be used as base values for thesdkconfig
. -
ESP_IDF_SDKCONFIG
: A path (absolute or relative) to the esp-idfsdkconfig
file. -
MCU
: The mcu name (e.g.esp32
oresp32c3
). If not set this will be automatically detected from the cargo target.