raddec

Protocol-agnostic RADio DECoding packet library

A raddec is an open-standard representation of a radio decoding. This library provides functionality to manipulate any raddec as JSON and to convert to/from its binary representation.

raddec overview

raddec 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 core to reelyActive's Pareto Anywhere open source IoT middleware and barnowl modules which interface with gateways, readers and APs across vendors and technologies.

Open Source and Published

In addition to being permissively-licensed open source software, our paper raddec: Elevating IoT Interoperability Through a Common Radio Decoding Data Format was published and presented at the 2024 IEEE 10th World Forum on Internet of Things (WF-IoT) in Ottawa, Canada.

raddec poster

Learn more at reelyactive.com/science.

Motivation

Radio-Frequency IDentification (RFID), Real-Time Location Systems (RTLS) and M2M (Machine-to-Machine) communications share several key properties:

transmitters transmit packets that may be received by one or more receivers
each transmitter and receiver has its own identifier
each received packet produces metadata including a timestamp and a Received Signal Strength Indication (RSSI)

For a broad range of applications, it is useful to identify, to locate and to collect ambient data from wireless devices, and this raddec library is developed with the intent of providing a protocol-agnostic means of representing and efficiently transferring such information across networks.

Overview

A raddec has two forms: an encoded form in which it has a strict binary representation, and a decoded form in which it typically has a less-restrictive JSON representation. The JSON representation is as follows:

{
  transmitterId: "aabbccddeeff",
  transmitterIdType: 2,
  rssiSignature: [{
      receiverId: "001bc50940810000",
      receiverIdType: 1,
      rssi: -69,
      numberOfDecodings: 3
  }],
  packets: [ /* As hexadecimal strings */ ],
  timestamp: 1343392496789
}

See the reelyActive Developer's Cheatsheet for a developer-friendly overview of the raddec JSON.

This library provides functionality to encode a raddec, typically in anticipation of network transport to a destination computer, and to decode the same raddec, typically to facilitate manipulation and storage of the contained information.

Hello raddec!

const Raddec = require('raddec');

// The minimal raddec includes simply a transmitter identifier and type
let raddec = new Raddec({ 
    transmitterId: "aa:bb:cc:dd:ee:ff",
    transmitterIdType: Raddec.identifiers.TYPE_EUI48
});

// One or more decodings by receivers are typically added
raddec.addDecoding({
    receiverId: "00-1b-c5-09-40-81-00-00",
    receiverIdType: Raddec.identifiers.TYPE_EUI64,
    rssi: -69
});

// Encoding results in a compact representation
let encoded = raddec.encodeAsHexString();
console.log(encoded);
// -> 10001702aabbccddeeff013a0101001bc509408100000b (23 bytes)

// Decoding restores a standard, easy-to-manipulate JSON object
raddec = new Raddec(encoded);

// A trim prunes any non-standard properties, adds timestamp if none present
raddec.trim();
console.log(raddec);
// {
//    transmitterId: "aabbccddeeff",
//    transmitterIdType: 2,
//    rssiSignature: [{
//        receiverId: "001bc50940810000",
//        receiverIdType: 1,
//        rssi: -69,
//        numberOfDecodings: 1
//    }],
//    timestamp: 1343392496789
//  }

// Flattening creates a JSON object suitable for storage/search/retrieval,
//   with the default options shown below
let options = {
    includePackets: true,        // Applicable when packets property is present
    includeRssiSignature: false, // Note that the rssiSignature is NOT flat
    maxNumberOfReceivers: 15,    // Only considered if
    rssiThreshold: -127          //   includeRssiSignature is true
};
let flattened = raddec.toFlattened(options);
console.log(flattened);
// {
//    transmitterId: "aabbccddeeff",
//    transmitterIdType: 2,
//    receiverId: "001bc50940810000",
//    receiverIdType: 1,
//    rssi: -69,
//    numberOfDecodings: 1,
//    numberOfReceivers: 1,
//    timestamp: 1343392496789
//  }

