esp-rs/rust-build esp-rs/rust-build

  • Stars
    star
    249
  • Rank 162,987 (Top 4 %)
  • Language
    PowerShell
  • License
    MIT License
  • Created about 3 years ago
  • Updated 2 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
esp-rs/rust-build
github

esp-rs

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Installation tools and workflows for deploying/building Rust fork esp-rs/rust with Xtensa and RISC-V support

rust-build

Nightly checks

This repository contains:

If you want to know more about the Rust ecosystem on ESP targets, see The Rust on ESP Book chapter

Table of Contents

Xtensa Installation

Deployment is done using espup

espup installation

cargo install espup
espup install # To install Espressif Rust ecosystem
# [Unix]: Source the following file in every terminal before building a project
. $HOME/export-esp.sh

Or, downloading the pre-compiled release binaries:

  • Linux aarch64 
    curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-aarch64-unknown-linux-gnu -o espup
chmod a+x espup
./espup install
# Source the following file in every terminal before building a project
. $HOME/export-esp.sh
  • Linux x86_64 
    curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-unknown-linux-gnu -o espup
chmod a+x espup
./espup install
# Source the following file in every terminal before building a project
. $HOME/export-esp.sh
  • macOS aarch64 
    curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-aarch64-apple-darwin -o espup
chmod a+x espup
./espup install
# Source the following file in every terminal before building a project
. $HOME/export-esp.sh
  • macOS x86_64 
    curl -L https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-apple-darwin -o espup
chmod a+x espup
./espup install
# Source the following file in every terminal before building a project
. $HOME/export-esp.sh
  • Windows MSVC 
    Invoke-WebRequest 'https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-pc-windows-msvc.exe' -OutFile .\espup.exe
.\espup.exe install
  • Windows GNU 
    Invoke-WebRequest 'https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-pc-windows-msvc.exe' -OutFile .\espup.exe
.\espup.exe install

For Windows MSVC/GNU, Rust environment can also be installed with Universal Online idf-installer: https://dl.espressif.com/dl/esp-idf/

Download installer in Bash

Deprecated method

curl -LO https://github.com/esp-rs/rust-build/releases/download/v1.72.0.0/install-rust-toolchain.sh
chmod a+x install-rust-toolchain.sh

Linux and macOS

The following instructions are specific for the ESP32 and ESP32-S series based on Xtensa architecture.

Instructions for ESP-C series based on RISC-V architecture are described in RISC-V section.

Prerequisites

  • Linux:
    • Dependencies (command for Ubuntu/Debian): 
      apt-get install -y git curl gcc clang ninja-build cmake libudev-dev unzip xz-utils \
python3 python3-pip python3-venv libusb-1.0-0 libssl-dev pkg-config libpython2.7

No prerequisites are needed for macOS.

Installation commands

git clone https://github.com/esp-rs/rust-build.git
cd rust-build
./install-rust-toolchain.sh
. ./export-esp.sh

Run ./install-rust-toolchain.sh --help for more information about arguments.

Installation of different version of the toolchain:

./install-rust-toolchain.sh --toolchain-version 1.72.0.0
. ./export-esp.sh

Set up the environment variables

We need to update environment variables as some of the installed tools are not yet added to the PATH environment variable, we also need to add LIBCLANG_PATH environment variable to avoid conflicts with the system Clang. The environment variables that we need to update are shown at the end of the install script and stored in an export file. By default this export file is export-esp.sh but can be modified with the -f|--export-file argument.

We must set the environment variables in every terminal session.

Note
If the export variables are added to the shell startup script, the shell may need to be refreshed.

