TapHome

Shelly H&T Gen3

Packet Parser → MQTT
Submitted by
Last updated: 03. 2026
Shelly H&T Gen3

The Shelly H&T Gen3 is a battery-powered (4x AA) Wi-Fi temperature and humidity sensor with a large e-paper display. TapHome communicates with the device over MQTT using Gen2+ RPC notifications on the events/rpc topic. This is the recommended protocol for battery-operated Shelly Gen3 devices, since the sensor sleeps most of the time and publishes data only on wake-up events.

The template creates a single Temperature & Humidity Sensor device and a module-level Battery service attribute. An offline detection mechanism monitors the last received timestamp and raises warnings or errors when the device has not reported for an extended period.

Configuration

MQTT Client ID

Each Shelly H&T Gen3 has a unique MQTT Client ID in the format shellyhtg3-<MAC12>, where <MAC12> is the full 12-character MAC address in uppercase hex (e.g., shellyhtg3-AABBCCDDEEFF). This ID also serves as the default MQTT topic prefix.

The Client ID can be found:

  • On the device label (MAC address)
  • In the Shelly web UI: Settings → MQTT → Client ID
  • Via API: GET http://<device-ip>/rpc/Mqtt.GetConfig → client_id field
Template setup

After importing the template in TapHome:

  1. Open the Shelly H&T Gen3 MQTT module
  2. Set the MQTT Broker IP to the address of the MQTT broker
  3. Set the Port (default 1883)
  4. Set the MQTT ID import parameter to the device’s Client ID (e.g., shellyhtg3-AABBCCDDEEFF)

The module subscribes to <device-id>/# and the listener scripts parse NotifyStatus JSON-RPC events from the events/rpc topic.

Ensure MQTT is enabled on the Shelly H&T Gen3 and rpc_ntf (RPC notifications) is set to true (the default). The template relies on events/rpc notifications, not individual status topics.

Measurement and reporting behavior

The Shelly H&T Gen3 operates differently depending on the power source:

  • Battery mode — wakes every 1 minute for measurement. Reports to MQTT if temperature changes more than 0.5 °C or humidity changes more than 5%. An unconditional status report is sent every 2 hours if no threshold-based reports were triggered.
  • USB power mode — wakes every 5 minutes for measurement, display update, and reporting on every cycle.

The e-paper display updates when temperature changes more than 0.2 °C or humidity changes more than 3%.

The device is battery-operated and not permanently connected to the MQTT broker. Expect gaps between readings, especially in battery mode. If the sensor location has weak Wi-Fi signal, frequent reconnection attempts can reduce battery life.

Device capabilities

Temperature and humidity

The sensor device reads temperature and humidity from NotifyStatus events on the events/rpc topic:

  • Temperature — ambient temperature in Celsius, read from params['temperature:0'].tC
  • Humidity — relative humidity percentage, read from params['humidity:0'].rh (the listener script divides the value by 100 to convert to the 0–1 range expected by TapHome)

Both values are read-only and update whenever the sensor wakes up and publishes data.

The temperature report threshold is configurable on the device (default 0.5 °C, range 0.5–5.0 °C). The humidity report threshold defaults to 5% (range 1–20%). These thresholds can be adjusted via the Shelly web UI or API to balance reporting frequency against battery life.

Battery monitoring

The module exposes a Battery [%] service attribute that reads the battery charge percentage from params['devicepower:0'].battery.percent in the NotifyStatus event. A low battery warning is triggered when the level drops below 30%.

The battery level updates with every sensor report. On 4x AA batteries, the expected battery life is approximately 1 year under normal conditions.

Offline detection

The template monitors device connectivity using a timestamp-based mechanism. The module listener script stores the Unix timestamp from each NotifyStatus event in the timestamp custom variable. The read script then compares the stored timestamp against the current time:

  • Offline > 12 hours — WARNING: “Device is offline > 12H”
  • Offline > 24 hours — ERROR: “Device is offline > 24H”

This is particularly useful for battery-operated devices that may go silent due to depleted batteries or Wi-Fi connectivity loss.

Additional capabilities

The Shelly H&T Gen3 also publishes an online/offline status via the MQTT Last Will and Testament (LWT) topic, battery voltage in Volts, and external power status (whether USB Type-C is connected). Individual component status topics (status/temperature:0, status/humidity:0, status/devicepower:0) are available when status_ntf is enabled, and temperature is also available in Fahrenheit. The device features an e-paper display with configurable temperature unit and clock format. These capabilities can be added in a future template update.

Troubleshooting

Sensor not reporting data
  1. Verify the Shelly H&T Gen3 is connected to Wi-Fi and MQTT is enabled in the device settings (Settings → MQTT → Enable)
  2. Check that rpc_ntf is set to true (default) — the template requires RPC notifications on events/rpc
  3. Confirm the MQTT ID import parameter matches the device’s Client ID exactly (e.g., shellyhtg3-AABBCCDDEEFF)
  4. Use an MQTT client (e.g., MQTT Explorer) to subscribe to <device-id>/# and verify the sensor publishes NotifyStatus messages on wake-up
  5. Check the device battery level — depleted batteries prevent the sensor from connecting to Wi-Fi
Humidity reading appears incorrect
  1. The TapHome template divides the raw humidity value by 100 (e.g., rh: 55.3 becomes 0.553 in TapHome). This is expected behavior — TapHome uses a 0–1 range internally
  2. The sensor has a configurable humidity offset (Humidity.SetConfig → offset) — verify it is not set to an incorrect value
  3. The operating humidity range of the sensor is 30–70% RH. Readings outside this range may be less accurate
