# HiveHub V0.7 — sign in once, trust the numbers 🐝

V0.6 gave the hub a way to listen to a hive. V0.7 is mostly about making sure
what the hub reports is true: a full codebase audit ran across firmware,
server and dashboard, and many of its fixes are for failures that happened
without any error message. Examples: alerts for hives 3–18 were thrown
away, HiveInside acoustics never reached the insight engine, a "verified"
recording could be missing half its bytes, and sensors at the end of a long
pairing list were never read.

New features arrive alongside the fixes: single sign-on through
authentik / OpenID Connect, a HivePal app API that covers what the local
dashboard can do, automatic recording gain for HiveInside audio, an
optional external setup button, and full support for HiveTraffic
maintenance mode.

---

✨ New features

Single sign-on for the dashboard (authentik / OIDC)

The dashboard can now sign users in through an OpenID Connect provider
(authentik by default). The backend runs the Authorization Code flow with PKCE
as a confidential client and validates the ID token against the provider's
JWKS. It then issues the usual HttpOnly session cookie, so no provider token
reaches the browser.

• Users are matched to existing dashboard accounts by e-mail
  (case-insensitive). The role always comes from the local account. Unknown
  or duplicated addresses are refused.
• email_verified is required by default (OIDC_REQUIRE_EMAIL_VERIFIED).
• Signing out of an SSO session also signs you out at the provider.
• Admins can create SSO-only accounts (no password, e-mail required).
• OIDC_DISABLE_PASSWORD_LOGIN=true makes the dashboard SSO-only. It only
  takes effect while SSO is fully configured, so it cannot lock everybody out.
• Works behind Cloudflare: the backend now sends its own User-Agent, which
  Cloudflare's Browser Integrity Check accepts.

Configuration: OIDC_* environment variables, documented in
docs/sso-authentik.md.

HivePal app API

HivePal can now do most of what the local dashboard can:

• Hive links: per-hive names and HivePal hive IDs, so a hive slot stays
  linked to its HivePal hive after a rename (migration 031).
• Relay status: firmware status now includes the latest HiveInside and
  HiveTraffic versions and the relay status of each slot.
• Remote AP mode: POST /app/devices/{id}/provisioning/start.
• Export: NDJSON backup through GET /app/devices/{id}/export/measurements[/summary].
• Range delete: POST /app/devices/{id}/measurements/delete (owner only,
  requires the claim code).

The mock server accepts HivePal bearer tokens and honours max_points, so
HivePal can be developed against it.

Automatic recording gain for hive audio

At a fixed 0 dB gain a hive was close to inaudible. Recordings now default to
Auto. A HiveInside on firmware 0.8.0+ measures a short pre-roll and
picks one gain for the whole clip. The gain it applied is stored with the
recording (migration 035) and shown in the dashboard. Fixed gains from
−20 to +40 dB are still available in the new Gain selector.

Older HiveInside nodes treat Auto as a fixed +20 dB, which still gives a
usable recording.

HiveTraffic: maintenance mode and smarter polling

• Maintenance intervals (HiveTraffic protocol v6). While a counter is on
  the bench in maintenance mode its totals are frozen. The hub now passes
  maint_s through to the server. These intervals are shaded as
  "Counter maintenance" in the traffic chart, and insights skip them, so a
  bench test no longer looks like a quiet day at the hive.
• "Not polled" instead of "Fault". With more counters than the per-wake
  read budget, a counter that wasn't due for a read this wake used to show as
  faulty. It now shows "Not polled" with the age of its last reading, and the
  counter cards keep the last known totals.
• MQTT / Home Assistant now publishes the derived interval_in/out
  values for bee counters. Before this release those entities were announced
  but never received a value.
• Web configurator can now combine sensors on one hive: one entry for
  each lane (climate beacon or DS18B20, bee counter, HiveHeart). Setups like
  a HiveTraffic counter next to a HiveInside can now be generated.
• HiveTraffic firmware can now be registered through the JSON
  POST /api/v1/firmware/releases endpoint as well as the upload form.

Optional external setup button (XIAO ESP32-C6)

With #define ENABLE_EXTERNAL_SETUP_BUTTON 1 in secrets.h, a push-button
between D0 and GND opens the provisioning AP. Unlike the on-board
USER/BOOT button it:

