forward-sensor-data-to-initial-state.html

<!DOCTYPE HTML>
<html>
  <head>
    <title>Forward BLE sensor data to Initial State | diyActive</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="Use the reelyActive platform to listen for sensor data from third-party Bluetooth beacons and forward the real-time stream to Initial State.">
    <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>
              Forward BLE sensor data to Initial State <br>
              <small> Collect and visualise the data from any sensor beacon with ease </small> 
            </h1>
            <p> <a href="https://initialstate.com/" target="_blank">Initial State</a> is a web platform which lets you <i>stream data from your devices and applications to beautiful visualizations in your web browser</i>.  In this tutorial we'll show how to use the reelyActive platform to listen for sensor data from third-party Bluetooth beacons and forward the real-time stream to Initial State. </p>
            <img src="images/sensorbeacon-initialstate.jpg"
                 class="img-responsive center-block">
            <h2> <del>Hears</del> Here's a motivating example<br>
                 <small> Temperature and humidity timeseries from a sensor beacon </small> </h2>
            <iframe src="https://app.initialstate.com/embed/#/tiles/AVwqkydWmjV2yRC8TP1oxRYpl4zuIttl" style="width:100%; height:860px"></iframe>
            <p> The above uses the <i>share by embed</i> feature of Initial State.  You can also open the visualisation directly in your browser via <a href="https://app.initialstate.com/#/tiles/4707dec8-a185-4e83-bd22-a7930017b625" target="_blank">this link</a>. </p>
            <h2> What's a BLE sensor beacon? </h2>
            <p> A Bluetooth Low Energy (BLE) sensor beacon is a device which <i>spontaneously</i> transmits the data from its embedded sensors.  Any listening devices in range can receive such messages. </p>
            <p> Note that the transmitter and the receiver <i>do not</i> need to be paired, and a single transmission can be received by <i>multiple</i> listening devices. </p>
            <p> The following non-exhausive list includes sensor beacons which are recognised by <a href="https://github.com/reelyactive/advlib#advlib" target="_blank">advlib</a>, our open source packet decoding library: </p>
            <table class="table table-striped table-reelyactive">
              <caption> SELECT BLE SENSOR BEACONS </caption>
              <thead>
                <tr>
                  <th> Manufacturer </th>
                  <th> Model </th>
                  <th> Sensors </th>
                </tr>
              </thead>
              <tbody>
                <tr>
                  <td> Minew </td>
                  <td> <a href="http://www.minewtech.com/minew-web-en/minew_sensor.html" target="_blank">S1</a> </td>
                  <td> Temperature, Humidity </td>
                </tr>
                <tr>
                  <td> Minew </td>
                  <td> <a href="http://www.minewtech.com/minew-web-en/minew_sensor.html" target="_blank">I7</a> </td>
                  <td> Acceleration (3-axis) </td>
                </tr>
                <tr>
                  <td> Estimote </td>
                  <td> <a href="https://estimote.com/" target="_blank">Sticker Beacon</a> </td>
                  <td> Temperature, Acceleration (3-axis) </td>
                </tr>
              </tbody>
            </table>
            <h2> Prerequisites </h2>
            <h3> Sensor Beacon </h3>
            <p> Obtain a sensor beacon from the list above, or any other sensor beacon whose packets you are able to decode. </p>
            <h3> Listening Device </h3>
            <p> This tutorial will assume you have either a <a href="https://shop.reelyactive.com/collections/starter-kits" target="_blank">reelyActive starter kit</a> or a BLE-capable Raspberry Pi and have completed the corresponding tutorial: </p>
            <p class="text-center">
              <a class="btn btn-default" href="install-a-starter-kit.html"
                 target="blank" role="button"> Install a Starter Kit </a>
              <a class="btn btn-default" href="make-a-pi-hub.html"
                 target="blank" role="button"> Make a Pi Hub </a>
            </p>
            <h3> Initial State Account </h3>
            <p> Create a (free) Initial State account or sign into your existing account: </p>
            <p class="text-center">
              <a class="btn btn-default" target="blank"
                 href="https://app.initialstate.com/#/register"
                 role="button"> Register </a>
              <a class="btn btn-default" target="blank"
                 href="https://app.initialstate.com/#/login"
                 role="button"> Sign in </a>
            </p>
            <p> Then create a new Stream Bucket and note the <b>Bucket Key</b> and <b>Access Key</b> from the settings. </p>
            <img src="images/sensorbeacon-initialstate-keys.jpg"
                 class="img-responsive center-block">
            <h2> The code </h2>
            <p> The following code example for Node.js will listen using a reelyActive minimal starter kit, and push the temperature and humidity data of a single Minew S1 beacon, as specified by its 48-bit identifier, to Initial State. </p>
            <pre> 
