Données en direct (WebSocket)

Avec le WebSocket, vous recevez les mesures et les changements des appareils au moment où ils se produisent. L’application HAM utilise la même connexion. Pour une seule mesure à la fois, l’API REST est plus simple.

Adresse

wss://DEVICE_SERVER:9001

• DEVICE_SERVER est la valeur du champ device_server de chaque appareil. Vous la trouvez avec get_user_devices.php.
• Les appareils d’un même compte peuvent être sur des serveurs différents. Ouvrez une connexion pour chaque serveur différent, pas une pour chaque appareil.
• Le port 9001 doit être ouvert pour les connexions sortantes. Voir les exigences réseau.

Format des messages

Chaque message que vous envoyez est un tableau JSON :

[command_id, payload]

Le command_id est un nombre entier. Commencez à 1 et augmentez-le à chaque message. La réponse a le même command_id.

La taille maximale d’un message est de 20 KiB. Le serveur ferme la connexion si vous envoyez un message plus grand.

1. Authentification

Le premier message après la connexion est l’authentification :

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

Vous pouvez aussi envoyer {"access_token": "YOUR_ACCESS_TOKEN"}. Voir authentification.

Réponse	Signification
[]	Succès
["Access Denied"]	Clé ou jeton incorrect. Le serveur ferme la connexion.
[1,[{},"Rate limit"]]	Trop de connexions en peu de temps

Limite de connexions : 15 par 60 secondes pour une clé API. 25 par 60 secondes pour un jeton d’accès.

2. S’abonner aux appareils (SUBSCRIBE)

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

Champ	Signification
c	SUBSCRIBE
server	Toujours true
serialnos	Les numéros de série des appareils sur ce serveur
unsubscribe-others	true : le serveur arrête les abonnements précédents de cette connexion

Réponse : [2,[{},""]]. Le serveur ignore les appareils auxquels vous n’avez pas accès. Il n’envoie pas d’erreur pour eux.

Pour arrêter tous les abonnements, envoyez [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Mises à jour d’état

Immédiatement après l’abonnement, le serveur envoie l’état actuel de chaque appareil. Ensuite, il envoie une mise à jour à chaque changement.

Les mises à jour sont des objets JSON, pas des tableaux :

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

Champ	Contenu
serialno	L’appareil
R	Les mesures, brutes, avec le code de mesure comme clé
O	Les valeurs des sorties, dans l’ordre de output_names
T	Les programmes horaires de l’appareil
S	Les paramètres de l’appareil
previous	Les valeurs cumulées de la période précédente, pour les appareils avec des compteurs
alarms	Les alarmes actives
is_local	true si votre connexion et l’appareil sont sur le même réseau

• Une mise à jour peut avoir seulement les champs qui ont changé. Fusionnez-la dans l’état que vous avez déjà.
• Le serveur regroupe les changements pendant environ 100 ms avant d’envoyer une mise à jour.
• Ignorez les messages que vous ne reconnaissez pas.

Pour convertir les valeurs brutes, utilisez les définitions de famille. Voir l’API REST.

Garder la connexion ouverte

• Le serveur envoie des pings WebSocket. Votre bibliothèque doit répondre par un pong. La plupart des bibliothèques le font automatiquement.
• Si la connexion se ferme, connectez-vous à nouveau. L’application attend 100 ms la première fois et 10 secondes ensuite.
• Après une nouvelle connexion, envoyez à nouveau l’authentification et l’abonnement.

Exemple Node.js

Node.js 22 a un WebSocket intégré.

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

Un exemple complet Node.js se trouve dans nodejs_hamapi_example.zip. Il contient la bibliothèque hamapi.js et le fichier example.js.

1. Dans example.js, indiquez server, api_key et les numéros de série.
2. Exécutez npm install, puis node example.js.

La bibliothèque ne se reconnecte pas quand la connexion se ferme. Ajoutez cela dans votre code.

Voir aussi

• API REST
• Webhooks des règles