TapHome

Shelly Sensor Add-On

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 04. 2026
Shelly Sensor Add-On

Shelly Sensor Add-On (sprzedawany jako Shelly Plus Add-On) to galwanicznie izolowana płytka rozszerzeń, która wpina się w złącze add-on kompatybilnego urządzenia Shelly Plus, Gen3 lub Gen4. Rozszerza hostujące Shelly o magistralę 1-Wire dla temperatury (DS18B20), wejście cyfrowe (kontaktron / styk bezpotencjałowy), wejście analogowe (0–10 V / 0–100 %) oraz woltomierz 0–10 V. Add-on nie jest samodzielnym urządzeniem Wi-Fi — odczytywany jest przez interfejs HTTP hosta Shelly w sieci lokalnej, więc TapHome kieruje zapytania na adres IP hosta, a nie na osobny adres add-onu.

Szablon TapHome udostępnia cztery czujniki temperatury DS18B20 (Component ID 100–103), jeden kontaktron, jedno wejście analogowe i jeden woltomierz. Wszystkie wartości są odczytywane przez standardowe API Shelly Gen2+ JSON-RPC na porcie 80 — połączenie z chmurą nie jest wymagane.

Podłączenie sprzętowe

Add-on osadza się na hoście Shelly przez firmowe złącze szeregowe i pobiera 3,3 V DC bezpośrednio z hosta (pobór poniżej 0,5 W bez czujników). Dostępne dla użytkownika zaciski są pogrupowane w blok analogowo-cyfrowy i trzy pozycje czujnika 1-Wire.

Zaciski analogowe i cyfrowe
  • ANALOG IN — wejście analogowe 0–10 V (dokładność ±5 %, próg raportowania 1 %)
  • DIGITAL IN — wejście dla styku bezpotencjałowego / kontaktronu (True: od −15 V do 0,5 V, False: od 2,5 V do 15 V)
  • VREF OUT — napięcie odniesienia (maks. 1 mA) do zasilania czujników z dzielnikiem potencjometrycznym
  • VREF+R1 OUT — napięcie odniesienia z rezystorem pull-up 10 kΩ, przeznaczone do dzielników napięcia z NTC i fotorezystorem
  • GND × 2 — powroty masy
Magistrala 1-Wire

Trzy trójzaciskowe grupy (VCC, DATA, GND) dzielą wewnętrznie wspólną linię danych 1-Wire. Do 5 sond DS18B20 można podłączyć równolegle na wspólnej magistrali; alternatywnie pojedynczy czujnik DHT22 może zająć magistralę (DHT22 blokuje skanowanie OneWire w stanie aktywnym). Łączny prąd wyjścia VCC jest ograniczony do 10 mA, co wystarcza dla pięciu sond DS18B20.

Maksymalny przekrój przewodu na wszystkich zaciskach to 1 mm² (17 AWG).

Nie łącz DHT22 z sondami DS18B20 na tej samej magistrali. DHT22 blokuje enumerację OneWire i hostujące Shelly nie zdoła ponownie przeskanować magistrali, dopóki jest podłączony.

Konfiguracja

Shelly Sensor Add-On nie ma własnego adresu IP. Podczas importu szablonu TapHome wpisz w parametrze IpAddress adres IP hosta Shelly (urządzenia Plus / Gen3 / Gen4, na którym zamontowany jest add-on) — domyślnie 192.168.0.1.

Cała komunikacja odbywa się przez API Gen2+ JSON-RPC po HTTP GET na porcie 80. Raz na cykl odpytania szablon wczytuje /rpc/Sys.GetStatus i /rpc/SensorAddon.GetPeripherals do wewnętrznych zmiennych cache, po czym skrypt każdego urządzenia odpytuje własny endpoint (Temperature.GetStatus, Input.GetStatus lub Voltmeter.GetStatus).

Kompatybilne urządzenia hostujące

Add-on współpracuje z następującymi urządzeniami Shelly (z listy kompatybilności producenta):

  • 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

Firmware hosta Shelly musi udostępniać usługę SensorAddon — starsze wydania firmware Plus mogą jej nie zawierać. Zaktualizuj hosta do najnowszego firmware, jeśli w interfejsie web brakuje menu add-on.

