Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .github/workflows/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ jobs:
python-version: '3.12'
- name: Install PlatformIO Core
run: pip install --upgrade platformio
# Filesystem builds compile the clock preview (web/emulator/build.mjs) with Emscripten.
# Firmware builds compile the clock preview (web/emulator/build.mjs) with Emscripten.
- name: Read the Emscripten version
id: emsdk
run: echo "version=$(node web/emulator/build.mjs --emsdk-version)" >> "$GITHUB_OUTPUT"
Expand All @@ -45,5 +45,3 @@ jobs:

- name: Build PlatformIO Project
run: pio run --environment ulanzi
- name: Build Filesystem Image
run: pio run --target buildfs --environment ulanzi
10 changes: 2 additions & 8 deletions .github/workflows/build_release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ jobs:
python-version: "3.12"
- name: Install PlatformIO Core
run: pip install --upgrade platformio
# Filesystem builds compile the clock preview (web/emulator/build.mjs) with Emscripten.
# Firmware builds compile the clock preview (web/emulator/build.mjs) with Emscripten.
- name: Read the Emscripten version
id: emsdk
run: echo "version=$(node web/emulator/build.mjs --emsdk-version)" >> "$GITHUB_OUTPUT"
Expand All @@ -77,16 +77,13 @@ jobs:
# Build Release
- name: Build Release Project
run: pio run --environment ulanzi
- name: Build Release Filesystem Image
run: pio run --target buildfs --environment ulanzi
- name: Collect Release artifacts
run: |
mkdir artifacts
cp .pio/build/ulanzi/bootloader.bin artifacts/
cp .pio/build/ulanzi/partitions.bin artifacts/
cp ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin artifacts/
cp .pio/build/ulanzi/firmware.bin artifacts/
cp .pio/build/ulanzi/littlefs.bin artifacts/
# The site's face simulator, and the factory settings the home page's live clock starts from.
- name: Build the face simulator
run: |
Expand All @@ -103,16 +100,13 @@ jobs:
sed -i 's/# -DDEBUG_MEMORY/ -DDEBUG_MEMORY/' platformio.ini
- name: Build Debug Project
run: pio run --environment ulanzi_debug
- name: Build Debug Filesystem Image
run: pio run --target buildfs --environment ulanzi_debug
- name: Collect Debug artifacts
run: |
mkdir artifacts-debug
cp .pio/build/ulanzi_debug/bootloader.bin artifacts-debug/
cp .pio/build/ulanzi_debug/partitions.bin artifacts-debug/
cp ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin artifacts-debug/
cp .pio/build/ulanzi_debug/firmware.bin artifacts-debug/
cp .pio/build/ulanzi_debug/littlefs.bin artifacts-debug/

