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 shipping hub is powered through a DC barrel jack — the kit includes a USB-to-DC-jack cable so any 5 V USB adapter or power bank will run it. (Self-built DevKit hubs take 5 V over USB-C instead.) 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-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-XXXX
IP:   192.168.4.1

The setup AP is an open network — no password. XXXX is the last four hex digits of the hub's MAC, so two hubs on the same shelf never collide. The AP always comes up on channel 6 (channels 1 and 2 don't radiate on some hub revisions).

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. Wakes, samples the sensor, transmits, waits for ACK, sleeps for the configured interval (default 5 minutes).

An unpaired transmitter behaves exactly the same as a paired one — it runs the normal wake → measure → send → sleep cycle. It does not stay awake, and it does not blink to signal that it's unpaired. That's deliberate: a unit sitting in a box waiting to be paired would flatten its cell doing that. Pairing is only ever offered via the BOOT-hold gesture below.

Pairing flow

Pairing is only offered during a 10-second window that opens on power-on or reset. Outside that window the BOOT button is ignored — this is deliberate, so an installed transmitter can't be knocked out of service by a stray press, and so an unpaired unit doesn't sit awake draining its cell.

1. Put the hub into pairing mode first (web UI → Devices → Pair New, 60-second window).
2. On the TX, press RESET once to open the boot window.
3. Immediately press and hold BOOT. The status LED blinks slowly at first, then switches to a fast blink at the 2-second mark.
4. Release while it's fast-blinking. Release is the trigger — holding on past 5 s gives you Wi-Fi update mode instead.
5. The WS2812 blinks blue while it searches, then green three times on success and the TX reboots.
6. Hub display briefly shows the paired tank; PWA / web UI updates.

If the blue blink stops without a green confirmation, the TX didn't hear the hub. See Troubleshooting → Pairing.

The BOOT button — all four gestures

Everything below happens inside that same 10-second post-reset window. The LED tells you which gesture you're in before you commit:

Hold	LED while holding	Triggers	Action
< 2 s	Slow blink (0.5 s)	—	Nothing
2–5 s	Fast blink (0.15 s)	On release	Pair — blue blink while searching, green ×3 on success
> 5 s	Solid	At 5 s, automatically	Wi-Fi AP (TankSync-TX-XXXX) for local firmware update + diagnostics. LED pulses cyan.
> 15 s	Very rapid blink (0.05 s)	At 15 s, automatically	Factory reset — erases NVS: pairing, settings, calibration, LoRa config. LED blinks red.

Two of these fire on their own without you releasing the button, so a "just hold it down and see what happens" approach will eventually wipe the transmitter. Watch the blink rate.

Wi-Fi AP mode is genuinely useful once the TX is installed: connect a phone to its hotspot to flash firmware locally (no cable, no LoRa) and read live sensor + link diagnostics.

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.