RtlsDevGuide RPP DG-011

RTLS Developers Guide
Building indoor location applications using the Red Point Positioning RTLS system
2014 Red Point Positioning Corporation
Contents
1 About This Guide
1.1 Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Introduction
3 REST API (HTTP Verbs)
3.1 Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Get all the locations
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Get a single location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Sub-locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Get all the sub-locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Get a single sub-location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Get all sublocations within a given location . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Get all the nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Get all the nodes active within an interval
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 Get all the mobile nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.4 Get all the fixed nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.3.5 Get all the bridge nodes
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3.6 Get all the bridge nodes in a given sublocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.3.7 Get all the images for a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.4 Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.4.1 Get all the sensors types on a given node
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.4.2 Get the sensor values on a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.5 Node Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5.1 Get the diagnostic values for a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5.2 Get the link quality for a given source node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 Publish/Subscribe Interface
17
4.1 Example Ruby Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.2 Example C++ Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5 Non-REST API
19
5.1 Server Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Contact
20
7 References
21
Page 1
About This Guide
This document is intended to be used by third-party developers who will be building location-based applications or
integrating existing software with Red Point Positionings RTLS system. It describes the application programming
interfaces (API) for configuring the indoor positing system, retrieving node information, including location, reading
sensor 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 setting
up 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
Introduction
The basic interface for communicating with the RPP system is the REST API. This allows third-party code to get and set
various parameters within the RTLS system. For example, it is a simple matter to query the system for radio nodes
seen within a given time-interval. This interface is flexible, but inherently inefficient for continuous operation because
of its polling nature.
The RBS also provides a publication/subscription mechanism that allows for push notifications to third-party clients
whenever there is an update to position or sensor data.
Details for each of these interfaces are provided in their respective sections below.
Page 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",
"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",
"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",
"location_id": 1,
"created_at": "2014-06-20T07:41:01.000Z",
"updated_at": "2014-06-20T07:41:01.000Z"
},
{
"id": 2,
"name": "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"
},
{
"created_at": "2013-10-11T05:51:15Z",
"id": 20,
"last_heard": "2013-10-24T02:59:35Z",
"name": "F #273",
"node_type_id": 1,
"position_x": 128,
"position_y": 942,
"position_z": 30,
Page 7
"updated_at": "2013-10-24T02:59:35Z",
},
{
"created_at": "2013-10-11T05:51:15Z",
"id": 21,
"last_heard": "2013-10-24T02:59:27Z",
"name": "F #280",
"node_type_id": 1,
"position_x": 66,
"position_y": 0,
"position_z": 30,
"updated_at": "2013-10-24T02:59:27Z",
},
...
]
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 and
sub-location.
GET /nodes/recent.json?interval=:timespec
[
{
"created_at": "2013-09-25T04:34:39Z",
"id": 18,
"last_heard": "2013-10-24T03:14:20Z",
"name": "B #248",
"node_type_id": 4,
"position_x": 315,
"position_y": 444,
"position_z": 30,
Page 8
"root_formed": true ,
"updated_at": "2013-10-24T03:14:20Z",
},
{
"created_at": "2013-10-11T05:52:47Z",
"id": 22,
"last_heard": "2013-10-24T03:14:24Z",
"name": "M #229",
"node_type_id": 2,
"position_x": 237,
"position_y": 360,
"position_z": 120,
"sublocation_id": "1",
"updated_at": "2013-10-24T03:14:24Z",
}
]
Parameters:
timespec (optional) - 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 5 days. The parameter is optional, with
the default specified by the
dr2.yml
15m.
config file with the parameter
default_node_time_interval.
The parameters default value is
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
[
{
"created_at": "2013-10-11T05:52:47Z",
"id": 22,
"last_heard": "2013-10-24T03:24:34Z",
Page 9
"name": "M #229",

"node_type_id": 2,
"position_x": 238,
"position_y": 359,
"position_z": 120,
"sublocation_id": "1",
"updated_at": "2013-10-24T03:24:34Z",
}
]
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 5
days. 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
[
{
"created_at": "2013-09-19T08:27:38Z",
"id": 13,
"last_heard": "2013-10-24T03:35:48Z",
"name": "F #226",
"node_type_id": 1,
"position_x": -5,
"position_y": 278,
"position_z": 30,
"sw_version": "0",
"updated_at": "2013-10-24T03:35:48Z",
Page 10
},
{
"created_at": "2013-10-11T05:51:15Z",
"id": 20,
"last_heard": "2013-10-24T03:35:49Z",
"name": "F #273",
"node_type_id": 1,
"position_x": 128,
"position_y": 942,
"position_z": 30,
"sw_version": "0",
"updated_at": "2013-10-24T03:35:49Z",
}
]
Parameters:
timespec (optional) - ?interval=:timespec The time specification in seconds (s), minutes (m), hours
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
[
{
"created_at": "2013-09-25T04:34:39Z",
"id": 18,
"last_heard": "2013-10-24T03:38:15Z",
"name": "B #248",
"node_type_id": 4,
"position_x": 315,
"position_y": 444,
"position_z": 30,
Page 11
"sw_version": "0",
"updated_at": "2013-10-24T03:38:15Z",
}
]
Parameters:
timespec (optional) - ?interval=:timespec the time specification in seconds (s), minutes (m), hours
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
[
{
"created_at": "2013-09-25T04:34:39Z",
"id": 18,
"last_heard": "2013-10-24T03:46:38Z",
"name": "B #248",
"node_type_id": 4,
"position_x": 315,
"position_y": 444,
"position_z": 30,
"sw_version": "0",
"updated_at": "2013-10-24T03:46:38Z",
}
]
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",
},
{
"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",
},
{
"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",
},
{
"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",
}
]
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, with
parameters default value is
dr2.yml
15m.
The
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:

dr2.yml
15m.
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:

dr2.yml
15m.
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:

dr2.yml
15m.
Page 16
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 the
publishing interface. Any subscriber listening to individual channels (#sensor/#position) will get the relevant data. If
you 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 server
puts 'Collecting updates from weather server'
subscriber = context.socket :SUB
subscriber.connect('tcp://192.168.56.20:7001')
# subscribe to both sensor and position updates
subscriber.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.recv
puts "received: #{s}"
end
4.2 Example C++ Subscriber
#include <zmq.hpp>
Page 17
#include <iostream>
#include <sstream>
// 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 server

std::cout << "About to receive data\n" << std::endl;
zmq::socket_t subscriber (context, ZMQ_SUB);
subscriber.connect("tcp://localhost:7001");
// we will have 2 channels
// #sensor for sensor data
// #position for mobile position updates
const char *filter = (argc > 1)? argv [1]: "#sensor ";
subscriber.setsockopt(ZMQ_SUBSCRIBE, filter, strlen (filter));
// Process 100 updates
// 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
//
int update_nbr;
long total_temp = 0;
for (update_nbr = 0; update_nbr < 100; update_nbr++) {
zmq::message_t update;
subscriber.recv(&update);
std::ostringstream oss(static_cast <char*>(update.data()));
std::cout << oss.str() << std::endl;
}
return 0;
Page 18
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 port
7122, it will answer to the originating socket via UDP with hton packed ip address of the server.
Page 19
Contact
Please dont hesitate to contact us directly:
Red Point Positioning Corporation

20 Webster Street, Suite 411
Brookline, MA 02446
USA
Email: info@redpointpositioning.com
Telephone: +1(617)207-4096
Page 20
References
RTLS System Users Guide. 2014. Red Point Positioning Corporation.

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

RtlsDevGuide RPP DG-011

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

RtlsDevGuide RPP DG-011

Caricato da

Copyright:

Formati disponibili

RTLS Developers Guide

RTLS Developers Guide

2014 Red Point Positioning Corporation

1.1 Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 REST API (HTTP Verbs)

3.1.2 Get a single location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2.1 Get all the sub-locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2.2 Get a single sub-location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2.3 Get all sublocations within a given location . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3.1 Get all the nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3.2 Get all the nodes active within an interval

3.3.3 Get all the mobile nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3.4 Get all the fixed nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.3.6 Get all the bridge nodes in a given sublocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.4.2 Get the sensor values on a given node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.1 Example Ruby Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.1 Server Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

RTLS Developers Guide

2014 Red Point Positioning Corporation

About This Guide

1.1 Where to find more information

RTLS Developers Guide

2014 Red Point Positioning Corporation

RTLS Developers Guide

2014 Red Point Positioning Corporation

REST API (HTTP Verbs)

Figure 1: Programming Model

Returns a list of locations as an array of hashes.

RTLS Developers Guide

2014 Red Point Positioning Corporation

3.1.2 Get a single location

Gets a single location.

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

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

RTLS Developers Guide

2014 Red Point Positioning Corporation

3.2.2 Get a single sub-location

Gets a single sub-location.

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.

RTLS Developers Guide

2014 Red Point Positioning Corporation

id (required) - The ID of a locations.

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

RTLS Developers Guide

2014 Red Point Positioning Corporation

3.3.2 Get all the nodes active within an interval

RTLS Developers Guide

2014 Red Point Positioning Corporation

config file with the parameter

The parameters default value is

3.3.3 Get all the mobile nodes

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

RTLS Developers Guide

2014 Red Point Positioning Corporation

"name": "M #229",

3.3.4 Get all the fixed nodes

Returns a list of all fixed nodes.

RTLS Developers Guide

2014 Red Point Positioning Corporation

3.3.5 Get all the bridge nodes

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

RTLS Developers Guide