TapHome

Shelly Sensor Add-On

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 04. 2026
Shelly Sensor Add-On

Il Shelly Sensor Add-On (commercializzato come Shelly Plus Add-On) è una scheda di espansione galvanicamente isolata che si innesta sul connettore add-on di un dispositivo Shelly Plus, Gen3 o Gen4 compatibile. Estende lo Shelly host con un bus 1-Wire per la temperatura (DS18B20), un ingresso digitale (contatto reed / pulito), un ingresso analogico (0–10 V / 0–100 %) e un voltmetro 0–10 V. L’add-on non è un dispositivo Wi-Fi autonomo — viene letto tramite l’interfaccia HTTP dello Shelly host nella rete locale, quindi TapHome punta all’IP dell’host e non a un IP dedicato dell’add-on.

Il template TapHome espone quattro sensori di temperatura DS18B20 (Component ID 100–103), un contatto reed, un ingresso analogico e un voltmetro. Tutti i valori vengono letti tramite l’API standard Shelly Gen2+ JSON-RPC sulla porta 80 — non è richiesta alcuna connessione cloud.

Collegamento hardware

L’add-on si inserisce sullo Shelly host tramite un connettore seriale proprietario e assorbe 3,3 V DC direttamente dall’host (consumo inferiore a 0,5 W senza sensori). I morsetti accessibili all’utente sono raggruppati in un blocco analogico/digitale e in tre posizioni sensore 1-Wire.

Morsetti analogici e digitali
  • ANALOG IN — ingresso analogico 0–10 V (accuratezza ±5 %, soglia di segnalazione 1 %)
  • DIGITAL IN — ingresso per contatto pulito / interruttore reed (True: da −15 V a 0,5 V, False: da 2,5 V a 15 V)
  • VREF OUT — tensione di riferimento (max. 1 mA) per alimentare sensori con partitore potenziometrico
  • VREF+R1 OUT — tensione di riferimento con resistenza di pull-up da 10 kΩ, progettata per partitori di tensione con NTC e fotoresistore
  • GND × 2 — ritorni di massa
Bus 1-Wire

Tre gruppi a tre terminali (VCC, DATA, GND) condividono internamente una linea dati 1-Wire comune. Fino a 5 sonde DS18B20 possono essere collegate in parallelo al bus condiviso; in alternativa un singolo sensore DHT22 può occupare il bus (il DHT22 blocca la scansione OneWire mentre è attivo). L’uscita VCC totale è limitata a 10 mA, sufficiente per cinque sonde DS18B20.

La sezione massima del conduttore su tutti i morsetti è 1 mm² (17 AWG).

Non mescolare un DHT22 con sonde DS18B20 sullo stesso bus. Il DHT22 blocca l’enumerazione OneWire e lo Shelly host non può rieseguire la scansione del bus mentre è collegato.

Configurazione

Il Shelly Sensor Add-On non ha un proprio indirizzo IP. Durante l’import del template TapHome, inserisci nel parametro IpAddress l’indirizzo IP dello Shelly host (il dispositivo Plus / Gen3 / Gen4 su cui è montato l’add-on) — il valore predefinito è 192.168.0.1.

Tutta la comunicazione usa l’API Gen2+ JSON-RPC via HTTP GET sulla porta 80. Una volta per ciclo di polling, il template legge /rpc/Sys.GetStatus e /rpc/SensorAddon.GetPeripherals in variabili di cache interne, dopodiché ogni script di dispositivo interroga il proprio endpoint dedicato (Temperature.GetStatus, Input.GetStatus o Voltmeter.GetStatus).

Dispositivi host compatibili

L’add-on funziona con i seguenti dispositivi Shelly (dalla lista di compatibilità del produttore):

  • Shelly Plus: 1, 1PM, 1 UL, 1PM UL, 2PM, 2PM UL, i4, i4DC, 0-10 V Dimmer PM, RGBW PM
  • Shelly Gen3: 1, 1PM, 2PM, Shutter, i4, DALI Dimmer, Dimmer 0/1-10 V PM, EM
  • Shelly Gen4: 1, 1PM, 2PM

Il firmware dello Shelly host deve esporre il servizio SensorAddon — le versioni Plus più vecchie potrebbero non averlo. Aggiorna l’host all’ultimo firmware se il menu dell’add-on è assente nell’interfaccia web.

Abilitare le periferiche Add-on

