Skip to content

Add Zigbee gateway diagnostics API - #14

Merged
JamesSmartCell merged 1 commit into
masterfrom
cursor/zigbee-gateway-diagnostics-4693
Nov 18, 2026
Merged

JamesSmartCell merged 1 commit into
masterfrom
cursor/zigbee-gateway-diagnostics-4693

Conversation

@JamesSmartCell

Copy link
Copy Markdown
Owner

Summary

Adds a Zigbee gateway diagnostics API that matches the ESP32-C6 firmware client (ZigbeeGateway-ESP32C6 main/diag.c / ota_update.c) wire format, plus admin feed/ack/command tooling and docs for the new zigbeediagnostics.percolate.one Caddy hostname.

Device API

  • POST /api/diag/zbgw — Host-independent path (same as prior homesolar target)
  • Auth via X-ZBGW-Diag against ZBGW_DIAG_TOKENS (comma-separated, constant-time compare; never hard-coded)
  • Stores arbitrary extra payload fields (64KB cap) in SQLite zigbee.db next to telemetry
  • Returns pending commands once: {"commands":[{"action":"restart"}]} (also supports queued ota_check)

Admin API (Bearer TELEMETRY_API_KEY)

  • GET /api/diag/zbgw/gateways
  • GET /api/diag/zbgw/events?afterId=&limit=
  • POST /api/diag/zbgw/ack — signed zbgw-ack:<upToId>:<nonce> (respects TELEMETRY_ACK_ENABLED)
  • POST /api/diag/zbgw/commands — signed zbgw-cmd:<mac>:<action>:<nonce>

Schema reserves device_pubkey / auth_approved for a future per-device P-256 signing scheme (TODO only).

OTA / tooling

  • Existing firmware coordinator serves GET /api/firmware/zigbee-gateway/latest (no special-casing)
  • npm run telemetry:zigbee:pull → data/zigbee-YYYYMMDD.jsonl (acks only with --ack)
  • npm run telemetry:zigbee:analyse — silent gateways, watchdog, Wi-Fi/MQTT flaps, reset reasons, OTA failures, unknown-device dumps
  • npm run telemetry:all — SmartLayer pull+analyse then Zigbee pull+analyse

Pi env vars for Rob

ZBGW_DIAG_TOKENS=<comma-separated-tokens>   # must match device X-ZBGW-Diag / CONFIG_ZBGW_DIAG_TOKEN
# optional:
# ZIGBEE_DB_PATH=./data/zigbee.db

Also add the Caddy site for zigbeediagnostics.percolate.one reverse-proxying to the same upstream as scriptproxy (see Caddyfile.example / README).

Tests

  • New vitest coverage for auth failures, storage, command queue delivery, admin feed/ack/commands, and zigbee-gateway firmware latest
  • Full suite green locally (260 tests); CI matrix Node 20 + 22

Do not merge until Rob has set the Pi env + Caddy block (master auto-deploys).

Open in Web Open in Cursor 

Implement POST /api/diag/zbgw matching ZigbeeGateway-ESP32C6 diag.c wire
format (X-ZBGW-Diag token auth, command delivery), SQLite storage next to
telemetry, admin feed/ack/command endpoints, zigbee-gateway OTA via the
existing firmware coordinator, and telemetry pull/analyse/all scripts.

Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
@JamesSmartCell
JamesSmartCell merged commit b2daf11 into master Nov 18, 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