--- title: "Shelly Plus 1PM" description: "Shelly Plus 1PM Gen2+ relay with power metering via MQTT. Real-time power (kW), energy (kWh), voltage, current and temperature through MQTT broker." url: "https://taphome.com/en/compatibility/shelly-plus-1pm-mqtt/" language: en lastmod: 2026-03-31 generator: hugo ai: topics: ["mqtt","electric-meter","wifi","relay","power-metering","gen2plus"] questions: ["How to integrate Shelly Plus 1PM with TapHome via MQTT?","What does the Shelly Plus 1PM MQTT TapHome template measure?","How to find the Shelly Plus 1PM MQTT Client ID?","Why is my Shelly Plus 1PM MQTT not reporting data?","What diagnostics are available for Shelly Plus 1PM via MQTT?","How to control the Shelly Plus 1PM relay over MQTT from TapHome?"] --- # Shelly Plus 1PM Communication: Packet Parser → MQTT - [Shelly Plus 1PM Product Page](https://www.shelly.com/en/products/shop/shelly-plus-1pm) - [Shelly Gen2+ MQTT API Documentation](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Mqtt/) > Network address > > With the MQTT broker built into TapHome, enter `127.0.0.1` as the broker address in TapHome. In the device, enter the IP address of the TapHome Core and give the Core an IP reservation in the router. > > [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/) ## Integration guide The Shelly Plus 1PM is a compact Gen2+ Wi-Fi relay switch with built-in power metering. It fits behind a standard wall switch and can control one circuit up to 16 A (3500 W at 230 V AC) or 10 A (30 V DC). This is the **MQTT variant** of the TapHome template — the device communicates through an MQTT broker instead of direct HTTP polling, which is useful in multi-controller environments or when the device is behind a different VLAN. The template exposes two devices: an **Electric Meter** for power and energy monitoring, and a **Switch** for relay control. Three module-level service attributes report internal temperature, voltage, and current. ## Configuration ### MQTT Client ID Each Shelly Plus 1PM has a unique MQTT Client ID in the format `shellyplus1pm-`, where `` is the 12-character hex MAC address (e.g., `shellyplus1pm-AABBCCDDEE00`). The Client ID can be found: - In the Shelly web UI: **Settings** → **MQTT** → **Client ID** - Via API: `GET http:///rpc/MQTT.GetConfig` → `client_id` field - On the device label (MAC address) > [!TIP] > This device supports **mDNS discovery**. You can use the hostname `shellyplus1pm-{MAC}.local` instead of an IP address when verifying connectivity. Replace `{MAC}` with the device's full MAC address in lowercase hex (e.g., `shellyplus1pm-aabbccddee00.local`). ### Enabling MQTT 1. Open the Shelly web UI: `http:///` 2. Navigate to **Settings** → **MQTT** 3. Enable **MQTT** 4. Set **Server**: `:` (e.g., `192.168.1.10:1883`) 5. The **Client ID** is pre-filled — leave as-is unless you have a specific reason to change it 6. Click **Save** and reboot the device > [!TIP] > To verify MQTT is working, use an MQTT client (e.g., MQTT Explorer) and subscribe to `shellyplus1pm-/#`. You should see status messages from the device, including `shellyplus1pm-/status/switch:0`. ### Template setup After importing the template in TapHome: 1. Open the **Shelly Plus 1PM MQTT Module** 2. Set the **MQTT Broker IP** and **Port** (default `1883`) 3. Set the **plug1topic** custom variable to the MQTT Client ID of the Shelly Plus 1PM (e.g., `shellyplus1pm-AABBCCDDEE00`) The module subscribes to `{plug1topic}/status/switch:0` and publishes control commands to `{plug1topic}/command/switch:0`. ## Device capabilities ### Power metering The Electric Meter device reads two values from the `{plug1topic}/status/switch:0` MQTT status message: - **Instantaneous power** — `apower` reported in watts, converted to kW by the template (divided by 1000) - **Cumulative energy** — `aenergy.total` reported in watt-hours, converted to kWh by the template (divided by 1000) The meter is read-only — it updates automatically whenever the device publishes a status message to the MQTT broker. ### Relay control The Switch device controls the relay: - **Read state** — subscribes to `{plug1topic}/status/switch:0` and reads the `output` boolean field - **Write state** — publishes `on` or `off` to `{plug1topic}/command/switch:0` The relay supports up to 3500 W / 16 A at 230 V AC. ### Diagnostics Three module-level service attributes are parsed from the same `status/switch:0` JSON payload: | Attribute | Unit | Description | |-----------|------|-------------| | Internal temperature | °C | Internal device temperature — monitors relay and PCB thermal state | | Voltage | V | AC supply voltage at the relay input | | Current | A | Load current through the relay output | All three attributes display "Unknown" until the first MQTT status message arrives (initial value is `NaN`). ### Additional capabilities The Shelly Plus 1PM also exposes power factor, network frequency, returned energy (for bidirectional metering), physical input state, toggle command, auto-off timer, and a force status update action through its MQTT API. These capabilities can be added in a future template update. ## Troubleshooting ### MQTT messages not arriving 1. Verify MQTT is enabled in the Shelly web UI (**Settings** → **MQTT**) 2. Confirm the broker address and port are correct in both the Shelly device and TapHome module settings 3. Check that the `plug1topic` custom variable matches the Shelly's MQTT Client ID exactly (e.g., `shellyplus1pm-AABBCCDDEE00`) 4. Use an MQTT client (e.g., MQTT Explorer) to subscribe to `shellyplus1pm-#` and verify the device publishes messages ### Power readings show zero 1. Confirm the load is connected through the Shelly relay (not bypassed) 2. Check that the relay is turned on — the meter only reads when current flows through the relay 3. Subscribe to `{plug1topic}/status/switch:0` with an MQTT client and verify `apower` returns a non-zero value ### Relay not responding to commands 1. Verify TapHome can reach the MQTT broker (correct IP and port in the module settings) 2. Check that the `plug1topic` value matches the device's MQTT Client ID 3. Test by publishing `on` to `{plug1topic}/command/switch:0` via an MQTT client — the relay should switch on ### Diagnostics showing "Unknown" 1. All three service attributes (temperature, voltage, current) show "Unknown" until the first status message arrives 2. If values remain "Unknown" after the device has been running, check that the MQTT connection is active and status messages are being published 3. Reboot the Shelly device to force a fresh status publish > [!WARNING] > Gen2+ Shelly devices support MQTT with optional TLS. If TLS is not configured, communication between the device and the MQTT broker is unencrypted (plain MQTT, port 1883). For encrypted communication, enable TLS in the Shelly MQTT settings and use port 8883. ## How to install in TapHome ### Prerequisites - Shelly device connected to Wi-Fi (2.4 GHz), e.g. through the Shelly app or the device's own access point - 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 > [!WARNING] > 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:///` 2. Navigate to **Internet & Security** → **Advanced — MQTT** 3. Enable **MQTT** 4. Set **MQTT Server**: `:` (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:///` 2. Navigate to **Settings** → **MQTT** 3. Enable **MQTT** 4. Set **Server**: `:` (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 With the TapHome built-in broker, `` is the IP address of the TapHome Core. Give the Core an IP reservation in the router, otherwise the device loses the broker when the router changes the address → [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/). > [!TIP] > To verify MQTT is working, use an MQTT client (e.g., MQTT Explorer) and subscribe to `shellies/#` (Gen1) or `/#` (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-`, 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:** `127.0.0.1` for the TapHome built-in broker (the control unit connects to itself, the address never changes); for an external broker its IP address (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 2 These devices appear in TapHome after import. Shelly Plus 1PM MQTT Module Module Service Attributes | | | |----------------------|--------------------------------------------------------------------| | Internal temperature | Internal device temperature — monitors relay and PCB thermal state | | Voltage | AC supply voltage at the relay input | | Current | Load current through the relay output | Custom Variables | | | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | `plug1topic` (string) | MQTT Client ID of the Shelly Plus 1PM — format is 'shellyplus1pm-<deviceid>'. Found in device web UI: Settings → MQTT Settings → Client ID | Listener ```taphome IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0) ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-'. The Device ID can be found by opening url 'http://shellyIpAddress', in Settings -> MQTT Settings -> Client ID."); RETURN(-1); END IF(RECEIVEDMSG.TOPIC = plug1topic + "/status/switch:0") internalTemp := PARSEJSON(RECEIVEDMSG.PAYLOAD, "temperature.tC"); voltage := PARSEJSON(RECEIVEDMSG.PAYLOAD, "voltage"); current := PARSEJSON(RECEIVEDMSG.PAYLOAD, "current"); VAR errors := PARSEJSON(RECEIVEDMSG.PAYLOAD, "errors", TRUE); IF (!ISNULL(errors)) VAR errCount := LENGTH(errors); VAR i := 0; VAR errorText := ""; WHILE i < errCount IF LENGTH(errorText) errorText += ", "; END errorText := errorText + GETAT(errors, i); i += 1; LOOP IF LENGTH(errorText) ADDERROR(errorText); END END END ``` Service Attributes Internal temperature ```taphome IF(ISNAN(internalTemp), "Unknown", internalTemp + "°C"); ``` Voltage ```taphome IF(ISNAN(voltage), "Unknown", voltage + "V"); ``` Current ```taphome IF(ISNAN(current), "Unknown", current + "A"); ``` Electric Meter Electricity Meter Read-only Instantaneous power (kW) and cumulative energy (kWh) from MQTT status payload numeric Unit: kW / kWh Listener ```taphome IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0) ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-'. The Device ID can be found by opening url 'http://shellyIpAddress', in Settings -> MQTT Settings -> Client ID."); RETURN(-1); END IF(RECEIVEDMSG.TOPIC = plug1topic + "/status/switch:0") Ed := PARSEJSON(RECEIVEDMSG.PAYLOAD, "apower") / 1000.0; To := PARSEJSON(RECEIVEDMSG.PAYLOAD, "aenergy.total") / 1000.0; END ``` Switch Switch Read and write Relay on/off control via MQTT command topic boolean Values / States: ON · OFF Write switch state ```taphome VAR value := IF(St = 1, "on", "off"); MQTTPUBLISH(plug1topic + "/command/switch:0", value); ``` Listener ```taphome IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0) ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-'. The Device ID can be found by opening url 'http://shellyIpAddress', in Settings -> MQTT Settings -> Client ID."); RETURN(-1); END IF(RECEIVEDMSG.TOPIC = plug1topic + "/status/switch:0") St := PARSEJSON(RECEIVEDMSG.PAYLOAD, "output"); END ``` **Connection:** Packet Parser → MQTT • Hostname: `shellyplus1pm-{MAC}.local` Possible improvements (8) - Power Factor — Power factor value, available in switch:0 status JSON for metered devices - Network Frequency — AC network frequency in Hz, available in switch:0 status JSON - Returned Energy — Returned/exported energy in Wh, for bi-directional metering scenarios - Connection Status — LWT topic — true on connect, false on disconnect. Could detect offline device. - Toggle Command — Toggle relay state; template only supports on/off - Auto-off Timer — Turn ON with auto-off timer in seconds via 'on,N' command - Input State — Physical switch/button input state, available via Input.GetStatus RPC method over MQTT - Force Status Update — Request device to publish current status on all component topics ## Import parameters Enter these values when you import the XML. | Asked in the app | Default | |------------------------|--------------------------| | Mqtt Broker IP address | `192.168.0.1` | | Mqtt Broker port | `1883` | | Shelly MQTT Client ID | `shellyplus1pm-deviceId` | ## Sources - Shelly Gen2+/Gen3 RPC API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/) 2026-03-29 - Shelly Gen2+ Switch Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Switch/) 2026-03-29 - Shelly Gen2+ System (Sys) Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Sys/) 2026-03-29 - Shelly Gen2+ WiFi Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/WiFi/) 2026-03-29 - Shelly Gen2+ MQTT Component API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Mqtt/) 2026-03-29 - Home Assistant Shelly Integration [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-29 - Shelly Plus 1PM Knowledge Base — specs & wiring [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-plus-1pm) 2026-03-31 ## Related Documentation - [MQTT Integration](https://taphome.com/en/compatibility/mqtt-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/) - [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/) - [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/) - [MQTT Broker](https://taphome.com/en/docs/integration/packet-parser/mqtt-broker/) - [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/)