Aktywacja peryferiów Add-on

Add-on konfiguruje się jednorazowo w interfejsie web hosta Shelly — TapHome go nie konfiguruje. Przed importem szablonu wykonaj następujące kroki:

  1. Osadź płytkę add-on na złączu add-on hosta Shelly i załącz zasilanie hosta.
  2. Otwórz interfejs web hosta pod adresem http://{host-ip}/ i zaloguj się.
  3. Przejdź do Settings → Add-on i zarejestruj add-on (w tle wywołuje to Sys.SetConfig z device.addon_type = "sensor"). W razie prośby zrestartuj hosta.
  4. Otwórz Settings → Components → Peripherals i kliknij przycisk +.
  5. Wybierz typ peryferium — Temperature (DS18B20), Digital Input, Analog Input lub Voltmeter.
  6. Dla DS18B20 kliknij Rescan, zaznacz każdą wykrytą sondę i wybierz Add and reboot. Pierwsza sonda otrzymuje Component ID 100, druga 101 i tak dalej.
  7. Dla Digital Input ustaw Mode na Switch lub Button (szablon czyta state z tego Componentu).
  8. Dla Analog Input i Voltmeter domyślne wartości są w porządku — istotne są tylko nazwa i próg delta.

Szablon TapHome ma na stałe ustawione Component ID 100–103 dla DS18B20 oraz ID 100 dla kontaktronu, wejścia analogowego i woltomierza. Podczas dodawania peryferiów w interfejsie web Shelly sprawdź, czy przypisane ID odpowiadają tej numeracji — jeśli usuniesz peryferium i dodasz je ponownie, Shelly przydzieli następny wolny ID, który może przekroczyć 103, a urządzenie TapHome po cichu przestanie odbierać dane.

Przed usunięciem peryferium zanotuj jego Component ID. Jeśli wymieniasz sondę DS18B20, skorzystaj raczej z akcji Edit → Update address w interfejsie web — Component ID pozostanie ten sam.

Na hoście Shelly musi być wyłączone HTTP Digest Authentication — TapHome nie wysyła uwierzytelnionych żądań. Pozostaw urządzenie bez uwierzytelniania lub ogranicz dostęp na poziomie sieci.

Możliwości urządzenia

Szablon grupuje siedem czujnikowych urządzeń tylko do odczytu pod jednym modułem HTTP kierującym do hosta Shelly.

Sondy temperatury (DS18B20)

Udostępnione są cztery sondy temperatury DS18B20 OneWire, po jednej na Component ID 100–103:

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

Każde urządzenie ma konfigurowalną przez użytkownika zmienną Id (wartość domyślna odpowiada pozycji). Interwał odpytywania to 15 sekund na sondę. Interfejs web Shelly pozwala dostroić próg delta (0,1–5 °C) i offset (±50 °C) każdej sondy do kalibracji.

Kontaktron (wejście cyfrowe)

Reed Contact (100) czyta /rpc/Input.GetStatus?id=100 → state (boolean). W interfejsie Shelly wejście musi być skonfigurowane jako Switch lub Button (nie Analog ani Count). Interwał odpytywania: 2,5 sekundy. Domyślna wartość zmiennej Id to 100.

Wejście analogowe

Analog Input (100) czyta /rpc/Input.GetStatus?id=100 → percent, dzieląc przez 100, aby wartość była znormalizowana do ułamka 0,0–1,0, którego TapHome oczekuje dla wejść analogowych. Wejście musi być skonfigurowane jako Analog w interfejsie Shelly. Dokładność ±5 %, próg raportowania 1 %. Interwał odpytywania: 2,5 sekundy.

Uwaga: kontaktron i wejście analogowe dzielą Component ID 100 — sprzęt Shelly ma na add-onie tylko jedno wejście cyfrowe i jedno analogowe, a aktywny tryb wybiera typ wejścia w interfejsie web (switch/button vs analog). W TapHome użyj albo urządzenia Reed Contact, albo Analog Input, nie obu jednocześnie.

Woltomierz

