Entities Reference

Entities Reference

Complete catalogue of every entity the integration creates, what it represents, and when it's available.

Entities are namespaced by hub_id (MAC-derived) so multi-hub homes never have collisions:

sensor.smartghar_<hub_id>_tank_<n>_level
                  └── 12-char hex MAC ──┘

---

Sensors (read-only)

Per tank

Entity	Unit	Source	Notes
sensor.smartghar_<hub>_tank_<n>_level	%	state.level_pct	Current water-level percentage. Visible by default.
sensor.smartghar_<hub>_tank_<n>_voltage	V	state.voltage	TX battery voltage. Visible.
sensor.smartghar_<hub>_tank_<n>_lora_signal	dBm	state.rssi	LoRa signal strength (closer to 0 = better). Visible.
sensor.smartghar_<hub>_tank_<n>_connection_state	text	state.conn_state	online / stale / lost / waiting. Visible.
sensor.smartghar_<hub>_tank_<n>_water_volume	L	computed: capacity_l × level_pct / 100	Current volume in litres. Visible.
sensor.smartghar_<hub>_tank_<n>_water_consumed	L	derived from level deltas	Cumulative consumption — drives HA Energy dashboard. Visible.

Per hub (hidden by default)

Entity	Unit	Source	Notes
sensor.smartghar_<hub>_uptime	s	info.uptime_s	Seconds since hub last booted. Toggle on under entity registry if you want it visible.
sensor.smartghar_<hub>_wi_fi_signal	dBm	info.wifi_rssi	Hub's Wi-Fi signal strength.
sensor.smartghar_<hub>_firmware_version	text	info.fw_version	Current firmware (e.g. "2.7.2").

---

Binary sensors

Entity	Source	Notes
binary_sensor.smartghar_<hub>_firmware_update_available	info.ota.available	True when newer firmware exists on the OTA channel. device_class: update.
binary_sensor.smartghar_<hub>_tank_<n>_sensor_not_responding	state.sensor_error (per tank)	v0.8.0+ — true when the TX is alive but its ultrasonic sensor failed to echo on the last read. device_class: problem, diagnostic category. Pre-rx-v2.8.0 firmware doesn't emit the field; reads Off permanently — no false positives.
binary_sensor.smartghar_<hub>_tank_<n>_sensor_stuck	state.sensor_stuck (per tank)	v0.8.0+ — true when the sensor has reported a constant reading across 20 wake cycles regardless of actual water level. Symptom of a defective JSN-SR04M / AJ-SR04M module. device_class: problem, diagnostic category. Requires rx-v2.8.3+.

---

Switches

v0.8.0+ — requires hub firmware rx-v2.8.4+. Older firmware silently skips registration (no permanent-unavailable clutter).

Entity	What it does	Category
switch.smartghar_<hub>_buzzer_alerts	Master mute for the hub's physical buzzer. Off silences every alert except the boot tone (which always plays on power-up — that's intentional, confirms the hub is initialized).	Configuration

---

Select entities

v0.8.0+ — requires hub firmware rx-v2.8.4+.

Entity	Options	What it does	Category
select.smartghar_<hub>_buzzer_volume	Quiet / Standard / Loud	Global volume profile for the hub buzzer. Applies uniformly to every alert. Per-alert profiles are not exposed by design — per-alert enables live on the hub local web UI under "Advanced".	Configuration

---

Update entity

Entity	What it does
update.smartghar_<hub>_firmware	Surfaces firmware OTA in HA's sidebar Updates section. Native Install button triggers POST /api/v1/hub/ota/install. Same UX as HACS / ESPHome / Tasmota updates.

---

Editable entities

Per tank (text)

Entity	Range	Notes
text.smartghar_<hub>_tank_<n>_name	up to 15 chars	Editable tank name. Edits propagate to PWA via the existing config-sync MQTT path.

Per tank (number)

Entity	Range	Category	Notes
number.smartghar_<hub>_tank_<n>_capacity	50–50000 L	Configuration	Used to compute volume + consumption.
number.smartghar_<hub>_tank_<n>_tx_sleep_interval	60–3600 s	Diagnostic	Time between TX wakes. Longer = better battery, slower readings.
number.smartghar_<hub>_tank_<n>_tx_samples_per_wake	1–10	Diagnostic	How many sensor reads the TX averages per wake.
number.smartghar_<hub>_tank_<n>_lora_tx_power	1–22 dBm	Diagnostic	LoRa transmit power. Higher = more range, more battery drain.

Per hub (number)

Entity	Range	Notes
number.smartghar_<hub>_led_brightness	0–255	Hub LED strip brightness slider.

---

Buttons

Per hub

Entity	What it does	Category
button.smartghar_<hub>_check_for_firmware_updates	Trigger an OTA manifest check on demand.	Diagnostic
button.smartghar_<hub>_identify	Blink the hub's status LED ~5×. Find the hub physically.	Default
button.smartghar_<hub>_reboot_hub	Restart the hub cleanly. Unreachable for ~30 s.	Diagnostic

Per tank

Entity	What it does
button.smartghar_<hub>_tank_<n>_identify	Blink that tank's specific LED on the hub strip. Find which TX is which when you have multiple tanks. Requires hub strip ≥8 LEDs.

---

Events

Entity	When it fires	Payload (in state_attributes)
event.smartghar_<hub>_tank_<n>_fill_event	Tank level rises ≥5% between coordinator ticks (auto-detected refill)	from_pct, to_pct, delta_pct, volume_l, tank_name

Subscribe to these in automations using:

trigger:
  - platform: state
    entity_id: event.smartghar_..._fill_event
    not_to: ['unknown', 'unavailable']

---

Services

Service	Purpose
smartghar.refill_marker	Manually log a refill (volume, source, cost, note). Fires smartghar_refill_marker HA event for automations to act on. Useful when auto-detection misses a fast fill, or to record metadata like vendor / cost.

Example call:

service: smartghar.refill_marker
data:
  tank: sensor.smartghar_<hub>_tank_1_level
  volume_l: 5000
  source: tanker
  cost: 450
  note: Sharma Tankers, receipt 4521

---

Diagnostics

Settings → Devices & Services → SmartGhar → ⋮ → Download diagnostics produces a redacted JSON dump of the integration's state for bug reports. Hub IDs, hostnames, and tokens are auto-redacted.

---

Things deliberately NOT exposed

These live in the SmartGhar PWA / local web UI only — the integration doesn't expose them by design:

• Wi-Fi credential editing (sensitive)
• MQTT credentials (sensitive)
• TX pairing / unpairing flow (workflow with state machine, needs guided UX)
• Tank deletion (destructive — PWA has confirmation flow with tank-name re-entry)
• Factory reset (catastrophic without a confirm dialog)
• Sensor calibration min/max distance values (require guided flow to set correctly)

Principle: HA is for monitoring + everyday tweaks. The PWA is for setup, pairing, calibration, and destructive ops. See the Three-Surface Parity rule for the full reasoning.