Firmware Updates
8 minute read
The PoE ports on your Cruiser are managed by an ESP32-C6 module running Exaviz
firmware. That firmware is flashed at the factory, and exaviz-flash updates it
in the field.
Most people never need to run it. Update when support asks you to, or when a release in the changelog fixes something you are actually seeing.
Install
sudo apt update
sudo apt install exaviz-tools
The package is exaviz-tools; the command it installs is exaviz-flash. It is
available for Debian (Bookworm, Trixie) and Ubuntu (Questing, Resolute) on
Cruiser hardware.
Update to the current firmware
sudo exaviz-flash update
That is the whole thing. It picks the newest published firmware for your board, and it takes about a minute.
Stopping services that hold the PSE port...
Upgrading firmware: 1.1.0+fc57f97 -> 1.1.2-5668bc3
Backing up the firmware currently on the board...
Writing and verifying firmware 1.1.2-5668bc3 (about a minute)...
Verify passed.
Restarting services...
Done. The board is running firmware 1.1.2-5668bc3.
The PoE controller is being reprogrammed, so powered devices go down for roughly a minute and come back on their own. Pick a moment when that is acceptable.
Before you run it
Close the PoE Tool, and stop anything else that reads the PoE port. The
update talks to the ESP32 over the same serial port that PoE telemetry uses, and
two readers on one port corrupt each other. exaviz-flash stops the Exaviz
services itself and refuses to start if something else still holds the port.
Run it as root (sudo). It drives GPIO and the serial port directly.
SSH is fine. If your connection drops partway through, the update finishes anyway rather than leaving the board half-written.
If something goes wrong
Before writing anything, exaviz-flash copies the firmware already on your
board. If a write fails after that copy exists:
sudo exaviz-flash recover
That restores the copy. If a flash has failed, the tool tells you so and names this command.
Contact support@exaviz.com first, with exactly what the command printed. A power cycle can remove the evidence of what went wrong, and the recovery command works better than a reboot does.
The honest limit: recovery restores a copy taken by a previous run. If the very first update you ever run fails before it finishes taking that copy, there is nothing on disk to restore from and you will need us to help you directly.
Other commands
| Command | What it does |
|---|---|
sudo exaviz-flash update | Install the newest published firmware, keeping the firmware type you are already on |
sudo exaviz-flash update --fw-version 1.1.2-5668bc3 | Install one specific version |
sudo exaviz-flash stock | Reinstall the standard WiFi + Bluetooth firmware, the one the board shipped with |
sudo exaviz-flash zigbee | Install the Zigbee coordinator firmware (see the note below) |
sudo exaviz-flash recover | Restore the backup taken before the last update |
sudo exaviz-flash --about | Report this install: version, where its API key comes from, board serial, and whether the firmware service can serve Zigbee. Writes nothing |
man exaviz-flash | Full manual page |
Installing the Zigbee firmware
sudo exaviz-flash zigbee replaces the WiFi + Bluetooth firmware on the ESP32-C6 with
the Zigbee coordinator firmware. The module runs one or the other, never both, so the
CM5’s own WiFi covers networking afterwards.
It takes two runs, with one reboot in between. The first run installs a device-tree overlay and reboots. After the board comes back, run the same command again and it flashes the firmware.
Why a reboot is needed, and why it cannot be done in one step
Zigbee mode is not only different firmware. The ESP32-C6 is normally wired to the CM5 as an SDIO device so its WiFi and Bluetooth can be used by the host, and that wiring is described in the device tree the board is given at boot.
In Zigbee mode that SDIO path has to be gone. If it stays, the CM5’s card host power-cycles the ESP32 on every cold boot, which restarts the Zigbee coordinator underneath your network. So the change is not “add something for Zigbee”, it is “the SDIO description must not be there” - and something the board was told about at boot cannot be untold while it is running.
Raspberry Pi OS can load overlays at runtime with dtoverlay, and that genuinely works for
adding one. It cannot remove an overlay that came from config.txt: those are already
merged into the tree the firmware handed the kernel before Linux started, and dtoverlay -l
does not even list them. That is why the reboot is real rather than us being cautious.
The board reboots once. If you see it reboot a second time, or the command reports that it could not confirm the overlay, stop and contact support@exaviz.com rather than power-cycling: the firmware write happens only after the overlay is confirmed, so a board in that state has not been half-flashed.
sudo exaviz-flash recover restores the WiFi + Bluetooth firmware from the backup taken
before the change, so this is reversible.
The firmware installs and the module runs as a Zigbee coordinator, but Home Assistant’s ZHA integration cannot use it yet: ZHA supports five radio types and the ESP32-C6 speaks a sixth. Pairing Zigbee devices through Home Assistant does not work today. That gap is ours. See the Cruiser FAQ for the detail, and email support@exaviz.com if you would like to be told when it is ready.
If a command reports no API key
sudo exaviz-flash --about shows where the tool is getting its API key. If it says
NONE FOUND, the installed package is a local build rather than the published one:
sudo apt-get install --reinstall exaviz-tools
Updating when you are running Zigbee
sudo exaviz-flash update keeps you on the firmware type you already have. On a board
running the Zigbee coordinator firmware it installs the newest Zigbee build, and it will
not quietly put you back on the standard WiFi + Bluetooth firmware. Switching type is always
something you ask for explicitly, with sudo exaviz-flash zigbee or sudo exaviz-flash stock.
The rehearsal tells you which one it resolved, so you can check before committing:
Rehearsal passed for board CRU-000123: zigbee firmware 1.1.3-aa19b06 is available ...
This board is running zigbee, so `update` stays on zigbee. It will not change
which firmware you are on.
Rehearsing an update
sudo exaviz-flash update --dry-run checks everything and writes nothing, so you can
see what an update would do before it does it.
This needs version 1.0.0 or newer. On the withdrawn 0.1.x builds, --dry-run
stopped with does not match board record for serial CRU-000001. That was a
placeholder in the tool, never a fact about your board. If you see it, you are on an
old build: run sudo apt update && sudo apt install exaviz-tools and try again.
Commands write by default. update, stock and recover all act on your board
unless you add --dry-run. recover cannot be rehearsed at all and will say so.
If sudo exaviz-flash zigbee stopped with “Cannot confirm the service can serve
zigbee firmware without this board’s serial”, that was our bug and it is fixed.
The command needed your board’s serial number and looked in only two places, one of
them a file that exists only on boards running exaviz-management. It now asks the
board, which answers without being reset. Nothing on your board was changed when it
stopped, so there is nothing to undo:
sudo apt update && sudo apt upgrade
sudo exaviz-flash zigbee
You need exaviz-flash 1.0.14 or newer for that fix. Check with
sudo exaviz-flash --about, which also reports the serial it found.
What version am I on?
For the tool version, exaviz-flash --version (or -v).
For the firmware version, the line exaviz-flash update prints as it runs
(Upgrading firmware: A -> B) is the reliable way to see where you were and
where you landed. The firmware reports its version when it starts, so the tool
reads it by restarting the module during an update.
--version reports the tool, not the firmware. Before 1.0.0 it selected the
firmware version; that is now --fw-version, and the old spelling is refused
with a message naming the new flag rather than silently doing nothing.
Troubleshooting
“still in use” / “in use by another process”
Something is holding the PoE port. Close the PoE Tool, and stop any script or
container reading /dev/pse. Home Assistant integrations that poll PoE status
count too.
“another exaviz-flash run already holds…” A second update is already running. Let it finish; do not start two.
“could not read the running firmware version” The module did not report a version, usually because it is not currently running its application. The update still proceeds, and your existing backup is deliberately kept rather than overwritten.
“Refusing to flash” for any other reason The tool stops before touching the board when something does not look right. The message says what it found. Send it to support@exaviz.com rather than working around it.
Where firmware versions are listed
Every released firmware version, with what changed, is on the Product Changelogs page under ESP32 PoE Firmware.
Last modified August 18, 2026