From cc28ed880b1fbfd2b3aae60572ed3633cf880322 Mon Sep 17 00:00:00 2001 From: bonamin Date: Mon, 20 Jul 2026 20:11:26 +0300 Subject: [PATCH] docs(ApiReferencePage): document system.set_identity console command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Firmware side added an MQTT-only sysadmin command to override a device's factory-set identity (serial/hw_family/hw_revision) — see project-vesper commit 64a8bc2. Per docs/README.md's console-sync rule, mirrors the same command into the console's live API Reference page. Note: this repo had substantial other pending uncommitted work (diagnostics reports, boot history, log retention, etc.) in this same file and elsewhere at the time of this commit — left untouched and still uncommitted, only the system.set_identity hunk is included here. Co-Authored-By: Claude Sonnet 5 --- .../developer/ApiReferencePage.jsx | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/frontend/src/pages/engineering/developer/ApiReferencePage.jsx b/frontend/src/pages/engineering/developer/ApiReferencePage.jsx index 434e80e..28e5e2f 100644 --- a/frontend/src/pages/engineering/developer/ApiReferencePage.jsx +++ b/frontend/src/pages/engineering/developer/ApiReferencePage.jsx @@ -666,6 +666,26 @@ const NAMESPACES = [ example: '{ "v": 2, "cmd": "system.restart" }', warning: null, }, + { + cmd: 'system.set_identity', + handler: 'SystemHandler', + transports: ['MQTT'], + description: 'Sysadmin-only override of the device\'s factory-set identity (serial, hw_family, hw_revision). Writes NVS and reboots to apply. The console is responsible for updating this device\'s backend record — including re-deriving its MQTT password from the new serial — in the same operation; firmware does not touch the backend.', + contents: [ + { field: 'serial', type: 'string', required: true, notes: 'New unique device serial. Must match what the backend record is updated to, or MQTT auth will break (password is HMAC-derived from serial).' }, + { field: 'hw_family', type: 'string', required: true, notes: 'New hardware family code (e.g. "VS"). Selects which OTA channel/binary the device pulls — must match actual hardware.' }, + { field: 'hw_revision', type: 'string', required: true, notes: 'New hardware revision code (e.g. "01"). Sent together with hw_family; must match actual hardware.' }, + ], + response: '{ "status": "SUCCESS", "type": "system.set_identity", "message": "Device identity updated. Restarting in 2 seconds to apply." }', + errors: [ + { message: 'system.set_identity is only available via MQTT', condition: 'Command sent over WebSocket, HTTP, or UART' }, + { message: 'Missing required fields: serial, hw_family, hw_revision (all required)', condition: 'One or more fields absent or not a string — no partial updates' }, + { message: 'serial, hw_family and hw_revision must be non-empty', condition: 'One or more fields present but empty string' }, + { message: 'Failed to persist new identity to NVS — device identity unchanged', condition: 'NVS write or commit failed' }, + ], + example: '{ "v": 2, "cmd": "system.set_identity", "contents": { "serial": "PV000000000001", "hw_family": "VS", "hw_revision": "01" } }', + warning: 'Non-reversible from the device\'s side, and dangerous if the backend record isn\'t updated to match: a serial mismatch breaks MQTT auth, and a wrong hw_family/hw_revision can pull an OTA build for the wrong hardware. Reboots 2s after a successful response.', + }, ], }, {