TapHome

Shelly UNI

Packet Parser → MQTT
Submitted by
Last updated: 04. 2026
Shelly UNI

The Shelly UNI is a compact universal Wi-Fi I/O module (20 × 33 × 13 mm) from the Shelly Gen1 platform. It provides one ADC voltage input, two potential-free open-collector outputs and two digital inputs — designed to retrofit legacy appliances without a hub.

TapHome communicates with the device over MQTT. The template subscribes to the shellies/<prefix>/... topic tree and publishes commands to .../relay/{0,1}/command. The module exposes 5 devices: 1 analog input, 2 switches and 2 reed contacts.

Hardware connection

Power supply

Shelly UNI is a low-voltage module and cannot be powered directly from the 230 V mains. Supply either:

  • 12–36 V DC via Red (+) and Black (GND), or
  • 12–24 V AC via Red and Black (no polarity)

An external low-voltage power adapter is required. Device consumption is below 1 W.

Do not connect the Red/Black leads to mains voltage. Hazardous voltage may still be present on the IN_1 / IN_2 / OUT1 / OUT2 terminals depending on the external circuit — installation must be performed by a qualified electrician.

Pigtail wiring legend

The device ships with a color-coded pigtail cable:

WireTerminalFunction
RedVCC12–36 V DC (or 12–24 V AC together with Black)
BlackGNDGround (or AC phase with Red)
WhiteADC_INAnalog input (0–12 V or 0–30 V range)
YellowVCC_SENSOR3.3 V DC output for one-wire sensors
BlueDATA_SENSOROne-wire data (DS18B20 / DHT22)
GreenGND_SENSORSensor ground
Light brownIN_1Digital input 1
Dark brownIN_2Digital input 2

The two potential-free outputs are marked OUT1 and OUT2 on the module body.

Digital inputs (IN_1, IN_2)

Each digital input is potential-free and can be driven by either a DC or AC source:

  • DC: HIGH when ≥ 2.2 V, LOW below 2.2 V, max 36 V DC
  • AC: HIGH when ≥ 12 V, LOW below 12 V, max 24 V AC

Typical use cases are reed contacts (window/door sensors, float switches) and push-buttons shorting the input to GND through an external supply.

Shelly UNI reed contact wiring with DC supply
Shelly UNI reed contact wiring with AC supply
Shelly UNI button/switch wiring with DC supply
Shelly UNI button/switch wiring with AC supply
Potential-free outputs (OUT1, OUT2)

Each output is an open-collector, potential-free contact with the following absolute limits:

  • 100 mA maximum current
  • 300 mW maximum power
  • 24 V AC or 36 V DC maximum switched voltage

These ratings are too low for mains loads — to switch real loads (lights, pumps, valves) connect the outputs to an external relay or contactor and power that relay’s coil from a matching low-voltage source.

Shelly UNI potential-free output wiring diagram
Analog input (ADC)

A single ADC channel on the White (ADC_IN) lead supports two voltage ranges, selectable in the Shelly web UI:

  • 0–12 V — higher resolution for low-voltage signals
  • 0–30 V — wider range for battery / DC-link monitoring

The selected range is stored on the device only — the TapHome template reads the raw published value and cannot detect which range is active. Make sure the Shelly ADC range matches the signal you wire to the White lead.

Shelly UNI ADC input wiring diagram

Configuration

Device ID and MQTT prefix

Each Shelly UNI has a unique Shelly-ID equal to the last 6 characters of its MAC address (e.g. 35FA58). The resulting MQTT topic prefix is shellyuni-<Shelly-ID> (e.g. shellyuni-35fa58).

The Shelly-ID can be found:

  • On the device label (MAC address)
  • In the Shelly web UI: Settings → Device Info
  • Via API: GET http://<device-ip>/settings → device.hostname field

Shelly Gen1 devices advertise themselves via mDNS as shellyuni-<Shelly-ID>.local. You can use this hostname instead of a fixed IP address to reach the web UI.

Enabling MQTT

On a fresh device, MQTT is disabled. Enable it before importing the TapHome template:

  1. Connect to the device’s access point shellyuni-XXXXXX (password printed on the device) or reach it on your LAN
  2. Open the web UI at http://192.168.33.1/ (AP mode) or the LAN IP
  3. Go to Internet & Security → Advanced — Developer Settings
  4. Check Enable action execution via MQTT
  5. Set the broker IP and port (default 1883), leave username and password empty — TapHome does not support MQTT authentication on Gen1
  6. Save and reboot the device