Offline warnings despite sensor working
  1. The offline detection compares the stored timestamp against current time. If the TapHome Core clock is significantly off, false warnings may appear
  2. On battery power, the sensor reports only when thresholds are exceeded or every 2 hours unconditionally — gaps of up to 2 hours between reports are normal
  3. If the sensor is in a location with intermittent Wi-Fi, it may miss reporting windows. Verify Wi-Fi signal strength at the sensor location

How to install in TapHome

Prerequisites

  • Shelly device connected to Wi-Fi (see HTTP connection guide if not done yet)
  • MQTT broker running on your local network (e.g., Mosquitto, Home Assistant, or TapHome built-in broker)
  • TapHome CCU on the same network as the broker

On Gen1 devices, enabling MQTT disables Shelly Cloud. Both cannot run simultaneously. On Gen2/Plus devices this limitation does not apply.

Step 1 — Enable MQTT on the Shelly device

Gen1 devices (Shelly 1, 1PM, 2.5, EM, 3EM, Plug S, RGBW2, Dimmer, TRV…)

  1. Open the Shelly web UI: http://<device-ip>/
  2. Navigate to Internet & Security → Advanced — MQTT
  3. Enable MQTT
  4. Set MQTT Server: <broker-ip>:<port> (e.g., 192.168.1.10:1883)
  5. Optionally set MQTT User and MQTT Password if your broker requires authentication
  6. Click Save — the device will reboot and connect to the broker

Gen2 / Plus devices (Shelly Plus 1, Plus 1PM, Plus 2PM, Plus Plug S, Plus H&T, Pro 3EM…)

  1. Open the Shelly web UI: http://<device-ip>/
  2. Navigate to Settings → MQTT
  3. Enable MQTT
  4. Set Server: <broker-ip>:<port> (e.g., 192.168.1.10:1883)
  5. The Client ID is pre-filled with the device ID (e.g., shellyplus1pm-AABBCCDDEE) — leave as-is unless you have a specific reason to change it
  6. Click Save and reboot the device

To verify MQTT is working, use an MQTT client (e.g., MQTT Explorer) and subscribe to shellies/# (Gen1) or <device-id>/# (Gen2). You should see status messages from the device.

Step 2 — Find the Device ID / MQTT Client ID

Some templates require a Device ID or MQTT Client ID parameter. This is the unique identifier used in MQTT topics.

  • Gen1: found on the label as MAC address (e.g., AABBCCDDEE). Device ID = shelly<model>-<mac>, e.g., shelly1pm-AABBCCDDEE
  • Gen2/Plus: found in the Shelly web UI under Settings → Device Info → Device ID, or on the device label

Step 3 — Configure in TapHome

  1. In TapHome, add a new Packet Parser (MQTT) module
  2. IP Address: enter the MQTT broker IP (e.g., 192.168.1.10)
  3. Port: 1883 (default; use 8883 for TLS)
  4. Device ID / MQTT Client ID: enter the value from Step 2 (if required by the template)
  5. Import the template — TapHome will subscribe to the device topics automatically

Available devices

Shelly H&T Gen3 MQTT Module
Service Attributes
BatteryBattery charge percentage — low battery warning at <30%
Custom Variables

Shelly H&T Gen3 MQTT

Read (module)
if !ISNAN(timestamp)
	DATETIME now := NOW();
	var secondsSeen := now.UNIXTIME - timestamp;
	if secondsSeen > 12 * 60 * 60
		if secondsSeen > 24 * 60 * 60
			ADDERROR("Device is offline > 24H");
		else
			ADDWARNING("Device is offline > 12H");        
		end
	end
end
Listener
if INDEXOF(RECEIVEDMSG.Topic, "events/rpc") > 0
	var ts := PARSEJSON(RECEIVEDMSG.Payload, "params.ts", true);
	if(!ISNULL(ts), timestamp := ts);
    var bat := PARSEJSON(RECEIVEDMSG.Payload, "params['devicepower:0'].battery.percent", true);
	if(!ISNULL(bat), BatteryPercentage := bat);
end

if BatteryPercentage < 30
	ADDWARNING("Low battery (<30%)");
end
Service Attributes
Battery [%]
BatteryPercentage
Temperature & Humidity Sensor Temperature Sensor Read-only

Ambient temperature (°C) and relative humidity from NotifyStatus events — humidity converted to 0–1 range for TapHome

json Unit: °C / %RH json_path

Temperature & Humidity Sensor

Listener
if INDEXOF(RECEIVEDMSG.Topic, "events/rpc") > 0
	var temperature := PARSEJSON(RECEIVEDMSG.Payload, "params['temperature:0'].tC", true);
    if(!ISNULL(temperature), Te := temperature);
    var humidity := PARSEJSON(RECEIVEDMSG.Payload, "params['humidity:0'].rh", true);
    if(!ISNULL(humidity), Hu := humidity / 100);
end
Connection: Packet Parser → MQTT
Possible improvements (8)
  • Temperature Status Topic — Individual status topic (when status_ntf: true). Template uses events/rpc instead — functionally equivalent.
  • Humidity Status Topic — Individual status topic (when status_ntf: true). Template uses events/rpc instead — functionally equivalent.
  • DevicePower Status Topic — Individual status topic with battery.V (voltage). Template already reads battery.percent from events/rpc.
  • Connection Status (LWT) — Last Will and Testament topic — true on connect, false on disconnect. Template uses timestamp-based offline detection instead.
  • Temperature in Fahrenheit — Temperature also available in Fahrenheit (tF field). Template uses tC only.
  • E-Paper Display Configuration — Temperature unit (C/F) and clock format (12/24/disabled) — display-only configuration, not sensor data.
  • Battery Voltage — Battery voltage in Volts. Template reads only percent, not voltage.
  • External Power Status — Whether USB Type-C power is connected. Could distinguish battery vs USB power mode.

Sources