Receiving Messages

When WebSocket connection is created and valid OPEN message sent from client then server will send initial response messages to the WebSocket including current state information of all active devices in the network. After sending initial messages server will not send any new messages to WebSocket until some event occurs in the related network and/or to its devices. Use "onmessage" event listener of WebSocket to receive messages. Following code example shows how messages can be received from server.

webSocket.onmessage = function (event) {

  (new Response(event.data)).text().then(function (result) {

    let data = JSON.parse(result);
    if ("method" in data) {
      console.log(data);

      if (data.method === "unitChanged") {
        // Initial device state info and device state changed event
        // In case data.id is not in "network.units" list (fetched via API) this event can be ignored.

      } else if (data.method === "networkUpdated") {
        // Network changed event, for example device added to a group within the network

      } else if (data.method === "peerChanged") {
        // Online peers changed, for example new API client has joined the network when gateway is connected

      }

    }
  }, function (error) {
    console.log(error);
  });

};

Wire Status message

On specific situations server will respond with Wire Status message. For example initial WebSocket response message (received after OPEN message) will contain a "wireStatus" key/value pair that holds information if OPEN message was successful or not. This initial response message will include reference ID given by the client in the OPEN message (if any), this key/value pair will be simply named as "ref".

In some situations server will respond with Wire Status message when there was a problem handling the received message. For example if client sends invalid CONTROL message to server that contains invalid values then server will respond with wireStatus: invalidValueType message. This kind of response message will not include any reference ID or other identifier data and is only sent to the client that sent the related CONTROL message in the first place.

Following list includes possible wireStatus values.

openWireSucceed	Wire opened successfully.
keyAuthenticateFailed	API key authentication failed. Given key was invalid.
keyAuthorizeFailed	API key authorize failed. Given key has not been authorized or WebSocket functionality is not enabled for it.
invalidSession	Either access to given network is not authorized by session or given session is invalid.
tooManyWires	Trying to open more wires to the same network than is allowed. One wire per connection/network or maximum of 20 different wires per network are allowed.
invalidValueType	Received values are not in correct value type, for example when expecting a number but receiving string value instead.
invalidData	Received data is invalid and cannot be processed, for example expected list of items is in wrong data format.

Message method types

WebSocket event messages include a "method" key/value pair that holds information about what kind of event has occurred. In addition event messages will always include related wire ID originally given by the client, this key/value pair will be simply named as "wire".

Following list includes common event types that message can have.

unitChanged	Device state has changed from the previous known state. Returned device information and control state list contain the changed information. In case when receiving information about device that is currently not part of the network.units list (fetched via API) this event can be ignored.
peerChanged	API client/gateway has joined or left "active" network. In most cases no action required.
networkUpdated	Network setting or composition has somehow changed. Fetching latest network information from REST API and re-sending the OPEN message to WebSocket is recommended. *

note

The networkUpdated event is triggered by any persistent change in configuration of network or its scene or device. In other words if something else than state info changed and it needs to be stored to related configuration then it will require network info update.