# Shelly temperature + humidity sensors — `shelly_rpc` setup guide

Local-only integration with Shelly Gen2 / Gen3 H&T sensors over MQTT.
**No cloud roundtrip.** The sensors publish to your Otonomo box's
local mosquitto, the driver subscribes, the dashboard updates.

Tested against Shelly H&T Gen3 (battery-powered, ~30–45 min publish
cadence).

---

## Prerequisites

1. **One or more Shelly H&T Gen3 sensors.** ~€25 each on shelly.com
   or Amazon. The Plus / Pro range with plugged power works too;
   battery sensors are most common.
2. **Sensors paired to your WiFi** via the Shelly app.
3. **MQTT pointed at your Otonomo box.** In the Shelly app:
   - Open the device → **Settings → MQTT**
   - **Enable MQTT**
   - **Server**: `<your-otonomo-box-ip>:1883`
   - **Client ID**: leave default (Shelly auto-generates from MAC)
   - **MQTT prefix**: leave as the device ID (e.g. `shellyhtg3-a1b2c3`)
   - **Save** and wait 30 seconds for the device to reconnect.

Otonomo's local mosquitto listens on `:1883` with anonymous access
enabled on the loopback + LAN interface — no auth needed.

---

## Verifying the sensor is publishing

From any machine on your LAN:

```bash
mosquitto_sub -h <otonomo-box-ip> -t 'shelly+/+' -v
```

Within ~5 minutes (battery wake cycle) you should see lines like:

```
shellyhtg3-a1b2c3/status/temperature:0  {"id":0,"tC":21.4,"tF":70.5}
shellyhtg3-a1b2c3/status/humidity:0     {"id":0,"rh":47.5}
```

If nothing appears: the sensor isn't pointing at your box, or it's
asleep. Press the sensor's button once to wake it; the next status
publish goes out within 2 seconds.

---

## Configuring the driver

1. Local UI → `/drivers` → **shelly_rpc** under "Temperature Sensor"
   → **Install**.
2. **Add instance**:

   | Field | Value | Why |
   |-------|-------|-----|
   | Instance ID | `shelly_rpc.dining` (or wherever the sensor is) | Unique per sensor |
   | `mqtt_host` | `127.0.0.1` | local broker is on the same box |
   | `mqtt_port` | `1883` | mosquitto default |
   | `device_id` | `shellyhtg3-a1b2c3` | from the sub output above — required |
   | `cache_file` | `/var/lib/otonomo/shelly_<name>_cache.json` | recommended; survives broker restarts |

3. **Create instance**.

Add one driver instance per Shelly. The cards on the local UI's
overview page show each sensor independently.

---

## Verifying it landed

- Local UI → main page should show a temperature card for your sensor
  with the latest reading + age in seconds/minutes.
- A reading age >60 minutes means the sensor is sleeping between
  cycles — expected behaviour. If it's >2 hours, check the battery.

---

## Common pitfalls

### "no data after 30 minutes"

Battery-powered Shelly H&T publishes only on:
- Wake interrupt (button press, big temp change)
- Scheduled wake (default: every 30–45 min)
- Boot

If it's been more than 45 min and nothing arrived, the sensor lost
its WiFi or your broker IP changed. Open the Shelly app → device
page → there's a connectivity timestamp. If it's stale, hit
**"Refresh"**; the sensor wakes and reconnects.

### Multiple sensors, only one shows up

You added multiple `shelly_rpc` driver instances but only one's
device_id is correct. Check the actual `device_id` strings via
`mosquitto_sub` (see verification section above) and update the
remaining instances' configs at `/drivers`.

### Cache file permissions

The `cache_file` is written by the `otonomo` system user. If you
change the path to a directory it can't write to, the driver still
works but loses readings across broker reconnects (no big deal —
the sensor publishes again within the next wake cycle).

---

## Sensor placement tips

For best results, especially if you'll pair the readings with the
heating orchestrator:

1. **Place in occupied rooms**, not stairwells or hallways. Average
   indoor air, not transit air.
2. **At waist height**, away from direct sun and radiators. Wall
   between sensor and a window minimizes solar drift.
3. **Battery side facing down** if mounted vertically — keeps any
   condensation away from the contacts.

For multi-room targeting, one sensor per heating zone is the typical
arrangement. The cloud orchestrator preferentially uses the sensor
nearest the room's thermostat target.

---

## What Otonomo will do with this driver

**Observe mode**: visualize the room temperature + humidity on the
overview + per-device pages.

**Active mode**, when paired with a heat-pump (`daikin_local`,
`panasonic_aquarea`, `vaillant_ebus`) and the appropriate capability
opt-in:
- Adjusts heat-pump / boiler setpoint to drive the **room** to
  target, not the indoor unit's intake temperature
- Detects open-window-or-door events from a sudden temperature drop
  and pauses heating until the room recovers
- Uses humidity to nudge the dehumidifier control if you also have one

---

## References

- Shelly Gen3 MQTT API:
  https://shelly-api-docs.shelly.cloud/gen2/General/MqttIntroduction
- Otonomo driver source — `otonomo_drivers/drivers/shelly_rpc/`

Independent interoperability tool. Not affiliated with Allterco
Robotics (the maker of Shelly).