L’add-on si configura una tantum nell’interfaccia web dello Shelly host — TapHome non lo configura. Completa i passaggi seguenti prima di importare il template:

  1. Innesta la scheda add-on sul connettore add-on dello Shelly host e alimenta l’host.
  2. Apri l’interfaccia web dell’host su http://{host-ip}/ ed effettua l’accesso.
  3. Vai in Settings → Add-on e registra l’add-on (in background viene chiamato Sys.SetConfig con device.addon_type = "sensor"). Riavvia l’host se richiesto.
  4. Apri Settings → Components → Peripherals e clicca sul pulsante +.
  5. Scegli il tipo di periferica — Temperature (DS18B20), Digital Input, Analog Input o Voltmeter.
  6. Per DS18B20 clicca Rescan, spunta ogni sonda rilevata e scegli Add and reboot. La prima sonda riceve il Component ID 100, la seconda 101 e così via.
  7. Per Digital Input imposta Mode su Switch o Button (il template legge state da questo Component).
  8. Per Analog Input e Voltmeter le impostazioni predefinite vanno bene — rilevanti sono solo nome e soglia delta.

Il template TapHome fissa i Component ID 100–103 per DS18B20 e ID 100 per contatto reed, ingresso analogico e voltmetro. Quando aggiungi periferiche nell’interfaccia web Shelly, verifica che gli ID assegnati corrispondano a questa numerazione — se elimini e ri-aggiungi una periferica, Shelly assegna il successivo ID libero, che può superare 103 e il dispositivo TapHome smetterà silenziosamente di ricevere dati.

Prima di rimuovere una periferica, annota il suo Component ID. Se sostituisci una sonda DS18B20, preferisci l’azione Edit → Update address nell’interfaccia web — in questo modo il Component ID rimane invariato.

Sull’host Shelly la HTTP Digest Authentication deve essere disabilitata — TapHome non invia richieste autenticate. Lascia il dispositivo senza autenticazione o limita l’accesso a livello di rete.

Funzionalità del dispositivo

Il template raggruppa sette dispositivi sensore di sola lettura sotto un unico modulo HTTP che punta allo Shelly host.

Sonde di temperatura (DS18B20)

Vengono esposte quattro sonde di temperatura DS18B20 OneWire, una per Component ID 100–103:

  • Temperature Sensor DS18B20 (100) — legge /rpc/Temperature.GetStatus?id=100 → tC (°C)
  • Temperature Sensor DS18B20 (101) — legge /rpc/Temperature.GetStatus?id=101 → tC
  • Temperature Sensor DS18B20 (102) — legge /rpc/Temperature.GetStatus?id=102 → tC
  • Temperature Sensor DS18B20 (103) — legge /rpc/Temperature.GetStatus?id=103 → tC

Ogni dispositivo dispone di una variabile personalizzata Id configurabile dall’utente (il valore predefinito corrisponde alla posizione). L’intervallo di polling è di 15 secondi per sonda. L’interfaccia web Shelly consente la regolazione fine della soglia delta (0,1–5 °C) e dell’offset (±50 °C) di ogni sonda per la calibrazione.

Contatto reed (ingresso digitale)

Reed Contact (100) legge /rpc/Input.GetStatus?id=100 → state (boolean). Nell’interfaccia Shelly l’ingresso deve essere configurato come Switch o Button (non Analog o Count). Intervallo di polling: 2,5 secondi. Il valore predefinito della variabile Id è 100.

Ingresso analogico

Analog Input (100) legge /rpc/Input.GetStatus?id=100 → percent, dividendolo per 100 in modo che il valore sia normalizzato alla frazione 0,0–1,0 attesa da TapHome per gli ingressi analogici. L’ingresso deve essere configurato come Analog nell’interfaccia Shelly. Accuratezza ±5 %, soglia di segnalazione 1 %. Intervallo di polling: 2,5 secondi.

Nota che il contatto reed e l’ingresso analogico condividono il Component ID 100 — l’hardware Shelly dispone di un solo ingresso digitale e di un solo ingresso analogico sull’add-on, e la modalità attiva è determinata dal type dell’ingresso nell’interfaccia web (switch/button vs analog). In TapHome usa il dispositivo Reed Contact oppure l’Analog Input, non entrambi contemporaneamente.

Voltmetro

