Telegram Botu ile MQTT Üzerinden Cihaz Kontrolü

Telegram botu, MQTT cihazları için uzaktan kumanda ve alarm kanalı edinmenin en hızlı yollarından biridir: ücretsiz, çok platformlu bir sohbet arayüzü ve push bildirimleri elde edersiniz, üstelik geliştirmeniz gereken bir uygulama yoktur. Bot iki iş yapan küçük bir servis olarak çalışır: siz /on lamp yazdığınızda devices/lamp/set topic'ine ON gibi komutlar publish eder ve alarm ile durum topic'lerine abone olup bunları sohbetinize iletir.

Bu eğitim, bu köprüyü Python'da python-telegram-bot ve aiomqtt ile kuruyor, yalnızca sizin chat ID'nize kısıtlıyor ve donanım işin içine girmeden önce her yolu mosquitto_pub ve mosquitto_sub ile test ediyor.

Mimari

You (Telegram app) ──/on lamp──▶ Telegram API ──▶ bot.py ──PUBLISH testmqtt/tgbot/lamp/set "ON"──▶ broker ──▶ device
device ──PUBLISH testmqtt/tgbot/lamp/state "ON" (retained)──▶ broker ──▶ bot.py (cache for /status)
device ──PUBLISH testmqtt/tgbot/greenhouse/alert "..."──▶ broker ──▶ bot.py ──▶ Telegram chat

Cihaz Telegram ile hiç konuşmaz; yalnızca MQTT konuşur. Bu yüzden bir ESP32'nin veya Raspberry Pi'nin bot token'ına ya da HTTPS istemcisine ihtiyacı olmaz ve daha sonra aynı topic'ler üzerinde ikinci bir kontrolcü olarak bir dashboard veya Home Assistant ekleyebilirsiniz. Topic yapısı, MQTT ile komut ve kontrol yazısında anlatılan olağan komut/durum ayrımını izler:

Botu oluşturun

1. Telegram'da @BotFather ile bir sohbet açın, /newbot gönderin, bir ad ve bot ile biten bir username seçin.
2. BotFather'ın döndürdüğü token'ı kopyalayın. Bu bir sırdır: ona sahip olan herkes botunuzun kimliğine bürünebilir.
3. İsterseniz komutların sohbet menüsünde görünmesi için BotFather'a on - switch a device on, off - switch a device off, status - show device states içeriğiyle /setcommands gönderin.

İki kütüphaneyi kurun (Python 3.10+):

pip install "python-telegram-bot>=21" "aiomqtt>=2"

İkisi de asyncio kütüphanesidir ve uyumlu olmalarının nedeni budur: botun polling döngüsü ile MQTT bağlantısı aynı event loop'ta çalışır ve bir komut handler'ı doğrudan await client.publish(...) çağırabilir. İstemci hakkında daha fazlası için aiomqtt ile Python'da asenkron MQTT yazısına bakın.

Bot

@@BOTCODE@@

Dikkat çekmeye değer birkaç tasarım kararı:

• Tüm bot için tek bir MQTT bağlantısı. Bağlantının sahibi worker'dır ve onu bot_data içinde saklar; handler'lar her komutta yeniden bağlanmak yerine bu bağlantıyı kullanır. Broker düşerse döngü beş saniye sonra yeniden bağlanır, bu arada handler'lar "Broker not connected" yanıtını verir.
• Durumlar retained mesajlardan gelir. Cihazlar state'i retain bayrağıyla publish ettiği için bot, abone olur olmaz — yeniden başlatmadan sonra bile — her cihazın son durumunu bilir. Bkz. retained mesajlar.
• Bilinmeyen sohbetlere sessizlik. Yalnızca /whoami herkese yanıt verir; böylece kendi chat ID'nizi öğrenebilirsiniz. Publish eden her komut önce allowlist'i kontrol eder.
• Alarmlara debounce uygulanır. Aksi halde kararsız bir sensör Telegram'ın hız sınırlarına takılır ve gerçek alarmları boğar.

Donanım olmadan çalıştırın ve test edin

