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 "Hello, World" demo for how to use and build this crate
Feature pio
This is currently the default for installing all build tools and building the esp-idf
C
library. It uses platformio via the
embuild crate.
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_pio.rs or script of this crate.
Experimental feature native
Download all tools and build the esp-idf
using its own tooling.
Warning: This is an experimental feature and subject to changes.
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
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.