HiveTraffic night mode: schedule, traffic gate, config and UI

[MacNite]

The HiveHub half of night mode. Pairs with MacNite/HiveTraffic#14, which adds the device-side suspension. Deploy order below.

Why

A HiveTraffic counter's 48 IR emitters are its power budget — 24 series pairs behind 22 Ω ballast, ~0.5–1.0 A peak, an order of magnitude above everything else on that board. European honey bees are diurnal (flight needs light, and stops below roughly 10 °C regardless), so overnight that current buys nothing.

The split

HiveHub owns the schedule because the counter cannot: it has no RTC, no NVS and no network, while this device has NTP and a DS3231 good to ±2 ppm. Once per cycle the existing GATT session carries one extra 5-byte write telling the counter how long to stop sensing — no extra scan, no extra connect. The counter forgets it on any reset and it expires on its own, so a HiveHub that dies mid-night cannot leave a counter blind.

Fails safe by construction

firmware/include/night_mode.h is a pure header with host tests, because this goes wrong quietly in both directions: suspend when you should not and a day's foraging becomes a row of zeros that reads as bad weather; fail to suspend and nothing happens except a flat battery three weeks later.

Every uncertain path returns keep counting — no valid local time, no traffic baseline, a window whose ends are equal, a relay in flight. The worst outcome of a bug here is a counter that counts, which is what it did before.

Two rules worth flagging as decisions rather than details:

• start == end is an empty window, never a 24-hour one. The other reading would let one mis-set field stop a counter for good, an hour at a time, with nothing in the data saying why.
• No traffic baseline postpones rather than proceeds. "I don't know how busy this hive is" is not "it is quiet". Costs one cycle after a reboot.

The traffic gate

The "not yet" rule that was asked for: if more than N bees crossed in the last cycle, night mode waits. It differences the previous cycle's totals, held in RTC memory across HiveHub's own deep sleep — without that there would never be a previous reading and the gate would postpone forever. Reboots are attributed the same way server/measurements.py does, so the gate and the charted interval never disagree.

Timezone is load-bearing, not cosmetic

The device clock is UTC (configTime(0, 0, …)). Without a TZ a window entered as 20:00 fires at 21:00 local in summer, discarding an hour of foraging on exactly the long evenings that have most of it. Stored as a POSIX TZ string because the ESP32 carries no tz database; the dashboard offers presets for the common zones plus free text.

Scope

• Ships OFF. An existing device is unaffected until it is turned on.
• Settings live in device_configs (migration 025), edited under Device & admin.
• Applied on every config fetch, not behind the config_version gate — that gate exists to protect a portal-side tare, and night mode has no portal counterpart. Turning the window off has to take effect next cycle, not after an unrelated edit bumps the version.
• Persisted in NVS, so a hub that boots without WiFi still honours the last known window — which is precisely the deployment this is for.
• Mirrored into the public demo dashboard so it stays representative.

Wire revision

The parser learns fw:4 (idle_s, status bit 0x80) and keeps reading fw:2/fw:3. The addition is purely additive, so it already read v4 documents correctly — what it could not do is tell a suspended counter from a broken one, which is the point of reading it.

The "relay at night" interaction

docs/hivetraffic-bee-counter.md recommends relaying firmware at night because a transfer costs counted bees. Deep sleep would have made that the one time of day a counter is unreachable. A suspended counter stays advertising, so relays run exactly as in daylight; HiveHub additionally declines to suspend a counter whose relay is unfinished.

Verification

Run locally, all green:

• firmware/host_test/run_tests.sh — 111 + 35 checks
• test_ruuvi_decode, test_beehive_decode, test_bee_counter_wire, test_night_mode (new)
• test_counter_rules, test_accel_rules, test_ble_sensor_rules, test_sd_import, test_data_export
• 38 pytest cases across test_tempcomp / test_hive_tempcomp / test_hiveheart_fft / test_relay_ota_gate / test_publish
• test_pairing_lifecycle --require-db against a real PostgreSQL 16
• node --check on every dashboard/website script

Also verified against a live PostgreSQL, beyond what CI covers: the config round-trip (defaults off, partial patch, config_version bump, pre-existing fields not shifted by the new columns), the CHECK constraints, and migration 025 applied to a pre-025 device_configs — twice, to prove idempotency, with the pre-existing row landing on night mode off.

Not verified here: the ESP32 firmware build. The sandbox blocks the PlatformIO registry, so firmware-build in CI is the first compile of the firmware changes.

Deploy order

This PR must ship before any counter running HiveTraffic#14, since HiveHub is what decides when to suspend and needs to understand idle_s first.

---

Generated by Claude Code