Canlı veriler (WebSocket)

WebSocket ile cihazların ölçümlerini ve değişikliklerini oldukları anda alırsınız. HAM uygulaması aynı bağlantıyı kullanır. Tek seferlik bir ölçüm için REST API daha basittir.

Adres

wss://DEVICE_SERVER:9001

• DEVICE_SERVER, her cihazın device_server alanının değeridir. Onu get_user_devices.php ile bulursunuz.
• Bir hesabın cihazları farklı sunucularda olabilir. Her cihaz için değil, her farklı sunucu için bir bağlantı açın.
• Port 9001 giden bağlantılar için açık olmalıdır. Bkz. Ağ gereksinimleri (BT için).

Mesaj biçimi

Gönderdiğiniz her mesaj bir JSON dizisidir:

[command_id, payload]

command_id bir tam sayıdır. 1’den başlayın ve her mesajda artırın. Yanıtta aynı command_id bulunur.

Bir mesajın en büyük boyutu 20 KiB’dir. Daha büyük bir mesaj gönderirseniz sunucu bağlantıyı kapatır.

1. Kimlik doğrulama

Bağlantıdan sonraki ilk mesaj kimlik doğrulamadır:

[1, {"api_key": "YOUR_API_KEY"}]

{"access_token": "YOUR_ACCESS_TOKEN"} da gönderebilirsiniz. Bkz. kimlik doğrulama.

Yanıt	Anlamı
[]	Başarılı
["Access Denied"]	Yanlış anahtar veya token. Sunucu bağlantıyı kapatır.
[1,[{},"Rate limit"]]	Kısa sürede çok fazla bağlantı

Bağlantı sınırı: bir API anahtarı için 60 saniyede 15. Bir erişim token’ı için 60 saniyede 25.

2. Cihazlara abone olma (SUBSCRIBE)

[2, {"c": "SUBSCRIBE", "server": true, "serialnos": ["e11:123", "e9:456"], "unsubscribe-others": true}]

Alan	Anlamı
c	SUBSCRIBE
server	Her zaman true
serialnos	Bu sunucudaki cihazların seri numaraları
unsubscribe-others	true: sunucu bu bağlantının önceki aboneliklerini durdurur

Yanıt: [2,[{},""]]. Sunucu erişiminiz olmayan cihazları atlar. Onlar için hata göndermez.

Tüm abonelikleri durdurmak için [3, {"c": "UNSUBSCRIBE", "server": true}] gönderin.

3. Durum güncellemeleri

Abonelikten hemen sonra sunucu her cihazın geçerli durumunu gönderir. Sonra bir şey her değiştiğinde bir güncelleme gönderir.

Güncellemeler diziler değil, JSON nesneleridir:

{
  "serialno": "e11:123",
  "R": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
  "O": [],
  "alarms": [],
  "is_local": false
}

Alan	İçerik
serialno	Cihaz
R	Ölçüm koduna göre ham ölçümler
O	output_names sırasına göre çıkış değerleri
T	Cihazın zaman çizelgeleri
S	Cihaz ayarları
previous	Sayaçları olan cihazlar için önceki dönemin birikmiş değerleri
alarms	Etkin alarmlar
is_local	Bağlantınız ve cihaz aynı ağdaysa true

• Bir güncelleme yalnızca değişen alanları içerebilir. Onu zaten sahip olduğunuz durumla birleştirin.
• Sunucu bir güncelleme göndermeden önce değişiklikleri yaklaşık 100 ms boyunca gruplar.
• Tanımadığınız mesajları yok sayın.

Ham değerleri dönüştürmek için aile tanımlarını kullanın. Bkz. REST API.

Bağlantıyı açık tutma

• Sunucu WebSocket ping’leri gönderir. Kütüphanenizin bir pong ile yanıt vermesi gerekir. Çoğu kütüphane bunu otomatik olarak yapar.
• Bağlantı kapanırsa tekrar bağlanın. Uygulama ilk seferde 100 ms, sonra 10 saniye bekler.
• Yeni bir bağlantıdan sonra kimlik doğrulamayı ve aboneliği tekrar gönderin.

Node.js örneği

Node.js 22’de yerleşik bir WebSocket vardır.

const ws = new WebSocket('wss://DEVICE_SERVER:9001');
let id = 1;

ws.onopen = () => {
  ws.send(JSON.stringify([id++, { api_key: 'YOUR_API_KEY' }]));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (Array.isArray(msg) && msg.length === 0) {
    ws.send(JSON.stringify([id++, {
      c: 'SUBSCRIBE', server: true,
      serialnos: ['e11:123'], 'unsubscribe-others': true
    }]));
  } else if (!Array.isArray(msg) && msg.serialno) {
    console.log(msg.serialno, msg.R);
  }
};

Tam bir Node.js örneği nodejs_hamapi_example.zip dosyasındadır. Dosya hamapi.js kütüphanesini ve example.js dosyasını içerir.

1. example.js içinde server, api_key ve seri numaralarını ayarlayın.
2. npm install çalıştırın, sonra node example.js çalıştırın.

Bağlantı kapandığında kütüphane tekrar bağlanmaz. Bunu kodunuza ekleyin.

Ayrıca bkz.

• REST API
• Kurallardan webhook’lar