{"id":22859988,"url":"https://github.com/reelyactive/raddec","last_synced_at":"2025-04-30T17:46:15.675Z","repository":{"id":47503903,"uuid":"138879085","full_name":"reelyactive/raddec","owner":"reelyactive","description":"Protocol-agnostic RADio DECoding packet library.  We believe in an open Internet of Things.","archived":false,"fork":false,"pushed_at":"2025-01-06T13:25:04.000Z","size":302,"stargazers_count":9,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T18:34:22.070Z","etag":null,"topics":["ble","library","m2m","packet-decoding","packet-encoding","pareto-anywhere","raddec","rfid","rtls","wifi"],"latest_commit_sha":null,"homepage":"https://www.reelyactive.com/ambient-data/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reelyactive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-27T12:34:05.000Z","updated_at":"2025-03-15T09:33:08.000Z","dependencies_parsed_at":"2025-01-07T02:45:30.746Z","dependency_job_id":"dc5e5242-e98d-41a0-ac2e-c929e6f6dd44","html_url":"https://github.com/reelyactive/raddec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fraddec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fraddec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fraddec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fraddec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reelyactive","download_url":"https://codeload.github.com/reelyactive/raddec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251754195,"owners_count":21638468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","library","m2m","packet-decoding","packet-encoding","pareto-anywhere","raddec","rfid","rtls","wifi"],"created_at":"2024-12-13T09:08:37.004Z","updated_at":"2025-04-30T17:46:15.658Z","avatar_url":"https://github.com/reelyactive.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"raddec\n======\n\nProtocol-agnostic RADio DECoding packet library\n-----------------------------------------------\n\nA __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.\n\n![raddec overview](https://reelyactive.github.io/raddec/images/overview.png)\n\n__raddec__ is a lightweight [Node.js package](https://www.npmjs.com/package/raddec) 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](https://www.reelyactive.com/pareto/anywhere/) open source IoT middleware and [barnowl](https://github.com/reelyactive/barnowl) modules which interface with gateways, readers and APs across vendors and technologies.\n\n\nOpen Source _and_ Published\n---------------------------\n\nIn addition to being permissively-licensed open source software, our paper [raddec: Elevating IoT Interoperability Through a Common Radio Decoding Data Format](https://ieeexplore.ieee.org/document/10811227) was published and presented at the 2024 IEEE 10th World Forum on Internet of Things (WF-IoT) in Ottawa, Canada.  Learn more at [reelyactive.com/science](https://www.reelyactive.com/science/).\n\n\nMotivation\n----------\n\nRadio-Frequency IDentification (RFID), Real-Time Location Systems (RTLS) and M2M (Machine-to-Machine) communications share several key properties:\n- transmitters transmit packets that may be received by one or more receivers\n- each transmitter and receiver has its own identifier\n- each received packet produces metadata including a timestamp and a Received Signal Strength Indication (RSSI)\n\nFor a broad range of applications, it is useful to identify, to locate and to collect [ambient data](https://www.reelyactive.com/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.\n\n\nOverview\n--------\n\nA __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:\n\n```javascript\n{\n  transmitterId: \"aabbccddeeff\",\n  transmitterIdType: 2,\n  rssiSignature: [{\n      receiverId: \"001bc50940810000\",\n      receiverIdType: 1,\n      rssi: -69,\n      numberOfDecodings: 3\n  }],\n  packets: [ /* As hexadecimal strings */ ],\n  timestamp: 1343392496789\n}\n```\n\nSee the [reelyActive Developer's Cheatsheet](https://reelyactive.github.io/diy/cheatsheet/) for a developer-friendly overview of the __raddec__ JSON.\n\nThis 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.\n\n### Hello raddec!\n\n```javascript\nconst Raddec = require('raddec');\n\n// The minimal raddec includes simply a transmitter identifier and type\nlet raddec = new Raddec({ \n    transmitterId: \"aa:bb:cc:dd:ee:ff\",\n    transmitterIdType: Raddec.identifiers.TYPE_EUI48\n});\n\n// One or more decodings by receivers are typically added\nraddec.addDecoding({\n    receiverId: \"00-1b-c5-09-40-81-00-00\",\n    receiverIdType: Raddec.identifiers.TYPE_EUI64,\n    rssi: -69\n});\n\n// Encoding results in a compact representation\nlet encoded = raddec.encodeAsHexString();\nconsole.log(encoded);\n// -\u003e 10001702aabbccddeeff013a0101001bc509408100000b (23 bytes)\n\n// Decoding restores a standard, easy-to-manipulate JSON object\nraddec = new Raddec(encoded);\n\n// A trim prunes any non-standard properties, adds timestamp if none present\nraddec.trim();\nconsole.log(raddec);\n// {\n//    transmitterId: \"aabbccddeeff\",\n//    transmitterIdType: 2,\n//    rssiSignature: [{\n//        receiverId: \"001bc50940810000\",\n//        receiverIdType: 1,\n//        rssi: -69,\n//        numberOfDecodings: 1\n//    }],\n//    timestamp: 1343392496789\n//  }\n\n// Flattening creates a JSON object suitable for storage/search/retrieval,\n//   with the default options shown below\nlet options = {\n    includePackets: true,        // Applicable when packets property is present\n    includeRssiSignature: false, // Note that the rssiSignature is NOT flat\n    maxNumberOfReceivers: 15,    // Only considered if\n    rssiThreshold: -127          //   includeRssiSignature is true\n};\nlet flattened = raddec.toFlattened(options);\nconsole.log(flattened);\n// {\n//    transmitterId: \"aabbccddeeff\",\n//    transmitterIdType: 2,\n//    receiverId: \"001bc50940810000\",\n//    receiverIdType: 1,\n//    rssi: -69,\n//    numberOfDecodings: 1,\n//    numberOfReceivers: 1,\n//    timestamp: 1343392496789\n//  }\n\n```\n\n\nProperties\n----------\n\nA __raddec__ _must_ include the following mandatory properties and _may_ include any or all of the following optional properties.\n\n### Mandatory Properties\n\nA __raddec__ includes the following three mandatory properties in both its _encoded_ (binary) and _decoded_ (JSON) form.\n\n| Property          | Type            | Description                          |\n|:------------------|:----------------|:-------------------------------------|\n| transmitterId     | String          | Hexadecimal string, lowercase, no separators |\n| transmitterIdType | Number          | Single byte (0-255)                  |\n| rssiSignature     | Array of Object | Ordered from strongest to weakest RSSI |\n\nEach object in the rssiSignature array includes the following properties.\n\n| Property          | Type            | Description                          |\n|:------------------|:----------------|:-------------------------------------|\n| receiverId        | String          | Hexadecimal string, lowercase, no separators |\n| receiverIdType    | Number          | Single byte (0-255)                  |\n| rssi              | Number          | In dBm                               |\n| numberOfDecodings | Number          | Range of 1-255 (0 reserved)          |\n\nAny object in the rssiSignature array may also include the following property.\n\n| Property          | Type            | Description                          |\n|:------------------|:----------------|:-------------------------------------|\n| receiverAntenna   | Number          | Antenna ID or Antenna Port           |\n| aoa               | Array of Number | Angle of Arrival: azimuth, elevation |\n\nNote 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.\n\n\n### Optional Properties\n\nA __raddec__ _may_ include any or all of the following properties.\n\n| Property    | Type            | Description                                  |\n|:------------|:----------------|:---------------------------------------------|\n| timestamp   | Number          | UNIX epoch (millisecond precision)           |\n| packets     | Array of String | Hexadecimal string, lowercase, no duplicates |\n| events      | Array of Number | Index list of associated events              |\n| position    | Array of Number | X, Y, Z coordinates                          |\n| protocolSpecificData | Object | May include any protocol-specific properties |\n\nWhen encoding a __raddec__, the optional properties to include must be explicitly specified, as the following example illustrates:\n\n```javascript\nlet encodedRaddec = raddec.encodeAsHexString({ includeTimestamp: true,\n                                               includePackets: true,\n                                               includeEvents: true,\n                                               includePosition: true });\n```\n\nNote that `protocolSpecificData` is _not_ included in the binary representation of a __raddec__, it exists only as JSON.\n\n\nSupported Wireless Protocols\n----------------------------\n\nThe __raddec__ library is being developed with consideration for the following protocols/standards:\n- Bluetooth Low Energy (broadcaster/observer roles)\n- WiFi (ex: probe requests)\n- RAIN RFID\n- EnOcean Alliance\n- LPWAN (various standards)\n- proprietary Active RFID (ex: reelyActive)\n\n\nQuick Reference\n---------------\n\nBoth _identifier types_ and _event types_ are represented as numerical indexes for efficient manipulation and compact storage.\n\n### Identifier Types\n\nThe identifier type indexes, which can be found in the _identifiers.js_ file, are as follows:\n\n| Index | Raddec.identifiers. | Description                                    |\n|:------|:--------------------|:-----------------------------------------------|\n| 0     | TYPE_UNKNOWN        | Unknown identifier type                        |\n| 1     | TYPE_EUI64          | EUI-64 (used by reelyActive infrastructure)    |\n| 2     | TYPE_EUI48          | EUI-48 (WiFi, BLE public addresses)            |\n| 3     | TYPE_RND48          | Random 48-bit advertiser address (BLE)         |\n| 4     | TYPE_TID96          | 96-bit tag identifier (EPC Tag Data Standard)  |\n| 5     | TYPE_EPC96          | 96-bit Electronic Product Code (EPC)           |\n| 6     | TYPE_UUID128        | 128-bit Universally Unique Identifier (UUID)   |\n| 7     | TYPE_EURID32        | 32-bit EnOcean Unique Radio Identifier (EURID) |\n| 8+    | - RESERVED -        | Reserved for future use                        |\n\n### Event Types\n\nThe event type indexes, which can be found in the _events.js_ file, are as follows:\n\n| Index | Raddec.events.  | Description                                         |\n|:------|:----------------|:----------------------------------------------------|\n| 0     | APPEARANCE      | First decoding of the transmitter in recent memory  |\n| 1     | DISPLACEMENT    | Change of strongest receiver by transmitter         |\n| 2     | PACKETS         | New packet payload received from transmitter        |\n| 3     | KEEPALIVE       | Periodic update of transmitter's recent decoding(s) |\n| 4     | DISAPPEARANCE   | Transmitter no longer decoded by any receiver       |\n| 5-7   | - RESERVED -    | Reserved for future use                             |\n\n\nWhat's next?\n------------\n\nThis 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](https://www.reelyactive.com/contact/).\n\n\nContributing\n------------\n\nDiscover [how to contribute](CONTRIBUTING.md) to this open source project which upholds a standard [code of conduct](CODE_OF_CONDUCT.md).\n\n\nSecurity\n--------\n\nConsult our [security policy](SECURITY.md) for best practices using this open source software and to report vulnerabilities.\n\n\nLicense\n-------\n\nMIT License\n\nCopyright (c) 2018-2025 [reelyActive](https://www.reelyactive.com)\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR \nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, \nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE \nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER \nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, \nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN \nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fraddec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freelyactive%2Fraddec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fraddec/lists"}