TapHome

Shelly UNI

Packet Parser → MQTT
Inviato da
Ultimo aggiornamento: 04. 2026
Shelly UNI

Shelly UNI è un modulo I/O universale Wi-Fi compatto (20 × 33 × 13 mm) della piattaforma Shelly Gen1. Offre un ingresso di tensione ADC, due uscite open-collector a potenziale libero e due ingressi digitali — pensato per aggiornare apparecchi esistenti senza centrale.

TapHome comunica con il dispositivo tramite MQTT. Il template si sottoscrive all’albero dei topic shellies/<prefix>/... e pubblica comandi su .../relay/{0,1}/command. Il modulo espone 5 dispositivi: 1 ingresso analogico, 2 interruttori e 2 contatti reed.

Collegamento hardware

Alimentazione

Shelly UNI è un modulo a bassa tensione e non può essere alimentato direttamente dalla rete 230 V. Alimentalo con:

  • 12–36 V DC tramite conduttore rosso (+) e nero (GND), oppure
  • 12–24 V AC tramite conduttore rosso e nero (senza polarità)

È necessario un alimentatore esterno a bassa tensione. Il consumo del dispositivo è inferiore a 1 W.

Non collegare i conduttori rosso/nero alla tensione di rete. Sui morsetti IN_1 / IN_2 / OUT1 / OUT2 può essere presente tensione pericolosa in base al circuito esterno — l’installazione deve essere eseguita da un elettricista qualificato.

Legenda cavo pigtail

Il dispositivo è fornito con un cavo pigtail a colori:

ConduttoreMorsettoFunzione
RossoVCC12–36 V DC (o 12–24 V AC insieme al nero)
NeroGNDMassa (o fase AC con il rosso)
BiancoADC_INIngresso analogico (range 0–12 V o 0–30 V)
GialloVCC_SENSORUscita 3,3 V DC per sensori one-wire
BluDATA_SENSORDati one-wire (DS18B20 / DHT22)
VerdeGND_SENSORMassa del sensore
Marrone chiaroIN_1Ingresso digitale 1
Marrone scuroIN_2Ingresso digitale 2

Le due uscite a potenziale libero sono contrassegnate con OUT1 e OUT2 sul corpo del modulo.

Ingressi digitali (IN_1, IN_2)

Ogni ingresso digitale è a potenziale libero e può essere pilotato da una sorgente DC o AC:

  • DC: HIGH quando ≥ 2,2 V, LOW sotto 2,2 V, max 36 V DC
  • AC: HIGH quando ≥ 12 V, LOW sotto 12 V, max 24 V AC

Casi d’uso tipici sono i contatti reed (sensori di finestre/porte, interruttori a galleggiante) e i pulsanti che cortocircuitano l’ingresso su GND tramite un’alimentazione esterna.

Cablaggio contatto reed Shelly UNI con alimentazione DC
Cablaggio contatto reed Shelly UNI con alimentazione AC
Cablaggio pulsante/interruttore Shelly UNI con alimentazione DC
Cablaggio pulsante/interruttore Shelly UNI con alimentazione AC
Uscite a potenziale libero (OUT1, OUT2)

Ogni uscita è un contatto open-collector a potenziale libero con i seguenti limiti assoluti:

  • corrente massima 100 mA
  • potenza massima 300 mW
  • tensione massima commutata 24 V AC o 36 V DC

Questi valori sono troppo bassi per carichi di rete — per commutare carichi reali (luci, pompe, valvole) collega le uscite a un relè o contattore esterno e alimenta la bobina di quel relè da una sorgente a bassa tensione adeguata.

Schema di cablaggio dell'uscita a potenziale libero di Shelly UNI
Ingresso analogico (ADC)

Un singolo canale ADC sul conduttore bianco (ADC_IN) supporta due intervalli di tensione, selezionabili nell’interfaccia web di Shelly:

  • 0–12 V — risoluzione più alta per segnali a bassa tensione
  • 0–30 V — intervallo più ampio per monitoraggio di batteria / DC-link

