Datos en directo (WebSocket)

Con el WebSocket usted obtiene las lecturas y los cambios de los dispositivos en el momento en que ocurren. La app HAM usa la misma conexión. Para una lectura cada vez, la API REST es más sencilla.

Dirección

wss://DEVICE_SERVER:9001

• DEVICE_SERVER es el valor del campo device_server de cada dispositivo. Lo encuentra con get_user_devices.php.
• Los dispositivos de una cuenta pueden estar en servidores diferentes. Abra una conexión por cada servidor diferente, no una por cada dispositivo.
• El puerto 9001 debe estar abierto para conexiones salientes. Consulte los requisitos de red.

Formato de los mensajes

Cada mensaje que usted envía es un array JSON:

[command_id, payload]

El command_id es un número entero. Empiece en 1 y auméntelo con cada mensaje. La respuesta tiene el mismo command_id.

El tamaño máximo de un mensaje es 20 KiB. El servidor cierra la conexión si usted envía un mensaje mayor.

1. Autenticación

El primer mensaje después de la conexión es la autenticación:

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

También puede enviar {"access_token": "YOUR_ACCESS_TOKEN"}. Consulte la autenticación.

Respuesta	Significado
[]	Correcto
["Access Denied"]	Clave o token incorrectos. El servidor cierra la conexión.
[1,[{},"Rate limit"]]	Demasiadas conexiones en poco tiempo

Límite de conexiones: 15 cada 60 segundos para una clave API. 25 cada 60 segundos para un token de acceso.

2. Suscribirse a dispositivos (SUBSCRIBE)

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

Campo	Significado
c	SUBSCRIBE
server	Siempre true
serialnos	Los números de serie de los dispositivos de este servidor
unsubscribe-others	true: el servidor detiene las suscripciones anteriores de esta conexión

Respuesta: [2,[{},""]]. El servidor omite los dispositivos a los que usted no tiene acceso. No envía un error por ellos.

Para detener todas las suscripciones, envíe [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Actualizaciones de estado

Inmediatamente después de la suscripción, el servidor envía el estado actual de cada dispositivo. Después envía una actualización cada vez que algo cambia.

Las actualizaciones son objetos JSON, no arrays:

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

Campo	Contenido
serialno	El dispositivo
R	Las lecturas, sin procesar, con el código de lectura como clave
O	Los valores de las salidas, en el orden de output_names
T	Las programaciones del dispositivo
S	Los ajustes del dispositivo
previous	Los valores acumulados del periodo anterior, para dispositivos con contadores
alarms	Las alarmas activas
is_local	true si su conexión y el dispositivo están en la misma red

• Una actualización puede tener solo los campos que cambiaron. Combínela con el estado que ya tiene.
• El servidor agrupa los cambios durante unos 100 ms antes de enviar una actualización.
• Ignore los mensajes que no reconoce.

Para convertir los valores sin procesar, use las definiciones de familia. Consulte la API REST.

Mantener la conexión abierta

• El servidor envía pings de WebSocket. Su biblioteca debe responder con un pong. La mayoría de las bibliotecas lo hacen automáticamente.
• Si la conexión se cierra, conéctese de nuevo. La app espera 100 ms la primera vez y 10 segundos después.
• Después de una conexión nueva, envíe de nuevo la autenticación y la suscripción.

Ejemplo con Node.js

Node.js 22 tiene un WebSocket integrado.

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 ejemplo completo con Node.js está en nodejs_hamapi_example.zip. Contiene la biblioteca hamapi.js y el archivo example.js.

1. En example.js, escriba server, api_key y los números de serie.
2. Ejecute npm install y después node example.js.

La biblioteca no se conecta otra vez cuando la conexión se cierra. Añada esto en su código.

Véase también

• API REST
• Webhooks desde reglas