TapHome

Shelly Plus 1PM

Packet Parser → MQTT
Submitted by
Last updated: 04. 2026
Shelly Plus 1PM

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-<DEVICEID>, where <DEVICEID> 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://<device-ip>/rpc/MQTT.GetConfig → client_id field
  • On the device label (MAC address)

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://<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 — 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 shellyplus1pm-<DEVICEID>/#. You should see status messages from the device, including shellyplus1pm-<DEVICEID>/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:

AttributeUnitDescription
Internal temperature°CInternal device temperature — monitors relay and PCB thermal state
VoltageVAC supply voltage at the relay input
CurrentALoad 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

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 (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 Plus 1PM MQTT Module Module
Service Attributes
Internal temperatureInternal device temperature — monitors relay and PCB thermal state
VoltageAC supply voltage at the relay input
CurrentLoad 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

Shelly Plus 1PM MQTT Module

Listener
IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0)
    ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-<deviceid>'. 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
IF(ISNAN(internalTemp), "Unknown", internalTemp + "°C");
Voltage
IF(ISNAN(voltage), "Unknown", voltage + "V");
Current
IF(ISNAN(current), "Unknown", current + "A");
Shelly Plus 1PM MQTT Power Electricity Meter Read-only

Instantaneous power (kW) and cumulative energy (kWh) from MQTT status payload

numeric Unit: kW / kWh

Shelly Plus 1PM MQTT Power

Listener
IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0)
    ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-<deviceid>'. 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
Shelly Plus 1PM MQTT Switch Switch

Relay on/off control via MQTT command topic

boolean
Values / States: ON · OFF

Shelly Plus 1PM MQTT Switch

Write switch state
VAR value := IF(St = 1, "on", "off");
MQTTPUBLISH(plug1topic + "/command/switch:0", value);
Listener
IF(INDEXOF(plug1topic, "shellyplus1pm-deviceid") = 0)
    ADDERROR("Set correct 'plug1topic' value in module variables. Topic format is 'shellyplus1pm-<deviceid>'. 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
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

Sources