Dane na żywo (WebSocket)

Przez WebSocket dostajesz odczyty i zmiany urządzeń w chwili, gdy się zdarzają. Aplikacja HAM używa tego samego połączenia. Dla jednego odczytu naraz prostsze jest REST API.

Adres

wss://DEVICE_SERVER:9001

• DEVICE_SERVER to wartość pola device_server każdego urządzenia. Znajdziesz ją przez get_user_devices.php.
• Urządzenia jednego konta mogą być na różnych serwerach. Otwórz jedno połączenie dla każdego innego serwera, a nie jedno dla każdego urządzenia.
• Port 9001 musi być otwarty dla połączeń wychodzących. Zobacz wymagania sieciowe.

Format wiadomości

Każda wysyłana wiadomość to tablica JSON:

[command_id, payload]

command_id to liczba całkowita. Zacznij od 1 i zwiększaj ją z każdą wiadomością. Odpowiedź ma ten sam command_id.

Maksymalny rozmiar wiadomości to 20 KiB. Serwer zamyka połączenie, jeśli wyślesz większą wiadomość.

1. Uwierzytelnienie

Pierwsza wiadomość po połączeniu to uwierzytelnienie:

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

Możesz też wysłać {"access_token": "YOUR_ACCESS_TOKEN"}. Zobacz uwierzytelnianie.

Odpowiedź	Znaczenie
[]	Powodzenie
["Access Denied"]	Błędny klucz lub token. Serwer zamyka połączenie.
[1,[{},"Rate limit"]]	Zbyt wiele połączeń w krótkim czasie

Limit połączeń: 15 na 60 sekund dla jednego klucza API. 25 na 60 sekund dla jednego tokenu dostępu.

2. Subskrypcja urządzeń (SUBSCRIBE)

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

Pole	Znaczenie
c	SUBSCRIBE
server	Zawsze true
serialnos	Numery seryjne urządzeń na tym serwerze
unsubscribe-others	true: serwer zatrzymuje wcześniejsze subskrypcje tego połączenia

Odpowiedź: [2,[{},""]]. Serwer pomija urządzenia, do których nie masz dostępu. Nie wysyła dla nich błędu.

Aby zatrzymać wszystkie subskrypcje, wyślij [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Aktualizacje stanu

Zaraz po subskrypcji serwer wysyła bieżący stan każdego urządzenia. Potem wysyła aktualizację przy każdej zmianie.

Aktualizacje to obiekty JSON, a nie tablice:

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

Pole	Zawartość
serialno	Urządzenie
R	Odczyty, surowe, według kodu odczytu
O	Wartości wyjść, w kolejności output_names
T	Harmonogramy urządzenia
S	Ustawienia urządzenia
previous	Skumulowane wartości poprzedniego okresu, dla urządzeń z licznikami
alarms	Aktywne alarmy
is_local	true, jeśli Twoje połączenie i urządzenie są w tej samej sieci

• Aktualizacja może zawierać tylko pola, które się zmieniły. Scal ją ze stanem, który już masz.
• Serwer grupuje zmiany przez około 100 ms, zanim wyśle aktualizację.
• Ignoruj wiadomości, których nie rozpoznajesz.

Aby przeliczyć wartości surowe, użyj definicji rodzin. Zobacz REST API.

Utrzymanie połączenia

• Serwer wysyła pingi WebSocket. Twoja biblioteka musi odpowiedzieć pongiem. Większość bibliotek robi to automatycznie.
• Jeśli połączenie się zamknie, połącz się ponownie. Aplikacja czeka 100 ms za pierwszym razem i 10 sekund potem.
• Po nowym połączeniu wyślij ponownie uwierzytelnienie i subskrypcję.

Przykład w Node.js

Node.js 22 ma wbudowany WebSocket.

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);
  }
};

Pełny przykład w Node.js jest w pliku nodejs_hamapi_example.zip. Zawiera bibliotekę hamapi.js i plik example.js.

1. W pliku example.js ustaw server, api_key i numery seryjne.
2. Uruchom npm install, a potem node example.js.

Biblioteka nie łączy się ponownie po zamknięciu połączenia. Dodaj to w swoim kodzie.

Zobacz też

• REST API
• Webhooki z reguł