Enabling MQTT disables the Shelly Cloud connection on Gen1 devices. This is by design — the device cannot maintain both connections simultaneously. The Shelly mobile app will no longer control the device over the cloud; use MQTT or the local web UI instead.

Shelly Gen1 devices do not support MQTT over TLS. Communication between the device and the broker is unencrypted (plain MQTT, port 1883). Keep the broker on a trusted local network.

Template setup

When importing the template into TapHome, supply:

  • IpAddress — MQTT broker IP
  • Port — broker port (default 1883)
  • DeviceID — the 6-character Shelly-ID of the specific UNI (e.g. 35fa58)

The DeviceID import parameter is used to build the MQTTprefix custom variable (default shellyuni-$[DeviceID]). If you have set a custom mqtt_id on the Shelly device (overriding the default), edit the MQTTprefix variable on the module after import to match.

Disable HTTP authentication on the Shelly device (Internet & Security → Restrict Login). TapHome does not use HTTP on this template, but leaving auth enabled can complicate troubleshooting and firmware updates.

Device capabilities

Analog voltage measurement

The Analog Input device reads the ADC voltage from shellies/<prefix>/adc/0 and exposes it as a numeric value in volts. The script parses the incoming payload with TODOUBLE(TOSTRING(PAYLOAD)) — no scaling is applied.

The actual measurement range (0–12 V or 0–30 V) is configured on the Shelly device itself and is not reported over MQTT. The TapHome template cannot verify which range is active.

Switch outputs

Both open-collector outputs are exposed as standard TapHome Switch devices:

  • Switch 1 — OUT_1, topic shellies/<prefix>/relay/0, command topic .../relay/0/command
  • Switch 2 — OUT_2, topic shellies/<prefix>/relay/1, command topic .../relay/1/command

The listener maps payload on → ON (St=1) and off → OFF (St=0). Commands from TapHome are published as on / off on the respective command topic.

The outputs are potential-free and limited to 100 mA / 300 mW. Do not connect mains loads directly — use an external relay or contactor for anything heavier than low-power signaling devices.

Digital inputs (reed contacts)

Both digital inputs are exposed as Reed Contact devices with inverted logic:

  • Reed Contact 1 — IN_1, topic shellies/<prefix>/input/0
  • Reed Contact 2 — IN_2, topic shellies/<prefix>/input/1

The Shelly firmware publishes 1 when the input sees a voltage above its threshold and 0 when the input is pulled to GND. Since reed contacts and push-buttons typically short the input to GND in the closed / active state, the TapHome script inverts the payload:

1

Rc := IF(payload = "0", 1, 0)

This means Rc=1 in TapHome = contact closed (active, window open sensor triggered, button pressed), Rc=0 = contact open (inactive).

Additional capabilities

The Shelly UNI hardware also supports up to 3 × DS18B20 temperature sensors on the one-wire bus and — as an alternative — 1 × DHT22 humidity/temperature sensor. These sensors publish on shellies/<prefix>/ext_temperature/{0,1,2} and shellies/<prefix>/ext_humidity/0. The current MQTT template does not wire these topics into TapHome devices; they can be added in a future template update.

Similarly, the device exposes an online/offline LWT topic and short/long-press input events on input_event/{0,1} that are not consumed by this template.

For scene triggers based on button events (short press, long press), the input_event topic can be subscribed to from a separate MQTT client today — the TapHome template only tracks the raw input state.

Troubleshooting

Device not responding
  1. Verify the Shelly UNI is powered (Red/Black on 12–36 V DC or 12–24 V AC) and connected to Wi-Fi
  2. Open the Shelly web UI via the mDNS hostname shellyuni-<Shelly-ID>.local or its DHCP IP
  3. Confirm MQTT is enabled (Internet & Security → Advanced) and the broker IP/port match the TapHome import parameters
  4. Use an MQTT client (e.g. MQTT Explorer) to subscribe to shellies/# and verify the device publishes messages
