Over-the-Air Updates

01Before you start

What updates over the air

HydroNode firmware 0.5.0 or later

Flashed with the device builder. This is the last USB flash the board needs. Older firmware asks for it once.

An ESP32 for new firmware

ESP32, S2, S3, C3 and C6 take new firmware and new config. The ESP8266 takes config only, because it has no room for a second copy of the firmware.

A saved setup for config

Config changes start from the setup the device builder saved on the sensor. A sensor flashed before setups existed needs one reflash first.

Owner or Admin share

Fleet lists every sensor you own and every sensor shared with you at Admin level. Both may start changes. Read and Write shares do not appear.

Device	Firmware over the air	Config over the air
HydroNode firmware 0.5.0 or later on ESP32, S2, S3, C3 or C6	Yes, signed images only	Yes
HydroNode firmware 0.5.0 or later on ESP8266	No, new firmware needs USB	Yes
HydroNode firmware before 0.5.0	No, reflash once via USB	No, reflash once via USB
Your own sketch with the HydroNode library	No	No
ESPHome with the HydroNode component	Through ESPHome	Through ESPHome
LoRaWAN sensor	No	No

Firmware is the program on the board. Config is everything the device builder asked you: which sensors sit on which pins, how often the board sends, how it sleeps and which values go out. WiFi and the sensor secret are never part of a config change. The board keeps the ones it has.

02On the board

How a board installs an update

Every update is a job in Fleet. The board starts each step itself when it checks in, so HydroNode never reaches into your network. For new firmware the board downloads the image, checks its signature, restarts into it and checks itself before it keeps it.

A config change takes the same path without a download: the board receives the new settings with the reply, keeps its old config, writes the new one, restarts and checks. A change with firmware and config runs the firmware first and the config right after, as one job.

The states of a job and how to cancel one are explained in Changes.

03Verify & rollback

New firmware has to prove itself

After a restart into new firmware or a new config, the board does not sleep. It checks itself in its first wake cycle: up to three tries, 15 seconds apart, at most two minutes. Until it passes, the old firmware and the old config stay on the board. If it fails, or if the board restarts before the verdict, it goes back to what it ran before and reports why. You change nothing for that.

Verify mode	The update counts as good after	Use it for
Strict (default)	A signed reading accepted by HydroNode, and every configured sensor read.	Almost everything. A sensor that stops answering after an update is caught.
Lenient	The first signed reading accepted by HydroNode.	A device with a sensor that is already broken and would fail Strict every time.

Set the mode on three levels. Fleet settings (the gear on the Devices tab) holds your account default. Verify mode in the details of a device overrides it for that device, or follows the account default again. The bulk change dialog sets it for one change. The details show where the mode comes from, for example Strict (account) or Lenient (override).

A rolled back device shows Rolled back for 24 hours with the reason in code style. The details spell it out, for example: "The last update to 0.5.1 booted, but the BME280 did not answer in three tries. The device went back to 0.5.0 by itself and is running fine." Relays and LEDs keep their last state over every restart.

Reason	Meaning
sensor_read_failed:bme280	Strict only: this sensor did not answer in three tries.
ingest_failed:401	HydroNode refused the readings of the new version, here with this HTTP status.
server_unreachable	WiFi worked, HydroNode did not answer. The job is tried again later.
wifi_failed	The board did not get onto WiFi with the new version or config.
timeout	The check did not finish within two minutes.
config_invalid	The board could not read the new config and kept the old one.
boot_failed	The board restarted before the verdict, for example after a crash.

04Security & limits

Signed, checked and never with your WiFi

Signed firmware

Every firmware image is signed with a key that stays offline on a hardware security key. HydroNode checks the signature before it offers an image, and the board checks it again before it installs anything.

Config without secrets

Config changes travel over TLS, signed like commands. They never contain the WiFi password or the sensor secret. The board keeps its own.

Always a way back

The old firmware and the old config stay on the board until the new one passed its check. The bootloader and the partition table never change over the air.

Limits

Up to 30 changes per hour per account and 200 devices per change. HydroNode sends only a few firmware downloads at the same time; the others start a round later.

05Troubleshooting

When an update does not arrive

You see	What to do
Waiting for check-in does not end	The board sleeps or is offline. The job starts with its next reading. Check power and WiFi if it stays offline.
needs USB once	Reflash the board once in the device builder. From then on, it updates over the air.
Change config is greyed out	The reason stands under the buttons. Usually the sensor has no saved setup or its firmware is older than 0.5.0: reflash it once with the device builder.
Rolled back with sensor_read_failed	Check the wiring of that sensor. If it is broken on purpose, set the device to Lenient and update again.
Offered 3 times, not taken	Open the console. A refused offer names its reason, for example a wrong family or too little space.
Firmware 0.5.1 is not signed	The release is not signed yet. No board is offered new firmware until it is. Config changes still work.
A device is missing	Fleet shows sensors you own or administer. Read and Write shares do not appear.

Each step of an update also appears in the Device Console as an OTA line, for example ota download 62% or ota installed 0.5.1 in 41 s.