Voltmeter (100) legge /rpc/Voltmeter.GetStatus?id=100 → voltage (V). L’intervallo è 0–10 V con accuratezza ±5 % e soglia di segnalazione 0,1 V. È modellato come PacketParserVariable con capacità sensor — la tensione grezza viene esposta come valore scalare, non come tipo voltmetro dedicato. Intervallo di polling: 15 secondi.

Funzionalità aggiuntive

Il Shelly Sensor Add-On supporta nativamente anche un sensore di temperatura e umidità DHT22 (una singola sonda che crea sull’host i Component accoppiati temperature:100 e humidity:100). Il template TapHome collega la temperatura su tutti e quattro i dispositivi DS18B20 ma imposta lo script dell’umidità a NaN — l’umidità DHT22 non è quindi esposta. Gli utenti che necessitano dell’umidità possono estendere il template con uno script di lettura separato su /rpc/Humidity.GetStatus?id=100.

Esistono due ulteriori funzionalità a livello hardware/firmware ma fuori dallo scope di questo template: un quinto slot DS18B20 (il bus Shelly supporta fino a cinque sonde; il template interroga solo gli ID 100–103) e la modalità contatore di impulsi dell’ingresso digitale (counts.total, counts.by_minute, freq), che richiede di configurare l’ingresso come type=count nell’interfaccia Shelly. Entrambe potranno essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

L’host Shelly non risponde
  1. Verifica che lo Shelly host sia connesso al Wi-Fi e abbia un IP valido.
  2. Prova a usare l’hostname mDNS dell’host (es. shellyplus1pm-AABBCCDDEE.local) al posto dell’IP — l’IP potrebbe essere cambiato dopo un rinnovo DHCP. L’add-on eredita l’hostname dell’host, non ne ha uno proprio.
  3. Apri nel browser http://{host-ip}/rpc/Shelly.GetDeviceInfo — se risponde con JSON, l’host è raggiungibile.
  4. Verifica che il CCU TapHome e lo Shelly host siano sulla stessa rete / VLAN.
  5. Assicurati che la HTTP Digest Authentication sia disabilitata nell’interfaccia web Shelly.
I sensori non mostrano dati
  1. Apri l’interfaccia web Shelly → Components → Peripherals. Conferma che la periferica sia elencata con esattamente il Component ID atteso dal template (temperature:100–103, input:100, voltmeter:100). Se l’ID è sopra 103 o spostato, rinumera le periferiche eliminandole e ri-aggiungendole nell’ordine corretto, oppure modifica il template per adattarlo ai tuoi ID.
  2. Per DS18B20: clicca Rescan nella riga della periferica DS18B20 — l’indirizzo del bus dovrebbe risolversi. Se mostra N/A, controlla il cablaggio VCC/DATA/GND e la resistenza di pull-up da 10 kΩ su DATA (alcune schede DS18B20 generiche la omettono; lo Shelly la fornisce internamente).
  3. Interroga l’endpoint direttamente: GET http://{host-ip}/rpc/Temperature.GetStatus?id=100. La risposta deve contenere un valore tC non nullo.
  4. Riavvia lo Shelly host dopo aver aggiunto o rimosso periferiche. I Component potrebbero non apparire fino al riavvio.
L’ingresso analogico legge zero
  1. Conferma che il type dell’ingresso nell’interfaccia Shelly sia impostato su analog (non switch, button o count). Il template legge percent, popolato solo in modalità analog.
  2. Controlla il cablaggio — una sorgente 0–10 V deve essere tra ANALOG IN e GND. Per sensori con partitore potenziometrico (NTC, fotoresistore) usa VREF+R1 OUT (con pull-up integrato da 10 kΩ) invece di VREF OUT.
  3. Ricorda che TapHome riceve il valore come frazione 0,0–1,0 (il template divide percent per 100).
Manca l’umidità DHT22

È una limitazione intenzionale del template — lo script readhumidity è fissato a NaN su ogni slot di dispositivo DS18B20. L’hardware dell’add-on supporta DHT22, ma per esporre l’umidità in TapHome devi estendere il template con un dispositivo dedicato che legga /rpc/Humidity.GetStatus?id=100 → rh. DS18B20 e DHT22 non possono coesistere sullo stesso bus — rimuovi le sonde DS18B20 se passi a DHT22.

La quinta sonda DS18B20 non è visibile

