Jilia exposes realtime notifications of device state changes via WebSockets. Sockets provide immediate notification of a state change event as opposed to regularly polling the device with HTTP requests.

The Device Interaction page describes how to monitor a Jilia device using an open WebSocket. The example provided covers property changes of a single, specific device. However, it is also possible open WebSockets that subscribe to changes across a range of devices and servers.

This means that one can, for example, know when any light connected to a hub turned on. One can even be notified when any light connected to any active hub turns on.

NOTE: In order to successfully call Jilia resources, you must have a valid authentication token. The examples below will not include the use of an access token. For help obtaining and using a token, please see Application Authentication.

NOTE: Examples below will use command line calls to the node socket utility wscat.

Events Connection

The initial socket connection must be made to the Jilia /events resource.

>wscat -c wss://api.jilia.io/v1/events
connected (press CTRL+C to quit)
>

All messages sent and recieved within the open socket are JSON formatted.

Subscription Request

You must submit at least one subscription request to receive events over the socket connection. A subscription request informs the server of the events you are interested in receiving. The subscription request must include a type property set to "subscribe" and a topic property that describes the events of interest.

{
  "type": "subscribe",
  "topic": "**"
}

The above example subscription is the most general request possible in that it will subscribe to all events across all servers.

An optional limit property can be included as part of a subscription request. The limit is the number of events to be received before the client is automatically unsubscribed from the topic.

{
  "type": "subscribe",
  "topic": "**",
  "limit": 100
}

An unsubscribe-ack event is received when the specified limit value is reached.

{
  "type":"unsubscribe-ack",
  "subscriptionId":1,
  "timestamp":1449598490500
}

Subscription Response

If the subscription request is successful, the client will receive a subscription acknowledgement message with four properies:

  1. type: will be "subscribe-ack"
  2. timestamp: UTC timestamp of when the message was sent
  3. topic: The provided topic
  4. subscriptionId: An identifier included in all events sent for the provided topic

A successfull subscription request and response:

> {"type":"subscribe", "topic":"*/light/**"}
< {"type":"subscribe-ack","timestamp":1449597826414,"topic":"*/light/**","subscriptionId":1}

Unsubscribe

To unsubscribe from a topic, send an unsubscribe request message with the id received as part of the successful subscription.

{
  "type":"unsubscribe",
  "subscriptionId":2
}

A successful unsubscribe request and response:

> {"type":"unsubscribe", "subscriptionId": 2}
< {"type":"unsubscribe-ack","timestamp":1449600026008,"subscriptionId":2}

NOTE: It is possible to continue to receive events while the unusbscribe request is processed.

Event Messages

After a successful subscription, event messages will begin arriving. Each event message will contain the following five properties:

  1. type: Must be set to the string "event"
  2. topic: The topic to which the message belongs
  3. subscriptionId: Identifier of the associated subscription
  4. timestamp: A UTC timestamp of when the message was sent
  5. data: The data payload for the message

The following is an event message received after a light device changed to the "off" state. (The server and device ids have been replaced with {server-id} and {device-id}).

{
  "type":"event",
  "topic":"{server-id}/light/{device-id}/onOff",
  "timestamp":1449599990628,
  "subscriptionId":1,
  "data":"Off"
}

Ping

The open event stream connection will close if idle for more than a minute. The client can send occasional "ping" messages to maintain an open connection and prevent the socket from unexpectedly closing. Ping messages are defined in the WebSocket protocol.

Most WebSocket libraries (e.g. node's ws and python's autobahn) provide the ability to send pings and handle pong responses. This is not, however, always the case (e.g. JavaScript running in the browser). When "native" pings are not possible, the ping topic is available.

> {"type":"ping"}
< {"type":"pong","timestamp":1469572621149}

As with the WebSocket protocol, data can be attached to the ping message, and the pong will echo that data.

> {"type":"ping", "data":1}
< {"type":"pong","timestamp":1469572764771,"data":1}
> {"type":"ping", "data":"two"}
< {"type":"pong","timestamp":1469572781196,"data":"two"}

The topic property value in events is the fully qualified version. It represents the precise topic that triggered the event and will not necessarily match the topic value used to create the subscription.

Topics

The pattern for topic values is hierarchical, with each level delimited by a forward slash (/). The levels can be derived from information about a server, a device, and a stream:

{server-name}/{device-type}/{device-id}/{stream-name}

Topics may include wildcards, represented by an asterisk (*), and may be used in hierarchical topics. A single asterisk (*) denotes a wildcard for a single level of the hierarchy. A double asterisk (**) denotes a wildcard for multiple levels of the hierarchy.

The following example topic will match all temperature events for thermostat devices connected to my-server. The use of a wildcard in the {device-id} position ensures that we receive events for all thermostats.

my-server/thermostat/*/temperature

The following topic will match all light device type events, regardless of the specific device id or the specific type of event.

my-server/light/**

The above topic can be generalized to cover light events across all active servers by replacing the server id with the wildcard character.

*/light/**

Errors

Any encountered issue will result in an error message with the following properties:

  1. type: Must be set to the string "error".
  2. code: Error code defining the error. See Error Codes below.
  3. timestamp: A UTC timestamp of when the message was sent.
  4. topic: The topic of the subscription.

Error Codes

  • 400: Bad Request - Invalid JSON in request
  • 405: Method Not Supported - Invalid "type" value for incoming message.
  • 500: Server Error