Troubleshooting

Troubleshooting

Common issues and how to fix them. If you're hitting something not listed here, see FAQ or open a GitHub issue.

"Cannot connect to host tanksync-XXXX.local — MDNS lookup failed"

Affected versions: v0.3.1 to v0.6.0
Fixed in: v0.6.1

Cause: Earlier versions stored the hub's .local mDNS hostname expecting the OS resolver to translate it on every request. On HAOS-on-Proxmox, Docker bridge networking, and some VLAN setups, that resolution path is unreliable.

Fix: Update to v0.6.1+, then delete + re-add the integration so the new code stores the IP directly:

1. Settings → Devices & Services → SmartGhar → ⋮ → Delete
2. Settings → System → Restart Home Assistant
3. Re-add via auto-discovery (or manually with the hub's IP)

The new install stores the IP. DHCP changes are still handled — zeroconf re-discovery updates the stored IP within ~1 hour when the hub re-broadcasts.

Auto-discovery doesn't fire

After installing the integration via HACS and restarting HA, you'd expect to see a "Discovered" card on Settings → Devices & Services. If you don't:

Check 1: Did you restart HA after installing?

HA reads each integration's manifest zeroconf list only at startup. Without a restart, the discovery filter for _smartghar._tcp isn't activated.

Settings → System → Restart Home Assistant

Check 2: Is HA in a network mode that blocks multicast?

Install type	Multicast reaches HA?
HAOS (Home Assistant Operating System)	✅ Yes
Supervised	✅ Yes
Container with network_mode: host	✅ Yes
Container with bridge / default networking	❌ No
Core / venv on Linux	✅ Yes
Core in Docker Desktop (macOS / Windows)	❌ Often blocked
HAOS-as-VM on Proxmox with bridged vmbr0	✅ Yes

If you're on Container with bridge networking, switch to network_mode: host or use manual entry instead.

Check 3: Does the broadcast actually reach your network?

From any other device on the same LAN as the hub:

# Mac
dns-sd -B _smartghar._tcp local

# Linux
avahi-browse -r _smartghar._tcp

You should see your hub appear within a few seconds. If it doesn't appear there either, the issue is hub-side or network-side, not HA-side.

• Verify hub is connected to Wi-Fi (Settings → Devices & Services → SmartGhar → check wifi_signalsensor — should report a value, notunavailable`)
• Some managed switches drop multicast unless IGMP snooping is correctly configured. Check switch / router settings.

Check 4: Look in HA logs

Settings → System → Logs → search "smartghar"

You're looking for a line like:

[homeassistant.components.zeroconf] Discovered new device: smartghar
   with name TankSync Water Monitor.smartghar._tcp.local. on 192.168.0.30

If present: HA saw the broadcast. The Discovered card might be hidden somewhere on the page (refresh) or an ignored config entry exists already.

If absent: HA's zeroconf isn't seeing the broadcast. Re-check Check 2 / Check 3.

Manual entry (always works)

Settings → Devices & Services → Add Integration → SmartGhar
→ Hub IP address: <find in your router or hub web UI>
→ Submit

Entities show "unavailable"

Right after install or restart

Normal. The coordinator hasn't done its first poll. Wait ~30 seconds.

After a hub reboot

Normal during the reboot window (~30s for hub to come back). The integration retries with exponential backoff and reconnects once the hub is alive.

Persistent unavailable state

1. Test the hub directly:

   curl http://<hub-ip>/api/v1/info

   • Returns JSON: hub is healthy. Issue is in the integration. Check HA logs for smartghar errors.
   • Doesn't respond: hub is offline. Check power, Wi-Fi, network reachability.

2. Check the WebSocket connection:

   Settings → System → Logs → search "WS connected to hub"
   

   If you see WS dropped repeatedly, your network path to the hub is unstable. The integration falls back to 30-second polling automatically.

State updates take 30+ seconds (real-time push not working)

The integration prefers WebSocket push (~3s updates) but falls back to 30s polling if WS isn't available.

Why WS might not be working:

• Hub firmware is older than rx-v2.7.0 (which introduced WS) — update firmware
• Network drops the WS connection frequently — check network stability
• HA in a strict network mode that blocks WebSocket upgrades from the hub's IP

Check status: Settings → System → Logs → search "smartghar.*WS". You should see WS connected to hub <id>.

Bidirectional edits don't sync to PWA

When you rename a tank in HA, the change should appear in the SmartGhar PWA within ~30 seconds.

If it doesn't:

1. Verify the hub is connected to the SmartGhar cloud (`Settings → Devices & Services → SmartGhar → check the firmware version sensor — if it shows a value, the hub is at least responsive).
2. Open the hub's local web UI (http://<hub-ip>/), check the System tab → MQTT status. Should be connected.
3. If MQTT is disconnected: the cloud sync is the broken bit. Hub will retry; meanwhile your local edit persists on the hub itself.

Update available never goes away

The "Firmware update available" binary sensor / update entity polls the hub's info.ota field. The hub does its own OTA check every 24 hours. Press the Check for firmware updates button to force one immediately.

If after pressing the button the update still says available even though you've installed:

• Wait ~1 minute for the next coordinator refresh
• The hub may have just rebooted; first post-reboot poll might show stale OTA state. Wait 30 seconds.

TX battery voltage shows 5.03 V (when expected is 3.5–4.2 V for Li-ion)

The TX firmware can be in a mode where it reads the input/USB voltage rather than the battery cell. This is typically:

• During / right after charging
• When the TX is on a USB power source rather than battery
• Older TX firmware variants where the voltage divider isn't calibrated

This is a TX-firmware/hardware concern, not an integration issue. The integration faithfully reports what the TX sends. If voltage stays >5V for an extended period of unplugged battery operation, file an issue with hub + TX firmware versions.

"I see only one entity per tank, where's the rest?"

Many entities are hidden by default in the entity registry to keep dashboards uncluttered:

• Hub uptime, Wi-Fi signal, firmware version
• Tank LoRa signal (visible from v0.3.1+ — older versions had it hidden)

To enable hidden entities:

Settings → Devices & Services → SmartGhar → click hub → "+ N entities not shown"
→ Toggle "Enabled" on the ones you want

Filing a bug

GitHub Issues

Include:

• HA version (Settings → System → Repairs → System Information)
• Integration version (visible on Settings → Devices & Services → SmartGhar)
• Hub firmware version (sensor.smartghar_..._firmware_version, or hub web UI)
• Logs filtered to custom_components.smartghar
• Diagnostics download: Settings → Devices & Services → SmartGhar → ⋮ → Download diagnostics (auto-redacts sensitive fields)