HiveHub V0.4 — in-hive nodes, over-the-air updates & data you can share 🐝

The fourth HiveHub release is about reach: reaching into the hive with a
proper wireless sensor node, reaching that node with firmware updates over the
air, and reaching out of the walled garden with backups and public charts.
Where V0.3 made the device flexible and robust, V0.4 makes the whole apiary —
hub, in-hive nodes and entrance counters — one system you can update, back up,
repair and publish from a single dashboard.

What is HiveHub?

HiveHub is an open-source, ESP32-based data collector for beehive sensors and
scales. One device gathers weight, temperature, humidity, sound, vibration,
entrance traffic, power state, and network state from up to 16 hives and sends
the readings to a self-hosted FastAPI + PostgreSQL backend, where they can be
viewed in HivePal or the built-in web
dashboard.

Highlights of this release

1. HiveInside is complete — including over-the-air updates

The in-hive sensor node is no longer a side project: HiveInside
is fully implemented, end to end, and shipping its own V0.1 release alongside
this one. HiveHub speaks to it at every level:

• Discovery & identity. HiveHub scans for nRF54LM20A HiveInside beacons
  (hiveinside_nrf54) and reads the board identity and firmware version
  straight out of the node's scan-response identity record — no connection, no
  configuration. The dashboard's Status card lists every in-hive sensor with the
  firmware it is actually running, and flags inline when a newer release exists.
• Firmware relay over BLE (OTA) — done. HiveInside has no WiFi, so HiveHub
  acts as the OTA relay: it streams the signed image from the backend
  straight into the node's GATT OTA service, chunk by chunk, without ever
  buffering the whole file. Nothing is committed on the node until size and
  CRC-32 verify, so a dropped transfer always leaves it on its old image.
  You pick a release in the dashboard, pick a node, and press go.
• Relay gating and targeting. The relay is gated on version (a node
  already on the target release is skipped) and can target any hive on the
  device, not just the first. Per-node relay state is visible in the dashboard
  while the transfer runs.
• Diagnostics that survive a sealed hive. A deployed node has no console, so
  the relay now surfaces the node's flash errno from the OTA STATUS read,
  and the hub-side crash that used to kill a relay mid-transfer was diagnosed and
  fixed. Firmware downloads are never gzipped, which was silently corrupting
  relayed images.

The same relay machinery now also carries HiveTraffic (BeeCounter) firmware
over BLE GATT, so entrance counters update the same way in-hive nodes do.

HiveInside is now nRF54LM20A-only. The deprecated ESP32-C6 HiveInside was
removed from firmware, backend (migration 020_drop_hiveinside_c6) and frontend.

2. Your data is yours — backup, restore, and publish

• Download / backup & restore measurement data. The dashboard can hand you
  every reading the server holds as a single NDJSON file and read it back in
  later — the same format the ESP32 writes to its SD card, so a backup feeds
  straight back through the existing Import SD card data path. Use it before
  re-deploying the stack, to migrate a beekeeper onto their own server, or to
  archive a device for analysis elsewhere. Admin-only, in the Admin section.
  See docs/backup-restore.md.
• Publish data — public chart embeds. An admin can publish a single chart
  under an unguessable link with no login, ready to <iframe> into a club
  page, blog or farm-shop site, with the same slice also available as JSON and
  CSV. ENABLE_PUBLIC_EMBEDS=false is a single server-side kill switch that
  404s every published link without deleting anything. Migration
  023_published_charts; see docs/publish-embed.md.

3. Pairing you can undo — and repair

Device pairing is now reversible and repairable. Previously, removing a
device in HivePal left it flagged as claimed with zero members: invisible to
everyone and impossible to re-claim, forever. Now the last member leaving
releases the device, there is an owner-only one-step release endpoint, the
claim endpoint distinguishes "no such code" (404) from "already claimed" (409),
and migration 022_release_orphaned_devices heals databases already stuck in
that state. On the firmware side a device notices it was un-paired on its next
upload and starts offering its claim code again by itself — re-pairing needs
no reflash and no factory reset. The dashboard also gained a real admin
Delete device (device plus its measurements, commands and config), guarded by
the claim code and a typed device ID.

4. Acoustics and vibration you can actually read

The Frequency-bands and Vibration pages were rebuilt around one shape: one
chart per hive, that hive's bands as the series, plotted over time — so a band
rising over a week and a one-day piping spike are both legible instead of
dissolving into a smear. Band labels now carry their Hz range
("Piping · 300–550 Hz"), the broadband vibration RMS sits in grey behind the
bands it totals, and Vibration got its own sidebar entry. The hive palette
was reordered for colour-vision accessibility (two hives that separated by
only ΔE 3.8 under deuteranopia now separate by ΔE 21.3, in both themes), and a
hive keeps its colour from the top-bar chip through every page.

