Skip to content

Troubleshooting

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

Troubleshooting

Quick lookup for the most common symptoms. For the deeper reference, see docs/troubleshooting.md in the repo — it's longer and gets updated whenever a new failure mode is reported.

Hub

OLED shows "NO DATA"

No transmitter is paired yet. Open the hub's local web UI → Devices → Pair new, then hold the TX BOOT button for 5 seconds. See First Boot → Pairing flow.

Captive portal doesn't appear after joining TankSync-Setup-XXXX

Open http://192.168.4.1 manually in your browser. iOS/Android auto-redirect is supported but doesn't fire on every device.

Wi-Fi scan button does nothing

The hub uses APSTA mode for scanning, which is occasionally flaky on first try. Hit Scan again, or power-cycle the hub.

MQTT shows "disconnected"

  • Check Wi-Fi is connected (Network tab → Wi-Fi panel shows green dot).
  • Verify the broker host / port match what's in your broker's config. For TLS, port is 8883; plaintext is 1883.
  • Username + password right? Some brokers are case-sensitive.
  • For local Mosquitto: confirm allow_anonymous false + your password matches.

OTA update fails

  • .bin must match the chip (-chip esp32 for hub, -chip esp32c3 for TX).
  • File must be under ~1.5 MB (OTA partition limit).
  • Try uploading directly via the local web UI's manual upload (System → Firmware → upload .bin) instead of via PWA.

Transmitter

Won't pair

  • Same LoRa frequency on hub and TX (865 / 868 / 915 MHz must match).
  • TX powered on within 60 seconds of pressing "Pair new" on the hub.
  • Power-cycle the TX, then retry.
  • If using TX firmware pre-v2.0.11, NETID-rotation might be orphaning it — flash the TX to v2.0.11 or later. See Firmware Versions.

Pairs but no readings

  • Sensor cable seated correctly in the screw terminal? TRIG + ECHO + 5V + GND, four wires.
  • Hub web UI → Devices → Edit your TX → check the calibration: full-distance (sensor-to-water when full, typically 20 cm) + empty-distance (sensor-to-bottom, typically 130 cm). Wrong values give 100% or 0% always.
  • Check the JSN-SR04T variant — some "M" variants ship in UART mode. See AJ-SR04M UART Mode.

Sensor reads zero (TX reports dist=0)

The ultrasonic didn't get an echo within the 30 ms timeout. Possible causes:

  • Tank water surface lower than 4 cm from the sensor face (the sensor needs ≥ 4 cm minimum range).
  • Tank water surface > 4 m from the sensor face (max range exceeded).
  • Sensor is dead — replace if no readings ever come through across multiple wakes.
  • Sediment / dust on the sensor face — wipe gently with a dry cloth.

The hub now flags this case with a "Sensor error" chip on the affected tank card (rx-v2.8.0+).

"Sensor stuck" warning chip

Variance-based detection: TX's water_pct hasn't changed across the last 20+ wake cycles, value looks plausible but is suspicious. Most common cause is a partially-failed sensor reporting its minimum-range value (typically 20-25 cm) regardless of actual water level. Replace the sensor. See feedback_sensor_stuck_at_floor_2026_05_22 for full context.

Battery drains in days, not months

  • 18650 actually 18650? Counterfeits with "5000 mAh" labels are usually 1500 mAh re-wrapped salvage. See Bill of Materials → sourcing.
  • Sleep interval not stuck at "always on"? Hub web UI → Devices → Edit → sleep_interval should be 300 s (5 min) default.
  • INA219 reads a constant high current (>5 mA average)? Wiring issue — check the high-side shunt placement.

Solar panel not charging

  • Panel wired the right way round? + to CN3791 IN+, - to GND. Reversed panel won't damage anything but won't charge either.
  • Panel in actual sun? Tested through Delhi summer says ~4 V at panel terminals in direct light. < 1 V means panel is shaded, dirty, or facing wrong direction.
  • 18650 already at 4.2 V? Then CN3791 has stopped charging deliberately — battery is full. Normal.

Multi-hub setups

Hubs at the same location, will they interfere?

No. Three isolation layers (per docs/troubleshooting.md):

  1. NETID — each hub picks a random Network ID 1-200 on first pair, keeps it forever. Radio-level filtering means Hub A's TXs never reach Hub B's MCU.
  2. Pair-mode is single-hub — PWA wizard asks which hub to pair to; only that one listens.
  3. MQTT topic scoping — each hub has a MAC-derived device ID; topics + DB rows are partitioned per hub.

Two hubs end up on the same NETID with ~0.5% probability. If it happens, factory-reset one — its next first-pair re-randomizes.

A tank shows "Tank N" instead of my custom name after re-pairing

The name + capacity + alerts are preserved via tombstone archive — but only for TXs that send their MAC in PAIR_REQ (TX firmware ≥ v2.0.11). Older TX firmware doesn't have MAC-based identity, so a delete is hard-delete and re-pair starts fresh.

One-time fix: flash the TX to v2.0.11 or later, then delete + re-pair once. From that point forward, MAC is recorded.

Cloud / PWA

"Tank still shows in PWA after I deleted it"

Fixed in rx-v2.7.11 + cloud (May 2026). Delete now publishes an MQTT remove_tx command to the hub and waits for ack before removing the DB row. If you still see it: hard-refresh the PWA (close + reopen).

PWA can't see the hub on local network

Browser fetch-from-local-IP is mixed-content-blocked (PWA served from HTTPS, hub serves HTTP). This is a deliberate browser security policy, not a bug. Use the hub's local web UI directly via http://<hub-ip>/ from the same Wi-Fi.

"Cloud disconnected" — hub stays on Wi-Fi

mqtt.smartghar.org is unreachable. Confirm:

  • DNS resolves: dig mqtt.smartghar.org should return an IP.
  • Port 8883 open from your network (some ISPs block outbound MQTT TLS).
  • TLS cert valid: openssl s_client -connect mqtt.smartghar.org:8883 -servername mqtt.smartghar.org.

If your ISP blocks port 8883, use port 1883 + your own broker. See Self-Host Guide.

Still stuck?

TankSync

Start here

Build it

Flash it

Use it

Reference

Main repo → HACS repo →

Clone this wiki locally