-
Notifications
You must be signed in to change notification settings - Fork 3
/
event-overview.html
344 lines (344 loc) · 18.5 KB
/
event-overview.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
<!DOCTYPE HTML>
<html>
<head>
<title>The reelyActive event data structure | diyActive</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Detailed explanation of the reelyActive event JSON which is consumed by platforms and applications.">
<link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet">
<link rel="stylesheet" href="style/main.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.6.2/angular.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/angular-ui-bootstrap/2.5.0/ui-bootstrap-tpls.min.js"></script>
<script type="text/javascript" src="js/diyactive.js"></script>
</head>
<body ng-app="diyActive">
<div ng-controller="InteractionCtrl">
<nav class="navbar navbar-default" role="navigation">
<div class="navbar-header">
<button type="button" class="navbar-toggle"
ng-init="navCollapsed = true"
ng-click="navCollapsed = !navCollapsed">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="https://www.reelyactive.com">
<strong>reely</strong>Active
</a>
</div>
<div class="collapse navbar-collapse" ng-class="!navCollapsed && 'in'"
ng-click="navCollapsed = true">
<ul class="nav navbar-nav navbar-right">
<li class="active"><a href="/"> diyActive </a></li>
<li class="dropdown" uib-dropdown on-toggle="toggled(open)">
<a href class="dropdown-toggle" uib-dropdown-toggle role="button"
data-toggle="dropdown" aria-haspopup="true"
aria-expanded="false">
Quick links <span class="caret"></span>
</a>
<ul class="dropdown-menu" uib-dropdown-menu role="menu">
<li role="menuitem">
<a href="https://github.com/reelyactive/" target="_blank">
reelyActive on GitHub
</a>
</li>
<li role="menuitem">
<a href="https://www.npmjs.com/~reelyactive" target="_blank">
reelyActive on npmjs
</a>
</li>
<li role="separator" class="divider"></li>
<li role="menuitem">
<a href="https://www.reelyactive.com" target="_blank">
reelyActive website
</a>
</li>
<li role="menuitem">
<a href="https://getpareto.com" target="_blank">
Pareto by reelyActive
</a>
</li>
<li role="separator" class="divider"></li>
<li role="menuitem">
<a href="https://shop.reelyactive.com" target="_blank">
Our online store
</a>
</li>
<li role="menuitem">
<a href="https://reelyactive.com/blog/" target="_blank">
Our blog
</a>
</li>
</ul>
</li>
</ul>
</div>
</nav>
<div class="container-fluid">
<div class="row">
<div class="col-xs-12 col-sm-10 col-sm-offset-1 col-md-8 col-md-offset-2 col-lg-6 col-lg-offset-3">
<h1>
The reelyActive event data overview <br>
<small> Detailed explanation of the event JSON </small>
</h1>
<p> An <b>event</b> is the consequence of an interaction between a radio-identifiable device and receiver infrastructure. The <b>event</b> is the core data structure used in the reelyActive platform — many applications need only consume <b>event</b>s. An <b>event</b> may have some or all of the following properties in addition to the basic properties: </p>
<p class="text-center">
<a class="btn btn-primary" href="#basic"> Basic </a>
<a class="btn btn-default" href="#contextual"> Contextual </a>
<a class="btn btn-default" href="#positioning"> Positioning </a>
<a class="btn btn-default" href="#session"> Session </a>
</p>
<!----- Basic event structure ----------------------------------->
<h2 id="basic">
Basic event structure <br>
<small> What you'd expect from a RTLS </small>
</h2>
<p> The following JSON represents a basic <b>event</b> — essentially <i>what</i> is <i>where</i> and <i>when</i> — as detailed below. </p>
<pre>
{
"time": 1420075425678,
"deviceId": "fee150bada55",
"deviceAssociationIds": [ "004c" ],
"receiverId": "001bc50940810000",
"rssi": 150,
"event": "appearance"
}
</pre>
<table class="table table-striped table-reelyactive">
<caption> BASIC EVENT PROPERTIES </caption>
<thead>
<tr>
<th> Property </th>
<th> Type </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<th> <tt>time</tt> </th>
<td> Number </td>
<td> <p> The time at which the <b>event</b> occurred, represented as the number of milliseconds since the Unix epoch (January 1st, 1970 UTC). </p> <i><u>Example</u>:</i> <tt>1420075425678</tt> is equivalent to 01 Jan 2015 01:23:45.678 GMT. </td>
</tr>
<tr>
<th> <tt>deviceId</tt> </th>
<td> String </td>
<td> <p> The (normally) unique identifier of the transmitting device to which the <b>event</b> corresponds. Expressed as a lowercase hexadecimal string without colons or dashes.</p> <i><u>Example</u>:</i> <tt>"fee150bada55"</tt> is equivalent to the 48-bit BLE advertiser address <tt>fe:e1:50:ba:da:55</tt>.</td>
</tr>
<tr>
<th> <tt>deviceAssociationIds</tt> </th>
<td> Array of String </td>
<td> <p> The list of complementary device identifiers included in the payload(s) of the device. Each is expressed as a lowercase hexadecimal string without colons or dashes.</p> <i><u>Example</u>:</i> <tt>[ "004c" ]</tt> is equivalent to the 16-bit BLE company identifier for Apple, Inc.</td>
</tr>
<tr>
<th> <tt>receiverId</tt> </th>
<td> String </td>
<td> <p> The unique identifier of the receiver which detects the device with the strongest signal strength in relation to the corresponding <b>event</b>. Expressed as a lowercase hexadecimal string without colons or dashes. </p> <i><u>Example</u>:</i> <tt>"001bc50940810000"</tt> is equivalent to the EUI-64 reelceiver address <tt>00-1b-c5-09-40-81-00-00</tt>. </td>
</tr>
<tr>
<th> <tt>rssi</tt> </th>
<td> Number </td>
<td> <p> The received signal strength indication (RSSI) as a unitless number, with greater values corresponding to greater received signal strength. In the case of reelyActive reelceivers, each unit represents 0.5dBm and the offset is constant for a given model, allowing for direct comparison. </p> <i><u>Example</u>:</i> <tt>183</tt> is 1.5dBm stronger than <tt>180</tt>. </td>
</tr>
<tr>
<th> <tt>event</tt> </th>
<td> String </td>
<td> <p> The nature of the <b>event</b> which is of one of the following four types, further detailed in the next section: <ul><li><tt>"appearance"</tt> <li><tt>"keep-alive"</tt> <li><tt>"displacement"</tt> <li><tt>"disappearance"</tt> </ul> </p> </td>
</tr>
</tbody>
</table>
<h3>
The four event types <br>
<small> Each describes the nature of the interaction </small>
</h3>
<img src="images/service-events.gif"
class="img-responsive center-block">
<table class="table table-striped table-reelyactive">
<thead>
<tr>
<th> Event type </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<th><tt> "appearance" </tt></th>
<td> <p> Indicates that the device is detected for the first time at a point of interest. </p> <i> This means that either the device has come within range of a radio receiver or has started transmitting. </i> </td>
</tr>
<tr>
<th><tt> "keep-alive" </tt></th>
<td> <p> Indicates that the device continues to be detected and has not displaced. </p> <i> The keep-alive is sent periodically (typically every few seconds) to indicate that the device remains at the same point of interest. </i> </td>
</tr>
<tr>
<th><tt> "displacement" </tt></th>
<td> <p> Indicates that the device has moved closer to a different point of interest. </p> <i> Specifically, it indicates that the device is detected at a stronger RSSI by a different radio receiver than previously. </i> </td>
</tr>
<tr>
<th><tt> "disappearance" </tt></th>
<td> <p> Indicates that the device is no longer detected at any point of interest. </p> <i> This means that the device has either gone out of range of all radio receivers or has stopped transmitting. </i> </td>
</tr>
</tbody>
</table>
<p> </p>
<!----- Contextual event properties ----------------------------->
<h2 id="contextual">
Contextual event properties <br>
<small> The addition of any associated metadata </small>
</h2>
<p> The following JSON represents the <i>additional</i> properties of a contextual <b>event</b>, which associates <i>meaning</i> to the device and receiver identifiers, as detailed below. </p>
<pre>
{
/* In addition to the basic event properties above... */
"deviceUrl": "https://myjson.info/stories/test",
"deviceTags": [ "mascot", "reelyActive" ],
"receiverUrl": "https://sniffypedia.org/Product/reelyActive_RA-R436/",
"receiverTags": [ "indoors" ],
"receiverDirectory": "farm:barn"
}
</pre>
<table class="table table-striped table-reelyactive">
<caption> CONTEXTUAL EVENT PROPERTIES </caption>
<thead>
<tr>
<th> Property </th>
<th> Type </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<th> <tt>deviceUrl</tt> </th>
<td> String </td>
<td> <p> The Uniform Resource Locator (URL) associated with the device, at which metadata is expected to be found. </p> <i><u>Example</u>:</i> <tt>"https://myjson.info/stories/test"</tt> points to the profile for our mascot. </td>
</tr>
<tr>
<th> <tt>deviceTags</tt> </th>
<td> Array of String </td>
<td> <p> Each tag represents a classifier for the device, which can be used to facilitate filtering and querying. </p> <i><u>Example</u>:</i> <tt>[ "mascot", "reelyActive" ]</tt> would classify the device as being associated with both a <i>mascot</i> and <i>reelyActive</i>. </td>
</tr>
<tr>
<th> <tt>receiverUrl</tt> </th>
<td> String </td>
<td> <p> The Uniform Resource Locator (URL) associated with the receiver, at which metadata is expected to be found. </p> <i><u>Example</u>:</i> <tt>"https://sniffypedia.org/Product/reelyActive_RA-R436/"</tt> points to the profile for a reelyActive reelceiver. </td>
</tr>
<tr>
<th> <tt>receiverTags</tt> </th>
<td> Array of String </td>
<td> <p> Each tag represents a classifier for the receiver, which can be used to facilitate filtering and querying. </p> <i><u>Example</u>:</i> <tt>[ "indoors" ]</tt> would classify the receiver as being associated with <i>indoors</i>. </td>
</tr>
<tr>
<th> <tt>receiverDirectory</tt> </th>
<td> String </td>
<td> <p> The hierarchical directory structure which specifies the semantic location of one or more points of interest. The levels of hierarchy are colon-separated. </p> <i><u>Example</u>:</i> <tt>"farm:barn"</tt> indicates a semantic location called <i>barn</i> contained within a semantic location called <i>farm</i>. </td>
</tr>
</tbody>
</table>
<p> </p>
<!----- Positioning event properties ---------------------------->
<h2 id="positioning">
Positioning event properties <br>
<small> The addition of real-time position </small>
</h2>
<p> The following JSON represents the <i>additional</i> properties of a positioned <b>event</b>, where the real-time 2D or 3D <i>position</i> is estimated, as detailed below. </p>
<pre>
{
/* In addition to the event properties above... */
"position": [ 0.0, 0.0 ],
"positioningMethod": "strongestReceiver"
}
</pre>
<table class="table table-striped table-reelyactive">
<caption> POSITIONING EVENT PROPERTIES </caption>
<thead>
<tr>
<th> Property </th>
<th> Type </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<th> <tt>position</tt> </th>
<td> Array of Number </td>
<td> <p> The estimated real-time position of the device, represented as a GeoJSON position. The array consists of either two or three values, representing a 2D or 3D position, respectively. </p> <i><u>Example</u>:</i> <tt>[ 0.0, 0.0 ]</tt> is the origin in 2D. </td>
</tr>
<tr>
<th> <tt>positioningMethod</tt> </th>
<td> String </td>
<td> <p> The name of the method used to estimate the position. </p> <i><u>Example</u>:</i> <tt>strongestReceiver</tt> simply applies the position of the strongest receiver of the device's transmissions. </td>
</tr>
</tbody>
</table>
<p> </p>
<!----- Session event properties -------------------------------->
<h2 id="session">
Session event properties <br>
<small> The addition of session data </small>
</h2>
<p> The following JSON represents the <i>additional</i> properties of an <b>event</b> with session data, which is detailed below. </p>
<pre>
{
/* In addition to the event properties above... */
"sessionId": "341f64ce-c001-babe-d0e5-cbf75095135e",
"sessionDuration": 600000
}
</pre>
<table class="table table-striped table-reelyactive">
<caption> SESSION EVENT PROPERTIES </caption>
<thead>
<tr>
<th> Property </th>
<th> Type </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<th> <tt>sessionId</tt> </th>
<td> String </td>
<td> <p> The 128-bit UUID assigned to the device's current session. Generated deterministically from the device's identifier(s). It is the physical analog to a Google Analytics <tt>clientId</tt> which "anonymously identifies a browser instance." </p> <i> A device with a non-cyclic identifier will always generate the same sessionId. </td>
</tr>
<tr>
<th> <tt>sessionDuration</tt> </th>
<td> Number </td>
<td> <p> The duration, in milliseconds, since the start of the current session. Once a session expires (after 5 minutes of non-detection, by default), any subsequent session will start with a <tt>sessionDuration</tt> of 0. </p> <i><u>Example</u>:</i> <tt>60000</tt> represents a session that has lasted 1 minute so far. </td>
</tr>
</tbody>
</table>
<p> </p>
<h2> Where do events come from? </h2>
<img src="images/pareto-by-reelyactive.jpg"
class="img-responsive center-block"><br>
<p> Our Pareto platform combines the convenience of SaaS with plug-and-play hardware. Your source for real-time real-world <b>event</b>s. </p>
<p class="text-center">
<a class="btn btn-primary" href="https://getpareto.com"
target="_blank" role="button"> Visit getpareto.com </a>
<a class="btn btn-default" href="pareto-socket-client.html"
role="button"> Connect to Pareto </a>
</p>
<hr>
<h2> What's next? </h2>
<p> Build <b>event</b>-driven web apps with beaver.js, connect a websocket client to Pareto to consume <b>event</b>s, or return to the diyActive home page. </p>
<p class="text-center">
<a class="btn btn-default" href="build-web-apps-with-beaver.html"
role="button"> Build web apps with beaver.js </a>
<a class="btn btn-default" href="pareto-socket-client.html"
role="button"> Connect to Pareto </a>
<a class="btn btn-success" href="/"
role="button"> Return to diyActive </a>
</p>
</div>
</div>
</div>
<footer class="footer">
<a href="/"
uib-tooltip="Do-it-yourself with reelyActive"
tooltip-placement="left"> diyActive </a> |
<a href="https://www.reelyactive.com"
uib-tooltip="We believe in an open Internet of Things"
tooltip-placement="right">
© reelyActive 2017-2018
</a>
</footer>
</div>
</body>
</html>