5. Home Assistant discovery that matches the hardware

Each in-hive beacon now gets the entities it actually reports, announced per
entity as each field first arrives — instead of one fixed HolyIot-shaped list.
A HiveInside no longer gets a pressure entity it can never populate, and it does
get its cell voltage, firmware version and its on-board vibration and acoustic
FFT bands. HA discovery also reports the real in-hive sensor type per
beacon.

6. Commands, CI & reliability

• Commands recover instead of stalling. Abandoned commands are recovered
  (migration 021_device_command_attempts) and the 5-minute command poll is
  gone — a device that dies mid-command no longer wedges the queue.
• Flashable firmware images published from CI. The GitHub workflow now
  builds and publishes ready-to-flash images; the dashboard's upload form
  detects the target and version from the firmware filename, so a stamped
  HiveInside artifact uploads with nothing typed in.
• Field fixes. The NAU7802 front end is warmed before its AFE offset is
  captured (better scale calibration), sd_ok reports the real SD card
  state, the relay's locate scan no longer faults in esp_timer_stop(), relay
  CRC-32 is parsed unsigned, and dashboard tooltips stay inside the viewport.
• Tests. New end-to-end suites cover the claim/release lifecycle against a
  real PostgreSQL, data export, publishing, and the OTA relay version gate.

7. Wired BeeCounter retired

The wired I²C BeeCounter transport and its ingest fields are gone — entrance
counting is BLE-based (HiveTraffic) on all new builds.

Component versions in this release

Component	Version	Location	Status
ESP32-C6 Scale Module PCB	V0.4	pcb-design/scale module/esp32-c6/ (_V0_4-Scale_Module-.zip)	✅ Recommended — tested and working
NAU7802 breakout PCB	v0.2	pcb-design/NAU7802 breakout pcb/ (_v0_2_NAU7802_breakout_board-.zip)	✅ Recommended — tested and working
Power Module PCB	V0.3	pcb-design/power module/	⚠️ Works — being discontinued
ESP32 30-pin Scale Module PCB	V0.3	pcb-design/scale module/esp32 (30 pin)/	❌ Obsolete
HiveHub firmware	0.24.13	firmware/ (pio run -e xiao_esp32c6)	✅ Current
Server (backend)	0.4.0	server/ + docker/ (reported by GET /health)	✅ Current
HiveInside node (in-hive)	V0.1 / fw 0.4.7	MacNite/HiveInside — Seeed XIAO nRF54LM20A Sense	✅ Complete, incl. BLE OTA
Database schema	migrations through 023	server/migrations/	✅ Applied automatically

Recommended setup

1. Fabricate/assemble the ESP32-C6 Scale Module (V0.4) — off-the-shelf modules on pin headers, no SMD soldering for the core build.
2. Need more than 2 wired scales? Add the NAU7802 breakout PCB on the I2C expansion header (up to 16 scales).
3. Flash the firmware with pio run -e xiao_esp32c6 and configure everything from the on-device provisioning portal.
4. Stand up the backend with Docker Compose (docs/docker-install.md) and claim the device in HivePal or the built-in dashboard.
5. Add HiveInside V0.1 nodes inside the hives — they are found by passive scan, and from then on you update them over the air from the dashboard.
6. Optionally enable the MQTT / Home Assistant bridge, e-mail / Web Push alerts and public chart embeds.

See pcb-design/README.md for board details and the
main README for the full setup guide.

Upgrade notes

• Migrations 020–023 run automatically on first start of the new
  backend. 022 releases devices your database is already carrying in the
  orphaned "claimed with zero members" state; it touches no readings.
• ESP32-C6 HiveInside nodes are no longer supported. Replace them with
  nRF54LM20A HiveInside V0.1 nodes.
• Wired BeeCounter ingest fields were retired — move to BLE HiveTraffic.
• ENABLE_PUBLIC_EMBEDS defaults to true; set it to false if you do not
  want anyone on your server to be able to publish a chart.

Deprecation notes

• The ESP32 30-pin Scale Module (HX711/INMP441-based) is obsolete. Existing boards keep working and the esp32dev firmware target remains, but no further board revisions are planned — use the ESP32-C6 Scale Module for new builds.
• The separate Power Module is being discontinued: the C6 Scale Module carries its own buck-boost regulator and battery fuel gauge, so most builds can power it directly.
• The wired DS18B20 in-hive temperature stack is OFF by default, and the wired I²C BeeCounter transport has been removed — in-hive temperature and entrance counting are BLE-based on new builds.
• The ESP32-C6 HiveInside variant has been removed from firmware, backend and frontend.