RtlsDevGuide RPP DG-011

RTLS Developers GuideBuilding indoor location applications using the Red Point Positioning RTLS system

RTLS Developers Guide 2014 Red Point Positioning Corporation

Contents

1 About This Guide 21.1 Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Introduction 3

3 REST API (HTTP Verbs) 43.1 Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.1.1 Get all the locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.1.2 Get a single location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.2 Sub-locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2.1 Get all the sub-locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2.2 Get a single sub-location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63.2.3 Get all sublocations within a given location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.3 Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3.1 Get all the nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.3.2 Get all the nodes active within an interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.3.3 Get all the mobile nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3.4 Get all the fixed nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.3.5 Get all the bridge nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.3.6 Get all the bridge nodes in a given sublocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.3.7 Get all the images for a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.4 Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4.1 Get all the sensors types on a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.4.2 Get the sensor values on a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.5 Node Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.5.1 Get the diagnostic values for a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.5.2 Get the link quality for a given source node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Publish/Subscribe Interface 174.1 Example Ruby Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.2 Example C++ Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5 Non-REST API 195.1 Server Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Contact 20

7 References 21

Page 1


1 About This Guide

This document is intended to be used by third-party developers who will be building location-based applications orintegrating existing software with Red Point Positionings RTLS system. It describes the application programminginterfaces (API) for configuring the indoor positing system, retrieving node information, including location, readingsensor values, and controlling actuators.

1.1 Where to find more information

For more information, please consult the references included at the end of this manual. Detailed information for settingup the RPP RTLS system may be found in the Users Guide (RTLS System Users Guide. 2014).

Additional support may be obtained online through the Red Point Positioning web site at the following URL:

http://redpointpositioning.com/support/

Page 2


2 Introduction

The basic interface for communicating with the RPP system is the REST API. This allows third-party code to get and setvarious parameters within the RTLS system. For example, it is a simple matter to query the system for radio nodesseen within a given time-interval. This interface is flexible, but inherently inefficient for continuous operation becauseof its polling nature.

The RBS also provides a publication/subscription mechanism that allows for push notifications to third-party clientswhenever there is an update to position or sensor data.

Details for each of these interfaces are provided in their respective sections below.

Page 3


3 REST API (HTTP Verbs)

Describe the model for interacting with the system. How is data stored? How do we retrieve it?

Figure 1: Programming Model

3.1 Locations

3.1.1 Get all the locations

Returns a list of locations as an array of hashes.

GET /locations.json

