docs(ApiReferencePage): document system.set_identity console command

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 <noreply@anthropic.com>
This commit is contained in:
2026-07-20 20:11:26 +03:00
co-authored by Claude Sonnet 5
parent 44609352b2
commit cc28ed880b
@@ -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.',
},
],
},
{