Build your own HiveHub.

The power jumper

The 1×3 pin header on the Scale Module selects the power source. Set the jumper to the top position when powered from a battery (through the TPS63020 buck-boost) and to the bottom position when powered from a 5 V power supply. Never bridge all three pins.

Mux rule — where the NAU7802 goes

The NAU7802 has a fixed I2C address, so two of them can never share one bus. Dual-scale build: one NAU7802 on the main PCB, no mux. 3–16 scales: all NAU7802 modules (up to 8) go on the NAU7802 breakout PCB behind its TCA9548A mux — and no NAU7802 may be installed on the main PCB, or every read would collide with the muxed chips.

I2C pull-ups — avoid bus brownouts

Most I2C modules ship with their own pull-up resistors, and they add up in parallel: NAU7802, MAX17048 and mux modules generally carry 10 kΩ pull-ups, while RTC modules and wired SHT40 breakouts often carry 4.7 kΩ. Too many in parallel pull the bus so hard that the lines can no longer be driven low reliably — the bus "browns out" and devices drop off. Remove the 4.7 kΩ resistors from the RTC module and do not populate additional pull-ups on the PCB. The remaining module pull-ups are plenty.

Scales & sensors

Bolt two load cells per platform onto the aluminium U-profile and wire them to the NAU7802 screw terminals (E+, E−, A+, A−). Route the DS18B20 probe and the SP13 scale connectors through the enclosure wall, mount the SHT40 outside the box (shielded from rain and sun), install the IP65 button, and insert the RTC coin cell before closing up. Keep load-cell wiring away from the switching regulator.

Install the tools

Install VS Code, open its Extensions panel (Ctrl/Cmd+Shift+X), search for “PlatformIO IDE” and install it. Wait until PlatformIO finishes its first-time setup (status bar stops spinning), then restart VS Code.

Get the code & open the project

git clone https://github.com/MacNite/HiveHub.git

In VS Code: File → Open Folder… and select the HiveHub/firmware folder (the folder that contains platformio.ini — not the repository root). PlatformIO will detect the project and install the toolchain and libraries automatically on the first build.

Optional: pre-seed a config

You can flash completely unconfigured and do everything on the device's provisioning portal later (step 6). To pre-seed Wi-Fi, backend and hives instead, generate a secrets.h with the device config tool and save it as firmware/include/secrets.h (it is gitignored — never commit it).

Build & upload

Connect the XIAO ESP32-C6 via USB-C. In the PlatformIO toolbar (bottom status bar), pick the xiao_esp32c6 environment, then hit Upload (→ arrow). Or from a terminal:

cd HiveHub/firmware
pio run -e xiao_esp32c6 --target upload
pio device monitor   # serial log, 115200 baud

If the upload cannot find the port: hold the XIAO's BOOT button while plugging in USB, then retry. On Linux add yourself to the dialout group.

Verify

The serial monitor should show the boot banner, the antenna selection, the I2C devices it found and the first measurement cycle. Sensors you have not connected are simply reported as not present — nothing crashes.

Prerequisites

A host with Docker + the compose plugin installed, and — for devices in the field — a domain with HTTPS (the firmware verifies TLS; a reverse proxy with a Let's Encrypt certificate is the simplest setup).

Configure

git clone https://github.com/MacNite/HiveHub.git
cd HiveHub/docker
cp .env.example .env

Edit .env and set at least:

• API_KEY — master/admin key (openssl rand -hex 32)
• POSTGRES_PASSWORD — database password
• HIVEPAL_SERVICE_API_KEY / HIVEPAL_JWT_SECRET — only if you use HivePal
• PUBLIC_BASE_URL — your public HTTPS URL (used for OTA download links)
• ENABLE_LOCAL_DASHBOARD=true — for the built-in login-free dashboard
• volume paths for the database and firmware directories

Start it

docker compose up -d
docker compose logs -f api   # watch the first start

The API listens on port 31115. It auto-creates the database schema on first start — no manual migrations needed. Check http://<host>:31115/health and the interactive docs at /docs.

Expose it with HTTPS

Put a reverse proxy (Caddy, nginx, Traefik, NPM) in front of port 31115 with a valid certificate and point API_BASE_URL on the device at https://your-domain.example. NTP (UDP 123) must be reachable from the device's network so it can validate the certificate.

Detailed guides: docker-install.md · truenas-install.md

Watch the data

Built-in dashboard (no account): open http://<host>:31115/dashboard — charts, device config, OTA and calibration (demo). HivePal: claim the device by its claim code for accounts, sharing and mobile access.

Open the provisioning portal

Short-press the setup button. The device opens the HiveHub-Setup-XXXX Wi-Fi access point — connect to it and the portal appears (or open http://192.168.4.1). Set Wi-Fi credentials, the backend URL and API key, then add your hives: the portal auto-detects every NAU7802 channel and DS18B20 probe and lets you pair BLE in-hive sensors per hive. Settings persist on the device and survive OTA updates.

Calibrate each scale (tare + known weight)

1. In the portal, open Scale calibration — every configured channel shows its live reading.
2. With the platform empty, press Tare (zero).
3. Place a known weight (a 10–20 kg dumbbell plate or a canister of water you weighed on a kitchen scale works well — the heavier, the more accurate), type its mass in kg and press Set weight.
4. Verify: remove the weight (reading returns to ~0.00 kg), put it back (reading shows the known mass). Each change is saved to the device immediately and reported to the backend on the next upload.

Calibrate after final mechanical assembly — bolting the frame onto the hive stand changes the zero point. Re-tare at the start of the season. Remote recalibration later works from the dashboard/HivePal without a site visit (calibration mode).

Done — first data

Reboot out of the portal (“Save and reboot”). The device connects to your Wi-Fi, uploads its first measurement with its claim code, and shows up in the dashboard. From here on it wakes on its interval, measures, uploads and deep-sleeps.