Shelly Cihazları ve MQTT: Kurulum, Topic'ler ve RPC

Shelly cihazları MQTT'yi yerleşik olarak konuşur: cihazın web arayüzünü açın, MQTT'yi etkinleştirin, broker'ınızın host, port ve kimlik bilgilerini girin; röle durumunu yayınlamaya ve komut almaya başlar. Farklı olan topic düzenidir. Gen1 cihazlar (Shelly 1, 2.5, Plug S, H&T…) düz metin komutlarıyla sabit bir shellies/... ağacı kullanırken Gen2, Plus, Pro ve Gen3 cihazlar MQTT üzerinden çağırabileceğiniz bir JSON-RPC API sunar.

Bu eğitim iki nesli de kapsıyor: ayarlar, göreceğiniz topic'ler, komut gönderme ve cihazı Home Assistant, openHAB veya kendi kodunuza bağlamadan önce her şeyi komut satırından nasıl doğrulayacağınız.

Hangi nesle sahipsiniz?

Cihaz kimliği MAC adresinden türetilir. Web arayüzündeki cihaz bilgilerinde bulabilirsiniz; ya da cihaz bağlandıktan sonra #'e abone olup ilk gelen topic'lerden okuyabilirsiniz.

Gen1 kurulumu

Gen1 web arayüzünde Internet & Security → Advanced – Developer Settings bölümünü açın ve Enable action execution via MQTT seçeneğini işaretleyin. Şunları doldurun:

• Server: broker.connectmq.com:1883
• Username / Password: broker kimlik bilgileriniz
• Use custom MQTT prefix (isteğe bağlı): örneğin shellies/shelly1-A1B2C3 yerine testmqtt/shelly/hallway
• Clean session, Keep alive (60 sn uygundur), Max QoS ve Retain: retain, bir dashboard'un son röle durumunu anında görmesi için faydalıdır

Kaydedin; cihaz MQTT bağlantısını yeniden kurar. Gen1 cihazlarda bunun Shelly Cloud'u kapattığını unutmayın.

Gen1 topic'leri

shellies/shelly1pm-A1B2C3/online            true | false   (Last Will)
shellies/shelly1pm-A1B2C3/relay/0           on | off
shellies/shelly1pm-A1B2C3/relay/0/power     anlık güç (W)
shellies/shelly1pm-A1B2C3/relay/0/energy    enerji sayacı (watt-dakika)
shellies/shelly1pm-A1B2C3/input/0           0 | 1
shellies/shelly1pm-A1B2C3/temperature       dahili sıcaklık (°C)
shellies/shelly1pm-A1B2C3/relay/0/command   ← on | off | toggle yayınlayın
shellies/announce                           cihaz kendini duyurur (JSON)
shellies/command                            ← announce | update yayınlayın

Komutlar düz metindir. Röleyi açmak için .../relay/0/command topic'ine on yayınlayın; cihaz yeni değeri .../relay/0 üzerinde yayınlayarak yanıt verir. shellies/command topic'ine announce yayınlamak, broker'daki tüm Gen1 cihazların kimliklerini, IP'lerini ve firmware sürümlerini bildirmesini sağlar; kullanışlı bir keşif yöntemi. Panjurlar open, close, stop ile roller/0/command ve yüzde değeriyle roller/0/command/pos kullanır.

H&T gibi pilli cihazlar zamanın çoğunda uykudadır: uyanır, sensor/temperature ve sensor/humidity yayınlar ve bağlantıyı keser. Subscriber tarafını cihazın çevrimiçi olmasına değil, retained değerlere dayandırın.

Gen2, Plus ve Pro kurulumu

Settings → MQTT bölümünü açıp etkinleştirin:

• Server: broker.connectmq.com:8883 (TLS olmadan :1883)
• Client ID: varsayılan olarak cihaz kimliğidir; benzersiz tutun, bkz. MQTT client ID en iyi uygulamaları
• Username / Password
• SSL/TLS: No TLS, TLS no validation, TLS with default CA (genel sertifikalar için bunu kullanın) veya TLS with user CA
• MQTT Prefix: varsayılan olarak cihaz kimliğidir; örneğin testmqtt/shelly/plug1 yapın
• RPC status notifications over MQTT: olayları <prefix>/events/rpc üzerinde yayınlar
• Generic status update over MQTT: her bileşenin durumunu <prefix>/status/<bileşen> üzerinde yayınlar
• Enable MQTT Control: <prefix>/command/... üzerinde basit komutları kabul eder

MQTT ayarları değiştikten sonra yeniden başlatma gerekir. Yapılandırmanın tamamını arayüz olmadan, RPC API'sini HTTP üzerinden çağırarak da yapabilirsiniz:

curl -s -X POST http://192.168.1.50/rpc/MQTT.SetConfig \
  -d '{"config":{"enable":true,"server":"broker.connectmq.com:8883","ssl_ca":"ca.pem",
       "user":"username","pass":"password","topic_prefix":"testmqtt/shelly/plug1",
       "rpc_ntf":true,"status_ntf":true,"enable_control":true}}'

curl -s -X POST http://192.168.1.50/rpc/Shelly.Reboot

"ssl_ca": "ca.pem" yerleşik CA paketini seçer; "*" doğrulamayı kapatır, "user_ca.pem" ise yüklediğiniz bir sertifikayı kullanır. "*"'ı laboratuvar dışında kullanmayın; bkz. TLS bağlantısını test etme.

Gen2 topic'leri

testmqtt/shelly/plug1/online              true | false   (Last Will)
testmqtt/shelly/plug1/status/switch:0     {"id":0,"output":true,"apower":12.4,...}
testmqtt/shelly/plug1/events/rpc          {"method":"NotifyStatus","params":{...}}
testmqtt/shelly/plug1/command             ← status_update yayınlayın
testmqtt/shelly/plug1/command/switch:0    ← on | off | toggle yayınlayın
testmqtt/shelly/plug1/rpc                 ← JSON-RPC istekleri yayınlayın

Bileşenler tür:indeks biçiminde adreslenir: switch:0, input:1, cover:0, temperature:100. Generic status update açıkken her bileşenin tam durumu kendi topic'ine düşer; tüketmesi en kolay format budur. events/rpc, NotifyStatus farklarını ve NotifyEvent mesajlarını (örneğin buton basışları) taşır.

MQTT üzerinden RPC

HTTP ile çağırabildiğiniz her Gen2 metodu MQTT üzerinden de çalışır. <prefix>/rpc topic'ine bir JSON-RPC çerçevesi yayınlayın; cihaz <src>/rpc üzerinde yanıt verir, burada src istekte belirttiğiniz değerdir. Bu klasik bir istek/yanıt deseni.

{"id": 1, "src": "testmqtt/shelly/cli", "method": "Switch.Set", "params": {"id": 0, "on": true}}

{"id": 1, "src": "shellyplusplugs-a8032ab12345", "dst": "testmqtt/shelly/cli", "result": {"was_on": false}}

Kullanışlı metotlar: Shelly.GetStatus, Shelly.GetDeviceInfo, Switch.Toggle, Switch.GetStatus, Cover.GoToPosition, Sys.SetConfig. Hatalar result yerine bir error nesnesiyle (code ve message) döner.

Aşağıda bir RPC çağrısı gönderip eşleşen yanıtı bekleyen küçük bir Python yardımcısı (paho-mqtt 2.x) var:

import json, os, threading
import paho.mqtt.client as mqtt

PREFIX = "testmqtt/shelly/plug1"
SRC = "testmqtt/shelly/cli"
done = threading.Event()

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(f"{SRC}/rpc", qos=1)

def on_subscribe(client, userdata, mid, reason_codes, properties):
    req = {"id": 1, "src": SRC, "method": "Shelly.GetStatus"}
    client.publish(f"{PREFIX}/rpc", json.dumps(req), qos=1)

def on_message(client, userdata, msg):
    resp = json.loads(msg.payload)
    if resp.get("id") == 1:
        print(json.dumps(resp.get("result", resp.get("error")), indent=2))
        done.set()

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="shelly-rpc-cli")
client.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASS"])
client.tls_set()
client.on_connect, client.on_subscribe, client.on_message = on_connect, on_subscribe, on_message
client.connect("broker.connectmq.com", 8883)
client.loop_start()
print("ok" if done.wait(10) else "yanıt yok (prefix'i ve RPC ayarını kontrol edin)")
client.loop_stop()

Kurulumu test edin

Cihazı herhangi bir ev otomasyonu yazılımına eklemeden önce trafiğini doğrudan izleyin:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/#' -t 'testmqtt/shelly/#' -v

Ardından ikinci bir terminalden röleyi değiştirin ve durum topic'inin takip ettiğini kontrol edin:

# Gen1
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'shellies/shelly1pm-A1B2C3/relay/0/command' -m toggle

# "Enable MQTT Control" açık Gen2
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/shelly/plug1/command/switch:0' -m toggle

Aynısını tarayıcıda online MQTT istemcisi ile de yapabilirsiniz: prefix'e # ile abone olun, <prefix>/command topic'ine status_update yayınlayın; cihaz tam durumuyla yanıt verir. Bir wildcard'ın beklediğiniz topic'leri kapsadığından emin değilseniz onları topic matcher aracına yapıştırın.

Shelly topic'lerinizi tarayıcıda izleyin

Hiçbir şey görünmüyorsa: online topic'inin hiç true olup olmadığını, portun TLS ayarıyla eşleştiğini (TLS ile 8883, TLS'siz 1883) ve cihazın broker'ın host adını çözümleyebildiğini kontrol edin. Sürekli yeniden bağlanan bir cihaz çoğu zaman aynı client ID'yi kullanan başka bir istemciyle çakışıyordur.

Entegrasyon notları

• Home Assistant: Shelly cihazları genellikle MQTT kullanmayan yerel Shelly entegrasyonuyla eklenir. MQTT'yi tercih ediyorsanız entity'leri elle tanımlayın veya bir discovery betiği kullanın; bkz. Home Assistant ve MQTT.
• Topic tasarımı: home/<oda>/<cihaz> gibi özel bir prefix; Shelly, Tasmota ve Zigbee cihazlarını tek ve tutarlı bir ağaçta tutar; bkz. akıllı ev topic tasarımı.
• Retained durum: dashboard'ların yeniden başlatma sonrasında "unknown" göstermemesi için retain'i açın (Gen1) ya da status/... ile açılışta bir status_update isteğine güvenin (Gen2).
• Nesilleri karıştırmak: tüketicilerinizi her iki düzene göre yazın veya uygulamanıza ulaşmadan önce Node-RED'de normalleştirin.

Shelly'nin MQTT desteği tüketici donanımındaki en kapsamlılardan biridir: Gen1'de sade topic'ler, Gen2 ve sonrasında tam bir RPC API. Özel bir prefix belirleyin, entegre etmeden önce trafiği bir subscriber ile izleyin ve her cihazı kendi topic'leriyle sınırlayın.

Sıkça sorulan sorular