First Boot

First Boot

What happens — on the hub and the transmitter — between "power applied" and "tank levels showing up in the app."

---

Hub (RX) first boot

The hub is USB-C-powered; the moment it gets 5 V, the firmware starts.

Boot sequence (~6 s)

1. ESP32 boots, mounts NVS, checks for stored Wi-Fi credentials.
2. OLED splash: TankSync · v2.8.x · loading…
3. I²C scan — must find the SH1106 OLED at 0x3C. If absent, the display stays blank but the hub still runs.
4. UART probe — sends AT\r\n at 115200 baud to the RYLR998. Must receive +OK\r\n within 1.5 s.
5. If no Wi-Fi creds stored → goes into setup mode (AP TankSync-Setup-XXXX).
6. If Wi-Fi creds stored → tries to join; on success connects to the configured MQTT broker.
7. OLED switches to the standard 3-screen carousel (Tanks / Health / System) and the hub starts publishing.

What setup mode looks like

The hub's OLED shows the AP name and the IP 192.168.4.1. The LED ring/strip (if attached) shows a slow blue breathing glow — the "set me up" signal.

TankSync
Setup mode
SSID: TankSync-Setup-XXXX
PWD:  on OLED below
IP:   192.168.4.1

Hub LED ring — what the colours mean

If your hub has the optional LED ring/strip, it doubles as an at-a-glance status light. During transient states the whole ring animates in a distinct colour; the rest of the time it shows the tank-level gauge:

Ring shows	Meaning
Slow blue breathing	First-time setup / AP mode — connect to the hub's Wi-Fi to configure it
Rotating cyan comet	Pairing — listening for a transmitter
Rotating orange comet	Hub firmware update in progress
Rotating magenta comet	Updating a transmitter's firmware over LoRa
Level gauge (green → amber → red)	Normal operation — fill level of the tank shown on the screen

New in v3.6.2. Earlier firmware showed only a single blinking status pixel for these states.

Connect to that network from your phone; a captive portal opens. See Quick Start step 3.

Re-entering setup mode later

• Hold the BOOT button on the hub for 5 seconds.
• Or visit http://<hub IP>/factory-reset (will require confirm).

---

Transmitter (TX) first boot

The TX is battery + solar powered. When the power switch closes (or you plug the 18650 in), the firmware starts.

Boot sequence (~3 s)

1. ESP32-C3 boots from deep-sleep wake reason (or hard power-on).
2. WS2812 blinks blue for ~500 ms — "I'm alive."
3. UART probe to the RYLR998 (same AT\r\n handshake as the hub).
4. I²C scan at 0x40 — if INA219 found, switches to Variant B (current + voltage telemetry). If absent, uses the GPIO 0 voltage divider (Variant A).
5. If unpaired — WS2812 pulses cyan every 5 s, indicating "looking for hub." Stays awake; doesn't sleep.
6. If paired — wakes, samples the sensor, transmits, waits for ACK, sleeps for the configured interval (default 5 minutes).

Pairing flow

1. With the hub already on and in normal mode, hold the TX BOOT button 5 seconds.
2. WS2812 turns solid cyan, then transmits a pairing beacon.
3. Hub responds; LED turns solid green for 2 s = success.
4. Hub OLED briefly shows paired tank: <name>; PWA / web UI updates.

If the cyan pulse continues for more than 30 s, the TX is not receiving the hub's beacon. See Troubleshooting → Pairing.

Sleep cycle

In normal operation the TX is only awake for ~250 ms per cycle:

• Take 5 ultrasonic samples (5 ms each) → median = level.
• Read INA219 (or ADC).
• Build a TANK packet → transmit → wait up to 3 s for ACK → up to 3 retries.
• Go back to deep sleep for SLEEP_INTERVAL_S (default 300 s).

Average current draw is around 1.5 mA with the standard configuration → typical 18650 lasts months without solar, indefinitely with the panel.

---

Where the firmware version shows up

After first boot, you can confirm what's running:

• Hub OLED — System screen shows RX v2.8.x and the build short SHA.
• Hub web UI — Footer shows Receiver firmware vX.Y.Z on every page.
• Hub MQTT — publishes firmware_version field in retained /hub/status topic.
• TX — publishes tx_version in every TANK packet → hub forwards to MQTT → visible in PWA Devices and Firmware updates pages.

If the version doesn't match what you flashed, see Firmware Versions — there's a known historical gotcha with version stamping that was fixed in rx-v2.8.5.