Barnowl Baby Steps

Here we'll present how to write simple JavaScript programs that do potentially interesting and useful things with barnowl, our free middleware package for Node.js.

Installing Node.js

If you don't already have Node.js installed, be sure to do so first! Installation is easy on all platforms.

Let's do it

Installing barnowl

The easy way is via npm. Create a new directory called baby-barnowl, then from that directory run:
npm install barnowl

Yeah, that's it, you're done!


If you prefer to install from github, instead clone the barnowl repository.

Running barnowl and telling it where to listen

It's as simple as three lines of code! First you load barnowl, second, you create an instance of barnowl and, third, you tell that instance where to listen for packets. Create a new file called baby-barnowl.js in the same directory and paste in the following lines of code:

var barnowl = require('barnowl');
var middleware = new barnowl();
middleware.bind({ protocol: 'test',
                  path: 'default' }); 

If you've already completed the Install a Starter Kit tutorial, you'll likely want to update the protocol and path to listen for your hardware. The 'test' protocol specified above will initiate a packet generator that can be used in the absence of hardware.

If you run this code, it will listen for and process any received packets. In order to do something useful we'll need to handle the output as we'll show next.

Printing packets to the console

Barnowl outputs visibilityEvents which our code can listen for. To listen for these events and output the data to the console (something potentially useful), paste in these additional lines of code:

middleware.on('visibilityEvent', function(tiraid) {
  console.log(tiraid); // Useful code goes here
});         

Now run your code as follows to see data packets output to the console:
node baby-barnowl.js

Wait, what's a tiraid?

A tiraid combines three elements:

  • timestamp
  • radio decodings
  • identifier

These are in fact the three core elements of hyperlocal context (which you can learn more about on the reelyActive website). Radio decodings and location are effectively equivalent if the location of the decoding devices is known (as is typically the case for fixed infrastructure).

The data produced by barnowl is always structured as these three elements. In the following sections, we'll see how we can filter based on these criteria.

Filtering packets by signal strength

Perhaps we're only interested in outputting data to the console for devices that are physically close to a reelceiver. In other words, we only display the data when the signal strength is above a threshold. To do so, we simply wrap the console.log(tiraid); from the previous example in an if statement which tests the signal strength or rssi (Received Signal Strength Indication):

var rssi = tiraid.radioDecodings[0].rssi;
if(rssi > 160) {
  console.log(tiraid);
}           

Now run your code again and try moving the detected wireless device(s) closer and farther away from the reelceiver(s).

Filtering packets by identifier

Perhaps we're only interested in outputting data to the console for a specific device. In other words, we only display the data when it is associated with a given device identifier. To do so, we again wrap the console.log(data); from the previous example in an if statement which tests the identifier:

var identifier = tiraid.identifier.value;
if(identifier === '001bc50940100000') {
  console.log(tiraid);
}           

Now run your code again and confirm that only packets from the given device are being output to the console.

Going one step further with reelib

The reelib package is a library for common reelyActive methods. Next we'll show how it simplifies printing the data stream to the console or to a file. Install reelib as follows:
npm install reelib

Prettier printing to the console

Create a new file called baby-barnowl-print.js and paste in the following code:

var barnowl = require('barnowl');
var reelib = require('reelib');

var middleware = new barnowl();
middleware.bind({ protocol: 'test',
                  path: 'default' });

middleware.on('visibilityEvent', function(tiraid) {
  console.log(reelib.tiraid.toShortString(tiraid));
});         

Now run your code as follows to see data packets output to the console in a single line:
node baby-barnowl-print.js

Logging data to a file

Create a new file called baby-barnowl-log.js and paste in the following code:

var barnowl = require('barnowl');
var reelib = require('reelib');
var fs = require('fs');

var middleware = new barnowl();
middleware.bind({ protocol: 'test',
                  path: 'default' });

fs.appendFile('log.csv', reelib.tiraid.CSV_HEADER + '\r\n');

middleware.on('visibilityEvent', function(tiraid) {
  var csv = reelib.tiraid.toCSVString(tiraid);
  fs.appendFile('log.csv', csv + '\r\n');
});         

Now run your code as follows for the data to be written as comma-separated values to the file log.csv:
node baby-barnowl-log.js

You can easily analyze and graph the data by opening log.csv in a spreadsheet program such as Excel or Google Sheets.

What's next?

Read the barnowl story and learn more about our software stack. Build web apps with beaver.js to do much the same but in your web browser rather than the command line.

The barnowl story Build web apps with beaver.js Return to diyActive