WebSocket Event API (/apievents)

1 - Overview

The device exposes a WebSocket server on port 80 that lets a client subscribe to state changes in real time. Instead of polling the REST interface, the client opens one persistent connection, registers the events it cares about, and the device pushes a JSON frame on every change.

Relationship to the REST API: Every WebSocket event has a matching REST endpoint of the same name. For example, the DeviceStatus event corresponds to GET /api/DeviceStatus. The payload in the WebSocket data field is identical to the data field in the corresponding REST response. Refer to the OpenAPI specification for full data schemas.

Push vs. poll: Use WebSocket subscriptions when you need low-latency notification of state changes, such as field evaluation results, I/O port switching, or temperature alarms. Use the REST interface for one-shot reads or configuration writes.

2 - Endpoint and Connection

Connect to:

ws://<device-ip>/apievents

Port 80. No authentication is required to open the connection. The device does not require periodic ping/keep-alive frames.

The following are illustrative examples only; many other WebSocket libraries exist with varying compression support:

3 - Message Format

All messages are JSON text frames. Five message types are used:

3.1  Register - client → device

Send one registration message per event after the connection is open. The clientId is a caller-chosen integer echoed back in every device response for that registration.

{
  "type":     "register",
  "event":    "temperatureAlarmStatus",
  "clientId": 1
}

3.2  Registration confirmation - device → client

On a successful registration the device immediately sends the current value in data. A status of 0 means success. Dispatch this message to your event handler exactly as a live event push - it is the first data point.

{
  "type":     "register",
  "event":    "temperatureAlarmStatus",
  "clientId": 1,
  "status":   0,
  "data":     { "AlarmState": "NoAlarm" }
}

3.3  Event push - device → client

Whenever the subscribed value changes, the device sends:

{
  "type":     "event",
  "event":    "temperatureAlarmStatus",
  "clientId": 1,
  "status":   0,
  "data":     { "AlarmState": "OverTemp" }
}

The data schema is identical to the data field of the matching GET /api/<EventName> response. Refer to the OpenAPI specification for full schema definitions.

3.4  Error response - device → client

If the event name is unknown or not available on this firmware, the device sends a registration response with status != 0. The connection stays open and other registrations on the same connection are not affected.

{
  "type":     "register",
  "event":    "nonExistentEvent",
  "clientId": 2,
  "status":   1,
  "error":    "Failed to register event for this connection due to an internal error. Does the event exist?"
}

3.5  Deregister - client → device

To stop receiving an event, send:

{
  "type":     "deregister",
  "event":    "temperatureAlarmStatus",
  "clientId": 1
}

No response is sent on deregistration.

4 - Step-by-Step

{ "type": "register", "event": "DeviceStatus",          "clientId": 0 }  // wait 200 ms
{ "type": "register", "event": "FieldEvaluationResult", "clientId": 1 }  // wait 200 ms
{ "type": "register", "event": "temperatureAlarmStatus","clientId": 2 }  // ...

5 - Dispatch Pattern

Incoming frames must be dispatched based on both type and status.

connection = websocket_connect("ws://<device-ip>/apievents")

// Register events one at a time with 200 ms gap
for each (clientId, eventName) in enumerate(events):
    connection.send({ "type": "register", "event": eventName, "clientId": clientId })
    sleep(200 ms)

// Receive loop
while connection is open:
    message = connection.receive()
    obj     = json_parse(message)

    type   = obj["type"]
    status = obj["status"]
    event  = obj["event"]

    if type == "event"  OR  (type == "register" AND status == 0):
        dispatch(event, obj["data"])      // live update OR initial value on registration

    elif type == "register" AND status != 0:
        log_error(event, obj["error"])    // registration rejected — other events unaffected

6 - Advanced Options - Throttle and Queue

Pass an optional options object when registering to control delivery behaviour.

6.1  Throttle

Limits how frequently event messages are delivered. Excess events are dropped before entering the queue.

{
  "type":     "register",
  "event":    "LSPdatetime",
  "clientId": 7,
  "options": {
    "throttle": {
      "minOutputIntervalMs": 5000
    }
  }
}

6.2  Queue

Each registered event has its own per-event queue on the shared connection.

"options": {
  "queue": {
    "priority":      "HIGH",
    "maxSize":       10,
    "discardIfFull": "OLDEST"
  }
}

Throttle is applied before queuing: excess events are discarded and never enter the queue.

7 - Subscribable Events

Event names are case-sensitive. The full data schema for each event is defined in the OpenAPI specification under the corresponding GET endpoints.

8 - Reconnect Strategy

The device may close the connection on network interruption or a firmware restart. There is no session state preserved across connections - all subscriptions must be re-registered after reconnection.