Voltmeter (100) czyta /rpc/Voltmeter.GetStatus?id=100 → voltage (V). Zakres to 0–10 V z dokładnością ±5 % i progiem raportowania 0,1 V. Jest modelowany jako PacketParserVariable z możliwością sensor — surowe napięcie udostępniane jest jako wartość skalarna, a nie jako dedykowany typ woltomierza. Interwał odpytywania: 15 sekund.

Dodatkowe możliwości

Shelly Sensor Add-On natywnie obsługuje również czujnik temperatury i wilgotności DHT22 (pojedyncza sonda tworząca na hoście sparowane Componenty temperature:100 i humidity:100). Szablon TapHome łączy temperaturę na wszystkich czterech urządzeniach DS18B20, ale skrypt wilgotności ma na stałe wpisane NaN — wilgotność DHT22 nie jest zatem udostępniana. Użytkownicy potrzebujący wilgotności mogą rozszerzyć szablon o oddzielny skrypt odczytu na /rpc/Humidity.GetStatus?id=100.

Dwie kolejne funkcje istnieją na poziomie sprzętu/firmware, ale wychodzą poza zakres tego szablonu: piąty slot DS18B20 (magistrala Shelly obsługuje do pięciu sond; szablon odpytuje tylko ID 100–103) oraz tryb licznika impulsów na wejściu cyfrowym (counts.total, counts.by_minute, freq), który wymaga skonfigurowania wejścia jako type=count w interfejsie Shelly. Oba mogą zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

Host Shelly nie odpowiada
  1. Sprawdź, czy host Shelly jest podłączony do Wi-Fi i ma prawidłowy adres IP.
  2. Spróbuj użyć hostname mDNS hosta (np. shellyplus1pm-AABBCCDDEE.local) zamiast IP — IP mogło zmienić się po odnowieniu DHCP. Add-on dziedziczy hostname hosta, nie ma własnego.
  3. Otwórz w przeglądarce http://{host-ip}/rpc/Shelly.GetDeviceInfo — jeśli odpowie JSON-em, host jest osiągalny.
  4. Sprawdź, czy TapHome CCU i host Shelly są w tej samej sieci / VLAN.
  5. Upewnij się, że HTTP Digest Authentication jest wyłączone w interfejsie web Shelly.
Czujniki nie pokazują danych
  1. Otwórz interfejs web Shelly → Components → Peripherals. Potwierdź, że peryferium jest na liście z dokładnie tym Component ID, którego oczekuje szablon (temperature:100–103, input:100, voltmeter:100). Jeśli ID jest powyżej 103 lub przesunięte, przenumeruj peryferia przez usunięcie i ponowne dodanie we właściwej kolejności, albo dostosuj szablon do swoich ID.
  2. Dla DS18B20: kliknij Rescan w wierszu peryferium DS18B20 — adres magistrali powinien zostać rozpoznany. Jeśli pokazuje N/A, sprawdź okablowanie VCC/DATA/GND i rezystor pull-up 10 kΩ na DATA (niektóre generyczne płytki DS18B20 go pomijają; Shelly zapewnia go wewnętrznie).
  3. Zapytaj endpoint bezpośrednio: GET http://{host-ip}/rpc/Temperature.GetStatus?id=100. Odpowiedź powinna zawierać niezerową wartość tC.
  4. Zrestartuj hosta Shelly po dodaniu lub usunięciu peryferiów. Componenty mogą się nie pojawić aż do restartu.
Wejście analogowe czyta zero
  1. Potwierdź, że type wejścia w interfejsie Shelly jest ustawiony na analog (nie switch, button ani count). Szablon czyta percent, które jest wypełnione tylko w trybie analogowym.
  2. Sprawdź okablowanie — źródło 0–10 V musi być między ANALOG IN a GND. Dla czujników z dzielnikiem potencjometrycznym (NTC, fotorezystor) użyj VREF+R1 OUT (z wbudowanym pull-up 10 kΩ) zamiast VREF OUT.
  3. Pamiętaj, że TapHome otrzymuje wartość jako ułamek 0,0–1,0 (szablon dzieli percent przez 100).
Brakuje wilgotności DHT22