Il template interroga solo gli ID 100–103. Una quinta sonda registrata nell’interfaccia web Shelly come temperature:104 esiste sull’host ma non viene letta da TapHome. Sposta la sonda di interesse in uno degli slot 100–103 (elimina e ri-aggiungi in ordine) oppure estendi il template con un quinto dispositivo che punta a id=104.

Come installare in TapHome

Prerequisiti

  • Dispositivo Shelly installato e acceso
  • Rete Wi-Fi locale (2,4 GHz)
  • TapHome CCU sulla stessa rete

Passaggio 1 — Collegare Shelly al Wi-Fi

Opzione A — App Shelly (consigliata):

  1. Scarica l’app Shelly (iOS / Android)
  2. Tocca + → Add Device e segui la procedura guidata di associazione Bluetooth
  3. Inserisci le credenziali Wi-Fi quando richiesto

Opzione B — Modalità AP (senza app):

  1. Al primo avvio il dispositivo crea un hotspot: ShellyXXX-AABBCCDDEE
  2. Collega il tuo telefono/PC a questo hotspot
  3. Apri http://192.168.33.1 → Internet & Security → Wi-Fi Mode - Client
  4. Inserisci SSID e password → Save

Shelly supporta solo reti a 2,4 GHz. Le reti a 5 GHz non appariranno nella scansione.

Passaggio 2 — Trovare l’indirizzo IP

Dopo la connessione al Wi-Fi, trova l’indirizzo IP assegnato tramite uno di questi metodi:

  • App Shelly: Dettaglio dispositivo → Device info → Indirizzo IP
  • Interfaccia web Shelly: Connettiti all’AP del dispositivo prima della configurazione Wi-Fi — l’IP viene mostrato dopo il salvataggio
  • Tabella DHCP del router: Cerca un hostname come shelly1pm-AABBCCDDEE
  • mDNS: Esegui il ping di shelly<model>-<mac>.local (es. shelly1pm-AABBCCDDEE.local) dalla stessa rete

Assegna un IP statico (prenotazione DHCP) nel tuo router per il dispositivo Shelly per evitare che l’indirizzo cambi dopo un riavvio del router.

Passaggio 3 — Configurazione in TapHome

  1. In TapHome, aggiungi un nuovo modulo Packet Parser (HTTP)
  2. IP Address: inserisci l’IP dal passaggio 2 (es. 192.168.1.50)
  3. Port: 80 (predefinito, nessuna modifica necessaria)
  4. Importa il template — TapHome interrogherà periodicamente /status per leggere lo stato del dispositivo

L’autenticazione HTTP è disabilitata per impostazione predefinita sui dispositivi Shelly. Se hai abilitato la protezione con accesso, TapHome attualmente non supporta HTTP Basic Auth — mantieni l’autenticazione disabilitata per l’integrazione con TapHome.

Dispositivi disponibili

Shelly Sensor Add-On Modulo
Variabili personalizzate

Shelly Sensor Add-On

Lettura (modulo)
var res := sendhttprequest("/rpc/Sys.GetStatus");
SysGetStatus := res.Content;
res := sendhttprequest("/rpc/SensorAddon.GetPeripherals");
SensorAddonGetPeripherals := res.Content;
Ingresso analogico Ingresso analogico Solo lettura

Ingresso analogico 0–10 V / 0–100 % — legge /rpc/Input.GetStatus?id=100 → percent e divide per 100, esponendo il valore come frazione 0,0–1,0. Richiede che il tipo di ingresso sia impostato su analog nell'interfaccia web Shelly. Accuratezza ±5 %

numeric Unità: % (normalised) json_path
Variabile: Id — Component ID della periferica dell'ingresso analogico sull'host Shelly (le periferiche add-on usano 100–199; il primo ingresso analogico è 100)

Ingresso analogico

Lettura livello ingresso
var res := sendhttprequest("/rpc/Input.GetStatus?id=" + Id);
parsejson(res.Content, "percent") / 100
Contatto reed Contatto reed Solo lettura

Ingresso digitale contatto pulito / reed — legge /rpc/Input.GetStatus?id=100 → state (true = chiuso, false = aperto). Richiede che il tipo di ingresso sia impostato su switch o button nell'interfaccia web Shelly (condivide il Component ID 100 con l'ingresso analogico — una sola modalità attiva alla volta)

boolean json_path
Variabile: Id — Component ID della periferica dell'ingresso digitale sull'host Shelly (predefinito 100)

