Esp32 Rust Nix
I recently decided I was tired of the standard C++ toolchain for esp32 and wanted to explore the rust ecosystem for microcontrollers. I feel it was WELL worth it, the ergonomics are amazing.
There is an interesting problem to solve when trying to write and compile rust code for esp microcontrollers. There are two main things to understand about the complexity in this problem. In this instance, the complexity here is caused by the collision of two systems designed for peak extensibility
The Toolchain
The trouble with building rust code for an esp32 is not really any different from building any low-level code with cross platform intent. The essential path that rust provides its users for building rust code into actual binaries is called a toolchain. A toolchain contains the pipeline of invocable software that builds (and even runs) the code you write.
Depending on your ESP chip series you will have to select whether you are targeting an XTensa chip or a RISC chip. The RISC-V architechture has the advantage of being open source and it seems that it has a real edge over the older XTensa. I actually can’t view the cadance website for XTensa since they appear to have blocked South African traffic.
Sadly, all of my chips are XTensa, so I will need to be selecting those, rather than having access to the newer and basically first-class citizens that are the RISC-V series.
Rust for ESP
Espressif have already published some pretty good documentation on making this happen. Frankly it’s way WAY easier than jumping through the hoops of using a specific IDE (looking at you, arduino) or setting up something big like platformio.
Espressif have leveraged the rust toolchain beautifully to make developing rust for an ESP32 platform as ergonomic as it is for more common host platforms.
For older XTensa chips, they even have their own rust-compiler fork that they maintain, AND they have a tool called espup that manages installing the toolchain components so that your esp32 projects are worked on in the same was as ANY other project in your environment.
This is also sadly where the complexity for nixos starts
The Nix of it all
The rust toolchain happens to be a fairly sophisticated system for keeping a bunch of binaries available with each required environment assembling the tools that they need. This is a great practise but it requires a mapping layer between the patterns present in the rust ecosystem and the nix package system.
There is a bulletproof implementation of this mapping that leverages nix overlays to achieve all the best parts of this design while still achieving nix ergonomics. My intuition is that there is a really clean way to get our extensa compiler and other tools to extend this overlay system but in practice I found it was a bit harder than I really wanted.
It was at this point that I was considering making an overlay system for this particular case, but fortunately someone else had taken up the torch!
This is the esp-rs-nix project by leighleighleigh, and it manages to create this overlay with pretty minimal fuss. It’s less complete than the oxalica flake system, but to my absolute delight it DID work for the pile of esp dev boards that I have.
It’s also quite a well put together repo, meaning that even if you had a truly ancient espressif chip series it would still be worth investigating forking this rather than starting over from scratch
A moderate solution
If you were just here for the code snippet then I’m sorry you had to go through all that. We can basically copy the flake.nix used in the repo, while including the leighleigh project as an input.
# flake.nix
{
inputs = {
flake-parts.url = "github:hercules-ci/flake-parts";
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
esp = {
url = "github:leighleighleigh/esp-rs-nix";
inputs = {
nixpkgs.follows = "nixpkgs";
flake-parts.follows = "flake-parts";
};
};
};
outputs =
inputs@{ flake-parts, esp, ... }:
flake-parts.lib.mkFlake { inherit inputs; } {
systems = [
"x86_64-linux"
"aarch64-linux"
"aarch64-darwin"
];
perSystem =
{
config,
self',
inputs',
pkgs,
system,
...
}:
{
devShells.default = pkgs.mkShell {
packages = [
inputs'.esp.packages.esp-rs
pkgs.rust-analyzer
pkgs.rustup
pkgs.espflash
pkgs.pkg-config
pkgs.stdenv.cc
];
shellHook = ''
# This variable is important - it tells rustup where to find the esp toolchain,
# without needing to copy it into your local ~/.rustup/ folder.
export RUSTUP_TOOLCHAIN=${inputs'.esp.packages.esp-rs}
'';
};
};
};
}
This is the code that I use at the time of publishing for managing my own esp32 projects. I have a lot of ESP32 projects, so I don’t mind telling you how I set up these projects for the first time.
Set-up
Remember: This is for an XTensa target. Some steps may be superfluous for the modern and more sexy RISC-V series chips.
Step uno:
esp-generate is probably my favourite
way to bootsrap an esp project. If you’re on nix you can pop it into your shell
and go esp-generate which will pop you into an interactive setup.
Step two:
Copy the relevant flake.nix into your generated project, on my system I have a wrapper command to plonk the flake in after I call esp generate.
Step three:
nix develop and away you go! cargo run --release will build and flash
the hello world code directly.
Simply Beautiful