Home

SmartGhar — Home Assistant Integration Wiki

Local-first Home Assistant integration for the SmartGhar IoT product family — currently TankSync (water-tank monitoring), with PowerSync (energy), GasSync, and others on the roadmap.

This wiki is the canonical user-facing documentation. The repo's docs/ folder mirrors most of this content for in-repo browsing, but the wiki has the richer navigation experience.

Quick start: see Installation · First time? read this Home page top to bottom · Looking for something specific? use the sidebar →

---

What this integration does

For every SmartGhar Hub on your local network, you get:

• Real-time tank state in HA — level, voltage, LoRa signal, connection state — pushed via WebSocket every ~3 seconds
• Editable configuration — rename tanks, change capacity, control LEDs, trigger OTA, identify hardware, all from inside HA
• HA-native firmware updates — appears in HA's sidebar Updates section like HACS / ESPHome / Tasmota
• Energy dashboard integration — cumulative water consumption with device_class: water slots into HA's native Water consumption panel
• Automation events — fill_complete events fire on detected refills
• Multi-hub native — each hub auto-discovers and gets its own device card
• Open protocol — third parties can write their own clients against the Protocol-v1 spec

New in HACS v0.8.0 — buzzer entities + sensor health. The hub's physical buzzer (rx-v2.8.0+) now has full HA controls: switch for master enable, select for volume profile (Quiet/Standard/Loud), and smartghar.test_buzzer service for previewing alert patterns. Also adds per-tank sensor_not_responding and sensor_stuck binary sensors — clean automation surfaces for unhealthy ultrasonic sensors. Buzzer entities require rx-v2.8.4+ on the hub; sensor health works from rx-v2.8.0+.

---

Why this exists

Most consumer water-tank IoT products require a vendor cloud account, OAuth dance, and outbound internet from your HA install. SmartGhar is built differently:

• Local-first. HA talks to the hub directly over your home network. Never reaches our cloud. Never makes outbound internet requests.
• Real-time. WebSocket push, not 30-second polling.
• Bidirectional. Read state and edit configuration. Edits propagate to the SmartGhar PWA via the existing config-sync pipeline.
• Multi-hub. Three hubs in your home? They each get their own device.
• Open. Protocol spec is Apache-2.0. No vendor lock-in.
• Open-core friendly. DIY-builders running open firmware get the same integration as commercial-kit customers.

---

Architecture in one diagram

   ────────────── Local LAN ─────────────────────┐
   │                                             │
   │  ┌──────────────┐         ┌──────────────┐  │
   │  │ TankSync Hub │  mDNS   │ Home         │  │
   │  │   (ESP32)    │◄───────►│ Assistant    │  │
   │  │              │  HTTP   │ + smartghar  │  │
   │  │  /api/v1/*   │◄───────►│ HACS         │  │
   │  │              │  WS     │              │  │
   │  └──────┬───────┘◄───────►│              │  │
   │         │                 └──────────────┘  │
   │         │ (parallel,                        │
   │         │  unrelated to                     │
   │         │  HA path)                         │
   └─────────┼───────────────────────────────────┘
             ▼
       ┌─────────────────┐
       │ tanksync.       │  ← cloud + PWA for away-from-home
       │ smartghar.org   │     (HA never touches this)
       └─────────────────┘

The HA integration sits entirely on the LAN side. The cloud + PWA are a parallel access path for users who need away-from-home control — they're not in HA's data flow at all.

---

Where to go from here

Get started

• Installation — HACS setup, first config, common gotchas
• Energy-Dashboard — set up HA's native water-consumption tracking

Reference

• Entities-Reference — every sensor, button, service, event explained
• Multi-Hub-Setup — naming, areas, dashboards for households with multiple hubs
• Protocol v1 spec — for third-party client builders

Help

• Troubleshooting — common errors and fixes
• FAQ — quick answers to frequent questions
• GitHub Issues — report bugs

---

Latest release

See Releases and CHANGELOG. At time of writing, the integration is at v0.6.1 (Energy dashboard, refill_marker service, automation blueprints, hub-IP storage fix).

Required hub firmware: rx-v2.7.0+ for protocol v1, rx-v2.7.1+ for identify endpoints, rx-v2.7.2+ for per-tank identify in the local web UI.

---

License

Code: MIT
Protocol spec: Apache-2.0

The license split is deliberate: the protocol gets the patent grant of Apache-2.0 so third-party implementers have legal cover; the reference Python client gets the simpler MIT for contribution friction.