fix(api): speak the real TRMNL device protocol

[glani]

Problem

The server implements a protocol the TRMNL firmware doesn't use, so all device data was lost while endpoints answered 200 OK. Observed in production (mg-1.giglabo.com, 17 days uptime):

• devices: 4740 rows, all UNKNOWN-<hex>, one per poll
• device_logs: 0 rows after thousands of accepted POST /api/log
• battery_readings: 0 rows

Causes and fixes

1. Identification (ID header). The firmware sends its MAC in ID, not X-Device-MAC (terminus doc/api.adoc). _get_device_mac now reads ID first, and returns None for unidentified callers instead of minting a random UNKNOWN-<hex> — that fallback was what registered a new device on every request.

2. Log payload shape. Current firmware posts {"logs": [...]}; only {"log": {"logs_array": [...]}} was handled, so real payloads fell through to a silent debug-level "unknown format" branch. Both shapes are stored now, and an unrecognized body is logged at WARNING with its content — a silent drop is how this went unnoticed for weeks.

3. Battery telemetry. The TRMNL protocol has no battery endpoint. Devices report Battery-Voltage / RSSI / FW-Version / Refresh-Rate in request headers and repeat them inside log entries. Readings are taken from there, throttled to one sample per device per 15 min (the firmware polls every ~2 min). POST /api/battery stays for manual reporting.

Also in scope:

• last_seen was written in local time while the DB defaults are UTC — a skew equal to the server's offset, visible in the data.
• LOG_LEVEL / server.log_level config: handler diagnostics are DEBUG and the level was hardcoded to INFO, so nothing could be debugged without rebuilding the image.

Tests

tests/test_device_api.py — 14 tests over a throwaway SQLite DB: ID header identification, anonymous callers registering nothing, both log formats, battery extraction from headers and log entries, sampling throttle, and the loud unrecognized-payload path.

./scripts/check_code.sh passes ruff/black/flake8; mypy is down one pre-existing error, the rest are the untouched yaml-stub baseline.

Follow-ups (not in this PR)

• Retention/pruning for device_logs, battery_readings, devices
• One-off cleanup of the 4739 junk device rows in prod
• GET /api/setup mints a fresh random api_key per call and never persists it

🤖 Generated with Claude Code