Contatto reed

Lettura
var res := sendhttprequest("/rpc/Input.GetStatus?id=" + Id);
parsejson(res.Content, "state")
Sensore di temperatura (DS18B20 #1) Sensore di temperatura Solo lettura

Prima sonda DS18B20 sul bus 1-Wire — legge /rpc/Temperature.GetStatus?id=100 → tC (°C). L'umidità è fissata a NaN (il template non espone DHT22)

numeric Unità: °C json_path
Variabile: Id — Component ID della prima sonda DS18B20 sull'host Shelly (predefinito 100)

Sensore di temperatura (DS18B20 #1)

Lettura umidità
NaN
Lettura temperatura
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Sensore di temperatura (DS18B20 #2) Sensore di temperatura Solo lettura

Seconda sonda DS18B20 sul bus 1-Wire — legge /rpc/Temperature.GetStatus?id=101 → tC (°C)

numeric Unità: °C json_path
Variabile: Id — Component ID della seconda sonda DS18B20 sull'host Shelly (predefinito 101)

Sensore di temperatura (DS18B20 #2)

Lettura umidità
NaN
Lettura temperatura
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Sensore di temperatura (DS18B20 #3) Sensore di temperatura Solo lettura

Terza sonda DS18B20 sul bus 1-Wire — legge /rpc/Temperature.GetStatus?id=102 → tC (°C)

numeric Unità: °C json_path
Variabile: Id — Component ID della terza sonda DS18B20 sull'host Shelly (predefinito 102)

Sensore di temperatura (DS18B20 #3)

Lettura umidità
NaN
Lettura temperatura
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Sensore di temperatura (DS18B20 #4) Sensore di temperatura Solo lettura

Quarta sonda DS18B20 sul bus 1-Wire — legge /rpc/Temperature.GetStatus?id=103 → tC (°C). Ultimo slot DS18B20 del template — il bus Shelly supporta fino a 5 sonde ma vengono interrogati solo gli ID 100–103

numeric Unità: °C json_path
Variabile: Id — Component ID della quarta sonda DS18B20 sull'host Shelly (predefinito 103)

Sensore di temperatura (DS18B20 #4)

Lettura umidità
NaN
Lettura temperatura
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Voltmetro Variabile Solo lettura

Misurazione di tensione 0–10 V — legge /rpc/Voltmeter.GetStatus?id=100 → voltage (V). Esposto come valore scalare di sola lettura tramite PacketParserVariable (non come tipo voltmetro nativo). Accuratezza ±5 %, soglia di segnalazione 0,1 V

numeric Unità: V json_path
Variabile: Id — Component ID della periferica voltmetro sull'host Shelly (predefinito 100)

Voltmetro

Lettura
var res := sendhttprequest("/rpc/Voltmeter.GetStatus?id=" + Id);
parsejson(res.Content, "voltage")
Connessione: Packet Parser → HTTP
Possibili miglioramenti (7)
  • DHT22 Humidity — Template hardcodes readhumidity = NaN on all four DS18B20 temperature devices. The add-on physically supports a DHT22 sensor (temperature + humidity) which creates paired humidity:100 + temperature:100 Components on the host. A separate PacketParser device reading humidity:100 → rh would expose this.
  • 5th DS18B20 slot — The Shelly Plus Add-on supports up to 5 DS18B20 probes on the shared 1-Wire bus. The template only wires 4 (IDs 100–103). A fifth probe registered as temperature:104 in the Shelly web UI would not be polled.
  • OneWire bus scan — Manufacturer API can discover unmapped DS18B20 probes. Not exposed as a TapHome service action — users must scan via the Shelly web UI. Useful for replacing physical probes.
  • Peripheral lifecycle management — Adding/removing/updating peripherals is performed exclusively via the Shelly web UI; the template does not expose these as TapHome service actions by design.
  • Enable / disable add-on — Activation is a one-time setup step performed in the Shelly web UI (or via Sys.SetConfig with device.addon_type = "sensor"). Not exposed by the template.
  • Pulse counter mode — Digital input can be configured as type=count and would expose counts.total / counts.by_minute / freq. Template only reads state (switch/button mode).
  • Voltmeter transformed value — Voltmeter supports an optional JavaScript expression (xvoltage.expr) that transforms the raw voltage (e.g. for a voltage-divided NTC temperature reading). Template reads only raw voltage.

Fonti