Getting started

  1. Flash critterOS — open the critterOS Uploader page in Chrome/Edge, plug the board in over USB, click Connect, and choose Flash firmware + filesystem — the firmware files are bundled into the page, nothing to download.
  2. Connect to WiFi — on first boot the board creates its own firefly WiFi network. Join it, open http://192.168.4.1 in your browser to see the critterOS dashboard, go to Settings, enter your WiFi credentials and restart the board. Then reconnect to your own WiFi and open http://firefly.local.
  3. Connect sensors and create panels and automations — follow the creating panels guide to add sensors and create panels.

Flashing options

MethodWhat you needLink
Web uploader (recommended)Chrome/Edge + USB cablecritterOS Uploader
USB bundle (ESP8266)Python + esptoolfirefly-usb-esp8266.zip
USB bundle (ESP32)Python + esptoolfirefly-usb-esp32.zip

Guides and reference

DocumentDescription
Board API referenceEvery HTTP endpoint and MQTT topic
Supported sensors & actuatorsEvery panel driver built into critterOS
How Firefly comparesFeature comparison with Tasmota, ESPHome, ESP Easy and other IoT platforms
Connecting to WiFiNetwork setup guide
Adding Sensors and Creating PanelsPanel creation guide
Panels DocumentationHow to use each panel type (timer, flow control, dispenser, etc.)
Automation & ProgramsScripting guide: IF/THEN rules, programs, variables, examples
Home Assistant integrationMQTT auto-discovery setup
Tasmota integrationUsing Firefly alongside Tasmota
Mini Relay ModuleAdding a 2-channel relay board
Third-party licensesLicense attributions

AI-assisted setup

  • New here? Paste the setup prompt into your AI assistant — it will walk you through flashing to first sensor.
  • Describe what you want automated and have it write you a backup file to restore.

Companion tools

  • critter-bridge — companion app for cloud IoT (ThingSpeak, Telegram) on ESP8266 and standalone ESP32 setups.

Supported hardware

The reference board is a Wemos D1 Mini (ESP8266, 4 MB flash) — every feature is developed and tested on it. Any ESP8266 board with 4 MB flash and the pins your panels need works the same way: build with pio run -e d1_mini.

ESP32 (D1-mini-footprint boards, e.g. node32s) builds from the same source with pio run -e node32s. See the ESP32 page for GPIO notes, flashing instructions, and ESP32-only direct cloud features. The D1-mini ESP32 keeps the same GPIO numbers behind the D labels as the ESP8266 (D1=GPIO5, D3=GPIO0, D4=GPIO2, D8=GPIO15…), so panels and shields carry over — the dashboard pin picker shows D labels first, then the bonus inner-row pins. A0 is GPIO36; for analog prefer A0 or GPIO32/33/34/35/39 (ADC1, unaffected by WiFi). Warning: clone boards vary — some map D labels to different GPIOs, and GPIO0/2/5/12/15 strap the boot while 34/35/36/39 are input-only, so check your board’s silkscreen before wiring relays or buttons to them. Flash over USB with the critterOS Uploader (ESP32 button) or with PlatformIO.

Hardware & wiring notes

A few wiring facts worth knowing before you hook up sensors (learned the hard way):

  • HC-SR04 ultrasonic sensor: power it from 5 V (the D1 mini VU pin), not 3.3 V, and always divide its Echo output down to ~3.3 V with a resistor divider — the ESP8266 GPIOs are not 5 V tolerant. D0 (GPIO16) cannot be used as the echo pin.
  • Active-low outputs: most relay boards energize on LOW. Firefly’s global active_low setting (default on) means ON always means “energized” in the dashboard, rules and MQTT — the physical pin level is handled for you. Output panels (digital_out, pwm) also have a per-panel Active low / inverted toggle for devices wired opposite to the board/global polarity (logical 0/100% or 0/1 stays the same while the pin drive is flipped for that panel).
  • Boot strapping pins: D4 must read HIGH and D8 LOW during reset. Make sure external wiring (like a servo pulling D8 high) can’t stop the board from booting.
  • Servo outputs: use any GPIO except D0 (no PWM) and A0 (input only). Power the servo from an external 5 V supply with a common ground.

Dashboard, automation and MQTT

Once the board is on your network (or in its own firefly access-point mode), open its address in a browser — usually just http://firefly.local. From the dashboard you can:

  • Create panels: pick an input or output, assign pins, give it a name.
  • Calibrate: offset/factor or two-point calibration, plus optional averaging per panel.
  • Automate: build IF/THEN rules with conditions on any panel or variable (e.g. IF tank - time > 1000 THEN relay1 = 1), grouped into programs.
  • Variables: define your own values and computed values, usable like panels in rules and on the OLED.
  • MQTT: publish panel states to any broker, or enable Home Assistant discovery so panels appear automatically as entities.
  • UDP (board-to-board): scatter bare boards next to remote sensors and subscribe to them with udp_remote input panels — they behave like local panels in the dashboard, OLED, rules, logging and MQTT. See the solutions page for details.
  • Log: record sensor values to a file and download it for analysis.
  • Backup / restore everything from the settings page.