To zamierzone ograniczenie szablonu — skrypt readhumidity jest wpisany na stałe jako NaN w każdym slocie urządzenia DS18B20. Sprzęt add-onu obsługuje DHT22, ale aby wystawić wilgotność w TapHome, trzeba rozszerzyć szablon o dedykowane urządzenie, które czyta /rpc/Humidity.GetStatus?id=100 → rh. DS18B20 i DHT22 nie mogą współistnieć na tej samej magistrali — usuń sondy DS18B20, jeśli przechodzisz na DHT22.

Piąta sonda DS18B20 niewidoczna

Szablon odpytuje tylko ID 100–103. Piąta sonda zarejestrowana w interfejsie web Shelly jako temperature:104 istnieje na hoście, ale TapHome jej nie czyta. Przenieś sondę, która cię interesuje, do jednego ze slotów 100–103 (usuń i dodaj ponownie w kolejności) lub rozszerz szablon o piąte urządzenie celujące w id=104.

Jak zainstalować w TapHome

Wymagania wstępne

  • Urządzenie Shelly zainstalowane i włączone
  • Lokalna sieć Wi-Fi (2,4 GHz)
  • TapHome CCU w tej samej sieci

Krok 1 — Podłącz Shelly do Wi-Fi

Opcja A — Aplikacja Shelly (zalecana):

  1. Pobierz aplikację Shelly (iOS / Android)
  2. Dotknij + → Add Device i postępuj zgodnie z kreatorem parowania Bluetooth
  3. Wprowadź dane logowania Wi-Fi, gdy zostaniesz o to poproszony

Opcja B — Tryb AP (bez aplikacji):

  1. Przy pierwszym uruchomieniu urządzenie tworzy hotspot: ShellyXXX-AABBCCDDEE
  2. Połącz telefon/PC z tym hotspotem
  3. Otwórz http://192.168.33.1 → Internet & Security → Wi-Fi Mode - Client
  4. Wprowadź SSID i hasło → Save

Shelly obsługuje tylko sieci 2,4 GHz. Sieci 5 GHz nie pojawią się podczas skanowania.

Krok 2 — Znajdź adres IP

Po połączeniu z Wi-Fi znajdź przypisany adres IP za pomocą jednej z poniższych metod:

  • Aplikacja Shelly: Szczegóły urządzenia → Device info → Adres IP
  • Interfejs webowy Shelly: Połącz się z AP urządzenia przed konfiguracją Wi-Fi — IP zostanie wyświetlone po zapisaniu
  • Tabela DHCP routera: Szukaj nazwy hosta takiej jak shelly1pm-AABBCCDDEE
  • mDNS: Pinguj shelly<model>-<mac>.local (np. shelly1pm-AABBCCDDEE.local) z tej samej sieci

Przypisz urządzeniu Shelly statyczny IP (rezerwację DHCP) w routerze, aby adres nie zmieniał się po ponownym uruchomieniu routera.

Krok 3 — Konfiguracja w TapHome

  1. W TapHome dodaj nowy moduł Packet Parser (HTTP)
  2. IP Address: wprowadź IP z kroku 2 (np. 192.168.1.50)
  3. Port: 80 (domyślny, nie wymaga zmiany)
  4. Zaimportuj szablon — TapHome będzie okresowo odpytywać /status w celu odczytu stanu urządzenia

Uwierzytelnianie HTTP jest domyślnie wyłączone na urządzeniach Shelly. Jeśli włączyłeś ochronę logowaniem, TapHome obecnie nie obsługuje HTTP Basic Auth — pozostaw uwierzytelnianie wyłączone dla integracji z TapHome.

Dostępne urządzenia

Shelly Sensor Add-On Moduł
Zmienne niestandardowe

Shelly Sensor Add-On

Odczyt (moduł)
var res := sendhttprequest("/rpc/Sys.GetStatus");
SysGetStatus := res.Content;
res := sendhttprequest("/rpc/SensorAddon.GetPeripherals");
SensorAddonGetPeripherals := res.Content;
Wejście analogowe Wejście analogowe Tylko do odczytu

Wejście analogowe 0–10 V / 0–100 % — czyta /rpc/Input.GetStatus?id=100 → percent i dzieli przez 100, udostępniając wartość jako ułamek 0,0–1,0. Wymaga ustawienia typu wejścia na analog w interfejsie web Shelly. Dokładność ±5 %

numeric Jednostka: % (normalised) json_path
Zmienna: Id — Component ID peryferium wejścia analogowego na hoście Shelly (peryferia add-on używają 100–199; pierwsze wejście analogowe to 100)

Wejście analogowe

Odczyt poziomu wejściowego
var res := sendhttprequest("/rpc/Input.GetStatus?id=" + Id);
parsejson(res.Content, "percent") / 100
Kontaktron Kontakt reed Tylko do odczytu

Cyfrowe wejście styk bezpotencjałowy / kontaktron — czyta /rpc/Input.GetStatus?id=100 → state (true = zwarte, false = rozwarte). Wymaga ustawienia typu wejścia na switch lub button w interfejsie web Shelly (dzieli Component ID 100 z wejściem analogowym — jednocześnie aktywny tylko jeden tryb)

boolean json_path
Zmienna: Id — Component ID peryferium wejścia cyfrowego na hoście Shelly (domyślnie 100)

Kontaktron

Odczyt
var res := sendhttprequest("/rpc/Input.GetStatus?id=" + Id);
parsejson(res.Content, "state")
Czujnik temperatury (DS18B20 #1) Czujnik temperatury Tylko do odczytu

Pierwsza sonda DS18B20 na magistrali 1-Wire — czyta /rpc/Temperature.GetStatus?id=100 → tC (°C). Wilgotność jest wpisana na stałe jako NaN (szablon nie udostępnia DHT22)

numeric Jednostka: °C json_path
Zmienna: Id — Component ID pierwszej sondy DS18B20 na hoście Shelly (domyślnie 100)

Czujnik temperatury (DS18B20 #1)

Odczyt wilgotności
NaN
Odczyt temperatury
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Czujnik temperatury (DS18B20 #2) Czujnik temperatury Tylko do odczytu

Druga sonda DS18B20 na magistrali 1-Wire — czyta /rpc/Temperature.GetStatus?id=101 → tC (°C)

numeric Jednostka: °C json_path
Zmienna: Id — Component ID drugiej sondy DS18B20 na hoście Shelly (domyślnie 101)

Czujnik temperatury (DS18B20 #2)

Odczyt wilgotności
NaN
Odczyt temperatury
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Czujnik temperatury (DS18B20 #3) Czujnik temperatury Tylko do odczytu

Trzecia sonda DS18B20 na magistrali 1-Wire — czyta /rpc/Temperature.GetStatus?id=102 → tC (°C)

numeric Jednostka: °C json_path
Zmienna: Id — Component ID trzeciej sondy DS18B20 na hoście Shelly (domyślnie 102)

Czujnik temperatury (DS18B20 #3)

Odczyt wilgotności
NaN
Odczyt temperatury
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Czujnik temperatury (DS18B20 #4) Czujnik temperatury Tylko do odczytu

Czwarta sonda DS18B20 na magistrali 1-Wire — czyta /rpc/Temperature.GetStatus?id=103 → tC (°C). Ostatni slot DS18B20 w szablonie — magistrala Shelly obsługuje do 5 sond, ale odpytywane są tylko ID 100–103

numeric Jednostka: °C json_path
Zmienna: Id — Component ID czwartej sondy DS18B20 na hoście Shelly (domyślnie 103)

Czujnik temperatury (DS18B20 #4)

Odczyt wilgotności
NaN
Odczyt temperatury
var res := sendhttprequest("/rpc/Temperature.GetStatus?id=" + Id);
parsejson(res.Content, "tC")
Woltomierz Zmienna Tylko do odczytu

Pomiar napięcia 0–10 V — czyta /rpc/Voltmeter.GetStatus?id=100 → voltage (V). Udostępniony jako skalarna wartość tylko do odczytu przez PacketParserVariable (nie natywne urządzenie voltmeter). Dokładność ±5 %, próg raportowania 0,1 V

numeric Jednostka: V json_path
Zmienna: Id — Component ID peryferium woltomierza na hoście Shelly (domyślnie 100)

Woltomierz

Odczyt
var res := sendhttprequest("/rpc/Voltmeter.GetStatus?id=" + Id);
parsejson(res.Content, "voltage")
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (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.

Źródła