Quick Start

Quick Start

The fastest way to get from "I have boards in hand" to "the hub is online and shows my tank level."

No toolchain install required. Flashing happens entirely in your browser via WebSerial.

---

What you need

• An assembled RX hub (ESP32-S3 module on the carrier board; the legacy ESP32 DevKit build still works too) and at least one TX node
• A USB-C cable for the hub
• A short USB-C cable for the TX (only needed once, for the initial flash)
• A laptop / desktop running Chrome or Edge (Firefox + Safari do NOT support WebSerial)
• 2.4 GHz Wi-Fi credentials for your home network

---

Step 1 — Flash the firmware (browser)

1. Open tanksync.smartghar.org/firmware in Chrome / Edge.
2. Plug the hub into your computer.
3. Click Install on the Receiver Hub card → browser asks which serial port → pick the CP210x device → click Connect.
4. Wait ~60 s. The button turns green when done.
5. Unplug the hub, plug in the TX node, click Install on the Transmitter card, repeat.

Step-by-step walkthrough with screenshots: Browser Flasher. If you'd rather use the IDF toolchain or a .bin you built yourself, see Manual Flashing.

---

Step 2 — Power up the hub

Plug the hub into a 5 V USB-C wall adapter. Within a few seconds the OLED shows:

TankSync
Setup mode
SSID: TankSync-XXXX
IP:   192.168.4.1

The hub is now broadcasting its own Wi-Fi network.

---

Step 3 — Configure Wi-Fi + MQTT

1. On your phone or laptop, join the TankSync-XXXX network. It's an open network — there is no password. The XXXX is the last four hex digits of the hub's MAC, so it's unique to your hub.
2. A captive-portal page should open automatically. If it doesn't, browse to http://192.168.4.1.
3. Enter your home Wi-Fi credentials.
4. Choose your MQTT path:
   • Cloud (default) — pre-filled with mqtt.smartghar.org:8883. Free tier covers up to 3 hubs.
   • Local broker — point at your own Mosquitto / HA broker. Works fully offline once set.
5. Save. The hub reboots and joins your Wi-Fi within ~10 s. The OLED switches to:

My Tank
Wi-Fi: TopFloor 2.4GHZ
IP:    192.168.0.56
0 tanks paired

---

Step 4 — Pair a TX node

1. On the hub's local web UI, go to Devices → Pair New. The hub listens for 60 seconds.
2. Power the TX (turn on its switch, or plug in its solar panel + cell).
3. Press RESET once, then immediately press and hold BOOT. This is the part people miss — the button only does anything during the 10-second window right after a reset or power-on. Holding BOOT on an already-running transmitter does nothing.
4. Keep holding until the status LED switches from a slow blink to a fast blink (about 2 seconds in), then release. Releasing is what triggers pairing.
5. The WS2812 blinks blue while it searches, then green three times when it's paired. The hub's LED ring (if attached) spins a cyan comet while it listens.
6. Open the hub's local web UI at the IP shown on the display. The new tank appears under Tanks with a level reading.

Repeat for additional tanks. You can pair up to 6 transmitters to one hub.

The BOOT button does four different things, all in that 10-second post-reset window. Watch the LED — it tells you which one you're about to get.

Hold	LED while holding	On release / at time	Action
< 2 s	Slow blink	—	Nothing
2–5 s	Fast blink	Release to trigger	Pair (blue → green)
> 5 s	Solid	Fires at 5 s, no release needed	Wi-Fi update mode (TankSync-TX-XXXX hotspot, LED pulses cyan)
> 15 s	Very rapid blink	Fires at 15 s	Factory reset — erases pairing, settings and calibration (LED blinks red)

So if you hold too long you'll land in Wi-Fi update mode instead of pairing. Let go as soon as the blink speeds up.

---

Step 5 — Open the PWA (optional)

If you chose the cloud path in step 3:

1. Sign in (or sign up) at tanksync.smartghar.org.
2. Add Hub → scan the QR sticker on your hub OR enter the Device ID shown on the hub's Cloud tab.
3. Within a few seconds the hub goes from unclaimed → linked. All your tanks show up in the PWA, on every device you sign in to.

If you chose the local path in step 3, skip the PWA — point your Home Assistant at your broker and follow HACS Integration.

---

Verify everything is working

You should see:

• OLED on the hub showing the tank count and current Wi-Fi IP.
• A tank-level reading in the web UI / PWA within ~30 s of power-on.
• The transmitter's WS2812 blinks green once per wake cycle (default every 5 minutes).

If any of those are missing, jump to Troubleshooting.