SocketIO

The Brain's zero-configuration socket.io service can be used to receive new events through an open connection. There are no hard limits on the amount of connections that may be created or on the lifetime of a connection.

Important note: Brain versions 2.x and older use socket.io 1.x, which is not the latest major version of socket.io. Socket.io 2.x is largely but not entirely backwards compatible with socket.io 1.x servers; it is therefore recommended to use a socket.io 1.x client. The next major Brain version is expected to implement socket.io 2.x.

The SocketIO service is particularly suitable for JavaScript based browser applications that need live updates from a Brain, but can potentially be used from any platform with a socket.io v1.x client library.

Receiving events

The procedure for setting up a SocketIO session:

1. Open a socket.io connection to the Brain hostname with an API key as query parameter, i.e. https://<brain-host>/?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
2. When connected, emit a 'subscribe' packet with an object specifying a topic_filter to start receiving events matching that filter; see Event filtering. Example: {"topic_filter": "items/+/moved-to/#"}
3. Optionally repeat (2) for additional topic filters as often as necessary.
4. Process incoming 'event' packets.

An event packet consists of an object with the following properties:

• topic_raw (string), the full event topic that was matched by one of the active filters.
• payload (object), additional event data not covered by the topic.

It is also possible to unsubscribe a previously subscribed topic in the same way as subscribing, except using an 'unsubscribe' packet instead of a 'subscribe' packet.

The socket.io connections are stateless and the subscriptions temporary. As soon as the connection is closed, everything about it is forgotten.

JavaScript code example

The following JavaScript example illustrates how events can be received using socket.io. It assumes the socket.io client library (io object) is already loaded.

var socket = io.connect('https://<brain-host>/?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');
socket.on('error', function(err) {
 console.error(err);
});
socket.on('connect', function() {
 socket.emit('subscribe', {topic_filter: 'items/+/appeared/#'});
 socket.emit('subscribe', {topic_filter: 'items/+/disappeared/#'});
 socket.emit('subscribe', {topic_filter: 'items/+/moved-to/#'});
 socket.emit('subscribe', {topic_filter: 'spots/+/connected/#'});
 socket.emit('subscribe', {topic_filter: 'spots/+/disconnected/#'});
});
socket.on('event', function(event) {
 var topicArgs = event.topic_raw.split('/');
 var resource = topicArgs.shift();
 var id = topicArgs.shift();
 var action = topicArgs.shift();
 console.log('Received ' + action + ' event for ' + resource + ' object ' + id + ' with additional arguments', topicArgs);
});

Testing with iocat

The Brain socket.io event service is compatible with the iocat utility. This can be useful when exploring, testing or debugging. Iocat can be installed using the npm package manager: npm install --global iocat.

Example usage of iocat with the Brain:

iocat --socketio https://<brain-host>/?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
> {"topic_filter": "items/#"}

[ { topic_raw: 'items/56446fabd8838577844a6f1b/appeared',
    payload:
     { code: '4d5245562d4d3530303535040008',
       type: 'tag',
       protocol: 'epcgen2',
       technology: 'rfid',
       time: '2018-09-03T13:24:32.058635Z' } } ]