Properties

A raddec must include the following mandatory properties and may include any or all of the following optional properties.

Mandatory Properties

A raddec includes the following three mandatory properties in both its encoded (binary) and decoded (JSON) form.

| Property | Type | Description | |:------------------|:----------------|:-------------------------------------| | transmitterId | String | Hexadecimal string, lowercase, no separators | | transmitterIdType | Number | Single byte (0-255) | | rssiSignature | Array of Object | Ordered from strongest to weakest RSSI |

Each object in the rssiSignature array includes the following properties.

| Property | Type | Description | |:------------------|:----------------|:-------------------------------------| | receiverId | String | Hexadecimal string, lowercase, no separators | | receiverIdType | Number | Single byte (0-255) | | rssi | Number | In dBm | | numberOfDecodings | Number | Range of 1-255 (0 reserved) |

Any object in the rssiSignature array may also include the following property.

| Property | Type | Description | |:------------------|:----------------|:-------------------------------------| | receiverAntenna | Number | Antenna ID or Antenna Port | | aoa | Array of Number | Angle of Arrival: azimuth, elevation |

Note that the optional receiverAntenna and aoa properties are not included in the binary representation of a raddec: this is a limitation of v0.x of this library.

Optional Properties

A raddec may include any or all of the following properties.

| Property | Type | Description | |:------------|:----------------|:---------------------------------------------| | timestamp | Number | UNIX epoch (millisecond precision) | | packets | Array of String | Hexadecimal string, lowercase, no duplicates | | events | Array of Number | Index list of associated events | | position | Array of Number | X, Y, Z coordinates | | protocolSpecificData | Object | May include any protocol-specific properties |

When encoding a raddec, the optional properties to include must be explicitly specified, as the following example illustrates:

let encodedRaddec = raddec.encodeAsHexString({ includeTimestamp: true,
                                               includePackets: true,
                                               includeEvents: true,
                                               includePosition: true });

Note that protocolSpecificData is not included in the binary representation of a raddec, it exists only as JSON.

Supported Wireless Protocols

The raddec library is being developed with consideration for the following protocols/standards:

Bluetooth Low Energy (broadcaster/observer roles)
WiFi (ex: probe requests)
RAIN RFID
EnOcean Alliance
LPWAN (various standards)
proprietary Active RFID (ex: reelyActive)

Quick Reference

Both identifier types and event types are represented as numerical indexes for efficient manipulation and compact storage.

Identifier Types

The identifier type indexes, which can be found in the identifiers.js file, are as follows:

| Index | Raddec.identifiers. | Description | |:------|:--------------------|:-----------------------------------------------| | 0 | TYPE_UNKNOWN | Unknown identifier type | | 1 | TYPE_EUI64 | EUI-64 (used by reelyActive infrastructure) | | 2 | TYPE_EUI48 | EUI-48 (WiFi, BLE public addresses) | | 3 | TYPE_RND48 | Random 48-bit advertiser address (BLE) | | 4 | TYPE_TID96 | 96-bit tag identifier (EPC Tag Data Standard) | | 5 | TYPE_EPC96 | 96-bit Electronic Product Code (EPC) | | 6 | TYPE_UUID128 | 128-bit Universally Unique Identifier (UUID) | | 7 | TYPE_EURID32 | 32-bit EnOcean Unique Radio Identifier (EURID) | | 8+ | - RESERVED - | Reserved for future use |

Event Types

The event type indexes, which can be found in the events.js file, are as follows:

| Index | Raddec.events. | Description | |:------|:----------------|:----------------------------------------------------| | 0 | APPEARANCE | First decoding of the transmitter in recent memory | | 1 | DISPLACEMENT | Change of strongest receiver by transmitter | | 2 | PACKETS | New packet payload received from transmitter |

Raddec

Install / Use

README