Arguments

  • -b|--build-target: Comma separated list of targets [esp32,esp32s2,esp32s3,esp32c3,all]. Defaults to: esp32,esp32s2,esp32s3
  • -c|--cargo-home: Cargo path.
  • -d|--toolchain-destination: Toolchain installation folder. Defaults to: <rustup_home>/toolchains/esp
  • -e|--extra-crates: Extra crates to install. Defaults to: ldproxy cargo-espflash
  • -f|--export-file: Destination of the export file generated. Defaults to: export-esp.sh
  • -i|--installation-mode: Installation mode: [install, reinstall, uninstall]. Defaults to: install
  • -k|--minified-llvm: Use minified LLVM. Possible values: [YES, NO]. Defaults to: YES
  • -l|--llvm-version: LLVM version.
  • -m|--minified-esp-idf: [Only applies if using -s|--esp-idf-version]. Deletes some idf folders to save space. Possible values [YES, NO]. Defaults to: NO
  • -n|--nightly-version: Nightly Rust toolchain version. Defaults to: nightly
  • -r|--rustup-home: Path to .rustup. Defaults to: ~/.rustup
  • -s|--esp-idf-version: ESP-IDF branch to install. When empty, no esp-idf is installed. Default: ""
  • -t|--toolchain-version: Xtensa Rust toolchain version
  • -x|--clear-cache: Removes cached distribution files. Possible values: [YES, NO]. Defaults to: YES

Windows Long path limitation

Several build tools have problem with long paths on Windows including Git and CMake. We recommend to put project on short path or use command subst to map the directory with the project to separate disk letter.

subst "R:" "rust-project"

Windows x86_64 MSVC

The following instructions are specific for the ESP32 and ESP32-S series based on Xtensa architecture. If you do not have Visual Studio and Windows 10 SDK installed, consider the alternative option Windows x86_64 GNU.

Instructions for ESP-C series based on RISC-V architecture are described in RISC-V section.

Prerequisites x86_64 MSVC

Installation of prerequisites using Winget:

winget install --id Git.Git
winget install Python # requirements for ESP-IDF based development, skip in case of Bare metal
winget install -e --id Microsoft.WindowsSDK
winget install Microsoft.VisualStudio.2022.BuildTools --silent --override "--wait --quiet --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64"

Installation of prerequisites using Visual Studio installer GUI - installed with option Desktop development with C++ - components: MSVCv142 - VS2019 C++ x86/64 build tools, Windows 11 SDK

Visual Studio Installer - configuration

Installation of MSVC and Windows 11 SDK using vs_buildtools.exe:

Invoke-WebRequest 'https://aka.ms/vs/17/release/vs_buildtools.exe' -OutFile .\vs_buildtools.exe
.\vs_BuildTools.exe --passive --wait --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows10SDK.20348

Installation of prerequisites using Chocolatey (run PowerShell as Administrator):

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
choco install visualstudio2022-workload-vctools windows-sdk-10.0 -y
choco install cmake git ninja python3 -y  # requirements for ESP-IDF based development, skip in case of Bare metal

Main installation:

Invoke-WebRequest 'https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-pc-windows-msvc.exe' -OutFile .\espup.exe
.\espup.exe install

Windows x86_64 GNU

The following instructions describe deployment with the GNU toolchain. If you're using Visual Studio with Windows 10 SDK, consider option Windows x86_64 MSVC.

Prerequisites x86_64 GNU

Install MinGW x86_64 e.g., from releases https://github.com/niXman/mingw-builds-binaries/releases and add bin to environment variable PATH

choco install 7zip -y
Invoke-WebRequest https://github.com/niXman/mingw-builds-binaries/releases/download/12.1.0-rt_v10-rev3/x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z -OutFile x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z
7z x x86_64-12.1.0-release-posix-seh-rt_v10-rev3.7z
$env:PATH+=";.....\x86_64-12.1.0-release-posix-seh-rt_v10-rev3\mingw64\bin"

Main installation:

Invoke-WebRequest 'https://github.com/esp-rs/espup/releases/latest/download/espup-x86_64-pc-windows-msvc.exe' -OutFile .\espup.exe
.\espup.exe install

Long path limitation

Several build tools have problem with long paths on Windows including Git and CMake. We recommend to put project on short path or use command subst to map the directory with the project to separate disk letter.

subst "R:" "rust-project"

RISC-V Installation

The following instructions are specific for ESP32-C based on RISC-V architecture.

Install the RISC-V target for Rust:

rustup target add riscv32imc-unknown-none-elf

Building projects

Cargo first approach

  1. Install cargo-generate

    cargo install cargo-generate

  2. Generate project from template with one of the following templates

    # STD Project
cargo generate esp-rs/esp-idf-template cargo
# NO-STD (Bare-metal) Project
cargo generate -a esp-rs/esp-template

To understand the differences between the two ecosystems, see Ecosystem Overview chapter of the book. There is also a Chapter that explains boths template projects:

  1. Build and flash:

    cargo espflash  <SERIAL>

    Where SERIAL is the serial port connected to the target device.

    cargo-espflash also allows opening a serial monitor after flashing with --monitor option.

    If no SERIAL argument is used, cargo-espflash will print a list of the connected devices, so the user can choose which one to flash.

    See Usage section for more information about arguments.

    If espflash is installed (cargo install espflash), cargo run will build, flash the device, and open a serial monitor.

If you are looking for inspiration or more complext projects see:

Idf first approach

When building for Xtensa targets, we need to override the esp toolchain, there are several solutions: - Set esp toolchain as default: rustup default esp - Use cargo +esp - Override the project directory: rustup override set esp - Create a file called rust-toolchain.toml or rust-toolchain with: toml [toolchain] channel = "esp"

  1. Get example source code

    git clone https://github.com/espressif/rust-esp32-example.git
cd rust-esp32-example-main

  2. Select architecture for the build

    idf.py set-target <TARGET>

    Where TARGET can be:

    • esp32 for the ESP32(Xtensa architecture). [Default]
    • esp32s2 for the ESP32-S2(Xtensa architecture).
    • esp32s3 for the ESP32-S3(Xtensa architecture).

  3. Build and flash

    idf.py build flash

Using Containers

Alternatively, some container images with pre-installed Rust and ESP-IDF, are published to Dockerhub and can be used to build Rust projects for ESP boards:

  • idf-rust
  • Some tags contain only the toolchain. The naming convention for those tags is: <xtensa-version>
  • Some tags contain full std environment with esp-idf installed, wokwi-server and web-flash to use them in Dev Containers. This tags are generated for linux/arm64 and linux/amd64, and use the following naming convention: <board>_<esp-idf>_<xtensa-version>
  • Some tags contain full no_stdenvironment, wokwi-server and web-flash to use them in Dev Containers. This tags are generated for linux/arm64 and linux/amd64, and use the following naming convention: <board>_<xtensa-version>
  • idf-rust-examples - includes two examples: rust-esp32-example and rust-esp32-std-demo.

Podman example with mapping multiple /dev/ttyUSB from host computer to the container:

podman run --device /dev/ttyUSB0 --device /dev/ttyUSB1 -it docker.io/espressif/idf-rust-examples

Docker (does not support flashing from a container):

docker run -it espressif/idf-rust-examples

If you are using the idf-rust-examples image, instructions will be displayed on the screen.

Using Dev Containers

Dev Container support is offered for VS Code, Gitpod, and GitHub Codespaces, resulting in a fully working environment to develop for ESP boards in Rust, flash and simulate projects with Wokwi from the container.

Template projects esp-template and esp-idf-template include a question for Dev Containers support.

More Repositories

1

awesome-esp-rust

Curated list of resources for ESP32 development in the Rust programming language
825
star
2

esp-hal

no_std Hardware Abstraction Layers for ESP32 microcontrollers
Rust
712
star
3

std-training

Embedded Rust on Espressif training material.
Rust
596
star
4

esp-rust-board

Open Hardware with ESP32-C3 compatible with Feather specification designed in KiCad
487
star
5

espflash

Serial flasher utility for Espressif SoCs and modules based on esptool.py
Rust
476
star
6

esp-idf-hal

embedded-hal implementation for Rust on ESP32 and ESP-IDF
Rust
449
star
7

esp-idf-template

A "Hello, world!" template of a Rust binary crate for the ESP-IDF framework.
CMake
414
star
8

esp-wifi-sys

Wi-Fi and BT drivers packaged for integration into bare-metal esp-wifi.
Rust
396
star
9

esp-idf-svc

Type-Safe Rust Wrappers for various ESP-IDF services (WiFi, Network, Httpd, Logging, etc.)
Rust
311
star
10

