Skip to content
Merged
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
7 changes: 7 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,13 @@ TELEMETRY_FEED_MAX_LIMIT=5000
# When true, ack endpoint always returns wouldDelete instead of deleting
TELEMETRY_ACK_ENABLED=false

# Zigbee gateway diagnostics (POST /api/diag/zbgw, header X-ZBGW-Diag)
# Comma-separated product tokens — never commit real tokens
# Generate: openssl rand -base64 32
ZBGW_DIAG_TOKENS=
# Optional separate SQLite path (default: sibling of TELEMETRY_DB_PATH → zigbee.db)
# ZIGBEE_DB_PATH=./data/zigbee.db

# Cloudflare R2 Configuration (for camera uploads and firmware storage)
# R2_ACCOUNT_ID=
# R2_ACCESS_KEY_ID=
Expand Down
16 changes: 16 additions & 0 deletions Caddyfile.example
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,19 @@
respond 403
}
}

# Zigbee gateway diagnostics hostname
# Devices POST to https://zigbeediagnostics.percolate.one/api/diag/zbgw
# Routes are Host-independent; reverse_proxy the same upstream as scriptproxy.
#
# zigbeediagnostics.percolate.one {
# handle /api* {
# reverse_proxy localhost:8081
# }
# handle {
# respond 403
# }
# }
#
# Or, if scriptproxy already uses a named upstream / site block, point both
# hostnames at that same reverse_proxy target.
70 changes: 70 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ Environment variables (or `application.properties` file):
- `TELEMETRY_FEED_MAX_LIMIT` - Maximum feed limit (default: 5000)
- `TELEMETRY_ACK_ENABLED` - Enable actual deletion via ack (default: false; when false, ack is forced dry-run)

- **Zigbee gateway diagnostics:**
- `ZBGW_DIAG_TOKENS` - Comma-separated product tokens for device `X-ZBGW-Diag` header (REQUIRED for `/api/diag/zbgw`)
- `ZIGBEE_DB_PATH` - Optional SQLite path (default: sibling of telemetry DB → `zigbee.db`)

- **Admin Authentication:**
- `ADMIN_ADDRESSES` - Comma-separated Ethereum addresses authorized for admin operations
- `TELEMETRY_ADMIN_ADDRESSES` - Additional addresses authorized for telemetry ack
Expand Down Expand Up @@ -75,10 +79,66 @@ Admin-protected operations require a signed challenge. The flow:
1. **GET /api/admin/challenge** - Returns `{nonce, expiresAt}` (nonce valid 60s)
2. Client signs EIP-191 personal_sign message: `<action>:<params>:<nonce>`
- For ack: `ack:<upToId>:<nonce>`
- For Zigbee ack: `zbgw-ack:<upToId>:<nonce>`
- For Zigbee command queue: `zbgw-cmd:<mac>:<action>:<nonce>` (`restart` | `ota_check`)
- For firmware upload: `firmware:<project>:<version>:<sha256>:<nonce>`
- For firmware rollback: `current:<project>:<version>:<nonce>`
3. Submit signature with request (nonce is single-use and burned after verification)

### Zigbee Gateway Diagnostics

Host-independent routes used by ESP32-C6 gateways (firmware `diag.c`). Devices may call
`https://zigbeediagnostics.percolate.one/api/diag/zbgw` (Caddy reverse-proxies that hostname
to the same upstream as `scriptproxy.percolate.one`).

**POST /api/diag/zbgw** (device)

Auth: header `X-ZBGW-Diag: <token>` must match one of `ZBGW_DIAG_TOKENS` (constant-time compare).
Payload capped at 64KB. Arbitrary extra fields are stored as JSON (watchdog counters, reset
reason, recovery stage, unknown-device descriptor dumps, etc.).

Example body (matches firmware wire format):
```json
{
"device_id": "aabbccddeeff",
"fw": "1.2.3",
"kind": "boot|error|ok|poll|device|device-added",
"ok": true,
"uptime_s": 120,
"reset": "power|software|panic|watchdog|brownout|sleep|other",
"heap": 120000,
"wifi_rssi": -55,
"mqtt_ok": true,
"zigbee_ok": true,
"devices": 2,
"code": "boot",
"message": "Gateway started"
}
```

Response (pending admin-queued commands are delivered once, then marked delivered):
```json
{ "commands": [{ "action": "restart" }] }
```

**Admin reads** (Bearer `TELEMETRY_API_KEY`, same as `/telemetry/*`):

| Endpoint | Description |
|----------|-------------|
| `GET /api/diag/zbgw/gateways` | List known gateways (mac, fw, first/last seen, last IP, status) |
| `GET /api/diag/zbgw/events?afterId=&limit=` | Event feed with after-id paging |
| `POST /api/diag/zbgw/ack` | Ack/delete events up to id (`zbgw-ack:<upToId>:<nonce>`; respects `TELEMETRY_ACK_ENABLED`) |
| `POST /api/diag/zbgw/commands` | Queue `restart` or `ota_check` (`zbgw-cmd:<mac>:<action>:<nonce>`) |

SQLite tables live in `zigbee.db` next to the telemetry DB (`zigbee_gateways`, `zigbee_events`,
`zigbee_commands`) with auto-migrating schema. Columns `device_pubkey` / `auth_approved` are
reserved for a future per-device P-256 signing scheme (admin-approved pubkey); not implemented yet.

**OTA:** Upload project `zigbee-gateway` via the existing firmware coordinator /
`npm run firmware:upload zigbee-gateway <semver> firmware.bin`. Devices (or tooling) can query
`GET /api/firmware/zigbee-gateway/latest` → `{version,url,sha256,size}`. No special-casing beyond
the project name.

### Telemetry Feed & Acknowledgement

**GET /api/telemetry/feed?afterId=<id>&limit=<n>**
Expand Down Expand Up @@ -348,13 +408,23 @@ Outputs markdown report with:
- Failing/slow API methods
- Attribution: proxy vs Web3E TcpBridge/UdpBridge vs device firmware

**Zigbee diagnostics pull & analyse:**

```bash
npm run telemetry:zigbee:pull # → data/zigbee-YYYYMMDD.jsonl (no ack)
npm run telemetry:zigbee:pull -- --ack # Pull + ack (only when --ack passed)
npm run telemetry:zigbee:analyse # Silent gateways, watchdog, Wi-Fi/MQTT flaps, OTA failures, unknown-device dumps
npm run telemetry:all # SmartLayer pull+analyse, then Zigbee pull+analyse
```

### Firmware Upload

**Upload firmware binary with admin signature:**

```bash
# Using npm scripts (recommended)
npm run firmware:upload GarageDoor 1.2.3 firmware.bin
npm run firmware:upload zigbee-gateway 1.2.3 firmware.bin

# Or using ts-node directly
ts-node tools/firmware/upload.ts <project> <version> <firmware.bin>
Expand Down
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@
"typecheck:tools": "tsc --project tsconfig.tools.json --noEmit",
"telemetry:pull": "ts-node tools/telemetry/pull.ts",
"telemetry:analyse": "ts-node tools/telemetry/analyse.ts",
"telemetry:zigbee:pull": "ts-node tools/telemetry/pull-zigbee.ts",
"telemetry:zigbee:analyse": "ts-node tools/telemetry/analyse-zigbee.ts",
"telemetry:all": "ts-node tools/telemetry/all.ts",
"firmware:upload": "ts-node tools/firmware/upload.ts"
},
"engines": {
Expand Down
Loading
Loading