Home

Awesome

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 middleware suite and barnowl modules which interface with gateways, readers and APs across vendors and technologies.

Motivation

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

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.

PropertyTypeDescription
transmitterIdStringHexadecimal string, lowercase, no separators
transmitterIdTypeNumberSingle byte (0-255)
rssiSignatureArray of ObjectOrdered from strongest to weakest RSSI

Each object in the rssiSignature array includes the following properties.

PropertyTypeDescription
receiverIdStringHexadecimal string, lowercase, no separators
receiverIdTypeNumberSingle byte (0-255)
rssiNumberIn dBm
numberOfDecodingsNumberRange of 1-255 (0 reserved)

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

PropertyTypeDescription
receiverAntennaNumberAntenna ID or Antenna Port
aoaArray of NumberAngle 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.

PropertyTypeDescription
timestampNumberUNIX epoch (millisecond precision)
packetsArray of StringHexadecimal string, lowercase, no duplicates
eventsArray of NumberIndex list of associated events
positionArray of NumberX, Y, Z coordinates
protocolSpecificDataObjectMay 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:

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:

IndexRaddec.identifiers.Description
0TYPE_UNKNOWNUnknown identifier type
1TYPE_EUI64EUI-64 (used by reelyActive infrastructure)
2TYPE_EUI48EUI-48 (WiFi, BLE public addresses)
3TYPE_RND48Random 48-bit advertiser address (BLE)
4TYPE_TID9696-bit tag identifier (EPC Tag Data Standard)
5TYPE_EPC9696-bit Electronic Product Code (EPC)
6TYPE_UUID128128-bit Universally Unique Identifier (UUID)
7TYPE_EURID3232-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:

IndexRaddec.events.Description
0APPEARANCEFirst decoding of the transmitter in recent memory
1DISPLACEMENTChange of strongest receiver by transmitter
2PACKETSNew packet payload received from transmitter
3KEEPALIVEPeriodic update of transmitter's recent decoding(s)
4DISAPPEARANCETransmitter no longer decoded by any receiver
5-7- RESERVED -Reserved for future use

What's next?

This library is currently in active development. Expect features to be added periodically. We recommend observing semantic versioning best practices for dependents should breaking changes be required. If you have an interest in using this library and/or have strong thoughts on its properties, kindly get in touch via our contact information.

Contributing

Discover how to contribute to this open source project which upholds a standard code of conduct.

Security

Consult our security policy for best practices using this open source software and to report vulnerabilities.

License

MIT License

Copyright (c) 2018-2024 reelyActive

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.