The Insights module turns the time-series your HiveHub already records — weight, hive temperature, ambient conditions, in-hive sound, entrance traffic and comb vibration — into a ranked list of plain-language alerts. Twelve rule-based detectors, each watching one colony behaviour, computed independently for every hive (up to 16 per ESP32).
Insights are computed in server/insights.py — pure Python, no database
access — and served from /api/v1/devices/{id}/insights. HivePal renders
them in the HiveScale → Insights card and caches them for five minutes.
Every alert traces back to one detector function and one documented threshold — no black box. You can read exactly why it fired.
Each call compares recent readings against a rolling baseline. The window is configurable with the lookback_days query parameter.
Every detector runs separately for scale 1 and scale 2, so two colonies on one device are assessed independently.
A flat list of alerts sorted by severity then time. Each carries a category, a confidence score and a human-readable description.
Every alert is tagged with one of four levels. HivePal uses them to colour-code the
alert rows and the per-hive badge on the latest-value panel — which always shows the
highest active severity (critical > warning > watch > info).
Informational classification — no action required.
A trend worth monitoring — inspect on your next routine visit.
Something is happening now — investigate within hours.
An acute event — immediate attention recommended.
A single detector can change level with context — a swarm departure is critical during the day but warning at night.
Twelve detectors, each a single function in insights.py with one documented
rule. They are grouped here by what they watch for; the number matches the reference doc.
Thermoregulation loosens hours-to-days before a swarm. Tells you: inspect for queen cells in the next 24–48 h.
In the final ~10–30 minutes the cluster gathers near the entrance and the upper hive spikes. Tells you: a swarm may leave within the half hour — ready a swarm box.
A departing swarm takes 50–70% of the adult bees in minutes — a near-step drop on the scale. Tells you: a swarm has very likely just left; check the hive.
A ~20 Hz comb vibration builds in the days-to-weeks before swarming and is clearest at night — below what hive microphones can hear. Tells you: plan swarm control.
A low-rate beacon (HolyIot / RuuviTag) can't compute the FFT band, so this trends its coarse night-time movement instead — deliberately lower confidence.
Without a queen, brood rearing stops, thermoregulation loosens and the weight curve stalls in season. Tells you: inspect for eggs and brood; plan a queen introduction.
Brood needs tight thermoregulation, so a narrow band around 34–35 °C confirms active rearing. Tells you: a quick health check — a watch warrants an inspection.
A robbed hive loses honey far faster than normal foraging swings. Tells you: reduce the entrance, or close / move the colony if it is sustained.
Daily weight delta is the classic nectar-flow proxy. Tells you: strong flow → consider a super; a negative delta → check for dearth, disease, robbing or queen problems.
Honey flows climb fast then plateau; harvesting at the top of the plateau maximises yield. Tells you: the flow looks finished — supers may be ready. Confirm by inspection.
A colony in slow decline bleeds weight while its thermoregulation deteriorates. Tells you: inspect within the next routine cycle for disease, queen status and stressors.
A strong cluster stays well above ambient and burns stores predictably. Tells you: verify food on the next mild day; consider emergency fondant.
Weight and hive temperature are the always-present base signals. Every other input is optional — when a sensor is fitted it raises confidence or promotes severity; when it is absent the detector quietly falls back to its weight/temperature rule. No detector ever requires an optional sensor.
Piping / tooting confirms pre-swarm, an agitated spectrum supports robbing, and the acoustic signature supports queenlessness. Integrated.
Asymmetric outflow confirms swarming, incoming spikes flag robbing, and forager decline supports queenlessness, absconding and winter checks. Integrated.
The ~20 Hz night-time comb signal microphones can't reach — fires the standalone pre-swarm detectors and boosts the temperature watch. Integrated.
The thresholds are starting values calibrated against a project spec and the public research below. A one-paragraph TL;DR of each lives in insights-sources-tldr.md.
Honeybee Democracy. The behavioural basis — swarming is a deliberate, days-long preparation, not a sudden event.
A persistent temperature rise above the brood nest precedes swarming — the basis for the pre-swarm temperature detectors.
Within-day hive-weight variation as a measure of colony activity — the day/night weight-delta foraging method.
A multi-sensor benchmark (weight + in-hive temp + entrance traffic) — the closest match to the HiveHub stack for validation.
53 hives, one year of audio + temperature + humidity — validation for the temperature-only queenlessness fallback.
A rising ~20 Hz night-time comb vibration predicted > 90% of swarms and never misfired — the basis for the vibration detector.
Comb vibration diverges from baseline days ahead of swarming — justifies a trend / baseline comparison over a fixed threshold.
A review recommending a low-frequency accelerometer to capture the ~20 Hz signal microphones miss — why HiveHub added one.
All thresholds are constants near the top of server/insights.py. The defaults
are sensible starting points — re-tune them against your own history, especially the
swarm-drop weight, the winter consumption rate and the foraging deltas, which all depend
on box size, climate and regional flow strength.
SWARM_WEIGHT_DROP_KG = 1.5 SWARM_WEIGHT_WINDOW_MIN = 30 PRE_SWARM_STD_MULTIPLIER = 1.5 ROBBING_WEIGHT_LOSS_KG_PER_HOUR = 0.4 QUEENLESS_TEMP_STDDEV_C = 1.0 WINTER_WEIGHT_LOSS_G_PER_WEEK = 300 HARVEST_FLOW_KG_PER_WEEK = 2.0 # … plus the per-sensor fusion thresholds
Planned: expose these per device via /api/v1/devices/{id}/config so you can
tune without redeploying the backend.
The authoritative detector catalogue with every threshold and source.
The ~20 Hz pre-swarm vibration signal and the hardware behind detectors 11 & 12.