Developping an air quality sensor with Rust, Nix and a Esp32 Xtensa
Introduction
After dabbling in embedded programming with small, fun projects, I decided to take on a more ambitious challenge: building an air quality monitor using Rust and an ESP32 microcontroller. This journey was tougher than I expected, but incredibly rewarding. Setting up this project was, frankly, a bit of a pain. Maybe it’s because I’m still sharpening my skills, or maybe it’s just inherently tricky. To compile Rust code for an ESP32 with its Xtensa chip, you need a specialized toolchain. It’s straightforward enough in theory, but doing it the “Nix way” added some complexity. The approach is not the “correct” Nix way, but it works on my machine, and this time, I’m shipping it! Interestingly, using RISC-V-based chips seems like it might be simpler, but that’s a story for another day.
Setup
Installing the toolchain
The heavy lifting for setting up the toolchain is handled by espup, a handy tool that downloads everything you need. This part could be “Nixified” (integrated into Nix for reproducibility), but I didn’t tackle that yet, I’ll save it for later. To flash the compiled code onto the ESP32, I paired espup with espflash, which does exactly what its name suggests.
Here’s what my flake.nix looks like:
{
description = "A Nix Flake for building and flashing Rust applications for Xtensa (ESP32)";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
flake-utils.url = "github:numtide/flake-utils";
};
outputs = {
self,
nixpkgs,
flake-utils,
}:
flake-utils.lib.eachDefaultSystem (system: let
pkgs = import nixpkgs {
inherit system;
};
in {
devShells.default = pkgs.mkShell {
name = "xtensa-esp32-dev-shell";
buildInputs = with pkgs; [
rustup # Add rustup for espup
cargo # Base Cargo (will be overridden by rustup)
cargo-espflash # For building and flashing
espup # For managing the toolchain
];
shellHook = ''
# Use a persistent HOME directory for rustup and cargo
export RUSTUP_HOME="$PWD/.rustup"
export CARGO_HOME="$PWD/.cargo"
mkdir -p "$RUSTUP_HOME" "$CARGO_HOME"
# Update PATH to include Cargo binaries
export PATH="$CARGO_HOME/bin:$PATH"
# Install the Xtensa toolchain via espup if not already present
if [ ! -f rust-toolchain.env ]; then
echo "Installing Xtensa Rust toolchain via espup..."
pkgs.espup/bin/espup install --export-file rust-toolchain.env
fi
# Source the toolchain environment
source rust-toolchain.env
rustup default esp
echo "Xtensa ESP32 development environment ready!"
echo "Rust version: $(rustc --version)"
'';
};
});
}
As you can see, it’s concise. Most of the magic happens in the shellHook, which sets up the environment and checks the current directory. I’ll admit it’s not the prettiest solution—Nix could store results in its store to avoid polluting the environment, and Cargo.toml could be tracked for better reproducibility. Those improvements are on my to-do list, but I prioritized finishing the project first.
Setting config.toml
To run cargo run --release from the terminal, I found I had to set the default toolchain with rustup default esp. This ensures the Xtensa toolchain is used, assuming config.toml is properly configured.
Implementing the Code
Let the Fun Begin
Time to write some code! The first big decision was: how low-level do I want to go? I could write everything from scratch, managing pointers unsafely and talking directly to the hardware, or take the easier route with a library. After exploring excellent resources like the Embedonomicon and Rust Embedded, I got a sense of the ecosystem and made my choice.
Esp-hal
I opted for a library: esp-hal (Hardware Abstraction Layer). It’s awesome! It offers plenty of resources, some outdated due to a shift from 0.x to 1.x, but migration libraries help bridge the gap. With esp-hal, you get a clean abstraction over the hardware, freeing you from pointer juggling so you can focus on the fun stuff—like making LEDs blink! I drew inspiration from its examples (check the docs). It supports everything from communication protocols to heap management, Wi-Fi, and Bluetooth.
GPIOs
GPIOs (General Purpose Input/Output pins) are the ESP32’s way of interacting with the outside world—think sensors, LEDs, or motors. The ESP32 has several pins, most of which you can use without much hassle (see the pinout reference). You decide which ones suit your needs. I went with:
peripherals.GPIO5,
peripherals.GPIO21,
peripherals.GPIO22,
peripherals.GPIO34,
peripherals.ADC1,
peripherals.I2C0,
- Pins 21 and 22: Used for I2C, a protocol that lets multiple devices chat over a shared bus—perfect for sensors.
- Pin 34: Connected to the ADC (Analog-to-Digital Converter), which turns analog signals (like sensor voltages) into digital values the ESP32 can understand.
- Pin 5: Reads data from a sensor.
Sensors
Now for the serious stuff: sensors! I wanted to read useful data: temperature, humidity, gases; and do something with it. The tricky part? Calibration. How do you know they’re set up right? I mostly crossed my fingers and hoped. The readings seemed off sometimes, so calibration is definitely on my list.
DHT11
The DHT11 is a cheap, simple sensor for temperature and humidity. It uses a capacitive humidity sensor and thermistor, sending digital signals via a data pin. It’s easy to use but not super accurate—expect ±2°C and ±5% humidity.
AHT21
The AHT21 is a step up: a precise temperature and humidity sensor using I2C. It’s reliable, low-power, and fast, with accuracies of ±0.3°C and ±2% humidity—way better than the DHT11.
MQ135
The MQ135 gas sensor was a challenge. It detects gases like CO2, alcohol, and benzene, but calibration is a beast. I struggled to figure out if the hardware, software, or both were misconfigured. I wrote my own driver, inspired by an Arduino C++ version, which meant learning about pins and ADCs.
Key ADC notes:
- ADC1 vs. ADC2: ADC1 (like GPIO34) is always available, unaffected by Wi-Fi. ADC2 works too, but not if Wi-Fi’s active (not an issue here).
- Input-Only Pins: GPIO34–39 (ADC1) are input-only, ideal for the MQ135’s analog output.
The MQ135’s attenuation setting (Attenuation::Attenuation11dB) in esp-hal scales the ADC’s input range to 0–3.3V, matching the sensor’s output. This ensures accurate readings without clipping. It needs a 24-hour preheat, and calibration is manual—think lighters and screwdrivers! Info is scarce; I found bits on CO2 and benzene but not much else. The datasheet says 5V, but I used ~4.7V with a 3.3V ESP32 pin, so a voltage divider is next to avoid frying it. My C++-inspired code needs async support and generalization.
Sudden Break
After days of smooth running (with restarts from shutting down my PC), it crashed with no logs. Debugging revealed I2C timeouts, supported by my ESP32 (forum link). The culprit? Jumper wires to a sensor with pinless holes. Loose connections messed with I2C. Soldering pins fixed it.
Rolling Median
I’m getting data: temperature, humidity, CO2, TVOC, etc., from three sensors. I built a RollingMedian struct using insertion sort, less memory, more CPU time. It’s a fair trade-off for avoiding dynamic allocations.
I currently use floats to represent the data, I probably could use integers, save more memory and convert it to floats on demand.
Adding a Screen
Adding an OLED screen was a breeze thanks to a library handling graphics. I plugged it in, added the library, and wrote a StrWriter struct to format text:
I preallocate a buffer for text—inefficient with all the copying, but it works for now.
Bluetooth
For a bit of excitement, I decided to use Bluetooth to send sensor data instead of HTTP. Spoiler alert: it was anything but exciting. Implementing Bluetooth turned out to be a much bigger headache than I anticipated.
First off, I overlooked a critical configuration for dynamic memory allocation, which is needed for the Wi-Fi/Bluetooth module. You have to include this in your code:
extern crate alloc;
and this on the .crate/config.toml
= ["alloc", "core"]
source This setup enables dynamic memory allocation, which Bluetooth relies on. Without it, you’re dead in the water.
Next, I chose to use the async module because it seemed like a natural fit, sensors and Bluetooth both involve waiting for responses, so why not handle that asynchronously? Big mistake.
Problems
I got lured in by the esp-hal Bluetooth examples. They looked so clean and straightforward! They worked fine out of the box, but when I tried tailoring them to my project, everything fell apart. I hit a wall of issues: memory allocation errors, Bluetooth refusing to respond without throwing errors, and sudden panics that came out of nowhere.
To troubleshoot, I tried running everything async on a single core, no luck. Then I split tasks across the ESP32’s two cores: sensors on the main core and Bluetooth on the second. Still no dice. I flipped it, putting Bluetooth on the main core and sensors on the second. Guess what? That didn’t work either.
Here are the specific errors I ran into and how I wrestled with them:
Memory Overflow Error
When I tried running Bluetooth on the second core, I got this cryptic linker error:
|
=
= This error means the linker couldn’t fit all the static data (stored in the .bss section) into the ESP32’s DRAM memory region (dram_seg). My program was using too much memory, 3752 bytes more than available. This likely happened because Bluetooth and sensor data buffers were hogging static memory. To fix it, I needed to optimize memory usage, so I reduced buffer sizes.
LoadProhibited Exception
Another head-scratcher was this runtime panic:
The LoadProhibited exception occurs when the CPU tries to read from an invalid memory address. This could be due to a null pointer dereference or accessing unallocated memory, possibly from a misconfigured Bluetooth stack or a bug in my async code. Who knows.
Broken Pipe Error
After switching Bluetooth to the first core and sensors to the second, I hit this:
I resorted to the ancient art of “turn it off and on again,” and it worked… briefly. I suspected the Wi-Fi/Bluetooth module needed a heap that the second core couldn’t access, but that was a guess. Moving Bluetooth to the main core magically resolved this.
StoreProhibited Exception
With Bluetooth, screen display, and rolling medians all allocating memory, I hit another panic:
i had to :
heap_allocator!;
The StoreProhibited exception (EXCCAUSE: 0x1D) happens when the CPU tries to write to an invalid memory address. My program was running out of heap memory for Bluetooth. This macro allocates a 72KB heap in the uninitialized DRAM section (.dram2_uninit), giving Bluetooth the dynamic memory it needed. It was a lifesaver, but I need to brush up on ESP32 memory management.
Mysterious Bluetooth Crash
I also stumbled across this error, which left me baffled:
)
)
)
)
)
)
Weirdly, this error vanished on its own. It seems tied to the Bluetooth stack (something about lld_evt.c and an Illegal exception), but I didn’t dig deeper since it stopped haunting me.
After all this, I realized my async dreams were doomed. Running Bluetooth on the main core and keeping things synchronous finally got things stable.
Result
My dreams of a sleek async implementation went up in flames. The Bluetooth code would start, loop indefinitely, and then vanish without a trace—no timeout, no error, just silence. I also tried the Embassy framework’s Bluetooth stack, hoping for a smoother ride, but their examples required patching packages, which felt like more trouble than it was worth. So, I waved the white flag on async. Instead, I switched to a synchronous approach and leveraged the ESP32’s second core to handle sensor data collection.
Here’s the setup: Bluetooth runs on the main core, serving notifications to any device that wants to listen. Sensor data (temperature, humidity, CO2, eCO2, and TVOC) is collected on the second core and sent to the main core via an embassy_sync channel.
The code looks like this:
let data = SensorsData ;
if let Err = SENSOR_CHANNEL.try_send ;
On the main core, Bluetooth reads the channel and sends the data:
loop
Is this the most elegant setup? Probably not, but it gets the job done. I can read the data from any Bluetooth device, and I wrote a script to pull the data and display it on my Waybar (I use NixOs btw). The data also shows up on the OLED screen, which is a nice touch: 
The setup looks a bit rough with all those exposed cables, so my next step is to get a 3D printer and design a case to make it look less like a science experiment gone wild. Soldering the connections properly will also help tidy things up.
That’s all, folks! Thanks for following my journey through the ups and downs of building this air quality monitor. I hope you had as much fun reading about it as I (sometimes) had building it!