Getting started
- 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.
- Connect to WiFi — on first boot the board creates its own
fireflyWiFi network. Join it, openhttp://192.168.4.1in 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 openhttp://firefly.local. - Connect sensors and create panels and automations — follow the creating panels guide to add sensors and create panels.
Flashing options
| Method | What you need | Link |
|---|---|---|
| Web uploader (recommended) | Chrome/Edge + USB cable | critterOS Uploader |
| USB bundle (ESP8266) | Python + esptool | firefly-usb-esp8266.zip |
| USB bundle (ESP32) | Python + esptool | firefly-usb-esp32.zip |
Guides and reference
| Document | Description |
|---|---|
| Board API reference | Every HTTP endpoint and MQTT topic |
| Supported sensors & actuators | Every panel driver built into critterOS |
| How Firefly compares | Feature comparison with Tasmota, ESPHome, ESP Easy and other IoT platforms |
| Connecting to WiFi | Network setup guide |
| Adding Sensors and Creating Panels | Panel creation guide |
| Panels Documentation | How to use each panel type (timer, flow control, dispenser, etc.) |
| Automation & Programs | Scripting guide: IF/THEN rules, programs, variables, examples |
| Home Assistant integration | MQTT auto-discovery setup |
| Tasmota integration | Using Firefly alongside Tasmota |
| Mini Relay Module | Adding a 2-channel relay board |
| Third-party licenses | License 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_lowsetting (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 (logical0/100%or0/1stays 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_remoteinput 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.