# The release assets that deploy_site.yml unpacks into the site.
- name: Package the release files
Expand Down Expand Up @@ -153,7 +147,7 @@ jobs:
version=${TAG#v-}
# The README's changelog for this version: the lines under its heading, up to the next heading.
awk -v heading="### $version" '$0 == heading { on = 1; next } on && /^##/ { exit } on' README.md > notes.md
printf '\nInstall it from https://nsclock.app/ with Chrome or Edge on a computer.\n' >> notes.md
printf '\nUpdate from the Firmware card in the clock'"'"'s settings page, or install it from https://nsclock.app/ with Chrome or Edge on a computer.\n' >> notes.md
if gh release view "$TAG" > /dev/null 2>&1; then
gh release upload "$TAG" dist/*.zip --clobber
else
Expand Down
14 changes: 14 additions & 0 deletions .github/workflows/deploy_site.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,20 @@ jobs:
unzip -q release/nightscout-clock-firmware.zip -d www/artifacts
unzip -q release/nightscout-clock-debug-firmware.zip -d www/debug/artifacts
unzip -q release/nightscout-clock-simulator.zip -d www/simulator
# Releases from before firmware updates (1.3.5 and earlier) also install a LittleFS image; later
# ones have none, so their installer leaves that part out.
python3 - <<'PY'
import json, os
for manifest in ("www/manifest.json", "www/debug/manifest-debug.json"):
with open(manifest) as f:
data = json.load(f)
folder = os.path.dirname(manifest)
for build in data["builds"]:
build["parts"] = [part for part in build["parts"] if not part["path"].endswith("littlefs.bin")
or os.path.exists(os.path.join(folder, part["path"]))]
with open(manifest, "w") as f:
json.dump(data, f, indent=4)
PY
cp www/debug/manifest-debug.json www/debug/manifest.json
- name: Upload artifact
if: steps.release.outputs.ready == 'true'
Expand Down
18 changes: 10 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,13 @@ When adding firmware behavior, prefer extending the existing module family inste

`lib/` contains third-party libraries vendored into the repository, including `LightResistor/`, `Hashing/`, `MelodyPlayer/`, `Fonts/`, and `Improv/`. Prefer keeping application-specific code in `src/`; only add to `lib/` when importing or maintaining an external library.

`data/` contains the runtime web assets packed into the LittleFS image served by the clock. The configuration UI source is in `web/src/`, with the original icon and timezone JSON in `web/src/assets/`. Before filesystem builds, PlatformIO runs `node web/emulator/build.mjs`, which compiles the display code from `src/` and `lib/` (faces, display, settings, periphery and alarm managers, fonts) to WebAssembly as `data/clockemu.js.gz`, the UI's clock preview, and then `node web/build.mjs` to generate `data/index.html.gz`, `data/favicon.ico.gz`, and `data/tzdata.json.gz`. These outputs are ignored by Git; commit their sources instead. Node.js must match the version in `.node-version`; no npm packages are required. The preview also needs Emscripten (the version printed by `node web/emulator/build.mjs --emsdk-version`) and the libraries PlatformIO installs; it is recompiled only when its inputs change.
`data/` contains the web assets and factory settings (`data/config_initial.json`) that the firmware build embeds (`board_build.embed_files` in `platformio.ini`, read through `src/EmbeddedFiles.h`); there is no filesystem image. The configuration UI source is in `web/src/`, with the original icon and timezone JSON in `web/src/assets/`. Before every firmware build, `scripts/build_web.py` runs `node web/emulator/build.mjs`, which compiles the display code from `src/` and `lib/` (faces, display, settings, periphery and alarm managers, fonts) to WebAssembly as `data/clockemu.js.gz`, the UI's clock preview, and then `node web/build.mjs` to generate `data/index.html.gz`, `data/favicon.ico.gz`, and `data/tzdata.json.gz`. These outputs are ignored by Git; commit their sources instead. Node.js must match the version in `.node-version`; no npm packages are required. The preview also needs Emscripten (the version printed by `node web/emulator/build.mjs --emsdk-version`) and the libraries PlatformIO installs, so a firmware build stops without them; the preview is recompiled only when its inputs change.

Settings are stored as one JSON entry in the `config` NVS partition (`src/ConfigStore.*`), not a file. The flash has two firmware slots (`partitions.csv`): `src/FirmwareUpdateManager.*` installs firmware uploaded from the settings page or `scripts/ota.sh` into the slot not running, keeps the previous one for going back, and returns to it when a newly installed firmware crashes before it has run for a minute.

`test/` contains the host-side tests; see Testing Guidelines.

`www/` is the project site at https://nsclock.app/, served by GitHub Pages: the home page with the browser installer, and the debug installer under `www/debug/`; it is not part of the firmware filesystem image. The release workflow (`.github/workflows/build_release.yml`) publishes each release tag as a GitHub release with three assets: the release firmware, the debug firmware, and the face simulator, which is the same clock preview, `data/clockemu.js.gz`, as a standalone page built from `web/simulator/` by `node web/build.mjs --simulator`, plus the factory settings that the home page's live clock starts from. `.github/workflows/deploy_site.yml` deploys `www/` with those assets unpacked into `www/artifacts/`, `www/debug/artifacts/` and `www/simulator/`: after every release, and whenever `www/` changes on `main`, using the release named by `data/version.txt`. `scripts/` contains contributor tooling for local build, upload, monitoring, release, and emulator/test-data tasks. Core firmware build configuration lives in `platformio.ini` and `partitions.csv`; `wokwi.toml` and `diagram.json` describe the Wokwi simulator project (see "Testing in the Wokwi simulator").
`www/` is the project site at https://nsclock.app/, served by GitHub Pages: the home page with the browser installer, and the debug installer under `www/debug/`; it is not part of the firmware. The release workflow (`.github/workflows/build_release.yml`) publishes each release tag as a GitHub release with three assets: the release firmware, the debug firmware, and the face simulator, which is the same clock preview, `data/clockemu.js.gz`, as a standalone page built from `web/simulator/` by `node web/build.mjs --simulator`, plus the factory settings that the home page's live clock starts from. `.github/workflows/deploy_site.yml` deploys `www/` with those assets unpacked into `www/artifacts/`, `www/debug/artifacts/` and `www/simulator/`: after every release, and whenever `www/` changes on `main`, using the release named by `data/version.txt`. `scripts/` contains contributor tooling for local build, upload, monitoring, release, and emulator/test-data tasks. Core firmware build configuration lives in `platformio.ini` and `partitions.csv`; `wokwi.toml` and `diagram.json` describe the Wokwi simulator project (see "Testing in the Wokwi simulator").

## Build, Test, and Development Commands

Expand All @@ -32,13 +34,13 @@ Use the IDE's PlatformIO actions or the helper scripts in `scripts/`; avoid call

- `scripts/build.sh`: the usual local build command for firmware changes.
- `scripts/build.sh --upload --monitor`: the usual edit-build-flash-monitor loop when testing on hardware.
- `scripts/build.sh --fs --upload --monitor`: use this when files in `data/` changed and the LittleFS web UI image must be rebuilt and reflashed.
- `scripts/ota.sh [--release] [--no-build] [--url <address>] [--password <password>]`: builds and installs the firmware over WiFi, the way the settings page installs an update, without a USB cable.

### Less common helpers

- `scripts/monitor.sh`: opens the serial monitor directly and saves logs under `logs/` using PlatformIO's `log2file` filter.
- `scripts/reset.sh`: use this if the device becomes unstable and does not restart cleanly after upload.
- `scripts/upload.sh --all`: use only for a full device refresh, when bootloader, partitions, firmware, and LittleFS all need to be reflashed.
- `scripts/upload.sh --all`: also writes the bootloader and partition table; needed once on a clock with the layout from before firmware updates (1.3.5 and earlier).
- `scripts/ns_emulator.py`: sends sample glucose entries to the device API for testing data processing and display behavior. Requires the clock's data source set to "API"; see the script's docstring for usage.
- `scripts/clock_address.py`: resolves the clock's address for scripts that call its API: `--url` first, then the git-ignored `.local_clock_ip` file in the repository root. New scripts that call the clock should use it.
- `scripts/merge_bins.sh`: merges the build outputs into a single distributable binary, but this is not part of the active day-to-day workflow.
Expand Down Expand Up @@ -70,15 +72,15 @@ For the web UI, keep JavaScript style consistent with the existing files in `web

## Compatibility and Validation Scope

- Firmware upgrades use a full reflash, including replacement of the configuration from `data/config_initial.json`. Do not add migration code, legacy-setting fallbacks, or downgrade compatibility unless explicitly requested.
- Settings survive firmware updates, and going back to the previous version. At boot the saved settings are laid over the firmware's factory settings (`src/SettingsOverlay.h`), at any depth, so a new setting needs only a default in `data/config_initial.json`, and an older version ignores the keys it does not know. A renamed or reinterpreted setting needs explicit handling; otherwise, do not add migration code, legacy-setting fallbacks, or downgrade compatibility unless explicitly requested.
- Configuration is managed through the provided Web UI. Hand-edited configurations and hostile configuration submissions to `/api/save` are outside the supported workflow. Validate user-editable fields in the UI; avoid duplicating those checks throughout the firmware without a concrete need.
- Keep checks required for normal operational failures, such as failed network requests, unavailable time, missing files, and malformed responses from external services. Keep bounds checks needed for memory safety and existing authentication controls.

## Testing Guidelines

`test/run_tests.sh` runs the host-side tests, which need only `g++` and Node.js and also run on every pull request. They cover logic that compiles without Arduino, such as `src/SettingsAlertWindow.h`, and the web UI's `web/src/js/schema.js`. Tests must exercise the real source rather than a copy of it; to test firmware logic, move it into an Arduino-free header in `src/`.

Host-side tests do not replace hardware testing: firmware changes must be validated by building and testing on a real device before a pull request is created, as described in "Pull request rules" in `CONTRIBUTING.md`. The normal workflow is `scripts/build.sh --upload --monitor`, or `scripts/build.sh --fs --upload --monitor` when files in `data/` changed.
Host-side tests do not replace hardware testing: firmware changes must be validated by building and testing on a real device before a pull request is created, as described in "Pull request rules" in `CONTRIBUTING.md`. The normal workflow is `scripts/build.sh --upload --monitor`, or `scripts/ota.sh` over WiFi.

Prefer testing against the real data source affected by your change. For display logic, parsing, and update flow, `scripts/ns_emulator.py` can push sample glucose entries into the device API so you can exercise behavior without waiting for live data.

Expand All @@ -90,7 +92,7 @@ The Wokwi simulator runs the firmware on a simulated ESP32 with the 32x8 matrix,

Coding agents run Wokwi simulations only when the user explicitly asks for them. They are not part of the standard verification sequence: do not run them automatically after a change, before a commit, or before a pull request. Each run is slow and uses the user's Wokwi CI minutes.

- `scripts/wokwi.sh [--no-build] [wokwi-cli options]` builds the `wokwi` PlatformIO environment (`-DWOKWI`) and a LittleFS image, then runs `wokwi-cli` in Wokwi's cloud. It needs `wokwi-cli` and a CI token in `WOKWI_CLI_TOKEN` or the git-ignored `.wokwi_token` file. The `wokwi` environment builds its LittleFS image with `scripts/wokwi_data.py`: `data/config_initial.json` plus `scripts/wokwi_config.json` (Wokwi-GUEST Wi-Fi, "API" data source), never your `data/config.json`. In VS Code, select the `wokwi` environment and run Build, Build Filesystem Image, and the custom "Merge Wokwi image" task (or `scripts/merge_bins.sh wokwi`) to make the `merged_firmware.bin` that `wokwi.toml` loads.
- `scripts/wokwi.sh [--no-build] [wokwi-cli options]` builds the `wokwi` PlatformIO environment (`-DWOKWI`), then runs `wokwi-cli` in Wokwi's cloud. It needs `wokwi-cli` and a CI token in `WOKWI_CLI_TOKEN` or the git-ignored `.wokwi_token` file. The `wokwi` build's factory settings are `data/config_initial.json` with `scripts/wokwi_config.json` (Wokwi-GUEST Wi-Fi, "API" data source) laid over it, and the simulated flash starts empty, so the clock starts from them. In VS Code, select the `wokwi` environment and run Build and the custom "Merge Wokwi image" task (or `scripts/merge_bins.sh wokwi`) to make the `merged_firmware.bin` that `wokwi.toml` loads.
- `wokwi-cli` cannot reach the clock over HTTP. The `wokwi` build replaces Improv's serial input with the commands in `src/WokwiConsole.h`: `bg <sgv> [trend] [minutes_ago]`, `clear`, and `screen`, which prints the LED colors.
- Scenarios in `scripts/wokwi_scenarios/` drive a run: `wait-serial`, `write-serial` for those commands, and `set-control` for buttons (`btn_left`, `btn_select`, `btn_right`) and the light sensor (`ldr`). Start from `smoke.yaml`.
- `python3 scripts/wokwi_screen.py <serial log> --ascii` turns the `screen` dumps into PNG files and text, because Wokwi cannot take screenshots of its NeoPixel canvas.
Expand All @@ -104,4 +106,4 @@ Before committing or opening a pull request, read and follow the introduction, "

The upload, reset, and monitor scripts resolve the same `upload_port` through `scripts/get_port.sh`. If flashing or monitoring fails on a different machine or after reconnecting the clock, update `upload_port` in `platformio.local.ini` before troubleshooting deeper firmware issues.

Treat `web/src/` as the web UI source and `data/` as the runtime payload built from it. If you change the device-served UI, verify the browser behavior; also verify the rebuilt filesystem image on hardware when the same change touches firmware.
Treat `web/src/` as the web UI source and `data/` as the runtime payload built from it. If you change the device-served UI, verify the browser behavior; the UI is part of the firmware, so verify it on hardware with the rebuilt firmware.
Loading