Botu yalnızca TELEGRAM_TOKEN ile başlatın, sohbette /whoami gönderin ve numarayı not edin. Ardından allowlist ile yeniden başlatın:

export TELEGRAM_TOKEN="123456:ABC..."        # BotFather'dan
export ALLOWED_CHAT_IDS="111111111"          # /whoami ile öğrendiğiniz chat ID
export MQTT_USER="username" MQTT_PASS="password"   # broker'ınız giriş istiyorsa
python bot.py

Şimdi cihazı siz oynayın. Bir terminalde botun ne publish ettiğini izleyin:

mosquitto_sub -h broker.connectmq.com -p 1883 -t 'testmqtt/tgbot/+/set' -v

Telegram'da /on lamp gönderin. Terminal 1, testmqtt/tgbot/lamp/set ON yazdırır. Yeni durumu bir cihazın yapacağı gibi bildirin, ardından bir alarm tetikleyin:

mosquitto_pub -h broker.connectmq.com -p 1883 -q 1 -r \
  -t testmqtt/tgbot/lamp/state -m ON

mosquitto_pub -h broker.connectmq.com -p 1883 -q 1 \
  -t testmqtt/tgbot/pump/alert -m 'Water level low (12 %)'

/status artık lamp: ON göstermeli ve sohbete ⚠️ pump: Water level low (12 %) gelmelidir. Alarmı 60 saniye içinde tekrar publish edin ve bastırıldığını doğrulayın. Tüm bunları terminal yerine online MQTT istemcisinden de yapabilirsiniz. Son olarak retained durumu temizleyin ki ortada kalmasın: mosquitto_pub -h broker.connectmq.com -t testmqtt/tgbot/lamp/state -r -n.

Botun topic'lerini tarayıcıda izleyin

Cihaz tarafı

Gerçek donanımda cihaz kendi set topic'ine abone olur, çıkışı değiştirir ve ortaya çıkan durumu retain ile publish eder. MicroPython'da umqtt.simple ile çekirdek kısım birkaç satırdır:

@@DEVCODE@@

Durumu işlemi yaptıktan sonra publish etmek, /status'u güvenilir kılan şeydir: bot sizin ne istediğinizi değil, cihazın ne yaptığını bildirir. Bir cihaz çevrim dışı kaldığında botun size haber verebilmesi için durum üzerinde bir Last Will veya bir availability topic'i ekleyin.

Güvenli hale getirin

Telegram'daki herkes bir bota ulaşabilir; bu yüzden ona herkese açık bir API gibi davranın:

1. Gösterildiği gibi sohbetleri allowlist ile sınırlayın. Gruplarda chat ID negatiftir; onu da diğerleri gibi listeye ekleyin.
2. Token'ı kodun dışında tutun: ortam değişkenleri veya bir secret manager kullanın, asla bir Git deposu değil.
3. Broker'a TLS ile bağlanın. Örnek 8883 portuna bağlanır; şifresiz 1883 yalnızca yerel denemeler için uygundur.
4. Botun broker kullanıcısını kısıtlayın. .../set üzerinde yazma, .../state ve .../alert üzerinde okuma yetkisine ihtiyacı vardır, başka hiçbir şeye değil. Kuralları bir ACL izin testiyle doğrulayın.

Kodsuz alternatifler

Görsel bir araç tercih ediyorsanız aynı köprü n8n'de (MQTT Trigger → Telegram node'u ve Telegram Trigger → MQTT node'u; bkz. n8n ile MQTT otomasyonları) veya Node-RED'de bir topluluk Telegram node'uyla da çalışır. Açık bir allowlist, debounce ve kendi deponuzda testler içeren tek bir küçük servis istediğinizde Python sürümü öne çıkar.

Telegram botu, MQTT'yi cebinizden kontrol edebileceğiniz bir şeye dönüştürür: komutlar publish olarak çıkar, durum retained mesaj olarak geri gelir ve alarmlar push bildirimi olarak ulaşır. Cihazın yalnızca MQTT konuşmasını sağlayın, botu kendi sohbetinize sınırlayın, alarmlara debounce uygulayın ve bir röle bağlamadan önce tüm döngüyü mosquitto ile test edin.

Sıkça sorulan sorular