const barnowl = require('barnowl');
const initialstate = require('initial-state');

const BUCKET_KEY = 'BUCKETKEYGOESHERE'; // Update these from
const ACCESS_KEY = 'ACCESSKEYGOESHERE'; //   Initial State settings
const SENSOR_MAC = 'ac233fa00000';      // From S1 Beacon label

var middleware = new barnowl();
var bucket = initialstate.bucket(BUCKET_KEY, ACCESS_KEY);
 
// This assumes minimal starter kit (see barnowl for where to listen)
middleware.bind( { protocol: 'serial', path: 'auto' } );
 
// Something was decoded
middleware.on('visibilityEvent', function(tiraid) {

  var isMAC = (tiraid.identifier.value === SENSOR_MAC);

  // Specified sensor beacon was decoded
  if(isMAC) {

    // Point to the data specific to this sensor
    var minew = tiraid.identifier.advData.serviceData.minew;

    // Push the sensor data values to the Initial State bucket
    bucket.push('temperature', minew.temperature);
    bucket.push('humidity', minew.humidity);
  }
});
            </pre>
            <h3> Configuration </h3>
            <p> If you happen to have a S1 beacon and a <a href="https://shop.reelyactive.com/products/starterkit-min" target="_blank">minimal starter kit</a>, the only configuration required is to update the <b>BUCKET_KEY</b>, <b>ACCESS_KEY</b> and <b>SENSOR_MAC</b>. </p>
            <p> Update the <i>middleware.bind</i> parameters if you're using something other than a minimal starter kit (<a href="https://www.npmjs.com/package/barnowl#where-to-listen" target="_blank">see barnowl: Where to listen?</a>). </p>
            <p> Update the sensor-specific code if you have a different sensor. </p>
            <h3> Install and run </h3>
            <p> Copy the configured code to a file called <b>server.js</b>.  From that directory, from the command line, first install the barnowl and initial-state packages, and then run as follows: </p>
            <pre>
npm install barnowl
npm install initial-state
node server</pre>
            <h3> Considerations </h3>
            <p> The above code will push <i>every</i> received packet to Initial State.  Consider adjusting the update rate of the sensor beacon as appropriate (if possible) or limiting the update rate in the code. </p>
            <p> Some sensor beacons will interweave packet types.  Consider verifying that sensor data is indeed present in the received packet before pushing to Initial State. </p>
            <h2> Don't give a hoot about sensor integration? </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.  Leave the sensor integration to us. </p>
            <p class="text-center">
              <a class="btn btn-primary" href="https://getpareto.com"
                 target="_blank" role="button"> Visit getpareto.com </a>
            </p>
            <hr>
            <h2> What's next? </h2>
            <p> Learn how to use a Raspberry Pi to collect and forward the sensor data (and so much more!), or learn how to create your own client-side sensor data visualisations using beaver.js, or return to the diyActive home page. </p>
            <p class="text-center">
              <a class="btn btn-default" href="make-a-pi-hub.html"
                 role="button"> Make a Pi Hub </a>
              <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-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> &nbsp; | &nbsp;
        <a href="https://www.reelyactive.com"
           uib-tooltip="We believe in an open Internet of Things"
           tooltip-placement="right">
          &copy; reelyActive 2017-2018
        </a>
      </footer>
    </div>
  </body>
</html>