Articles in this section

SocketIO

  • Updated
Follow

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.

The SocketIO service is particularly suitable for JavaScript based browser applications that need live updates from a Brain server, but can potentially be used from any platform with a socket.io 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 step 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.
{
  "topic_raw": "items/6051dedd89f1d306aeb06810/appeared/5e7cee7cbc4423033c25f6e3",
  "payload": {
    "code": "f4e41496fcfa",
    "type": "bluetitan",
    "protocol": "nanoble",
    "technology": "bluetooth",
    "time": "2022-10-14T14:20:02.021108Z"
  }
}

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);
});

Nodejs code example

The following nodejs example illustrates how events can be received using socket.io-client.

npm install socket.io-client

'use strict';
const io = require('socket.io-client');
const socket = io('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.on('disconnect', function() => {
  console.log('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);
});

HTML and Javascript code example

The following HTML and Javascript example illustrates how events can be received using socket.io-client in the browser.

<!DOCTYPE html>
<html>
<script src="https://cdn.socket.io/4.5.2/socket.io.js" integrity="sha384-2+LVKv/i4QG1Wf+uM0eKvM+hw78j6eMro4kLPJGJjjyOs+r+K9T7FMRKcKf8beMe" crossorigin="anonymous"></script>
<head>
  <title>Socket-IO Example</title>
</head>
<body></body>
<script>
const socket = io('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.on('disconnect', function() => {
  console.log('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);
});
</script>
</html>

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' } } ]

Related articles

Comments

0 comments

Article is closed for comments.