critter-bridge — cloud IoT for standalone boards

critter-bridge is a small companion app that runs on a PC, Raspberry Pi or any always-on device on your LAN. It pulls state from your Firefly boards and pushes it to free cloud IoT services (ThingSpeak first; Adafruit IO, InfluxDB Cloud and others on the roadmap) and to Telegram — things an ESP8266 cannot do reliably on its own.

Who needs it

  • ESP8266 users who want remote visibility (ThingSpeak charts, Telegram alerts) without Home Assistant.
  • ESP32 users who prefer a centralised setup: secrets live on the bridge, not on the board.

If you already run Home Assistant, you don't need the bridge — keep using HA's MQTT integration. If you have a single ESP32 board and no always-on device, use ESP32 direct cloud mode instead.

How it works

  • Pull-only, zero firmware changes. The bridge polls each board's existing /api/dashboard endpoint every 15–30 s. No tokens, no firmware updates, no board-side code.
  • ThingSpeak (first backend). Forwards panel values to a ThingSpeak channel (one board = one channel by default, so multiple boards never contend for the free-tier ~15 s update cadence).
  • Rules → Telegram. Panel-state conditions (threshold, hysteresis, per-rule cooldown) trigger Telegram messages. Credentials live only on the bridge.
  • Local web UI on port 8787 for board registry, ThingSpeak field mapping, rules, settings and an event log.

Quick start

git clone https://github.com/mfacen/critter-bridge
cd critter-bridge
./run.sh          # creates the Python venv on first run
# open http://localhost:8787

Requirements: Python 3.9+. The app creates config.json on first run; boards are auto-discovered from their UDP beacon, so you rarely need to type an IP.

Design notes

  • Trusted LAN. Traffic between the bridge and boards is plaintext HTTP, matching critterOS's hobbyist stance. Do not expose the board or the bridge beyond your LAN.
  • Polling wakes the OLED. /api/dashboard counts as a viewer in critterOS, so a polled board keeps its display awake.
  • Secrets stay on the bridge. ThingSpeak keys and Telegram tokens never reach a board.

Source

critter-bridge is a separate repository: github.com/mfacen/critter-bridge.