• wakes the hub from deep sleep and opens the AP straight away;
• is not a strapping pin, so holding it at power-up boots normally.

Factory reset stays on the USER button. The Scale Module PCB V0.5 design
files add the pads for this second button.

More of the data the hub already collects

• Barometric pressure from a BME280 on the hub (ambient_pressure_hpa)
  and sht_detected used to be dropped at ingest. They are now stored
  (migration 034). The Environment view uses the best pressure source it
  can find (hub sensor, then any in-hive beacon or HiveScale, including
  hives 3–18) and shows which one it used.
• HiveInside peak values (beacon frame v2: acceleration peak and mic
  peak) are now decoded and fill the existing "Peak level" charts.
• RuuviTag: battery voltage, TX power, movement counter, sequence number
  and data format are now forwarded.
• Accurate daily max/min weight. The Weight view used to compute daily
  max/min from thinned chart data and missed peaks. A new endpoint
  (/measurements/daily-weight) computes them from every reading, for ranges
  of 30 days and longer.

A dashboard that tells you more

• Status rows are named after the node and the hive (for example
  "In-hive sensor · shire-01"), cover all hives (1–18), and explain a fault:
  what failed, what data is missing because of it, and when the node was last
  heard. HiveTraffic status bits are decoded where the protocol documents
  them.
• Stale data is marked. Cards from an offline hub are greyed out and show
  their age, and every time-series view lists hubs whose last upload is
  overdue.
• Auto-refresh no longer wipes half-typed forms (calibration, hive names,
  inspection notes, passwords). It waits until you finish editing.
• Recording diagnostics. A failed audio session reports the actual reason,
  including hub heap figures. Hub buffer drops are shown separately from
  radio gaps. Every recording shows whether the upload arrived intact.
• Local time and hemisphere for insights. Rule windows and calendar days
  now use the site's local time: the device's night-mode preset, else
  INSIGHTS_TIMEZONE, else TZ. INSIGHTS_HEMISPHERE=south shifts the
  seasons.

---

🐛 Bugfixes

Insights and alerts

• No alerts were raised for hives 3–18. Every alert for those hives
  failed validation and was discarded without a log line. This is fixed, and
  any alert the engine has to drop is now logged.
• HiveInside acoustics never reached the insight engine. The piping, hum
  and stress evidence used by the pre-swarm, queenlessness and robbing
  detectors did nothing on HiveInside setups. Hives 3–18 were also given
  hive 2's microphone data.
• Inspections and calibration no longer trigger false alerts. Lifting a
  super during an inspection could raise a critical swarm alert. Weight after
  an inspection is now joined onto the level before it. In-hive temperature
  is ignored for 30 minutes afterwards while the brood nest settles.
• Rules need enough data to cover their time window. Previously, eight
  readings over seven minutes could produce "24 h hive temp held at 35 °C".
• Bee-counter rates use the actual elapsed time. One missed poll could
  double a rate. Daily totals now split an interval that spans midnight
  between the two days.
• Acoustic evidence must be fresh. A 13-day-old stress band could upgrade
  a current robbing alert. Bands now come from the newest reading that has
  them, at most 3 h old.
• Coverage changes. Traffic is only compared while counter coverage stays
  the same (same counter, banks and expanders). A replaced counter is no
  longer read as a reboot.

Bee counter (HiveTraffic) data

• Counter restarts are detected from uptime as well as totals, so a
  counter that rebooted and counted past its old total is no longer
  under-counted.
• Interval counts are kept separately per device, and a new counter MAC
  starts a fresh baseline.
• The nested hives[].bee_counter.interval_* values are now filled too. They
  used to be null while the flat fields had values.
• Night mode: turning night mode off now releases counters that are still
  idling. Idle durations now match how often each counter is actually read, so
  counters at the back of a long rotation no longer miss half of each gap.

Silent data loss

• GATT sensors beyond the per-wake read budget were never read. Both read
  loops (HiveTraffic counters and HiveHeart/HiveScale) now take turns, so
  every sensor is read at least once every ceil(n / budget) wakes.
• SD retry queue: a failed or short write while compacting the queue
  could replace it with a truncated file. The old queue is now kept.
• SD / bulk import removes duplicates by measurement_id, like live
  ingest. Lines recorded without a valid clock no longer abort the import.
• A timestamp without a UTC offset is read as UTC instead of causing an
  HTTP 500.