L’intervallo selezionato è memorizzato solo sul dispositivo — il template TapHome legge il valore grezzo pubblicato e non può rilevare quale intervallo sia attivo. Assicurati che l’intervallo ADC di Shelly corrisponda al segnale cablato al conduttore bianco.

Schema di cablaggio dell'ingresso ADC di Shelly UNI

Configurazione

Shelly-ID e prefisso MQTT

Ogni Shelly UNI ha uno Shelly-ID univoco pari agli ultimi 6 caratteri del suo MAC address (es. 35FA58). Il prefisso di topic MQTT risultante è shellyuni-<Shelly-ID> (es. shellyuni-35fa58).

Lo Shelly-ID si trova:

  • Sull’etichetta del dispositivo (MAC address)
  • Nell’interfaccia web Shelly: Settings → Device Info
  • Tramite API: GET http://<device-ip>/settings → campo device.hostname

I dispositivi Shelly Gen1 si annunciano via mDNS come shellyuni-<Shelly-ID>.local. Puoi usare questo hostname al posto di un IP fisso per raggiungere l’interfaccia web.

Abilitare MQTT

Su un dispositivo nuovo MQTT è disabilitato. Abilitalo prima di importare il template TapHome:

  1. Connettiti all’access point del dispositivo shellyuni-XXXXXX (la password è stampata sul dispositivo) o raggiungilo sulla LAN
  2. Apri l’interfaccia web su http://192.168.33.1/ (modalità AP) o sull’IP LAN
  3. Vai a Internet & Security → Advanced — Developer Settings
  4. Spunta Enable action execution via MQTT
  5. Imposta IP e porta del broker (default 1883), lascia vuoti username e password — TapHome non supporta l’autenticazione MQTT su Gen1
  6. Salva e riavvia il dispositivo

Abilitare MQTT disabilita la connessione a Shelly Cloud sui dispositivi Gen1. È voluto — il dispositivo non può mantenere entrambe le connessioni contemporaneamente. L’app mobile Shelly non controllerà più il dispositivo tramite cloud; usa MQTT o l’interfaccia web locale.

I dispositivi Shelly Gen1 non supportano MQTT su TLS. La comunicazione tra dispositivo e broker non è cifrata (MQTT semplice, porta 1883). Mantieni il broker su una rete locale fidata.

Configurazione del template

Durante l’import del template in TapHome fornisci:

  • IpAddress — IP del broker MQTT
  • Port — porta del broker (default 1883)
  • DeviceID — lo Shelly-ID di 6 caratteri dell’UNI specifico (es. 35fa58)

Il parametro di import DeviceID è usato per costruire la variabile custom MQTTprefix (default shellyuni-$[DeviceID]). Se hai impostato un mqtt_id personalizzato sul dispositivo Shelly (sovrascrivendo quello predefinito), modifica dopo l’import la variabile MQTTprefix del modulo in modo che corrisponda.

Disabilita l’autenticazione HTTP sul dispositivo Shelly (Internet & Security → Restrict Login). TapHome in questo template non usa HTTP, ma lasciarla attiva può complicare diagnostica e aggiornamenti firmware.

Capacità del dispositivo

Misurazione tensione analogica

Il dispositivo Analog Input legge la tensione ADC da shellies/<prefix>/adc/0 e la espone come valore numerico in volt. Lo script elabora il payload in ingresso con TODOUBLE(TOSTRING(PAYLOAD)) — senza alcuna scalatura.

L’intervallo di misura effettivo (0–12 V o 0–30 V) è configurato direttamente sul dispositivo Shelly e non viene trasmesso via MQTT. Il template TapHome non può verificare quale intervallo sia attivo.

Uscite di commutazione

Entrambe le uscite open-collector sono esposte come normali dispositivi Switch di TapHome:

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

Il listener mappa il payload on → ON (St=1) e off → OFF (St=0). I comandi da TapHome vengono pubblicati come on / off sul rispettivo topic di comando.

Le uscite sono a potenziale libero e limitate a 100 mA / 300 mW. Non collegare carichi di rete direttamente — per qualsiasi cosa più pesante di dispositivi di segnalazione a bassa potenza, usa un relè o un contattore esterno.

