OTA Updates (Over-The-Air)

Reading time: ~6 minutes · Execution time: ~3-5 minutes per device · Audience: those who already have a Controller and/or Dosing pump configured and online on the portal, and need to update its firmware

🔵 Advanced guide (technical) — not part of the onboarding path 01-08. Use this to update a device already in use. For first installation or for recovery of a "bricked" device, you must use USB flash (see guide 16).

1. What you are about to do

OTA (Over-The-Air) is the method to update the firmware of a device without cables, directly from the portal. No PC, no USB cable, no need to disassemble the controller from the cabinet under the tank. You click a button and in a few minutes the device updates itself.

In detail: when JoyReef releases a new firmware version (Controller or Dosing pump), the portal notices it and proposes the update on the device edit page, with a red "Update available" badge. By clicking "Start OTA":

1. The portal generates a temporary signed URL (valid for 30 minutes) to the firmware binary.
2. It sends 2 MQTT commands to the device: "here is the new firmware URL" + "download and install it".
3. The device downloads the binary via HTTP, writes it to flash memory, and reboots with the new firmware.
4. It comes back online after a few seconds with the updated version.

All of this automatically, without you having to do anything other than click the button.

In this guide:

• Understand when you can use OTA and when you must use USB.
• See how to start an OTA from the portal.
• Know how to diagnose if something goes wrong.

2. When OTA can be used

OTA works only if:

• ✅ The device is online on the portal (see status indicator on the /devices page). If it's offline, the MQTT message won't reach it.
• ✅ The device already has a working JoyReef firmware (even an old one): if it's completely blank or "bricked" (corrupted firmware, won't start), OTA cannot communicate with it → you must use USB flash.
• ✅ It's a Controller or a Dosing pump: Tasmota smart plugs have their own separate update system (from their administrative page, not from JoyReef).
• ✅ There is a newer version available compared to the installed one (if you are already on the latest, the button won't appear).

In all these cases → you can and should use OTA.

When you must instead use USB (guide 16)

• ❌ Device never flashed (brand new).
• ❌ Device does not start (corrupted firmware from a failed OTA or other).
• ❌ Device offline for weeks and you can't get it back online.
• ❌ You want to force a specific firmware (downgrade, test version, custom fork).

3. Open the page of the device to be updated

From the JoyReef portal:

1. Left menu → "Devices" (or Config → Devices).
2. Find the device to be updated in the list.
3. Click on the row → the edit device page opens (/devices/{id}/edit).

Scroll down to the "Firmware" section.

🖼️ Image to insert here (Firmware section on the device page): screenshot of the "Firmware" section of the edit device page, with a red "Update available" badge, "Current: 1.2.3" and "Latest available: 1.3.0" visible.

4. Read the Firmware section

The section shows:

Status pill

• 🔴 "Update available" = there is a newer version for this device.
• 🟢 "Updated" = you are already on the latest.

Versions

• Current: vX.Y.Z = the version currently installed on the device.
• Latest available: vX.Y.W = the latest published by JoyReef for this type of device.

Changelog (if update available)

If a new firmware is available, below the version numbers you will see the changelog of the new release: what has changed (bug fixes, new features, breaking changes). Read it before updating: sometimes there are important notes like "requires probe recalibration" or "ATO settings need to be reconfigured".

"Start OTA" button

Appears only if there is actually an update available. If you are already on the latest version, the button is not there (green "Updated" badge says so).

5. Step 1 — Start the OTA

Click the "Start OTA" button.

You will see a short confirmation message like "Command sent". From this moment:

1. For ~30 seconds you won't see anything change on the page (the device is downloading).
2. Then the device reboots itself → in the MQTT monitor/events (if you have the /events page open) you will see a short "Device offline" / "Device online".
3. Reload the page (F5): the Firmware section now shows: - Green "Updated" badge. - "Current: vX.Y.W" (new version). - Button disappeared.

You have updated. ✅

How long does it last?

Typically: 2-5 minutes total from pressing the button until the device is back online with the new firmware. Times depend on:

• Device WiFi speed (1-2 MB binaries).
• Server load hosting the binary.
• Firmware size (sometimes releases are "heavier").

6. Step 2 — Verify everything works after the update

After the OTA, do a quick check:

• ✅ Go to /devices → the device must be Online.
• ✅ Go to /events filter "Sensors" → sensor readings must arrive with recent timestamps.
• ✅ If it's a Controller: the /ato / temperature / water change page must still show the live monitor active (= real-time status of automations).
• ✅ If it's a Dosing pump: go to /dosers/{id}, try a small manual dose to verify it works.

If everything is fine, you're done. If something seems strange, go to the "If something goes wrong" section.

💡 Automation settings / calibrations / schedules are persistent through OTA updates. You don't need to reconfigure anything after a normal update. Exception: major updates that change the data schema (rare, usually announced in the changelog).

7. Updating multiple devices in sequence

If you have multiple devices to update (1 Controller + 1 Dosing pump, or multi-tank setup):

1. Update one at a time, waiting for each one to come back online before moving to the next.
2. Between one OTA and another, leave at least 1-2 minutes of "breathing space" for the WiFi/MQTT broker.

Do not update everything in parallel: OTA uses a lot of local WiFi bandwidth and MQTT bandwidth. With 3-4 parallel downloads, you risk some failing due to timeout.

💡 Suggested order: first the less critical devices (Dosing pump), then the more critical ones (Controller). If the Dosing pump has a problem with the new version, the ATO and sensors are still active on the Controller. If you update the Controller first instead, if there are problems you will be without ATO until you fix it.

8. When does the portal detect new firmware?

The portal periodically checks if there are new firmware versions published by JoyReef. Typically:

• The index is updated every time you open the /devices or /devices/{id}/edit page.
• If you have the page open and a new version is released in the meantime, you must reload (F5) to see it.

💡 Want to be notified of new releases? Currently, there is no automatic email notification for new firmware versions. Important releases are communicated on JoyReef channels (newsletter, website). For "minor" new firmware, just stop by /devices occasionally and check for red badges.

9. If something goes wrong

The "Start OTA" button does not appear

• You are already on the latest version (green "Updated" badge) → nothing to update.
• Device offline → OTA won't start if the device is not reachable. Bring it back online first.
• Device type not supported by OTA → Tasmota smart plugs do not have OTA from JoyReef. You must update them from their admin page (see Tasmota documentation).

I clicked "Start OTA" but nothing happens

• Device offline at the time of click → reload the /devices page, verify the device is online, try again.
• MQTT command lost (rare): wait 1 minute and try again.
• Device is downloading but it's slow (weak WiFi, busy server): wait up to 5 minutes before concluding it has failed.

Device offline after OTA, does not come back up

This is the worst-case scenario (rare but can happen). It indicates that the flash failed halfway through and the device does not have a working firmware. You must do recovery via USB:

1. Disconnect power from the device.
2. Connect it via USB cable to the PC.
3. Open the 16 — USB Flash guide.
4. Flash the latest firmware (or the one you were using before, if you prefer a downgrade).
5. Reconfigure WiFi if necessary (usually preserved).

💡 To reduce the risk of failed OTAs: make sure the device has a solid WiFi signal (RSSI > -70 dBm) before launching the OTA. An OTA that fails halfway due to connection loss is the #1 cause of "bricked devices".

"No firmware available" as an error

The portal cannot find a published firmware for that type of device. Causes:

• New device type not yet supported by the index (JoyReef side problem, please report).
• Device with unrecognized type in the model (happens for imported legacy devices). Contact support.

"The device already has the latest version" but I see the OTA button

The portal "sees" a newer firmware in the index, but the device says it is already on that version. Causes:

• Version string difference (v1.2.3 vs 1.2.3 vs v1.2.3-stable): the comparison can be wrong.
• Recently installed device with the same version but with old metadata in the portal: reload /devices and the badge should correct itself.

In any case, there is no risk: the "Start OTA" button is idempotente, at most it reflashes the same version.

After OTA, settings are gone

Rare exception, happens on major updates where the data schema changes. If this is the case, we announced it in the release changelog.

Solution:

• Reconfigure ATO / temperature / dosing pumps / water change from their respective pages (settings in the portal are saved on the server, not on the device — when you save, they are sent back to the device).
• If your data on the portal has disappeared instead, it's a serious bug → contact support.

10. Conclusion

OTA is the daily way to keep your JoyReef devices updated. USB remains as a fallback for recovery or first installation.

💡 Recommended frequency: check the /devices page every 2-3 months, or when you receive a release communication. There is no reason to voluntarily "skip" stable versions — updates include bug fixes that always improve the situation.

💡 Conservative strategy: if you have multiple separate tanks, update the "test" one first (or the least valuable), wait 1-2 weeks without problems, then update the others. JoyReef releases are tested, but "on two tanks in the world" is always better than "all at once".