Hive audio (especially on the 30-pin ESP32)

• The hub no longer resets mid-recording. A race between the BLE task and
  the upload loop could write to freed memory during teardown.
• Fewer seams in recordings. NimBLE's buffer pool was too small, and each
  upload chunk used three TLS records instead of one.
• Successful recordings are no longer reported as "HTTP 0". A timeout
  unit error gave the status-line read 15 ms. The session loop and final drain
  now have proper time limits.
• The 30-pin ESP32 can start the radio for a recording. Allocation order
  and heap peaks were reworked, and the measurement document is freed before
  commands run.
• Scheduling a recording no longer fails with a 500 error. Two columns
  from migration 030 were missing from the database setup code (init_db).
• Late pickups no longer fail. The streaming timeout was counted from the
  request time instead of the start of the upload, so a hub that woke late had
  its session marked "no audio arrived".
• "Verified" now means the file on disk was checked. The server computes
  its own CRC-32 of the stored audio (migration 036) and compares it, and
  the byte count, with what the hub reported. Truncated uploads are flagged.
• The OTA relay fails the command cleanly when BLE resources run out instead
  of crashing the hub. An audio-only build now compiles. Wired INMP441
  microphones are now handled per hive: a HiveInside on hive 1 no longer
  disables hive 2's wired microphone.

Firmware and time

• An RTC that lost power is set from NTP. Whether the RTC is present is now
  tracked separately from whether its time is valid (rtcTimeValid).
• The fallback timestamp no longer labels local time with a "Z" once night
  mode has set a time zone.
• HiveInside no longer reports made-up capture diagnostics
  ("0 Hz · 1 samples · ±2 g").

Server and dashboard

• Version ordering follows SemVer, so 1.2.3-rc1 no longer counts as
  newer than 1.2.4 in OTA offers.
• After an upgrade, browsers load the new dashboard JS/CSS instead of keeping
  the old version cached for an hour.
• MQTT now publishes the acoustic peak, and the Home Assistant vibration-peak
  entity is no longer retracted for HiveInside.
• HiveInside battery, board, device name and MAC now appear in API responses.

---

🔒 Security

• Upload routes check authentication before reading the body. An
  unauthenticated client could make the server buffer a large SD, JSON or
  firmware upload before getting its 401. Those routes now have their own
  size limits.
• Dashboard sessions can be revoked. Deleting an account or changing its
  password now ends its existing sessions (migration 033). Current sessions
  stay valid through the upgrade.
• Dependency upgrades: FastAPI 0.142.4, Starlette 1.7.0 and
  python-multipart 0.0.32, which fix the Range-header DoS and multipart
  advisories. python-jose (unfixed advisories) is replaced by PyJWT.
• The connection pool can no longer be exhausted by a burst of chart
  requests (dashboard and public embeds).

---

Component versions

Component	Version
HiveHub release	V0.7
Firmware	0.33.1 (was 0.30.0)
Server/backend	0.7.1 (was 0.5.1)
Database schema	migrations through 036
HiveInside node	0.6.2+ works · 0.8.0+ for automatic gain
HiveTraffic counter	0.5.0+ (protocol v6) for maintenance intervals
Recommended hardware	XIAO ESP32-C6 Scale Module V0.4 · V0.5 design files added (D0 setup-button pads)
Max hives per hub	18 (docs said 16 in a few places — corrected)

Before upgrading

1. Migrations 030–036 run automatically on startup. Nothing to run by
   hand. If you set up the database from scratch on 0.5.2, it is repaired as
   well.
2. Recordings stored before this release show as "unverified" instead of
   "verified", because they have no server-side checksum. The audio is
   unchanged and still plays.
3. New optional environment variables: OIDC_* (SSO), INSIGHTS_TIMEZONE,
   INSIGHTS_HEMISPHERE. Without them, behaviour is unchanged, except that
   insights now use the device's night-mode zone or TZ instead of UTC.
4. HiveInside 0.8.0 band values are 1.76 dB lower (window normalisation
   fix in HiveInside). Acoustic insights see a one-off step when a node is
   updated.
5. If you use the external D0 setup button, set
   ENABLE_EXTERNAL_SETUP_BUTTON 1 in secrets.h. It is off by default.

Full details: Single sign-on ·
Insights · API reference ·
Listening to a hive