Skip to content

Add firmware notification system for OTA updates - #9

Merged
JamesSmartCell merged 2 commits into
masterfrom
cursor/firmware-notify-devices-9be7
Nov 17, 2026
Merged

JamesSmartCell merged 2 commits into
masterfrom
cursor/firmware-notify-devices-9be7

Conversation

@JamesSmartCell

Copy link
Copy Markdown
Owner

Overview

Implements a complete firmware notification system to enable Over-The-Air (OTA) updates for SmartLayer IoT devices. This adds the "notify devices" step to the existing firmware upload infrastructure.

Changes

Core Features

  • Version Parsing: Parse firmware version format <project>@<semver>+<hash> from TCP login (opcode 0x09)
  • Device Registry: Store parsed project and semver on device sessions
  • Notify Endpoint: New POST /api/firmware/:project/notify with admin authentication
  • Auto-Notify: Optional ?notify=true flag on upload/current endpoints
  • CLI Support: Added --notify option to tools/firmware/upload.ts
  • Telemetry Integration: Expose updateAvailable in GET /telemetry/devices
  • Event Recording: Record firmware_notify telemetry events
  • Device Communication: Send updateReady API call to devices via opcode 0x04

Implementation Details

Version Format

New-style GarageDoor firmware uses:

garagedoor@1.2.0+ab12cd3

Legacy firmware (opcode 0x07, non-standard versions) is never notified and continues to work unchanged.

Selection Logic

The notify endpoint:

  1. Selects devices with matching project name
  2. Filters to new-format firmware only
  3. Compares semver (notifies if device version < latest version)
  4. Supports force: true to notify all devices
  5. Supports optional devices: [...] array to target specific devices

API Flow

  1. Upload firmware: POST /api/firmware/:project?version=1.2.0&notify=true
  2. Or notify later: POST /api/firmware/:project/notify
  3. Devices receive updateReady call via opcode 0x04
  4. Devices call GET /api/firmware/:project/latest to get metadata
  5. Devices download binary, verify SHA256, flash OTA, reboot

Testing

  • ✅ All existing tests pass (179 tests)
  • ✅ New tests for version parsing and comparison
  • ✅ New tests for notify endpoint (auth, filtering, force flag)
  • ✅ Typecheck passes for tools

Documentation

Complete documentation added in docs/firmware-ota.md:

  • API endpoint specifications
  • Firmware version format
  • End-to-end release steps
  • Device implementation guide
  • Troubleshooting guide

Security

  • Admin authentication required for notify endpoint
  • Legacy firmware never notified automatically
  • Devices verify SHA256 before flashing
  • All events logged in telemetry

Breaking Changes

None. This is purely additive. Legacy devices are unaffected.

Open in Web Open in Cursor 

cursoragent and others added 2 commits November 17, 2026 02:13
- Parse firmware version format '<project>@<semver>+<hash>' in TCP login (opcode 0x09)
- Store parsed project and semver on device sessions
- Add POST /api/firmware/:project/notify endpoint with admin auth
- Support optional notify flag on upload/current endpoints (?notify=true)
- Add --notify option to tools/firmware/upload.ts CLI
- Expose updateAvailable in GET /telemetry/devices
- Record firmware_notify telemetry events
- Send updateReady API call to devices via opcode 0x04
- Skip legacy firmware formats (never break old devices)
- Comprehensive tests for version parsing, selection logic, auth, and 0x04 send
- Document complete OTA flow in docs/firmware-ota.md

Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
- Extract semver from any format (plain, v-prefix, @project, +build)
- compareSemver/isOlder handle different version formats
- Treat unparseable latest versions as error (do not notify)
- Validate upload version is plain semver MAJOR.MINOR.PATCH
- Reject v-prefix, @project prefix, +build suffix at upload
- Add validation in POST /firmware/:project endpoint
- Add validation in tools/firmware/upload.ts with clear error messages
- Update docs: version must equal device FIRMWARE_SEMVER exactly
- Comprehensive tests for extractSemver, isPlainSemver, format mixing
- Tests for upload validation and unparseable version handling
- All 196 tests pass, typecheck passes

Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
@JamesSmartCell
JamesSmartCell merged commit 72e0ff9 into master Nov 17, 2026
4 checks passed
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.

2 participants