Home Assistant'ta USB Dongle için Kararlı Seri Port

Portun yeniden başlatmadan sonra “değişmemesi” için, /dev/ttyUSB0 veya /dev/ttyACM0 yerine kararlı yol olan /dev/serial/by-id/... (bazen by-path) belirtin. Bu, Home Assistant'taki Zigbee/Z‑Wave/USB‑UART kopmalarının çoğunu çözer.

Hangi yolu seçmeli: ttyUSB vs by-id vs by-path

/dev/ttyUSB0, /dev/ttyUSB1, /dev/ttyACM0 — bunlar “algılanma sırasına göre” verilen isimlerdir. Bugün dongle ttyUSB0 olabilir, yarın (yeniden başlatma, yeniden takma, ikinci bir USB cihazının bağlanması sonrası) ttyUSB1 olabilir.

/dev/serial/by-id/... — USB cihaz tanımlayıcılarından (model/çip/seri numarası) oluşturulan sembolik bağlantıdır. Genellikle değişmez ve “ayarla ve unut” senaryosu için uygundur.

/dev/serial/by-path/... — fiziksel USB portuna/topolojiye bağlıdır. Şu durumlarda faydalıdır:

• Cihazda benzersiz seri numarası yoksa ve by-id benzersiz değilse;
• Elinizde birden fazla aynı dongle varsa.

Hızlı Karşılaştırma

Home Assistant'ta doğru portu nerede bulabilirsiniz

Seçenek 1 (Arayüz üzerinden):

1. Ayarlar → Sistem → Donanım → Tüm donanımlar bölümünü açın.
2. Dongle'ınızı bulun (tty veya serial ile arama yapabilirsiniz).
3. /dev/serial/by-id/... biçimindeki yolu kopyalayın.

Seçenek 2 (HA terminali üzerinden): Terminal & SSH eklentisi yüklüyse, şunu çalıştırın:

ls -l /dev/serial/by-id

Solda ihtiyacınız olan kararlı yol, sağda ise bunun işaret ettiği hedef (örneğin ../../ttyUSB0) görünecektir.

Portu nereye yazmalı: Z-Wave JS, ZHA, Zigbee2MQTT, YAML

Z‑Wave JS

Eklenti/entegrasyon ayarlarında Seri port / Cihaz alanını belirtin:

/dev/serial/by-id/usb-...-if00-port0

Zigbee (ZHA)

Koordinatörü eklerken Seri cihaz yolu alanına şunu yazın:

/dev/serial/by-id/usb-...-if00-port0

ZHA zaten yapılandırılmışsa ve port değişikliği nedeniyle “bozulduysa”, genellikle yolu değiştirmek ve Home Assistant'ı yeniden başlatmak yeterlidir.

Zigbee2MQTT (eklenti)

Zigbee2MQTT configuration.yaml dosyasında:

serial:
  port: /dev/serial/by-id/usb-...-if00-port0

COM portundan veri okuyan entegrasyonlar (YAML)

Temel prensip aynıdır: ttyUSB0 yerine by-id belirtin. Örnek:

sensor:
  - platform: serial
    serial_port: /dev/serial/by-id/usb-...-if00-port0
    baudrate: 9600

Docker'da Home Assistant: Port nasıl yönlendirilir

Home Assistant bir konteyner içinde çalışıyorsa, host üzerindeki yol tek başına cihazın konteyner içinde görüleceğini garanti etmez.

Önerilen yöntem — belirli bir by-id yönlendirmektir:

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/serial/by-id/usb-...-if00-port0:/dev/serial/by-id/usb-...-if00-port0
    restart: unless-stopped

Birden fazla cihaz varsa, bazen dizinin tamamı yönlendirilir:

volumes:
  - /dev/serial:/dev/serial

Ancak bu, cihaz erişimi açısından daha az “hedefe yönelik” bir yaklaşımdır.

/dev/serial/by-id görünmezse: Tanılama

1. Home Assistant'ın dongle'ı görüp görmediğini kontrol edin: Ayarlar → Sistem → Donanım → Tüm donanımlar bölümünde. Eğer burası boşsa, sorun entegrasyonların altındaki katmandadır (kablo, güç, hub, VM yönlendirmesi).

2. Yeniden takma ve farklı USB portu. Özellikle ön panellerdeki portlar, pasif hub'lar ve uzun kablolar kullanılırken dikkatli olun.

3. Sanallaştırma (Proxmox/VirtualBox/ESXi). USB cihazının özellikle USB cihazı olarak (passthrough) yönlendirildiğinden ve host yeniden başlatıldığında “kopmadığından” emin olun.

4. Güç ve parazitler. Zigbee/Z‑Wave için genellikle şunlar yardımcı olur:

• 0,5–1 m USB uzatma kablosu (dongle'ı USB3/kasa/SSD'den uzaklaştırın);
• Port “güç düşüşü” yaşıyorsa beslemeli (powered) USB hub.

5. Sistemde by-id var ancak eklentinin açılır listesində yok. Bu normaldir: Yolu Donanım/terminalden alın ve port alanına manuel olarak yapıştırın.

Sık yapılan hatalar

• “Şu an çalışıyor” diye /dev/ttyUSB0 belirtmek ve yeniden başlatma sonrası kopma yaşamak.
• İkinci bir USB-Seri cihaz bağlamak ve neden ttyUSB* numaralarının yer değiştirdiğini anlamamak.
• Yolu fazladan boşluk/satır sonu ile kopyalamak — port doğru görünür ancak açılmaz.
• Docker'da by-id yerine ttyUSB0 yönlendirmek: Numara değiştiğinde konteyner cihazı “kaybeder”.
• by-path ve by-idyi karıştırmak: Dongle başka bir USB yuvasına takılırsa by-path bozulur.

SSS

Zigbee/Z‑Wave cihazlarını yeniden eşlemeden port değiştirilebilir mi?
Genellikle evet: Sadece aynı fiziksel koordinatör/kontrolcünün yolunu değiştirirsiniz. Ağ ve cihazlar yerinde kalır.

Hangisi daha iyi — by-id mi yoksa by-path mi?
by-id varsayılan olarak en iyi seçimdir. by-id benzersiz değilse (örneğin seri numarası olmayan iki aynı adaptör) ve dongle'lar her zaman sabit USB portlarında duruyorsa by-path kullanın.

Neden Home Assistant'ı VM/konteynere taşıdıktan sonra by-id “kayboluyor”?
Çoğu zaman cihaz VM/konteyner içine yönlendirilmemiştir veya değişken olan geçici ttyUSB* olarak yönlendirilmiştir. Tam olarak by-id yönlendirin ve passthrough/cihaz ayarlarını tekrar kontrol edin.