advlib

advlib is a library for decoding ambient wireless packets into web-standard JSON with a vendor/technology/application-agnostic set of properties.

advlib is a lightweight Node.js package that can run on resource-constrained edge devices as well as on powerful cloud servers and anything in between. It is included in reelyActive's Pareto Anywhere open source IoT middleware with its complementary processor and interpreter modules. There's even an interactive, browser-based version hosted from the gh-pages branch of this repository: reelyactive.github.io/advlib/

Open Source and Published

In addition to being permissively-licensed open source software, our paper Low-Power Wireless Advertising Software Library for Distributed M2M and Contextual IoT was published and presented at the 2015 2nd IEEE World Forum on Internet of Things (WF-IoT) in Milan, Italy. Learn more at reelyactive.com/science.

Processor modules

advlib is protocol-agnostic and currently supports the following processor modules:

• advlib-ble for Bluetooth Low Energy
• advlib-epc-tds for RAIN RFID (Electronic Product Code Tag Data Standard)
• advlib-esp for the EnOcean Wireless Standard (via the EnOcean Serial Protocol)

Interpreter modules

advlib currently supports the following interpreter module:

• advlib-interoperable for InteroperaBLE identifiers.

Hello advlib!

For example, process several raw packets received from a beacon by selecting Bluetooth Low Energy as the processor (advlib-ble) and including any relevant processor and interpreter libraries.

const advlib = require('advlib');

const PROCESSORS = [
    { processor: require('advlib-ble'),
      libraries: [ require('advlib-ble-services'),
                   require('advlib-ble-manufacturers') ],
      options: { ignoreProtocolOverhead: true } }
];
const INTERPRETERS = [ require('advlib-interoperable') ];

let packets = [
    'c21d04acbe55daba16096164766c6962206279207265656c79416374697665',
    'c21904acbe55daba1216aafe10fc017265656c7961637469766507',
    'c21804acbe55daba1116aafe20000c4815200000004500000258'
];
let processedPackets = advlib.process(packets, PROCESSORS, INTERPRETERS);
console.log(processedPackets);

Paste the code above into a decoder.js file. From the same folder, install package dependencies with the commands npm install advlib, npm install advlib-ble, ..., npm install advlib-interoperable. Then run the code with the command node decoder.js and observe the packets combined, in order of precedence, into a single JSON:

{ name: "advlib by reelyActive",
  txPower: -4,
  uri: "https://www.reelyactive.com",
  batteryVoltage: 3.144,
  temperature: 21.125,
  txCount: 69,
  uptime: 60000 }

Standard Properties

advlib observes the following standard properties to represent the information extracted from ambient data packets. New standard properties are added whenever new data cannot be effectively represented using the existing properties. Once established, a standard property should not change (unless otherwise noted).

| Property | Type | Notes | |:-----------------------------|:-----------------|-----------------------| | acceleration | Array of Number | [ x, y, z ] In g | | accelerationSamplingRate | Number | In Hz | | accelerationTimeSeries | Array of Array | [[x],[y],[z] ] In g | | ammoniaConcentration | Number | In ppm | | amperage | Number | In amps | | amperages | Array of Number | In amps | | angleOfRotation | Number | In degrees | | angularVelocity | Number | In degrees per second | | appearance | String | From Bluetooth | | batteryPercentage | Number | 0 to 100 (%) | | batteryVoltage | Number | In volts | | carbonDioxideConcentration | Number | In ppm | | carbonMonoxideConcentration | Number | In ppm | | count | Number | | | counts | Array of Number | | | deviceIds | Array of String | | | deviceType | String | | | dissolvedOxygen | Number | 0 to 100+ (%) | | distance | Number | In m | | duration | Number | In milliseconds | | durations | Array of Number | In milliseconds | | elevation | Number | In m | | encrypted | Object | See note below | | energy | Number | In kWh | | firmwareVersion | String | | | hardwareVersion | String | | | heading | Number | In degrees | | heartRate | Number | In beats per minute | | illuminance | Number | In lx | | interactionDigest | Array of Object | | | isButtonPressed | Array of Boolean | | | isButtonPressedCycle | Number | | | isCarbonMonoxideDetected | Boolean | | | isCarbonMonoxideDetectedCycle | Array ofBoolean | | | isContactDetected | Array of Boolean | | | isContactDetectedCycle | Number | | | isGasDetected | Array of Boolean | | | isGasDetectedCycle | Number | | | isHealthy | Boolean | | | isInputDetected | Array of Boolean | | | isInputDetectedCycle | Number | | | isLightDetected | Array of Boolean | | | isLightDetectedCycle | Number | | | isLiquidDetected | Array of Boolean | | | isLiquidDetectedCycle | Number | | | isMotionDetected | Array of Boolean | | | isMotionDetectedCycle | Number | | | isOccupancyDetected | Array of Boolean | | | isOccupancyDetectedCycle | Number | | | isSmokeDetected | Array of Boolean | | | isSmokeDetectedCycle | Number | | | isTamperDetected | Array of Boolean | | | isTamperDetectedCycle | Number | | | languages | Array of String | ISO 639-1 | | levelPercentage | Number | 0 to 100 (%) | | luminousFlux | Number | In lumens | | magneticField | Array of Number | [ x, y, z ] In G | | methaneConcentration | Number | In ppm | | name | String | | | nearest | Array of Object | | | nitrogenDioxideConcentration | Number | In ppm | | nitrogenOxidesIndex | Number | Index (1 to 500) | | numberOfOccupants | Number | | | numberOfOccupantsCycle | Number | | | numberOfReceivedDevices | Number | | | numberOfStrongestReceivedDevices | Number | | | passageCounts | Array of Number | [ entries, exits ] | | passageCountsCycle | Number | | | pH | Number | 0 to 14 (typical) | | pm1.0 | Number | In ug/m3 | | pm2.5 | Number | In ug/m3 | | pm10 | Number | In ug/m3 | | position | Array of Number | [ lon, lat, ele ] | | power | Number | In W | | pressure | Number | In Pa | | pressures | Array of Number | In Pa | | raw | String | Hexadecimal | | relativeHumidity | Number | 0 to 100 (%) | | relay | Object | See