Live data (WebSocket)

With the WebSocket you get the readings and the changes of the devices at the moment they happen. The HAM app uses the same connection. For one reading at a time, the REST API is simpler.

Address

wss://DEVICE_SERVER:9001

DEVICE_SERVER is the value of the device_server field of each device. You find it with get_user_devices.php.
The devices of one account can be on different servers. Open one connection for each different server, not one for each device.
Port 9001 must be open for outbound connections. See the network requirements.

Message format

Each message that you send is a JSON array:

[command_id, payload]

The command_id is an integer. Start at 1 and increase it with each message. The reply has the same command_id.

The maximum size of a message is 20 KiB. The server closes the connection if you send a larger message.

1. Authentication

The first message after the connection is the authentication:

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

You can also send {"access_token": "YOUR_ACCESS_TOKEN"}. See authentication.

Reply	Meaning
`[]`	Success
`["Access Denied"]`	Wrong key or token. The server closes the connection.
`[1,[{},"Rate limit"]]`	Too many connections in a short time

Connection limit: 15 per 60 seconds for one API key. 25 per 60 seconds for one access token.

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

Field	Meaning
`c`	`SUBSCRIBE`
`server`	Always `true`
`serialnos`	The serial numbers of the devices on this server
`unsubscribe-others`	`true`: the server stops the earlier subscriptions of this connection

Reply: [2,[{},""]]. The server skips the devices that you do not have access to. It does not send an error for them.

To stop all subscriptions, send [3, {"c": "UNSUBSCRIBE", "server": true}].

3. State updates

Immediately after the subscription, the server sends the current state of each device. Then it sends an update each time something changes.

The updates are JSON objects, not arrays:

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

Field	Content
`serialno`	The device
`R`	The readings, raw, keyed by reading code
`O`	The output values, in the order of `output_names`
`T`	The schedules of the device
`S`	The device settings
`previous`	The accumulated values of the previous period, for devices with counters
`alarms`	The active alarms
`is_local`	`true` if your connection and the device are on the same network

An update can have only the fields that changed. Merge it into the state that you already have.
The server groups changes for about 100 ms before it sends an update.
Ignore messages that you do not recognise.

To convert the raw values, use the family definitions. See the REST API.

Keep the connection open

The server sends WebSocket pings. Your library must reply with a pong. Most libraries do this automatically.
If the connection closes, connect again. The app waits 100 ms the first time and 10 seconds after that.
After a new connection, send the authentication and the subscription again.

Node.js example

Node.js 22 has a built-in 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);
  }
};

A complete Node.js example is in nodejs_hamapi_example.zip. It contains the hamapi.js library and the file example.js.

In example.js, set server, api_key and the serial numbers.
Run npm install, then node example.js.

The library does not connect again when the connection closes. Add this to your code.