Skip to content

First Boot

Jump to bottom
Ravi Singh edited this page May 23, 2026 · 1 revision

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 strip (if attached) pulses orange.

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

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.

TankSync

Start here

Build it

Flash it

Use it

Reference

Main repo → HACS repo →

Clone this wiki locally