Dados em direto (WebSocket)

Com o WebSocket, obtém as leituras e as alterações dos dispositivos no momento em que acontecem. A aplicação HAM utiliza a mesma ligação. Para uma leitura de cada vez, a API REST é mais simples.

Endereço

wss://DEVICE_SERVER:9001

• DEVICE_SERVER é o valor do campo device_server de cada dispositivo. Encontra-o com get_user_devices.php.
• Os dispositivos de uma conta podem estar em servidores diferentes. Abra uma ligação por cada servidor diferente, não uma por cada dispositivo.
• A porta 9001 tem de estar aberta para ligações de saída. Consulte os requisitos de rede.

Formato das mensagens

Cada mensagem que envia é uma matriz JSON:

[command_id, payload]

O command_id é um número inteiro. Comece em 1 e aumente-o a cada mensagem. A resposta tem o mesmo command_id.

O tamanho máximo de uma mensagem é 20 KiB. O servidor fecha a ligação se enviar uma mensagem maior.

1. Autenticação

A primeira mensagem depois da ligação é a autenticação:

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

Pode também enviar {"access_token": "YOUR_ACCESS_TOKEN"}. Consulte a autenticação.

Resposta	Significado
[]	Êxito
["Access Denied"]	Chave ou token errado. O servidor fecha a ligação.
[1,[{},"Rate limit"]]	Demasiadas ligações num curto período

Limite de ligações: 15 por 60 segundos para uma chave API. 25 por 60 segundos para um token de acesso.

2. Subscrever dispositivos (SUBSCRIBE)

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

Campo	Significado
c	SUBSCRIBE
server	Sempre true
serialnos	Os números de série dos dispositivos neste servidor
unsubscribe-others	true: o servidor para as subscrições anteriores desta ligação

Resposta: [2,[{},""]]. O servidor ignora os dispositivos a que não tem acesso. Não envia um erro para eles.

Para parar todas as subscrições, envie [3, {"c": "UNSUBSCRIBE", "server": true}].

3. Atualizações de estado

Imediatamente após a subscrição, o servidor envia o estado atual de cada dispositivo. Depois envia uma atualização cada vez que algo muda.

As atualizações são objetos JSON, não matrizes:

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

Campo	Conteúdo
serialno	O dispositivo
R	As leituras, em bruto, com o código da leitura como chave
O	Os valores das saídas, pela ordem de output_names
T	Os horários do dispositivo
S	As definições do dispositivo
previous	Os valores acumulados do período anterior, para dispositivos com contadores
alarms	Os alarmes ativos
is_local	true se a sua ligação e o dispositivo estão na mesma rede

• Uma atualização pode ter apenas os campos que mudaram. Junte-a ao estado que já tem.
• O servidor agrupa as alterações durante cerca de 100 ms antes de enviar uma atualização.
• Ignore as mensagens que não reconhece.

Para converter os valores em bruto, utilize as definições da família. Consulte a API REST.

Manter a ligação aberta

• O servidor envia pings WebSocket. A sua biblioteca tem de responder com um pong. A maioria das bibliotecas faz isto automaticamente.
• Se a ligação fecha, ligue-se outra vez. A aplicação espera 100 ms a primeira vez e 10 segundos depois disso.
• Depois de uma nova ligação, envie outra vez a autenticação e a subscrição.

Exemplo em Node.js

O Node.js 22 tem um WebSocket incorporado.

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

Um exemplo completo em Node.js está em nodejs_hamapi_example.zip. Contém a biblioteca hamapi.js e o ficheiro example.js.

1. Em example.js, defina server, api_key e os números de série.
2. Execute npm install e depois node example.js.

A biblioteca não volta a ligar quando a ligação fecha. Adicione isto ao seu código.

Consulte também

• API REST
• Webhooks das regras