Switches do not toggle
  1. Check the command topic path — it must be shellies/<prefix>/relay/0/command (not .../relay/0/set)
  2. Confirm that the TapHome module’s MQTTprefix variable matches the topic prefix the device actually publishes on
  3. Remember that the outputs are potential-free — without an external circuit supplying voltage, the output state changes but no load switches
Reed contact state is reversed

The template expects payload=0 to mean “contact closed”. If your external wiring pulls the input HIGH when the contact is active (inverse wiring), the state will appear reversed in TapHome. Rewire so that the contact shorts IN_1 / IN_2 to GND when active, or adjust the logic in a custom script.

ADC value out of expected range

The ADC range (0–12 V or 0–30 V) is set on the device and cannot be read back over MQTT. If the numeric value in TapHome looks wrong (e.g. 2× higher or lower than expected), open the Shelly web UI and check Settings → ADC range. The template assumes the device publishes the voltage directly and does no conversion.

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 UNI Module
Custom Variables
MQTTprefix (string) = shellyuni-$[DeviceID]MQTT topic prefix of the Shelly UNI device — defaults to shellyuni-{DeviceID} and is used as the base for all subscribed/published topics
Pass DeviceID as import parameter; find it in the Shelly web UI → Settings → Device Info (last 6 characters of MAC address). Custom mqtt_id set on the Shelly device overrides this default.
Analog Input Variable Read-only

ADC voltage measurement — dual-range 0–12 V or 0–30 V, selected on the device

numeric Unit: V

Analog Input

Listener
if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/adc/0"
    Va := TODOUBLE(TOSTRING(RECEIVEDMSG.PAYLOAD));
end
Switch 1 Switch

Potential-free open-collector output OUT_1 — max 100 mA / 300 mW, 24 V AC or 36 V DC

string
Values / States: ON · OFF

Switch 1

Write switch state
MQTTPUBLISH("shellies/" + MQTTprefix + "/relay/0/command", if(St, "on", "off"))
Listener
if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/relay/0"
    VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD);

    if(payload = "on", St := 1, St := 0);
end
Switch 2 Switch

Potential-free open-collector output OUT_2 — max 100 mA / 300 mW, 24 V AC or 36 V DC

string
Values / States: ON · OFF

Switch 2

Write switch state
MQTTPUBLISH("shellies/" + MQTTprefix + "/relay/1/command", if(St, "on", "off"))
Listener
if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/relay/1"
    VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD);

    if(payload = "on", St := 1, St := 0);
end
Reed Contact 1 Reed Contact Read-only

Digital input IN_1 — inverted logic, contact shorted to GND = active (1) in TapHome

string

Reed Contact 1

Listener
if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/input/0"
    VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD);

    Rc := if(payload = "0", 1, 0);
end
Reed Contact 2 Reed Contact Read-only

Digital input IN_2 — inverted logic, contact shorted to GND = active (1) in TapHome

string

Reed Contact 2

Listener
if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/input/1"
    VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD);

    Rc := if(payload = "0", 1, 0);
end
Connection: Packet Parser → MQTT
Possible improvements (8)
  • External Temperature Sensor 1 (DS18B20) — Hardware supports up to 3× DS18B20 on the one-wire bus (Blue DATA + Yellow VCC + Green GND). Not wired in this MQTT template; would need a PacketParserVariable listening on ext_temperature/0 (value 999 = invalid).
  • External Temperature Sensor 2 (DS18B20) — Second DS18B20 on the one-wire bus. Same pattern as sensor 1, different index.
  • External Temperature Sensor 3 (DS18B20) — Third DS18B20 on the one-wire bus. Same pattern as sensor 1, different index.
  • External Humidity Sensor (DHT22) — Hardware supports 1× DHT22 humidity/temperature sensor (mutually exclusive with DS18B20 chain). Not wired in this MQTT template; would need a PacketParserVariable on ext_humidity/0 (value 999 = invalid).
  • Connection Status (LWT) — Last-Will-Testament topic — 'true' on connect, 'false' on disconnect. Could be added to detect offline devices.
  • Input 1 Event — JSON payload {event, event_cnt} — short/long press events on IN_1, useful for scene triggers.
  • Input 2 Event — JSON payload {event, event_cnt} — short/long press events on IN_2.
  • Full Status JSON — Full /status JSON published periodically (firmware ≥ 1.8.0). Could be parsed for wifi_sta.rssi, update status, uptime.

Sources