Ingressi digitali (contatti reed)

Entrambi gli ingressi digitali sono esposti come dispositivi Reed Contact con logica invertita:

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

Il firmware Shelly pubblica 1 quando l’ingresso vede una tensione sopra la soglia e 0 quando l’ingresso è tirato a GND. Poiché i contatti reed e i pulsanti tipicamente cortocircuitano l’ingresso a GND nello stato chiuso / attivo, lo script TapHome inverte il payload:

1

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

Questo significa che Rc=1 in TapHome = contatto chiuso (attivo, sensore finestra aperta scattato, pulsante premuto), Rc=0 = contatto aperto (inattivo).

Ulteriori capacità

L’hardware di Shelly UNI supporta inoltre fino a 3 × DS18B20 sensori di temperatura sul bus one-wire e — in alternativa — 1 × DHT22 sensore di umidità/temperatura. Questi sensori pubblicano su shellies/<prefix>/ext_temperature/{0,1,2} e shellies/<prefix>/ext_humidity/0. L’attuale template MQTT non collega questi topic a dispositivi TapHome; possono essere aggiunti in un futuro aggiornamento del template.

Analogamente, il dispositivo espone un topic online/offline LWT e eventi di input di pressione breve/lunga su input_event/{0,1} che non sono consumati da questo template.

Per trigger di scena basati su eventi dei pulsanti (pressione breve, lunga), il topic input_event può essere sottoscritto oggi da un client MQTT separato — il template TapHome traccia solo lo stato grezzo dell’ingresso.

Risoluzione dei problemi

Il dispositivo non risponde
  1. Verifica che Shelly UNI sia alimentato (rosso/nero su 12–36 V DC o 12–24 V AC) e connesso al Wi-Fi
  2. Apri l’interfaccia web Shelly tramite l’hostname mDNS shellyuni-<Shelly-ID>.local o il suo IP DHCP
  3. Conferma che MQTT sia abilitato (Internet & Security → Advanced) e che IP/porta del broker corrispondano ai parametri di import TapHome
  4. Usa un client MQTT (es. MQTT Explorer) per sottoscriverti a shellies/# e verifica che il dispositivo pubblichi messaggi
Gli interruttori non commutano
  1. Controlla il percorso del topic di comando — deve essere shellies/<prefix>/relay/0/command (non .../relay/0/set)
  2. Verifica che la variabile MQTTprefix del modulo TapHome corrisponda al prefisso di topic su cui il dispositivo pubblica realmente
  3. Ricorda che le uscite sono a potenziale libero — senza un circuito esterno che fornisca tensione, lo stato dell’uscita cambia ma nessun carico viene commutato
Lo stato del contatto reed è invertito

Il template si aspetta che payload=0 significhi „contatto chiuso". Se il tuo cablaggio esterno tira l’ingresso a HIGH quando il contatto è attivo (cablaggio inverso), lo stato in TapHome apparirà invertito. Ricabla in modo che il contatto cortocircuiti IN_1 / IN_2 su GND quando attivo, oppure modifica la logica in uno script personalizzato.

Valore ADC fuori dall’intervallo atteso

L’intervallo ADC (0–12 V o 0–30 V) è impostato sul dispositivo e non può essere riletto via MQTT. Se il valore numerico in TapHome sembra errato (es. 2× più alto o più basso del previsto), apri l’interfaccia web Shelly e controlla Settings → ADC range. Il template assume che il dispositivo pubblichi la tensione direttamente e non effettua alcuna conversione.

Come installare in TapHome

Prerequisiti

  • Dispositivo Shelly connesso al Wi-Fi (vedi la guida alla connessione HTTP se non ancora fatto)
  • Broker MQTT attivo sulla rete locale (es. Mosquitto, Home Assistant o il broker integrato di TapHome)
  • TapHome CCU sulla stessa rete del broker

