API | WebSockets Connector

WebSockets Connector

Websockets is a protocol carried over single TCP connection heavily used in web based applications. Communication is based on publish-subscribe model, where client can subscribe to particular stream from Tag or Anchor and be immediately updated whenever its position is being changed.

Data received from WebSockets

Several types of data are possible to receive from Websockets:

  • change of any datastream for tag or anchor, for example: tag has changed position in X and Y axis and the clr (confidence level radius) changed to 0.10:
    {"body":{"id":"18","datastreams":[{"id":"posX","current_value":" 6.34","at":"2016-10-18 14:16:56.365"},{"id":"posY","current_value":" 2.27","at":"2016-10-18 14:16:56.365"},{"id":"clr","current_value":" 0.10","at":"2016-10-18 14:16:56.365"}]},"resource":"\/feeds\/18"}
  • change of battery/firmware version/hardware version/platform for tag, for example:
    {"body":{"id":"1","datastreams":[{"id":"battery_level","current_value":"77%","at":"2016-10-18 15:27:38.606"},{"id":"firmware_version","current_value":"3.115","at":"2016-10-18 15:27:38.606"}]},"resource":"\/feeds\/1"}
  • tag entering zone(s), for example tag with id 18 is entering danger zone (with zone id 100 and name my_danger_zone) which is located in building with id 7 on plan called my_plan at given UTC time. Note that tag could enter multiple zones at once
    {"body":{"id":"18","zones":[{"id":"100","type":"danger","name":"my_danger_zone","feed_id":"7","plan":"my_plan","at":"2016-10-18 15:02:07.610"}],"datastreams":[{"id":"posX","current_value":" 6.48","at":"2016-10-18 15:02:07.610"},{"id":"posY","current_value":" 2.32","at":"2016-10-18 15:02:07.610"},{"id":"clr","current_value":" 0.00","at":"2016-10-18 15:02:07.610"}]},"resource":"\/feeds\/18"}
  • zone change, for example tag with ID 23 entered zone with ID 2 at particular UTC time:
    {"body":{"feed_id":"23","zone_id":"2","status":"in","at":"2016-10-26 09:30:58.428415"},"resource":"\/zones\/2"}
    or tag left that zone 1 minute later:
    "{"body":{"feed_id":"23","zone_id":"2","status":"out","at":"2016-10-26 09:31:58.428415"},"resource":"\/zones\/2"}"

  • user created new feed (i.e. anchor, tag, building):
    {"body":{"data":{"id":"26","alias":"some general alias for anchor\/tag\/building\/...","title":"arbitrary feed title","private":"false","description":"This is some description for my feed.","feed":"Another description in another value","status":"live","updated":"2016-07-29 12:59:43.776046","created":"2016-07-29 12:59:43.776046","creator":"rtlsuser","version":"1.0.0","website":"www.websiteforthisfeed.com","tags":["metainformation","#rtls_type#anchor"],"datastreams":[{"id":"posX","current_value":"5.8","at":"2016-06-09 14:34:28.4545","symbol":"m","label":"meter","datapoints":[{"value":"4.2","at":"2016-06-09 14:34:28.4545"}]},{"id":"posY","current_value":"N\/A"},{"id":"posZ","current_value":"N\/A"}],"location":{"exposure":"indoor","ele":"","name":"","lat":"","lon":"","domain":"","disposition":""},"feed_id":"26"}},"method":"new_feed","resource":"\/user\/rtlsuser"}
    Note: this event is triggered whenever RTLS Server automatically detects and creates new anchor or tag

API for WebSockets

There are three methods available:
Subscribe

  1. to feed (tag/anchor) updates
    {"headers":{"X-ApiKey":"YOUR_KEY"},"method":"subscribe","resource":"/feeds/YOUR_FEED"}
  2. to zone changes
    {"headers":{"X-ApiKey":"YOUR_KEY"},"method":"subscribe", "resource":"/zones/YOUR_ZONE_ID"}
  3. to creation of new feeds (tags/anchors) by user USERNAME
    {"headers":{"X-ApiKey":"YOUR_KEY"}, "method":"subscribe", "resource":"/user/USERNAME"}


Unsubscribe

  1. to feed (tag/anchor) updates
    {"headers":{"X-ApiKey":"YOUR_KEY"},"method":"unsubscribe","resource":"/feeds/YOUR_FEED"}
  2. to zone changes
    {"headers":{"X-ApiKey":"YOUR_KEY"},"method":"unsubscribe", "resource":"/zones/YOUR_ZONE_ID"}
  3. to creation of new feeds (tags/anchors) by user USERNAME
    {"headers":{"X-ApiKey":"YOUR_KEY"}, "method":"unsubscribe", "resource":"/user/USERNAME"}


Put
{"headers":{"X-ApiKey":"YOUR_KEY"},"method":"put",options:{savetoDB:false}, "body":{"id":FEED_ID,"datastreams":[{"id":"posX","current_value":VALUE},{"id":"posY","current_value":VALUE}]}, "resource":"/feeds/FEED_ID"}

How to Subscribe and Receive Data via WebSockets (example)

Let’s use the Developer Console from Google Chrome web browser to be an independent on programming. The console can be found in Menu -> More tools -> JavaScript Console (CRTL+SHIFT+J)

chrome_console

Firstly Client must connect to Sensmap Server Websocket interface which resides implicitly on IP 192.168.225.2 and port 8080.

var conn = new WebSocket('ws://192.168.225.2:8080');
conn.onopen = function(e) {
console.log("Connection established!");
};

conn.onmessage = function(e) {
console.log(e.data);
};

ws_connection

“Connection established!” should appear within the console window. Now we can subscribe to the Tag 0x00205EFE1085. Before that we need to find unique ID called FEED_ID. This can be done visually through Sensmap Visualization or via REST command GET FEEDS / GET ANCHORS / GET TAGS request .

sensmap_tag_id

From picture above we see that Tag 0x00205EFE1085 has assigned ID 18.

Now we can subscribe to its datastream with a default read-only key 171555a8fe71148a165392904

conn.send('{"headers":{"X-ApiKey":"171555a8fe71148a165392904"},"method":"subscribe", "resource":"/feeds/18"}');

ws_subscribe

Then we need to update position of the Tag, therefore if you have RTLS System running you may start moving the Tag.
Immediately after the position is changed updated information should appear in console output. In our example position was updated to values [6.5, 2.6], see marked variables.

ws_data