# critterOS setup prompt — paste this into your AI assistant

You are helping me set up a **Firefly** home-automation controller running
the open critterOS firmware. The firmware serves a web dashboard from the
board itself — no app, no cloud, no coding required. Everything (sensors,
rules, logs) runs on the device.

## What I have

- An ESP8266 board (Wemos D1 Mini, NodeMCU, or equivalent with 4 MB flash)
  or an ESP32 board (D1-mini footprint, e.g. node32s), USB data cable,
  computer with Chrome/Edge (for the web flasher) or Python.
- Optionally: sensors/actuators (DS18B20 temperature, BMP180/BME280
  pressure, HC-SR04 ultrasonic, YF-S201 flow, HX711 load cell, relays,
  SG90 servos, push buttons) and the Firefly / Firefly Mini carrier board.

## Step 1 — Flash critterOS (pick one path)

Files: `firmware.bin` (program) and `littlefs.bin` (dashboard + storage).
Flash addresses are **always** `firmware.bin @ 0x0`, `littlefs.bin @ 0x300000`
(ESP8266) or `firmware.bin @ 0x10000`, `littlefs.bin @ 0x210000` (ESP32).
Flashing firmware alone keeps the configuration; flashing the filesystem
wipes panels, rules and settings (back up from the dashboard first).

- **Web (easiest):** open the site's critterOS Uploader page in Chrome/Edge,
  plug in USB, Connect, flash firmware-only (keeps config) or firmware +
  filesystem (erases the chip; factory fresh). Needs the CH340 USB driver if
  no port appears. ESP32: click the ESP32 button for a full flash (bootloader
  + partitions + firmware + filesystem).
- **Python script:** `pip install esptool`, then
  `python3 uploader.py --port /dev/ttyUSB0` (add `--full` to wipe config,
  `--erase` for a full chip erase, `--baud 115200` if flaky). Windows ports
  look like `COM3`.
- **Raw esptool:** `esptool.py --chip esp8266 --port <port> --baud 460800
  write_flash -z 0x0 firmware.bin 0x300000 littlefs.bin` (drop the second
  pair for firmware-only). For ESP32: `esptool.py --chip esp32 --port <port>
  write_flash 0x1000 bootloader.bin 0x8000 partitions.bin 0xe000 boot_app0.bin
  0x10000 firmware.bin 0x210000 littlefs.bin`.
- **Updating from 2.0-5c18013 or older?** Those builds used the Tasmota
  ESP8266 core. Do a one-time full USB flash with chip erase: web installer
  "Flash firmware + filesystem", or `python3 uploader.py --port ... --erase`.
  Firmware-only updates or OTA from those builds can boot-loop on
  `rf cal sector: 1020`. After that one-time migration, OTA works normally.
- If the flasher sticks at "Connecting": another cable (data, not
  charge-only), another port, then last resort jumper D3 (GPIO0) to GND,
  tap RST, flash, remove the jumper.

## Step 2 — WiFi onboarding

On first boot the board tries the stored network ~15 s, then opens an open
network called `firefly` and keeps retrying yours in the background. Join
`firefly`, open `http://192.168.4.1`, go to Settings, set `wifi_ssid` and
`wifi_pass` (2.4 GHz only), Save, Restart. Find it afterwards via the OLED
bottom line, `http://firefly.local` (mDNS), the UDP beacon
(`nc -ul 8421`), or the router client list.

## Step 3 — Dashboard tour (open the board's IP)

- **New Panel**: name (no spaces), type, hardware driver, pin(s). Inputs:
  `analog_in` (A0), `digital_in`, `ds18b20`, `bmp180`/`bme280`,
  `dht22` (temperature + humidity), `vl53l0x` (I2C time-of-flight
  distance), `mpu6050` (I2C accelerometer: x/y/z + temperature),
  `us_sensor` (HC-SR04: 5 V power, divided echo, never D0), `flow`
  (hall pulses), `hx711` (load cell, DT+SCK), `ir_remote` (IR remote
  button: raw NEC code → `button`, `repeat`). Outputs: `digital_out`
  and `pwm` (0–100 %, hardware PWM pins) — both honor the global
  `active_low` (default 1 = ON means energized) and have a per-panel
  **Active low / inverted** toggle for devices wired opposite polarity —
  `servo` (0–180°, external 5 V, not D0/A0). Plus `set` switches,
  `timer` schedules (`10-10` = off/on seconds, count limit, hours mode),
  `push_btn` (short / double / long press each runs a program), and
  `telegram` (ESP32 only — sends a message when triggered).
- Each card's bottom strip: **Log** (record), **OLED** (display), **MQTT**
  (publish) — lilac means on.
- **Calibration**: input cards have Low/High/Reset. Example (flowmeter in
  liters): Reset, run exactly 2 L through, High + enter `2`. Low + `0`
  tares any time.
- **Automation**: programs hold rules like
  `IF temperature > 25 THEN heater = 0`, firing once per edge or while
  true, with `&&` / `||` extras; plus ordered SET/WAIT steps on start.
  Sources: panels, plain/computed variables, other programs, `millis` /
  `time` / `board`. Names must be unique across all three.
- **Logger** records Log-enabled panels on an interval; **Backup**
  downloads the whole setup as one text file; **Restore** rebuilds from it.
- **Update** page: flash a downloaded `firmware.bin` from the browser
  (config kept) or the filesystem image (config wiped).

## Step 4 — Cloud IoT (optional)

### ESP8266: critter-bridge (companion app)
The ESP8266 can't do HTTPS reliably. Run critter-bridge on a PC or Pi
on your LAN — it pulls state from boards and pushes to ThingSpeak + Telegram.
Zero firmware changes. See /bridge/ on the website.

### ESP32: direct cloud mode
ESP32 can do HTTPS natively. Enable in Settings:
- `direct_cloud,1` — enable direct cloud mode
- `ts_write_key,<key>` + `ts_fields,pressure=1` — ThingSpeak upload on interval
- `tg_token,<bot token>` + `tg_chat_id,<chat id>` — Telegram alerts
- Create a **Telegram** panel and wire into a rule:
  `rule main IF pressure > 50 THEN SET tg1 = 1 once`

## Troubleshooting facts

- USB serial runs at 74880 baud. `uploadfs`/filesystem flashes wipe config.
- HC-SR04 needs 5 V (VU pin) + echo divider; ESP pins are not 5 V tolerant.
- D0 (GPIO16): no interrupts, no PWM. A0: input only. D8/GPIO15 and
  D4/GPIO2 are boot-strapping pins — mind levels at reset.
- Servos and relays take external 5 V with common ground, never board power.
- Dashboard polls every ~2.5 s; a hidden tab doesn't poll. If the UI looks
  stale after an update, hard-refresh once (the app now sends no-cache).
- Slow guest WiFi can stall the UI for seconds (3 KB synchronous sends);
  close the tab and use the OLED/buttons if it misbehaves.
- ESP32 GPIO: A0 is GPIO36; for analog prefer A0 or GPIO32/33/34/35/39
  (ADC1, unaffected by WiFi). Clone boards vary — check silkscreen.

Help me step by step. Ask which sensors and which board I have before
giving wiring instructions, and confirm each step worked before moving on.
