Skip to content

Install firmware updates from the settings page - #292

Open
ktomy wants to merge 3 commits into
mainfrom
firmware-updates-from-browser
Open

ktomy wants to merge 3 commits into
mainfrom
firmware-updates-from-browser

Conversation

@ktomy

@ktomy ktomy commented Nov 21, 2026

Copy link
Copy Markdown
Owner

What changed

  • Firmware card (WiFi & system tab) installs firmware from the clock's own settings page:
    • the version published on nsclock.app, release or debug; when the clock already runs that version, it offers only a switch to the other kind
    • a local file ("Install from file…")
    • "Go back to ", when the other slot holds a healthy NSClock build
  • Delivery: the browser downloads the file and uploads it; the clock never downloads firmware itself.
  • scripts/ota.sh installs a local build over WiFi, with --password / NSCLOCK_PASSWORD when the web password is on.
  • Update flow (src/FirmwareUpdateManager.*):
    • the update stops the data source, whichever it is, and frees its HTTP/TLS clients
    • the clock shows UPDATE, takes the upload into the slot that is not running, then shows SUCCESS (2 s) or FAILED (3 s) and restarts
    • it refuses files without the NSClock update marker, uploads too big for the slot, incomplete uploads, stalled uploads (15 s), no upload within 60 s, and images that fail their hash check
  • Automatic rollback: a new firmware that does not run for a minute returns to the previous one, which is then never offered again. Restarts the firmware chooses itself (saving settings, a data source's login restart) do not count as failures.
  • Flash layout (partitions.csv): two 1984 KB firmware slots and a 64 KB config NVS partition; LittleFS is gone.
  • Settings: stored as one JSON entry in NVS (src/ConfigStore.*) and laid over the factory settings at boot (src/SettingsOverlay.h), so they survive updates and going back.
  • Web UI: embedded in the firmware (board_build.embed_files), served with CRC ETags. Every firmware build now builds the web assets and the clock preview, so it needs Emscripten.
  • Tooling and docs: upload.sh writes boot_app0 so a USB install after an over-the-air update boots the USB firmware; --fs is removed; CI, the release workflow, the site manifests and the docs are updated.

Why

Updating meant a USB install from nsclock.app that also replaced all settings. Now an update keeps the settings and needs only the phone.

Every clock needs one more USB install (scripts/upload.sh --all, or the nsclock.app installer) because the partition table changes.

How it was tested

On a real Ulanzi clock:

  • the USB install of the new layout from 1.3.5, followed by importing the settings
  • about 25 updates over the air, between test builds 1.3.5 and 1.3.6, debug and release, written into both slots in both directions; two of them ran back to back within the first minute after boot
  • failure cases: a corrupted file, a random file, the 1.3.5 firmware with no marker, a file without the image's magic byte, an upload with a size header larger or smaller than the file, curl killed midway, a start with no upload, an oversized file, a missing size header
  • after each failure, the clock restarted on its old firmware and did not offer the broken image
  • 409 guards, 401 with the web password on, and ota.sh with no password, a wrong one and the right one
  • the API source answers 503 during an update
  • rollback from a build that aborts in setup(), and no rollback on a restart in the first minute
  • a USB flash while running the second slot, a factory reset, and every embedded route with ETag/304
  • the Firmware card's "Install from file" and "Go back" run in Chromium against the clock

test/run_tests.sh passes, including new tests for the offer logic and the marker.

Screenshots

The Firmware card on the WiFi & system tab:

WiFi & system tab

🤖 Generated with Claude Code

Until now a clock could only be updated with a USB install from
nsclock.app, which also replaced all settings. The settings page now
installs firmware itself: the Firmware card offers the version published
on nsclock.app (release or debug), a file from the phone or computer,
and going back to the version the last update replaced. The browser
downloads the file and uploads it, so the clock never downloads
firmware on its own. scripts/ota.sh installs a local build the same way.

The flash now has two firmware slots and a small partition for the
settings. An update stops the data source and frees its connections,
shows UPDATE, and writes the upload into the slot that is not running.
It shows SUCCESS and restarts on the new firmware, or shows FAILED and
restarts on the old one when the upload is refused, incomplete, stalls,
or fails its image check. Only files that carry NSClock's update marker
are accepted, which also keeps out versions made for the old layout. A
new firmware that does not survive its first minute makes the
bootloader return to the previous one, which is then not offered again.

Settings live as one JSON entry in NVS instead of a LittleFS file, and
are laid over the firmware's factory settings at boot, so they survive
updates and going back. The web UI is embedded in the firmware, which
replaces the filesystem image; every firmware build therefore builds the
web assets and the clock preview, and needs Emscripten.

Clocks need one more USB install with the new partition table; updates
come from the settings page after that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ktomy

ktomy commented Nov 21, 2026

Copy link
Copy Markdown
Owner Author

@nishanm, @adamecker could you please have a look at this PR? Thank you

ktomy and others added 2 commits November 21, 2026 12:14
The site deploy now leaves the LittleFS image out of the installer only
when the release it serves has none, so merging this keeps installing
1.3.5 with its filesystem until a release with firmware updates exists.

A settings read that fails, for lack of memory for example, no longer
counts as "nothing saved", which replaced the saved settings, WiFi
included, with the factory ones. The settings page reads them at any
time, while free memory can be low.

The firmware upload sets its data time before it is marked as started,
so the main loop cannot compare a stale time and declare a fresh upload
stalled. After a successful installation or going back, the Firmware
card keeps its actions disabled until the page is reloaded, because it
still describes the firmware that ran before. scripts/ota.sh sends the
login through stdin, so the password does not show in curl's arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Only a settings namespace or entry that does not exist counts as nothing
saved now. The settings are read with the NVS calls themselves, because
Preferences reports every error as "not there", and any other failure
no longer leads to the factory settings replacing the saved ones. Laying
the saved settings over the factory ones also fails as a whole when it
runs out of memory, instead of returning settings with values missing.
The read buffer has room for the terminator that String copies.

A data source that shows a fatal error keeps the main loop on that
error for minutes, so an update started meanwhile never got past
stopping the source. The error screen now hands over to an update once
one starts, and the update ends with a restart as usual.

When the answer to an upload is lost, the settings page checks which
firmware the clock runs after its restart, and reports the update as
installed when the clock now runs the uploaded build. A local file that
cannot be read, or is too big for the clock, gets a message instead of
leaving the Firmware card disabled. scripts/ota.sh is executable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant