integrate-your-service.html

<!DOCTYPE HTML>
<html>
  <head>
    <title>diyActive: Integrate your Service</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="Guide to integrating services on top of the reelyActive platform. Your service will consume a real-time stream of events represented in JSON format.">
    <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 src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.0.3/socket.io.slim.js"></script>
    <script type="text/javascript" src="js/socket.min.js"></script>
    <script type="text/javascript" src="js/beaver.js"></script>
    <script type="text/javascript" src="js/service.js"></script>
  </head>
  <body>
  <body ng-app="service">
    <div ng-controller="ServiceCtrl">
      <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-0 col-sm-1 col-md-2 col-lg-3"></div>
          <div class="col-xs-12 col-sm-10 col-md-8 col-lg-6">
            <h1> Integrate your Service </h1>
            <p> The reelyActive platform is designed to forward a real-time stream of events to complementary services.  First we'll define the <a href="#events">event data</a> that your service will need to ingest, then we'll describe the means by which your service can <a href="#ingestion">ingest the data</a>, and, finally, we'll suggest how to <a href="#storage">store the data</a>. </p>
            <a id="events"></a>
            <h2> Event data </h2>
            <p> There's just one type of data, an <b>event</b>, which is represented as JSON.  An <b>event</b> is the consequence of an interaction between a radio-identifiable device and receiver infrastructure. </p>
            <h3> Types of event </h3>
            <p> There are four <i>types</i> of <b>event</b>, as illustrated in the animation below. </p>
            <img src="images/service-events.gif"
                 class="img-responsive center-block">
            <h3> Basic event structure </h3>
            <p> An <b>event</b> always has the following basic structure: </p>
<pre>
{
  "event": "appearance",
  "time": 1420075425678,
  "deviceId": "fee150bada55",
  "receiverId": "001bc50940810000",
  "rssi": 150,
  "tiraid": { /* Included for legacy purposes only */ }
}
</pre>
            <p> The individual properties are each presented in their own tab below. </p>
            <uib-tabset>
              <!----- event ------------------------------------------------->
              <uib-tab heading="event">
                <p> An <b>event</b> can take one of four <i>types</i>, each described in the table below: </p>
                <table class="table table-hover">
                  <thead>
                    <tr>
                      <th> Event type </th>
                      <th> Description </th>
                    </tr>
                  </thead>
                  <tbody>
                    <tr>
                      <td><tt> "appearance" </tt></td>
                      <td> Indicates that the device is detected for the first time at a point of interest. <br> <i> Typically, this means that the device has come within range of a radio receiver. </i> </td>
                    </tr>
                    <tr>
                      <td><tt> "keep-alive" </tt></td>
                      <td> Indicates that the device continues to be detected and has not displaced. <br> <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>
                      <td><tt> "displacement" </tt></td>
                      <td> Indicates that the device has moved to a different point of interest. <br> <i> Specifically, it indicates that the device is detected at a stronger RSSI by a different radio receiver than previously. </i> </td>
                    </tr>
                    <tr>
                      <td><tt> "disappearance" </tt></td>
                      <td> Indicates that the device is no longer detected at any point of interest. <br> <i> Typically, this means that the device has gone out of range of all radio receivers. </i> </td>
                    </tr>
                  </tbody>
                </table>
              </uib-tab>
              <!----- time -------------------------------------------------->
              <uib-tab heading="time">
                <p> The <i>time</i> of an <b>event</b> is expressed as a number.  It is the number of milliseconds since the Unix epoch (January 1st, 1970 UTC). </p>
                <pre>1420075425678</pre>
                <p> The above is equivalent to 01 Jan 2015 01:23:45.678 GMT. </p>
              </uib-tab>
              <!----- deviceId ---------------------------------------------->
              <uib-tab heading="deviceId">
                <p> The <i>deviceId</i> of an <b>event</b> is expressed as a hexadecimal string.  It represents the (normally) unique identifier of the device to which the <b>event</b> corresponds.  In the case of Bluetooth Low Energy devices, this is the MAC address (which may be public or random, the distinction being made in the <i>tiraid</i>).  The <i>deviceId</i> does NOT include dashes or colons. </p>
                <pre>"fee150bada55"</pre>
                <p> The above is equivalent to the 48-bit identifier <tt>fe:e1:50:ba:da:55</tt> (human-friendly representation). </p>
              </uib-tab>
              <!----- receiverId -------------------------------------------->
              <uib-tab heading="receiverId">
                <p> The <i>receiverId</i> of an <b>event</b> is expressed as a hexadecimal string.  It represents the unique identifier of the radio receiver which detects the device with the strongest signal strength in relation to the corresponding <b>event</b>.  In the case of reelyActive reelceivers, this is the EUI-64 identifier. </p>
                <pre>"001bc50940810000"</pre>
                <p> The above is equivalent to the 48-bit identifier <tt>00-1b-c5-09-40-81-00-00</tt> (human-friendly representation). </p>
              </uib-tab>
              <!----- rssi -------------------------------------------------->
              <uib-tab heading="rssi">
                <p> The <i>rssi</i> of an <b>event</b> is expressed as a number.  It represents the received signal strength 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>
                <pre>150</pre>
                <p> The above is a unitless value which could be converted to an absolute value if a calibration is performed. </p>
              </uib-tab>
              <!----- tiraid ------------------------------------------------>
              <uib-tab heading="tiraid">
                <p> The <i>tiraid</i> of an <b>event</b> is included for legacy purposes (its pertinent properties are already included in the flattened <b>event</b>), and consists of three components (<u>ti</u>-<u>ra</u>-<u>id</u>), each described below. </p>
                <h4> <u>ti</u>mestamp </h4>
                <p> <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 timestamp</a>, represented as a String.  Includes date and time of day in <a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time" target="_blank">UTC</a>, with millisecond precision.  Example:</p>
<pre>2016-01-01T01:23:45.678Z</pre>
                <p> The timestamp represents the platform's interpretation of the time of the device's radio transmission which triggered the given event. </p>
                <h4> <u>ra</u>dioDecodings </h4>
                <p> Array of radioDecoding objects ordered from strongest [0] to weakest [n-1].  Each radioDecoding includes the <i>identifier</i> of the radio receiver, as well as the Received Signal Strength Indication, or <i>rssi</i>.  Example:</p>
<pre>
{
  "identifier": {
    "type": "EUI-64",
    "value": "001bc50940810000"
  }
  "rssi": 169
}
</pre>
                <p> The first radioDecoding in the array, <i>tiraid.radioDecodings[0]</i>, represents the radio receiver closest to the device, in other words, the device's location. </p>
                <h4> <u>id</u>entifier </h4>
                <p> The identifier of the radio transmitter device, which includes the entire payload of its transmission.  Example:</p>
<pre>
{
  "type": "ADVA-48",
  "value": "112233445566",
  "advHeader": {
    "type": "SCAN_REQ",
    "length": 12,
    "txAdd": "random",
    "rxAdd": "public"
  },
  "advData": {}
}
</pre>
                <p> The identifier value, <i>tiraid.identifier.value</i>, is the means by which the system distinguishes devices and thereby interprets events. </p>
              </uib-tab>
            </uib-tabset>
            <hr>
            <p> &nbsp; </p>
            <h3> Contextual event structure </h3>
            <p> An <b>event</b> may include contextual metadata about both the device and the receiver.  In this case several properties are added to the basic structure, as follows: </p>
<pre>
{
  "event": "appearance",
  "time": 1420075425678,
  "deviceId": "fee150bada55",
  "deviceAssociationIds": [],
  "deviceUrl": "http://myjson.info/stories/test",
  "deviceTags": [ 'test' ],
  "receiverId": "001bc50940810000",
  "receiverUrl": "http://sniffypedia.org/Product/reelyActive_RA-R436/",
  "receiverTags": [ 'test' ],
  "receiverDirectory": "test",
  "rssi": 150,
  "tiraid": { /* Included for legacy purposes only */ }
}
</pre>
            <p> The <i>additional</i> properties are each presented in their own tab below. </p>
            <uib-tabset>
              <!----- deviceAssociationIds ---------------------------------->
              <uib-tab heading="deviceAssociationIds">
                <p> The <i>deviceAssociationIds</i> of an <b>event</b> is expressed as an array of hexadecimal strings.  Each hexadecimal string represents a complementary device identifier included in its payload(s).  In the case of Bluetooth Low Energy devices, this can include 16-bit and 128-bit UUIDs, 16-bit company codes, as well as 160-bit concatenated iBeacon identifiers, among others.  These identifiers do NOT include dashes or colons. </p>
                <pre>[ '004c', 'dab59c4fa4d6ee286bfe8e0000bbc2bb12345678' ]</pre>
                <p> The above is equivalent to an iBeacon with UUID <tt>dab59c4f-a4d6-ee28-6bfe-8e0000bbc2bb</tt>, Major: <tt>1234</tt> and Minor: <tt>5678</tt>.  It includes Apple's company code: <tt>0x004c</tt>. </p>
              </uib-tab>
              <!----- deviceUrl --------------------------------------------->
              <uib-tab heading="deviceUrl">
                <p> The <i>deviceUrl</i> of an <b>event</b> is expressed as a string.  It represents a Uniform Resource Locator (URL) associated with the device, linking it to metadata. </p>
                <pre>"http://myjson.info/stories/test"</pre>
                <p> The above is a link to <a href="https://myjson.info/stories/test" target="_blank">http://myjson.info/stories/test</a> which <a href="http://reelyactive.github.io/cormorant/?url=http://myjson.info/stories/test" target="_blank">contains metadata as JSON-LD</a> within a human-friendly HTML representation. </p>
              </tab>
              <!----- deviceTags -------------------------------------------->
              <tab heading="deviceTags">
                <p> The <i>deviceTags</i> of an <b>event</b> is expressed as an array of strings.  Each string represents a classifier for the device. </p>
                <pre>[ 'test' ]</pre>
                <p> The above indicates that the device is part of a <tt>test</tt> class. </p>
              </uib-tab>
              <!----- receiverUrl ------------------------------------------->
              <uib-tab heading="receiverUrl">
                <p> The <i>receiverUrl</i> of an <b>event</b> is expressed as a string.  It represents a Uniform Resource Locator (URL) associated with the receiver, linking it to metadata. </p>
                <pre>"http://sniffypedia.org/Product/reelyActive_RA-R436/"</pre>
                <p> The above is a link to <a href="https://sniffypedia.org/Product/reelyActive_RA-R436/" target="_blank">http://sniffypedia.org/Product/reelyActive_RA-R436/</a> which <a href="http://reelyactive.github.io/cormorant/?url=http://sniffypedia.org/Product/reelyActive_RA-R436/" target="_blank">contains metadata as JSON-LD</a> within a human-friendly HTML representation. </p>
              </uib-tab>
              <!----- receiverTags ------------------------------------------>
              <uib-tab heading="receiverTags">
                <p> The <i>receiverTags</i> of an <b>event</b> is expressed as an array of strings.  Each string represents a classifier for the receiver. </p>
                <pre>[ 'test' ]</pre>
                <p> The above indicates that the receiver is part of a <tt>test</tt> class. </p>
              </uib-tab>
              <!----- receiverDirectory ------------------------------------->
              <uib-tab heading="receiverDirectory">
                <p> The <i>receiverDirectory</i> of an <b>event</b> is expressed as a string.  It represents a hierarchical directory structure which specifies the semantic location of one or more points of interest.  The levels of hierarchy are colon-separated. </p>
                <pre>"test"</pre>
                <p> The above indicates that the receiver is part of the <tt>test</tt> directory. </p>
                <pre>"test:subarea"</pre>
                <p> The above indicates that the receiver is part of the <tt>subarea</tt> of the <tt>test</tt> directory. </p>
              </uib-tab>
            </uib-tabset>
            <hr>
            <p><br><br></p>
            <a id="ingestion"></a>
            <h2> Ingesting data </h2>
            <p> Your service can ingest data as HTTP POSTs, over websockets, or using a custom service.  Each option is presented in its own tab below. </p>
            <uib-tabset>
              <!----- HTTP POST -------------------------------------------->
              <uib-tab heading="HTTP POST">
                <p> In this case, the reelyActive platform will POST events to your API. </p>
                <h3> Integration testbench </h3>
                <p> Paste the following into a file called <b>post-test.js</b>: </p>
<pre>
var barnowl = require('barnowl');
var barnacles = require('barnacles');
var middleware = new barnowl( { n: 2 } );
var notifications = new barnacles();
 
middleware.bind( { protocol: "test", path: "default" } );
notifications.bind( { barnowl: middleware } );

notifications.addService({
    service: "barnaclesrest",
    hostname: "localhost",
    port: 3010
});
</pre>
                <p> Then from the command line, run the following, in order: <br>
                <code> npm install barnowl </code> <br>
                <code> npm install barnacles </code> <br>
                <code> node post-test </code> </p>
                <p> Your service should now expect events to be POSTed to <b>http://localhost:3010/events</b> </p>
              </uib-tab>
              <!----- Websockets ------------------------------------------->
              <uib-tab heading="Websockets">
                <p> In this case, your service will connect to the websocket at a specific URL. </p>
                <p> Test your service with a live feed via <b>https://www.hyperlocalcontext.com</b> and you should receive the following: </p>

                <table class="table table-striped table-reelyactive">
                  <caption> REAL-TIME EVENT STREAM </caption>
                  <thead>
                    <tr>
                      <th> Transmitter ID </th>
                      <th> Event </th>
                      <th> Receiver ID </th>
                      <th> RSSI </th>
                      <th> Timestamp </th>
                    </tr>
                  </thead>
                  <tbody>
                    <tr ng-repeat="(id, event) in events">
                      <td> <tt> {{event.tiraid.identifier.value}} </tt> </td>
                      <td> {{event.type}} </td>
                      <td>
                        <tt>
                          {{event.tiraid.radioDecodings[0].identifier.value}}
                        </tt>
                      </td>
                      <td> {{event.tiraid.radioDecodings[0].rssi}} </td>
                      <td> {{event.tiraid.timestamp}} </td>
                    </tr>
                  </tbody>
                </table>
              </uib-tab>
              <!----- Custom services -------------------------------------->
              <uib-tab heading="Custom services">
                <p> In this case, you'll write a custom service that we'll integrate into our code base.  This is reserved for cases where HTTP POST and websockets are inappropriate. </p>
                <p> Visit the <a href="https://github.com/reelyactive/barnacles/tree/master/lib/services" target="_blank">barnacles/lib/services</a> directory on our GitHub for code examples of the existing custom services. </p>
              </uib-tab>
            </uib-tabset>
            <hr>
            <p><br><br></p>
            <a id="storage"></a>
            <h2> Storing data </h2>
            <p> If your service will store event data to a database, we suggest (at least) the following properties in flattened format: </p>
<pre>
{
  "event": "appearance",
  "time": 1451611425678,
  "deviceId": "112233445566",
  "receiverId": "001bc50940810000",
  "rssi": 169
}
</pre>
            <p> The presented values are taken from the tiraid example above.  We recommend using the <a href="https://www.npmjs.com/package/reelib#toflattenedevent" target="_blank">toFlattened()</a> method of our <a href="https://www.npmjs.com/package/reelib" target="_blank">reelib</a> package to flatten the event data in a standard format.  Install and reference the package, respectively, as follows: <br>
            <code> npm install reelib </code> </p>
<pre>
var reelib = require('reelib');

var event; // See Ingesting Data section

var flattenedEvent = reelib.event.toFlattened(event);

console.log(flattenedEvent);
</pre>
            <p><br><br></p>
            <h2> What's next? </h2>
            <p> <a href="http://www.reelyactive.com/contact/" target="_blank">Contact us</a> if you feel your service should be integrated with our <a href="http://getpareto.com" target="_blank">Pareto platform</a>. </p>
            <p class="text-center">
              <a class="btn btn-default" href="integrate-your-product.html"
                 role="button"> Integrate your Product </a>
              <a class="btn btn-default" href="integrate-your-mobile-app.html"
                 role="button"> Integrate your Mobile App </a>
              <a class="btn btn-success" href="index.html"
                 role="button"> Return to diyActive </a>
            </p>
          </div>
          <div class="col-xs-0 col-sm-1 col-md-2 col-lg-3"></div>
        </div>
      </div>
      <footer class="footer">
        <a href="/"> diyActive </a> &nbsp; | &nbsp;
        <a href="https://www.reelyactive.com">
          &copy; reelyActive 2016-2018
        </a>
      </footer>
    </div>
  </body>
</html>