--- title: "Shelly UNI" description: "Controlla due uscite a potenziale libero, leggi due ingressi digitali e una tensione ADC su Shelly UNI via MQTT. Template per Shelly UNI Gen1." url: "https://taphome.com/it/compatibility/shelly-uni-mqtt/" language: it lastmod: 2026-10-08 generator: hugo ai: topics: ["mqtt","i/o-module","shelly","gen1","wifi","low-voltage"] questions: ["Come integrare Shelly UNI con TapHome tramite MQTT?","Cosa controlla e misura il template Shelly UNI per TapHome?","Come collegare le uscite a potenziale libero di Shelly UNI a un carico reale?","Perché il contatto reed del mio Shelly UNI mostra lo stato invertito in TapHome?","Quale intervallo di tensione posso misurare sull'ingresso ADC di Shelly UNI?","Shelly UNI può leggere sensori DS18B20 di temperatura o DHT22 di umidità in TapHome?"] --- # Shelly UNI Comunicazione: Packet Parser → MQTT - [Shelly UNI — knowledge base](https://kb.shelly.cloud/knowledge-base/shelly-uni) - [Shelly UNI — documentazione](https://www.shelly.com/blogs/documentation/shelly-uni) > Indirizzo di rete > > Con il broker MQTT integrato in TapHome, inserisci `127.0.0.1` come indirizzo del broker in TapHome. Nel dispositivo inserisci l’indirizzo IP del TapHome Core e assegna al Core una prenotazione IP nel router. > > [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/) ## Guida all'integrazione 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//...` 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. > [!WARNING] > 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: | Conduttore | Morsetto | Funzione | |------------|----------|----------| | Rosso | VCC | 12–36 V DC (o 12–24 V AC insieme al nero) | | Nero | GND | Massa (o fase AC con il rosso) | | Bianco | ADC_IN | Ingresso analogico (range 0–12 V o 0–30 V) | | Giallo | VCC_SENSOR | Uscita 3,3 V DC per sensori one-wire | | Blu | DATA_SENSOR | Dati one-wire (DS18B20 / DHT22) | | Verde | GND_SENSOR | Massa del sensore | | Marrone chiaro | IN_1 | Ingresso digitale 1 | | Marrone scuro | IN_2 | Ingresso 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](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-reed-contact-dc_hu_4be040d051e42061.jpg) ![Cablaggio contatto reed Shelly UNI con alimentazione AC](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-reed-contact-ac_hu_425daade8b447828.jpg) ![Cablaggio pulsante/interruttore Shelly UNI con alimentazione DC](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-button-switch-dc_hu_c95c9802866cc9c7.jpg) ![Cablaggio pulsante/interruttore Shelly UNI con alimentazione AC](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-button-switch-ac_hu_f9d3f31ed08b9743.jpg) ### 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](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-load-output_hu_5cd4aa406bacbcc0.jpg) ### 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](https://taphome.com/images/compatibility/shelly-uni-mqtt/wiring-adc-input_hu_b1b1677c93ad99cb.jpg) ## 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-` (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:///settings` → campo `device.hostname` > [!TIP] > I dispositivi Shelly Gen1 si annunciano via mDNS come `shellyuni-.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 > [!WARNING] > 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. > [!WARNING] > 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. > [!TIP] > 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//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//relay/0`, topic comando `.../relay/0/command` - **Switch 2** — OUT_2, topic `shellies//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. > [!WARNING] > 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//input/0` - **Reed Contact 2** — IN_2, topic `shellies//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: ```taphome 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//ext_temperature/{0,1,2}` e `shellies//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. > [!TIP] > 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-.local` o il suo IP DHCP 3. Conferma che MQTT sia abilitato (**Internet & Security** → **Advanced — Developer Settings**) 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//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 (2,4 GHz), ad es. tramite l'app Shelly o l'access point del dispositivo stesso - Broker MQTT attivo sulla rete locale (es. Mosquitto, Home Assistant o il broker integrato di TapHome) - TapHome CCU sulla stessa rete del broker > [!WARNING] > 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:///` 2. Vai su **Internet & Security** → **Advanced — MQTT** 3. Abilita **MQTT** 4. Imposta **MQTT Server**: `:` (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:///` 2. Vai su **Settings** → **MQTT** 3. Abilita **MQTT** 4. Imposta **Server**: `:` (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 Con il broker integrato di TapHome, `` è l'indirizzo IP del TapHome Core. Assegna al Core una prenotazione IP nel router, altrimenti il dispositivo perde il broker quando il router cambia l'indirizzo → [Preparazione della rete](https://taphome.com/it/docs/setup/network-preparation/). > [!TIP] > Per verificare che MQTT funzioni, usa un client MQTT (es. MQTT Explorer) e sottoscrivi `shellies/#` (Gen1) o `/#` (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-`, 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:** `127.0.0.1` per il broker integrato di TapHome (l'unità di controllo si connette a sé stessa, l'indirizzo non cambia mai); per un broker esterno il suo indirizzo IP (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 5 Questi dispositivi compaiono in TapHome dopo l'importazione. 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 Listener ```taphome if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/adc/0" Va := TODOUBLE(TOSTRING(RECEIVEDMSG.PAYLOAD)); end ``` Interruttore 1 Interruttore Lettura e scrittura 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 Scrittura stato interruttore ```taphome MQTTPUBLISH("shellies/" + MQTTprefix + "/relay/0/command", if(St, "on", "off")) ``` Listener ```taphome if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/relay/0" VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD); if(payload = "on", St := 1, St := 0); end ``` Interruttore 2 Interruttore Lettura e scrittura 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 Scrittura stato interruttore ```taphome MQTTPUBLISH("shellies/" + MQTTprefix + "/relay/1/command", if(St, "on", "off")) ``` Listener ```taphome 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 Listener ```taphome 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 Listener ```taphome if RECEIVEDMSG.TOPIC = "shellies/" + MQTTprefix + "/input/1" VAR payload := TOSTRING(RECEIVEDMSG.PAYLOAD); Rc := if(payload = "0", 1, 0); end ``` **Connessione:** Packet Parser → MQTT • Hostname: `shellyuni-{shelly-id}.local` 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. ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |--------------------------|---------------| | Mqtt Broker Indirizzo IP | `192.168.0.1` | | Mqtt Broker port | `1883` | | Device ID | `XXXXXXXXX` | ## Fonti - Shelly Gen1 API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/) 2026-03-12 - Home Assistant Shelly Integration [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-12 - Shelly UNI Knowledge Base [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-uni) 2026-04-16 - Shelly UNI Documentation (shelly.com) [www.shelly.com](https://www.shelly.com/blogs/documentation/shelly-uni) 2026-04-16 - Shelly UNI User Guide [shellysa.co.za](https://shellysa.co.za/wp-content/uploads/2021/04/Shelly-UNI-User-Guide.pdf) 2026-04-16 [PDF](https://taphome.com/compatibility/devices/shelly-uni-mqtt/manufacturer/shelly-uni-user-guide.pdf) I documenti del produttore sono © dei rispettivi proprietari. Sono forniti così come pubblicati dal produttore, solo a titolo informativo. ## Documentazione correlata - [MQTT Integration](https://taphome.com/it/compatibility/mqtt-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/) - [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/) - [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/) - [Broker MQTT](https://taphome.com/it/docs/integration/packet-parser/mqtt-broker/) - [Script listener](https://taphome.com/it/docs/script/listener-scripts/)