[{

"id": 1,"name": "Default Building","description": "Default City","latitude": 39.9173,"longitude": 116.441,"elevation": 0.0,"street_address": "123 Main St","street_address2": null,"city": "Default City","state": "Earth","zip": 123456,

Page 4


"zip4": null,"model_name": "","rpl_prefix": 1,"rpl_version": 0,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"}]

3.1.2 Get a single location

Gets a single location.

GET /locations/:id.json

{"id": 1,"name": "Default Building","description": "Default City","latitude": 39.9173,"longitude": 116.441,"elevation": 0.0,"street_address": "123 Main St","street_address2": null,"city": "Default City","state": "Earth","zip": 123456,"zip4": null,"model_name": "","rpl_prefix": 1,"rpl_version": 0,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"}

Parameters:

id (required) - The ID of a sub-location.

3.2 Sub-locations

3.2.1 Get all the sub-locations

Returns a list of sub-locations as an array of hashes.

GET /sublocations.json

[{

"id": 1,"name": "Floor #1","description": "Office park, floor #1","location_id": 1,"created_at": "2014-06-20T07:41:01.000Z",

Page 5


"updated_at": "2014-06-20T07:41:01.000Z"},{

"id": 2,"name": "Floor #2","description": "Office park, floor #2","location_id": 1,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"}]

3.2.2 Get a single sub-location

Gets a single sub-location.

GET /sublocations/:id.json

{"id": 1,"name": "Floor #1","description": "Office park, floor #1","location_id": 1,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"}

Parameters:

id (required) - The ID of a sub-location.

3.2.3 Get all sublocations within a given location

Returns a list of sub-locations as an array of hashes within a given location.

GET /locations/:id/sublocations.json

[{

"id": 1,"name": "Floor #1","description": "Office park, floor #1","location_id": 1,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"},{

"id": 2,"name": "Floor #2","description": "Office park, floor #2","location_id": 1,"created_at": "2014-06-20T07:41:01.000Z","updated_at": "2014-06-20T07:41:01.000Z"}]

Page 6


Parameters:

id (required) - The ID of a locations.

3.3 Nodes

3.3.1 Get all the nodes

Returns a list of nodes in the database regardless of location and sub-location.

GET /nodes.json

[{

"announce_timestamp": "2013-10-24T02:58:13Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:52:47Z","id": 22,"last_heard": "2013-10-24T02:58:23Z","mac_address": "00cd00fffe000229","name": "M #229","node_type_id": 2,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "2013-10-24T02:58:23Z","position_x": 239,"position_y": 359,"position_z": 120,"ranging_frequency": 4,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": 1,"updated_at": "2013-10-24T02:58:23Z","current_system_timestamp": "2013-10-24T02:58:23+00:00"},{

"announce_timestamp": "2013-10-24T02:59:35Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:51:15Z","id": 20,"last_heard": "2013-10-24T02:59:35Z","mac_address": "00cd00fffe000273","name": "F #273","node_type_id": 1,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 128,"position_y": 942,"position_z": 30,"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z",

Page 7


"sequence_number": 0,"sublocation_id": 1,"updated_at": "2013-10-24T02:59:35Z","current_system_timestamp": "2013-10-24T02:59:36+00:00"},{

"announce_timestamp": "2013-10-24T02:59:27Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:51:15Z","id": 21,"last_heard": "2013-10-24T02:59:27Z","mac_address": "00cd00fffe000280","name": "F #280","node_type_id": 1,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 66,"position_y": 0,"position_z": 30,"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": 1,"updated_at": "2013-10-24T02:59:27Z","current_system_timestamp": "2013-10-24T02:59:36+00:00"},

...]

3.3.2 Get all the nodes active within an interval

Returns a list of nodes which have sent a heartbeat message within a specific interval regardless of location andsub-location.

GET /nodes/recent.json?interval=:timespec

[{

"announce_timestamp": "2013-10-24T03:14:20Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-09-25T04:34:39Z","id": 18,"last_heard": "2013-10-24T03:14:20Z","mac_address": "00cd00fffe000248","name": "B #248","node_type_id": 4,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 315,"position_y": 444,"position_z": 30,"ranging_frequency": 0,

Page 8


"reporting_frequency": 10,"root_formed": true,"root_formed_timestamp": "2013-10-23T02:03:08Z","sequence_number": 0,"sublocation_id": 1,"updated_at": "2013-10-24T03:14:20Z","current_system_timestamp": "2013-10-24T03:14:24+00:00"},{

"announce_timestamp": "2013-10-24T03:14:18Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:52:47Z","id": 22,"last_heard": "2013-10-24T03:14:24Z","mac_address": "00cd00fffe000229","name": "M #229","node_type_id": 2,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "2013-10-24T03:14:24Z","position_x": 237,"position_y": 360,"position_z": 120,"ranging_frequency": 4,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": "1","updated_at": "2013-10-24T03:14:24Z","current_system_timestamp": "2013-10-24T03:14:24+00:00"}]

Parameters:

timespec (optional) - The time specification in seconds (s), minutes (m), hours (h), or days (d), e.g. 5s stands5 seconds, 5m stands for 5 minutes, 5h stands for 5 hours, 5d stands for 5 days. The parameter is optional, withthe default specified by the dr2.yml config file with the parameter default_node_time_interval.The parameters default value is 15m.

3.3.3 Get all the mobile nodes

Returns a list of all mobile nodes regardless of location and sub-location.

GET /nodes/mobile.json

[{

"announce_timestamp": "2013-10-24T03:24:30Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:52:47Z","id": 22,"last_heard": "2013-10-24T03:24:34Z","mac_address": "00cd00fffe000229",

Page 9


"name": "M #229","node_type_id": 2,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "2013-10-24T03:24:34Z","position_x": 238,"position_y": 359,"position_z": 120,"ranging_frequency": 4,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": "1","updated_at": "2013-10-24T03:24:34Z","current_system_timestamp": "2013-10-24T03:24:34+00:00"}]

Parameters:

timespec (optional) - ?interval=:timespec The time specification in seconds (s), minutes (m), hours(h), or days (d), e.g. 5s stands 5 seconds, 5m stands for 5 minutes, 5h stands for 5 hours, 5d stands for 5days. If the interval is not specified, all mobiles nodes will be listed, regardless of recent activity.

3.3.4 Get all the fixed nodes

Returns a list of all fixed nodes.

GET /nodes/fixed.json

[{

"announce_timestamp": "2013-10-24T03:35:48Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-09-19T08:27:38Z","id": 13,"last_heard": "2013-10-24T03:35:48Z","mac_address": "00cd00fffe000226","name": "F #226","node_type_id": 1,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": -5,"position_y": 278,"position_z": 30,"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": 1,"sw_version": "0","updated_at": "2013-10-24T03:35:48Z","current_system_timestamp": "2013-10-24T03:35:49+00:00"

Page 10


},{

"announce_timestamp": "2013-10-24T03:35:49Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-10-11T05:51:15Z","id": 20,"last_heard": "2013-10-24T03:35:49Z","mac_address": "00cd00fffe000273","name": "F #273","node_type_id": 1,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 128,"position_y": 942,"position_z": 30,"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": false,"root_formed_timestamp": "1970-01-01T00:00:00Z","sequence_number": 0,"sublocation_id": 1,"sw_version": "0","updated_at": "2013-10-24T03:35:49Z","current_system_timestamp": "2013-10-24T03:35:49+00:00"}]

Parameters:

timespec (optional) - ?interval=:timespec The time specification in seconds (s), minutes (m), hours(h), or days (d), e.g. 5s stands 5 seconds, 5m stands for 5 minutes, 5h stands for 5 hours, 5d stands for 5days. If the interval is not specified, all mobiles nodes will be listed, regardless of recent activity.

3.3.5 Get all the bridge nodes

Returns a list of all bridge nodes regardless of location and sub-location.

GET /nodes/bridge.json

[{

"announce_timestamp": "2013-10-24T03:38:15Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-09-25T04:34:39Z","id": 18,"last_heard": "2013-10-24T03:38:15Z","mac_address": "00cd00fffe000248","name": "B #248","node_type_id": 4,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 315,"position_y": 444,"position_z": 30,

Page 11


"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": true,"root_formed_timestamp": "2013-10-23T02:03:08Z","sequence_number": 0,"sublocation_id": 1,"sw_version": "0","updated_at": "2013-10-24T03:38:15Z","current_system_timestamp": "2013-10-24T03:38:16+00:00"}]

Parameters:

timespec (optional) - ?interval=:timespec the time specification in seconds (s), minutes (m), hours(h), or days (d), e.g. 5s stands 5 seconds, 5m stands for 5 minutes, 5h stands for 5 hours, 5d stands for 5days. If the interval is not specified, all mobiles nodes will be listed, regardless of recent activity.

3.3.6 Get all the bridge nodes in a given sublocation

Returns a list of all bridge nodes regardless of location and sub-location.

GET /sublocation/:sublocation_id/bridge.json

[{

"announce_timestamp": "2013-10-24T03:46:38Z","bridge_mac_address": "00cd00fffe000248","created_at": "2013-09-25T04:34:39Z","id": 18,"last_heard": "2013-10-24T03:46:38Z","mac_address": "00cd00fffe000248","name": "B #248","node_type_id": 4,"parent_mac_address": "00cd00fffe000248","position_update_timestamp": "1970-01-01T00:00:00Z","position_x": 315,"position_y": 444,"position_z": 30,"ranging_frequency": 0,"reporting_frequency": 10,"root_formed": true,"root_formed_timestamp": "2013-10-23T02:03:08Z","sequence_number": 0,"sublocation_id": 1,"sw_version": "0","updated_at": "2013-10-24T03:46:38Z","current_system_timestamp": "2013-10-24T03:46:43+00:00"}]

Parameters:

sublocation_id (required) - The id of the sublocation in which the bridge(s) are configured.

Page 12


3.3.7 Get all the images for a given node

Reserved for future use.

GET /node/mac/:mac_address/photo.json?interval=1h

[{

"created_at": "2012-12-10T22:42:23Z","id": 5,"image":

{"url": "/uploads/photo/image/1/1355179343-test.jpg","name": nil,"node_id": 1,"updated_at": "2012-12-10T22:42:23Z"}}]

Parameters:

mac_address (required) - The mac address of the node

3.4 Sensors

3.4.1 Get all the sensors types on a given node

Returns a list the sensors on a given node.

GET /nodes/:node_id/show-sensor-types

[{

"bit_width": 16,"created_at": "2013-09-18T06:09:14Z","description": "Not Used: ADC0: Light sensor","formula": null,"id": 1,"name": "Not Used: ADC0: Light","updated_at": "2013-09-18T06:09:14Z","use_formula": false},{

"bit_width": 16,"created_at": "2013-09-18T06:09:14Z","description": "ADC1: Temperature sensor deg C","formula": null,"id": 2,"name": "ADC1: Temperature","updated_at": "2013-09-18T06:09:14Z","use_formula": false},{

"bit_width": 16,

Page 13


"created_at": "2013-09-18T06:09:14Z","description": "Not Used: ADC2","formula": null,"id": 3,"name": "Not Used: ADC2","updated_at": "2013-09-18T06:09:14Z","use_formula": false},{

"bit_width": 16,"created_at": "2013-09-18T06:09:14Z","description": "ADC3: Battery in mV","formula": null,"id": 4,"name": "ADC3: Battery","updated_at": "2013-09-18T06:09:14Z","use_formula": false},{

"bit_width": 16,"created_at": "2013-09-18T06:09:14Z","description": "The panic button","formula": null,"id": 5,"name": "Pushbutton","updated_at": "2013-09-18T06:09:14Z","use_formula": false}]

Parameters:

node_id (required) - The id of the node being queried

3.4.2 Get the sensor values on a given node

List the sensor values on a given node during the default interval or specified interval. The parameter is optional, withthe default specified by the dr2.yml config file with the parameter default_node_time_interval. Theparameters default value is 15m.

GET /nodes/:node_id/show-sensor-readings(?interval=:timespec)

[{

"created_at": "2013-10-24T11:52:41Z","id": 236791,"node_id": 22,"reading": 8,"sensor_type_id": 1,"sequence": 52,"updated_at": "2013-10-24T11:52:41Z"},...]

Page 14


Parameters:



3.5 Node Diagnostics

3.5.1 Get the diagnostic values for a given node

Returns a list of the diagnostics on a given node.

GET /nodes/:node_id/get_diag.json(?interval=timespec)

[{

"crc_bad": 2,"crc_good": 56,"created_at": "2013-01-17T00:23:09Z","id": 3,"node_id": 5,"packet_header_errors": 6,"preamble_errors": 0,"rx_sync_loss": 2,"sfdto_errors": 0,"tx_count": 33,"updated_at": "2013-01-17T00:23:09Z"}]

Parameters:



3.5.2 Get the link quality for a given source node

Returns a list of the link quality measurements originated from a given node.

GET /nodes/:node_id/get_link_qual.json(?interval=timespec)

[{

"created_at": "2013-01-16T23:23:18Z","dst_node_id": 4,"id": 1,"rx_count": 9,"src_node_id": 5,"test_timestamp": "2013-01-16T23:23:18Z",

Page 15


"tx_count": 10,"updated_at": "2013-01-16T23:23:18Z"}]

Parameters:



Page 16


4 Publish/Subscribe Interface

RPP supports a publish/subscribe interface based on the ZeroMQ library (ZeroMQ.).

Whenever a radio nodes position or sensor update arrives at the RBS, the base station will push the update to thepublishing interface. Any subscriber listening to individual channels (#sensor/#position) will get the relevant data. Ifyou subscribe to all channels ( as the subscribed channel), you will hear both sensor and position updates.

4.1 Example Ruby Subscriber

require 'rbczmq'

PUB_SUB_COUNT = 100

context = ZMQ::Context.new

# Socket to talk to serverputs 'Collecting updates from weather server'subscriber = context.socket :SUBsubscriber.connect('tcp://192.168.56.20:7001')

# subscribe to both sensor and position updatessubscriber.subscribe('')

# Sensor updates will be of format:## channel time_epoch,node_id,datum_sequence_number,

number_of_sensor_readings,sensor1,sensor2,sensor3,sensor4,sensor5## Did you see that channel is separated by space from the rest of data?# So you will see something like:## #sensor 1400111899,18,0,5,0,65515,0,65480,0## 5th sensor is wired to be a push button## Position updates will be of format:## channel time_epoch,node_id,position_x,position_y,position_z,

sublocation_id## #position 1400111899,18,100,100,100,1

1.upto(PUB_SUB_COUNT) do |update_nbr|s = subscriber.recvputs "received: #{s}"end

4.2 Example C++ Subscriber

#include

Page 17


#include #include

// Need https://github.com/zeromq/cppzmq.git somewhere// g++ ./rtls-cpp-subscriber.cpp -o rtls-cpp-subscriber -I /usr/local/opt/

zeromq/include -lzmq//

int main (int argc, char *argv[]){

zmq::context_t context (1);

// Socket to talk to serverstd::cout


5 Non-REST API

5.1 Server Discovery

The RPP system supports server discovery via UDP broadcast to port 7122. If the RBS receives a broadcast on port7122, it will answer to the originating socket via UDP with hton packed ip address of the server.

Page 19


6 Contact

Please dont hesitate to contact us directly:

Red Point Positioning Corporation20 Webster Street, Suite 411Brookline, MA 02446USA

Email: [email protected]: +1(617)207-4096

Page 20


7 References

RTLS System Users Guide. 2014. Red Point Positioning Corporation.

ZeroMQ. iMatix Corporation. http://zeromq.org/.

Page 21

About This GuideWhere to find more information

IntroductionREST API (HTTP Verbs)LocationsGet all the locationsGet a single location

Sub-locationsGet all the sub-locationsGet a single sub-locationGet all sublocations within a given location

NodesGet all the nodesGet all the nodes active within an intervalGet all the mobile nodesGet all the fixed nodesGet all the bridge nodesGet all the bridge nodes in a given sublocationGet all the images for a given node

SensorsGet all the sensors types on a given nodeGet the sensor values on a given node

Node DiagnosticsGet the diagnostic values for a given nodeGet the link quality for a given source node

Publish/Subscribe InterfaceExample Ruby SubscriberExample C++ Subscriber

Non-REST APIServer Discovery

ContactReferences

Date post:	06-Sep-2015
Category:	Documents
Upload:	rigorini
View:	222 times
Download:	3 times

RtlsDevGuide RPP DG-011

Documents