The firmware serves a small REST-style API plus MQTT topics for Home Assistant and other LAN clients.

Base URL: http://<board-ip> or http://firefly.local (mDNS).

Note: the URL of the firmware page on this site is /firmware/, but the board itself has no such path — all endpoints below are relative to the board’s own address.

Status and diagnostics

Method Endpoint Description
GET /api/health Uptime, heap, max free block, tick statistics
GET /api/dashboard Full state: version, device name, panels, oled, peers, logger, automation
GET /api/system Chip type (ESP8266 / ESP32) and build info
GET /api/sensordebug Raw I2C sensor data and chip ID (raw UT/UP, trigger/echo counts)
GET /api/i2cscan I2C bus scan. ?sda=/?scl= override pins; ?debug=1 adds idle line levels and ACK/NACK/fault counts
GET /api/peers Boards discovered on the LAN (UDP beacon list)

Settings and configuration

Method Endpoint Parameters
GET /api/settings — (returns all settings as plain text)
POST /api/settings body = full settings text (overwrites the file)
GET /api/backup — (downloads firefly-backup.txt)
POST /api/restore body = backup text
GET /api/reset — (reboots the board)

Panels

Method Endpoint Parameters
POST /api/createPanel name, type, input/output, hardware, pin, pin2, pin3, pin4, rpanel, mac, …
POST /api/panel/delete id
POST /api/panel/target id, target, enabled (bind a UDP remote panel)
POST /api/event id, value (trigger a panel event, e.g. a button press)
POST /api/pushbind btn, slot, target (bind a push button to a program)

Variables

Method Endpoint Parameters
POST /api/variables/add name, value
POST /api/variables/set name, value
POST /api/variables/delete name
POST /api/variables/computed/add name, a, b, op (+ - * /)

Automation

Method Endpoint Parameters
POST /api/automation/add program, action, op, target, pause
POST /api/automation/delete id
POST /api/automation/run id
POST /api/automation/set id, enabled
POST /api/automation/mode id, mode
POST /api/automation/program/add name
POST /api/automation/program/delete name
POST /api/automation/program/set name, running
POST /api/automation/program/run name
POST /api/automation/statement/add program, kind, target, pause
POST /api/automation/condition/add ruleId, op, logic
POST /api/automation/condition/delete ruleId, index

Display

Method Endpoint Parameters
GET /api/display text, timeout (seconds; 0 = until cleared) — push text to the OLED

OTA / update

Method Endpoint Parameters
POST /api/update/file multipart firmware — flash the sketch (keeps config)
POST /api/update/file?target=fs multipart firmware — flash LittleFS (wipes all config)

Time

Method Endpoint Parameters
POST /api/time/set epoch (Unix seconds)

Logger

Method Endpoint Description
GET /api/logger Logger status (enabled, interval, file, host)
GET /api/logger/file Download the log CSV

Static pages served by the board

Path Description
/ Web dashboard
/graph.html Value graph
/i2cscanner.html I2C scanner tool
/style.css Dashboard stylesheet

MQTT entry points

MQTT is an alternative to the HTTP API. Set mqtt_server (host or host:port) and mqtt_mode in Settings.

Direction Topic Purpose
Subscribe (command) cmnd/<device>/<panel> Set an output / send a value
Subscribe (command) cmnd/<device>/display Push text to the OLED
Publish (state) stat/<panel>/STATE Panel state (template configurable)
Publish (discovery) homeassistant/<type>/<device>_<panel>/config Home Assistant auto-discovery (when mqtt_mode=homeassistant)

Notes

  • Most POST endpoints return ok on success, bad args (400) or not found (404) on failure.
  • /api/update/file without target=fs keeps your configuration; with target=fs it wipes everything (panels, rules, settings, WiFi).
  • The board’s own address is usually reachable at http://firefly.local (mDNS) when it is on your home network, or at its LAN IP otherwise.
  • Both the HTTP API and the MQTT topics are served by the same firmware, so Home Assistant can drive outputs and the display without HTTP.