devprincekumar/sense-hive repository overview

⁠SenseHive

Lightweight, self-hosted MQTT data logger and dashboard. Run → Add Topic → Publish → See Data.

SenseHive subscribes to the MQTT topics you add, logs every message to SQLite 24/7 (with or without the dashboard open) and shows live values, history and device status in a clean web UI.

• Source, docs and issues: https://github.com/855princekumar/sense-hive⁠
• Home Assistant add-on: https://github.com/855princekumar/sensehive-ha-addon⁠
• pip package: pip install sensehive-iot

⁠Quick start

docker run -d --name sense-hive \
  -p 5000:5000 \
  -v $(pwd)/sensehive-data:/app/data \
  --restart unless-stopped \
  devprincekumar/sense-hive:latest

Open http://localhost:5000⁠ and sign in as admin with SENSEHIVE_ADMIN_PASSWORD if you set it, otherwise admin123 (change it under Settings → Account). The default broker is the public broker.hivemq.com; change it under Settings.

⁠Tags

One image runs on x86-64 servers and on ARM64 boards (Raspberry Pi 4/5, Jetson, Apple Silicon). Docker picks the right architecture automatically.

⁠Features

⁠What's new in 1.8.2

• The emulated fleet is in the image: docker exec sensehive python demo_fleet.py --broker HOST --register http://127.0.0.1:5000 fills the dashboard with devices and their last wills.
• A step-by-step quick start with real output and screenshots: https://github.com/855princekumar/sense-hive/blob/main/docs/QUICKSTART.md⁠

⁠What's new in 1.8.1

• sensehive-demo, an emulated fleet to try SenseHive with; the quick start (pip and Docker) is tested end to end with a broker and a browser in CI.
• Inside Home Assistant the page has no Sign out button; long topics wrap after a slash.
• React 19 bundled locally; Flask 3.1.3, cryptography 50, paho-mqtt 2.1+, Python 3.14.

⁠What's new in 1.8.0

• Add a heartbeat node without EdgeShell: Heartbeats, Add node, a join token; on the node git clone the agent and sudo python3 setup.py, and it appears by itself
• Many nodes: up to 500 tokens as a CSV for the agent's bulk SSH tool; HEARTBEAT_BROKER_USERNAME / HEARTBEAT_BROKER_PASSWORD for a broker with logins
• HEARTBEAT_MASTER_KEY=auto: every SenseHive its own private fleet; nodes of other SenseHives on the same broker never appear
• Tested without hardware: PowerPulse firmware on a simulated ESP32 and the heartbeat agent on a systemd node, in CI

⁠What's new in 1.7.0

• Secure topics: encrypted and signed per topic with keys SenseHive issues; devices publish under sensehive/secure/... and their topics appear by themselves. Bulk keys with CSV, keys bound on first use, unused keys expire, show again with the password, revoke
• Device code for Python, MicroPython, Node.js and Node-RED, and ESP32
• Heartbeat recycle bin: hide retired nodes, restore, delete for good, see when one comes back
• Guide: https://github.com/855princekumar/sense-hive/blob/main/docs/SECURE-TOPICS.md⁠

⁠Minimum requirements

1 core (ARMv8 64-bit or x86-64), 128 MB free memory (uses about 28 MB idle), 200 MB disk plus data, Docker 20.10+, a reachable MQTT broker, a correct clock (NTP).

⁠What's new in 1.6.1

• Heartbeat history always shows an outage that is still going on: how long an offline or silent node has been down since its last heartbeat, also when that was before the chosen range, on every range

⁠What's new in 1.6.0

• An (i) guide on the Topic logs and Heartbeats cards: what each view is for and how to use it
• Filter topics and heartbeat nodes by status (online, offline, silent or no last will)
• A secure deployment guide: one domain on 443 through a TLS proxy, the app's port never exposed

⁠What's new in 1.5.0

• Heartbeat history: every heartbeat kept (48 h), per-node charts for 1 minute to 30 days with breaks, CSV export for one, selected or all nodes
• Two cards on the dashboard switch between Topic logs and Heartbeats with a smooth fade; dialogs always fit the screen
• Hardened against hostile input: payload size cap, flood limit per node, API token lockout, CSV formula escaping, request size limit, more security headers

⁠What's new in 1.4.0

• EdgeShell's look (light by default, dark remembered), a layout that fits phones to desktops at 67 to 200 % zoom, a Heartbeats link in the top bar
• Browser code served by SenseHive itself under a strict Content Security Policy (no CDN), SQL-safe topic names, no default password on the sign-in page
• Browser UI test, ruff, Bandit and pip-audit in CI; full documentation at https://github.com/855princekumar/sense-hive/tree/main/docs⁠

⁠What's new in 1.3.0

• Sign-in hardening: salted password hashes (old ones upgraded automatically), lockout after repeated failures, a new session on each sign-in, cross-site changes refused, configurable cookie flags, SENSEHIVE_ADMIN_PASSWORD for the first password

⁠What's new in 1.2.0

• Heartbeat receiver (off by default): verifies encrypted heartbeats from edge nodes, per-node online/offline/silent state, /heartbeats page, read-only API with a bearer token. See the README

⁠What's new in 1.1.0

• Topic stats, tags, node grouping and LWT device status
• Data retention and SQLite WAL mode
• Wildcard topics are now logged
• JSON arrays and long values no longer overflow the cards
• Live updates reach every open browser tab
• Multi-arch image (amd64 + arm64); paho-mqtt 2.x support
• Home Assistant ingress support (used by the add-on)
• No development database shipped in the image
• v1.0 databases are migrated automatically. Keep your existing /app/data volume.

⁠Docker Compose

services:
  sense-hive:
    image: devprincekumar/sense-hive:latest
    container_name: sense-hive
    ports:
      - "5000:5000"
    volumes:
      - ./sensehive-data:/app/data
    environment:
      DEFAULT_BROKER_HOST: broker.hivemq.com   # first start only
      DEFAULT_TIMEZONE: UTC
    restart: unless-stopped

⁠Environment variables

⁠Home Assistant

HAOS / Supervised users can install the add-on in one click: it opens in the sidebar, connects to the Mosquitto add-on automatically and stores data in Home Assistant backups. See https://github.com/855princekumar/sensehive-ha-addon⁠

⁠Quality

Every image is built by CI after the full regression suite passes (73 tests on Python 3.9 to 3.13, including an end-to-end run against a real Mosquitto broker), plus a container health check and a pip package smoke test.