esp-idf-sys

Bindings for ESP-IDF (Espressif's IoT Development Framework)
Rust
270
star
11

espup

Tool for installing and maintaining Espressif Rust ecosystem.
Rust
220
star
12

esp32-hal

A hardware abstraction layer for the esp32 written in Rust.
Rust
193
star
13

book

The Rust on ESP Book
JavaScript
171
star
14

esp8266-hal

A experimental hardware abstraction layer for the esp8266 written in Rust.
Rust
157
star
15

esp-template

A minimal esp-hal application template for use with cargo-generate
Dockerfile
141
star
16

embuild

Build support for embedded Rust: Cargo integration with other embedded build ecosystems & tools, like PlatformIO, CMake and kconfig.
Rust
137
star
17

rfc2217-rs

IETF RFC2217 implementation in Rust
Rust
133
star
18

esp32

Peripheral access crate for the ESP32
Rust
126
star
19

embedded-svc

Rust APIs and abstractions for various embedded services (WiFi, Network, Httpd, Logging, etc.)
Rust
122
star
20

esp-pacs

Peripheral Access Crates for Espressif SoCs and modules
Rust
105
star
21

esp32-wifi

Rust ESP32 WiFi Library
Rust
79
star
22

no_std-training

Getting-started guide on using the Rust with Espressif SoCs using no_std.
Rust
62
star
23

espmonitor

Cargo tool for monitoring ESP32/ESP8266 execution
Rust
48
star
24

esp-openthread

Rust
45
star
25

xtensa-lx-rt

Minimal runtime/startup for Xtensa LX processors
Rust
44
star
26

esp-ieee802154

Low-level IEEE802.15.4 driver for the ESP32-C6 and ESP32-H2
Rust
36
star
27

esp-web-flash-server

Starts a local server serving a web page to flash a given ELF file
Rust
34
star
28

esp-backtrace

backtrace for ESP32 bare-metal
Rust
29
star
29

esp32c3

Peripheral access crate for the ESP32-C3
Rust
28
star
30

xtensa-lx

Low-level access to Xtensa LX processors
Rust
26
star
31

esp-storage

implementation of embedded-storage traits to access unencrypted ESP32 flash
Rust
25
star
32

esp8266

Peripheral access crate for the ESP8266
Rust
22
star
33

esp-riscv-rt

Minimal runtime / startup for RISC-V CPUs from Espressif
Rust
20
star
34

esp-println

Provides print! and println! implementations various Espressif devices
Rust
20
star
35

esp-mbedtls

mbedtls for ESP32 bare-metal
Rust
19
star
36

esp-flasher-stub

Rust implementation of flasher stub located in esptool
Rust
18
star
37

esp-alloc

A simple `no_std` heap allocator for RISC-V and Xtensa processors from Espressif
Rust
15
star
38

esp-flash-loader

A probe-rs flash loader for Espressif chips.
RPC
15
star
39

xtensa-toolchain

A GitHub Action to install the Rust compiler fork targeting Xtensa devices
11
star
40

docker-rust-esp

Rust build environment for the ESP32 and ESP8266
Dockerfile
10
star
41

esp-idf-part

A library for parsing and generating ESP-IDF partition tables
Rust
8
star
42

riscv-atomic-emulation-trap

An atomic emulation trap handler for non atomic RISCV targets
Rust
8
star
43

esp-serial-dbg

esp-serial-dbg - debugging of esp-hal based applications via serial
Rust
7
star
44

esp-rust-board-bsp

A board support package for the ESP Rust Board
Rust
7
star
45

esp-hal-community

Rust
7
star
46

esp-generate

Template generation tool to create no_std applications targeting Espressif's chips.
Rust
6
star
47

xtensa-atomic-emulation-trap

An atomic emulation trap handler for non atomic Xtensa targets
Rust
4
star
48

docs

3
star
49

rfcs

2
star
50

esp32s3

Peripheral access crate for the ESP32-S3
Rust
1
star
51

esp32s2

Rust
1
star
52

repo-activity-digest

Python
1
star