Most of this repository is one Cargo workspace: the fan-controller firmware and the crates that support it. Next to it sits serial, a browser tool for the same RS-485/Modbus bus, which is a plain npm project and not a workspace member. It was folded in from SantaClaas/serial and keeps its history here.
Packages can not be run from the workspace root. You need run them from their respective directory.
This is due to the fan-controller package only compiling with the thumbv6m-none-eabi target which is
specified in .config.toml which will only be read by cargo when running from the
that package directory.
There is currently an unstable per-package-target
cargo feature in the works on GitHub, but it does not support the
runner specified which is also required to run on a connected RP2040 pico.
probe-rs run and probe-rs attach put the RTT channel into blocking mode so no log lines are
lost. If the host then goes away while the firmware is running — the laptop sleeps, the battery
dies, the USB adapter drops out — nobody drains that buffer. With DEFMT_LOG=debug it fills in
milliseconds, and the next log call blocks inside a critical section, stopping every task. The
chip stays powered and answers SWD, so it looks alive; it just does nothing. No MQTT, no Modbus, no
reaction to Home Assistant. This is documented behaviour of defmt-rtt, not a fault here.
The firmware's own default is non-blocking, and that default is restored on reset, so:
probe-rs reset --chip RP2040after detaching leaves the controller able to run on its own. A power cycle does the same. It cost a night of ventilation control on 2026-09-06 to find this out.
If probe-rs gives a warning that the probe firmware is too old use these links https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html#updating-the-firmware-on-the-debug-probe https://github.com/raspberrypi/debugprobe/releases/tag/debugprobe-v2.2.3
If the MQTT discovery payload contains invalid values, it will usually be logged at under Settings > System Log
fan-controller/cyw43-firmware holds the CYW43439 blobs the Pico W's
Wi-Fi chip needs, taken from Infineon's
wifi-host-driver.
They are committed rather than fetched or submoduled, because include_bytes! in
main.rs bakes them into the binary at compile time — a checkout
without them does not build at all.
Redistributing them is permitted. They are covered by the Infineon Permissive Binary License, which allows redistribution in binary form as long as the copyright notice and disclaimer are provided with them. That is what the license file and the directory's own README are for, so keep both next to the blobs.
docs/manufacturer is a submodule pointing at the private
fan-documentation repo, which holds the
ebm-papst fan manuals and other possibly copyrighted manufacturer material kept out of this
public repo. Run git submodule update --init after cloning to fetch it (requires access to
that private repo).
Three kinds of device sit on the Modbus bus, and their documentation lives in three places:
| Device | Documentation |
|---|---|
| ebm-papst RadiCal fans | docs/manufacturer/radical/ (submodule) |
| Modbus relay module | docs/manufacturer/relay/ (submodule), and docs/relay.md for how it actually behaves |
| RS-485 temperature/humidity sensor | docs/temperature-sensor.md |
The temperature sensor has no manufacturer PDF — that markdown file, and the raw text it was formatted from, are the only documentation for it, which is why they live in this public repo rather than the submodule.
The relay has both: the manual in the submodule, and docs/relay.md for what the module was measured to do — the settings it shipped with, and the ASCII banner it sends on power-up that any parser talking to it has to survive.
serial opens a USB serial adapter straight from the browser with the Web Serial API and reads and writes device registers over Modbus RTU. It is how a device gets configured — its address, baud rate, correction values — before it is wired into the controller.
cd serial && npm install && npm run devIt also listens passively to bus traffic, the way debug-listener does from the desktop, but framed and decoded rather than printed as bytes.
It needs a Chromium-based browser; the Web Serial API is not available elsewhere. See serial/README.md.
.github/workflows/serial-pages.yml publishes it to GitHub
Pages on pushes to main that touch serial/. This needs Pages switched on for the repository
once — Settings → Pages → Build and deployment → Source: GitHub Actions — and it replaces the
deployment that used to run from the standalone SantaClaas/serial repository.