HiveHub is an ESP32-based data collector for beehive sensors and scales. It tracks weight, temperature, humidity, in-hive sound and vibration, and power state for up to 16 hives per ESP32, and sends everything to your own FastAPI + PostgreSQL backend.
Up to 16 hives per ESP32. Every sensor below is optional and compiled in per device — start with weight and add the rest as you build.
NAU7802 load-cell channels (I2C, with an optional TCA9548A mux on the breakout PCB) give each colony its own scale — up to 16 hives per ESP32.
DS18B20 probes on a shared 1-Wire bus, or an in-hive BLE sensor as an alternative source.
Stereo INMP441 I2S microphones with per-band FFT energy to catch piping and stress.
An in-hive BLE sensor (e.g. HiveInside) captures the ~20 Hz pre-swarm signal microphones miss.
A selectable I2C sensor records weather context alongside the hive readings: SHT4x (default), SHT3x, or a BME280 that also adds barometric pressure.
Optional MAX17048 LiPo fuel-gauge data (voltage, state-of-charge, alerts) for unattended deployments.
Pair any BLE-Sensor (in-hive or BLE-Scale) — no extra wiring. See supported devices or request support for new devices
Local buffering when uploads fail, plus an append-only persistent measurement backup.
Optional entrance traffic counting of incoming and outgoing bees over BLE/GATT.
Claim devices from HivePal without touching the database — just a pairing code.
Over-the-air updates, remote calibration, reboot, Wi-Fi reset and config versioning.
The backend auto-evaluates weight, temperature, sound and vibration into colony insights.
An optional, login-free web dashboard served straight from the backend — charts, status, device configuration and OTA/calibration controls. Try the demo →
A mains-or-solar ESP32 board plus off-the-shelf modules on pin headers — no SMD soldering required for the core build. All published PCBs are tested and working.
Seeed XIAO ESP32-C6 on the Scale Module V0.4 with off-the-shelf modules on pin headers: NAU7802 load-cell ADC · MAX17048 battery gauge · TPS63020 buck-boost · TP4056 USB-C charger · DS3231 RTC · microSD · SHT40 · DS18B20 probes · setup button · BLE in-hive sensors.
The NAU7802 breakout PCB adds a TCA9548A I2C mux with up to 8× NAU7802 — 16 scales in total per HiveHub.
CN3791 MPPT solar charger · 6 V solar panel · LiPo or 18650 pack — the MAX17048 reports the battery state with every measurement.
The full build guide with BOM, prices, wiring and setup lives on the Build your own page; pin maps are in docs/wiring.md.
Five steps from clone to live data. The firmware is a PlatformIO project; the backend is a Docker Compose stack. Building the hardware too? Start with the full build guide.
Clone the repository and open the firmware project in PlatformIO (VS Code extension or CLI).
git clone https://github.com/MacNite/HiveHub.git cd HiveHub
Bring up the FastAPI + PostgreSQL stack with Docker Compose. The API listens on port 31115.
cd docker cp .env.example .env # edit API_KEY, HIVEPAL_SERVICE_API_KEY, DB password, volumes docker compose up -d
See docker-install.md or truenas-install.md for hosting details.
Recommended: configure the device from its on-device provisioning portal. After flashing, hold the setup button to start the HiveHub Wi-Fi access point, connect to it, and set Wi-Fi, backend, hives and sensors right on the device. Those settings live in the device's storage and survive OTA updates.
Optionally pre-seed a brand-new device before first boot with the in-browser
config tool (it generates an optional secrets.h) — or skip it and
pair everything from the portal.
Manual route: cp firmware/include/secrets.example.h firmware/include/secrets.h and edit it.
Drop your secrets.h into firmware/include/, then build and upload.
cd firmware pio run --target upload pio device monitor # 115200 baud
On first boot the device sends measurements with its claim code. Two ways to watch it:
Built-in dashboard (no account): set ENABLE_LOCAL_DASHBOARD=true
and open http://<your-host>:31115/dashboard — a login-free web UI with
charts, status, OTA and calibration for a single-owner self-host
(see the live demo).
HivePal (multi-user app): claim the device from
HivePal with
POST /api/v1/app/devices/claim for accounts, sharing and mobile access.
Field configuration without reflashing: press the setup button to open the
HiveHub-Setup-XXXX Wi-Fi provisioning portal at http://192.168.4.1.
The login-free web dashboard served from the backend — how to enable and use it.
Per-hive vibration monitoring and the ~20 Hz swarm signal, from an in-hive BLE sensor.
LiPo (MAX17048) power-telemetry behaviour and the wake/deep-sleep cycle.
Get your wireless device added — request support as a GitHub issue and capture the data with nRF Connect.