Sui dispositivi Gen1, l’attivazione di MQTT disabilita Shelly Cloud. Entrambi non possono funzionare contemporaneamente. Sui dispositivi Gen2/Plus questa limitazione non si applica.

Passaggio 1 — Abilitare MQTT sul dispositivo Shelly

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

  1. Apri l’interfaccia web Shelly: http://<device-ip>/
  2. Vai su Internet & Security → Advanced — MQTT
  3. Abilita MQTT
  4. Imposta MQTT Server: <broker-ip>:<port> (es. 192.168.1.10:1883)
  5. Opzionalmente imposta MQTT User e MQTT Password se il broker richiede l’autenticazione
  6. Clicca su Save — il dispositivo si riavvierà e si connetterà al broker

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

  1. Apri l’interfaccia web Shelly: http://<device-ip>/
  2. Vai su Settings → MQTT
  3. Abilita MQTT
  4. Imposta Server: <broker-ip>:<port> (es. 192.168.1.10:1883)
  5. Il Client ID è precompilato con l’ID del dispositivo (es. shellyplus1pm-AABBCCDDEE) — lascialo così a meno che tu non abbia un motivo specifico per cambiarlo
  6. Clicca su Save e riavvia il dispositivo

Per verificare che MQTT funzioni, usa un client MQTT (es. MQTT Explorer) e sottoscrivi shellies/# (Gen1) o <device-id>/# (Gen2). Dovresti vedere i messaggi di stato dal dispositivo.

Passaggio 2 — Trovare il Device ID / MQTT Client ID

Alcuni template richiedono un parametro Device ID o MQTT Client ID. Questo è l’identificatore univoco utilizzato nei topic MQTT.

  • Gen1: si trova sull’etichetta come indirizzo MAC (es. AABBCCDDEE). Device ID = shelly<model>-<mac>, es. shelly1pm-AABBCCDDEE
  • Gen2/Plus: si trova nell’interfaccia web Shelly sotto Settings → Device Info → Device ID, oppure sull’etichetta del dispositivo

Passaggio 3 — Configurazione in TapHome

  1. In TapHome, aggiungi un nuovo modulo Packet Parser (MQTT)
  2. IP Address: inserisci l’IP del broker MQTT (es. 192.168.1.10)
  3. Port: 1883 (predefinito; usa 8883 per TLS)
  4. Device ID / MQTT Client ID: inserisci il valore dal passaggio 2 (se richiesto dal template)
  5. Importa il template — TapHome si sottoscriverà automaticamente ai topic del dispositivo

Dispositivi disponibili

Shelly UNI Modulo
Variabili personalizzate
MQTTprefix (string) = shellyuni-$[DeviceID]Prefisso del topic MQTT del Shelly UNI — predefinito shellyuni-{DeviceID}, usato come base per tutti i topic sottoscritti/pubblicati
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.
Ingresso analogico Variabile Solo lettura

Misurazione tensione ADC — doppio intervallo 0–12 V o 0–30 V, selezionato sul dispositivo

numeric Unità: V

Ingresso analogico

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

Uscita open-collector a potenziale libero OUT_1 — max 100 mA / 300 mW, 24 V AC o 36 V DC

string
Valori / Stati: ON · OFF

Interruttore 1

Scrittura stato interruttore
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
Interruttore 2 Interruttore

Uscita open-collector a potenziale libero OUT_2 — max 100 mA / 300 mW, 24 V AC o 36 V DC

string
Valori / Stati: ON · OFF

Interruttore 2

Scrittura stato interruttore
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
Contatto reed 1 Contatto reed Solo lettura

Ingresso digitale IN_1 — logica invertita, contatto chiuso verso GND = attivo (1) in TapHome

string

Contatto reed 1

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

    Rc := if(payload = "0", 1, 0);
end
Contatto reed 2 Contatto reed Solo lettura

Ingresso digitale IN_2 — logica invertita, contatto chiuso verso GND = attivo (1) in TapHome

string

Contatto reed 2

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

    Rc := if(payload = "0", 1, 0);
end
Connessione: Packet Parser → MQTT
Possibili miglioramenti (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.

Fonti