{"id":22859936,"url":"https://github.com/reelyactive/barnowl","last_synced_at":"2025-04-18T16:18:47.809Z","repository":{"id":50490350,"uuid":"16813811","full_name":"reelyactive/barnowl","owner":"reelyactive","description":"Universal converter of ambient RF decodings into standard JSON that is vendor/technology/application-agnostic.  We believe in an open Internet of Things.","archived":false,"fork":false,"pushed_at":"2024-08-06T14:14:37.000Z","size":638,"stargazers_count":35,"open_issues_count":0,"forks_count":8,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-07T23:08:36.689Z","etag":null,"topics":["barnowl","bluetooth-low-energy","iot","location-awareness","m2m","middleware","node-js","pareto-anywhere","raddec","rfid","rtls"],"latest_commit_sha":null,"homepage":"https://www.reelyactive.com/pareto/anywhere/","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":"2014-02-13T19:14:50.000Z","updated_at":"2024-08-06T14:14:40.000Z","dependencies_parsed_at":"2023-09-27T05:59:40.195Z","dependency_job_id":"877e5ef4-b6ab-4acf-8a9f-ed0abb10e2b3","html_url":"https://github.com/reelyactive/barnowl","commit_stats":{"total_commits":178,"total_committers":4,"mean_commits":44.5,"dds":"0.028089887640449396","last_synced_commit":"30ef91c5cfdac1b9e90a088314d2738d6ba544d7"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fbarnowl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fbarnowl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fbarnowl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reelyactive%2Fbarnowl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reelyactive","download_url":"https://codeload.github.com/reelyactive/barnowl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249517767,"owners_count":21284835,"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":["barnowl","bluetooth-low-energy","iot","location-awareness","m2m","middleware","node-js","pareto-anywhere","raddec","rfid","rtls"],"created_at":"2024-12-13T09:08:29.027Z","updated_at":"2025-04-18T16:18:47.787Z","avatar_url":"https://github.com/reelyactive.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"barnowl\n=======\n\n__barnowl__ converts ambient RF decodings into standard developer-friendly JSON that is vendor/technology/application-agnostic.\n\n![Overview of barnowl](https://reelyactive.github.io/barnowl/images/overview.png)\n\n__barnowl__ is a lightweight [Node.js package](https://www.npmjs.com/package/barnowl) 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](https://www.reelyactive.com/pareto/anywhere/) open source middleware suite where it consolidates the real-time data from several [barnowl-x modules](#where-to-listen), each of which interfaces with specific radio infrastructure, such as gateways, APs and readers.\n\n\nGetting Started\n---------------\n\nFollow our step-by-step tutorials to get started with __barnowl-x__ or __Pareto Anywhere__ using _specific_ infrastucture:\n- [Ambient Infrastructure tutorials](https://reelyactive.github.io/diy/devices/#infrastructure)\n\nLearn \"owl\" about the __raddec__ JSON data output:\n-  [reelyActive Developer's Cheatsheet](https://reelyactive.github.io/diy/cheatsheet/)\n\n\nQuick Start\n-----------\n\nClone this repository, install package dependencies with `npm install`, and then from the root folder run at any time:\n\n    npm start\n\n__barnowl__ will listen for UDP raddec packets on 0.0.0.0:50001 and output (flattened) __raddec__ JSON to the console.\n\n\nHello barnowl!\n--------------\n\nDeveloping an application directly from __barnowl__?  Start by pasting the code below into a file called server.js:\n\n```javascript\nconst Barnowl = require('barnowl');\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.addListener(Barnowl, {}, Barnowl.TestListener, {});\n\nbarnowl.on('raddec', (raddec) =\u003e {\n  console.log(raddec);\n  // Trigger your application logic here\n});\n```\n\nFrom the same folder as the server.js file, install package dependencies with the command `npm install barnowl`.  Then run the code with the command `node server.js` and observe the _simulated_ data stream of radio decodings (raddec objects) output to the console:\n\n```javascript\n{\n  transmitterId: \"001122334455\",\n  transmitterIdType: 2,\n  rssiSignature: [\n    {\n      receiverId: \"001bc50940810000\",\n      receiverIdType: 1,\n      rssi: -61,\n      numberOfDecodings: 2\n    },\n    {\n      receiverId: \"001bc50940810001\",\n      receiverIdType: 1,\n      rssi: -63,\n      numberOfDecodings: 2\n    }\n  ],\n  packets: [ '061b55443322110002010611074449555520657669746341796c656572' ],\n  timestamp: 1645568542222\n}\n```\n\nSee [Where to listen?](#where-to-listen) below to adapt the code to listen for your gateways, APs and/or readers.\n\n\nWhere to listen?\n----------------\n\n__barnowl__ includes a TestListener (see the _Hello barnowl!_ example above) and a UdpListener (see the first example below) while all other listeners exist as separate software packages to keep the code as lightweight and modular as possible.  The following table lists all these listener packages which integrate seamlessly with __barnowl__ in just two lines of code.\n\n| Listener package                                                  | Use with |\n|:------------------------------------------------------------------|:---------|\n| [barnowl-minew](https://github.com/reelyactive/barnowl-minew)     | Minew gateways (ex: G1, G2, MG3, MG4) |\n| [barnowl-aruba](https://github.com/reelyactive/barnowl-aruba)     | [HPE Aruba Networking access points](https://www.reelyactive.com/pareto/anywhere/infrastructure/aruba/) |\n| [barnowl-huawei](https://github.com/reelyactive/barnowl-huawei)   | Huawei access points |\n| [barnowl-reel](https://github.com/reelyactive/barnowl-reel)       | [reelyActive hardware](https://www.reelyactive.com/technology/reel/) (BLE, sub-GHz active RFID) |\n| [barnowl-hci](https://github.com/reelyactive/barnowl-hci)         | BLE radios on Linux computers (ex: Raspberry Pi, PC, ...) |\n| [barnowl-laird](https://github.com/reelyactive/barnowl-laird)     | Laird Connectivity gateways (ex: IG60-BL654) |\n| [barnowl-impinj](https://github.com/reelyactive/barnowl-impinj)   | Impinj RFID readers |\n| [barnowl-rfcontrols](https://github.com/reelyactive/barnowl-rfcontrols) | RF Controls RFC OS |\n| [barnowl-csl](https://github.com/reelyactive/barnowl-csl)         | CSL RFID readers |\n| [barnowl-chafon](https://github.com/reelyactive/barnowl-chafon)   | Chafon RFID readers |\n| [barnowl-llrp](https://github.com/reelyactive/barnowl-llrp)       | Low-Level Reader Protocol (LLRP) |\n| [barnowl-enocean](https://github.com/reelyactive/barnowl-enocean) | EnOcean (ex: USB dongle) |\n| [barnowl-tcpdump](https://github.com/reelyactive/barnowl-tcpdump) | WiFi radios on computers that can run tcpdump |\n| [barnowl-axis](https://github.com/reelyactive/barnowl-axis)       | AXIS Communications IP cameras |\n\n### Example: UDP raddecs\n\n```javascript\nconst Barnowl = require('barnowl');\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.on(\"raddec\", (raddec) =\u003e { /* Handle the raddec */ });\n\n// Add the included UDP listener with relevant options\nbarnowl.addListener(Barnowl, {}, Barnowl.UdpListener, { path: \"0.0.0.0:50001\" });\n```\n\n### Example: reelyActive hardware connected via serial port\n\n```javascript\nconst Barnowl = require('barnowl');\nconst BarnowlReel = require('barnowl-reel'); // 1: Include the interface package\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.on(\"raddec\", (raddec) =\u003e { /* Handle the raddec */ });\n\n// 2: Add the specific listener with relevant options\nbarnowl.addListener(BarnowlReel, {}, BarnowlReel.SerialListener, { path: \"auto\" });\n```\n\n### Example: built-in BLE radio of a Raspberry Pi\n\n```javascript\nconst Barnowl = require('barnowl');\nconst BarnowlHci = require('barnowl-hci'); // 1: Include the interface package\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.on(\"raddec\", (raddec) =\u003e { /* Handle the raddec */ });\n\n// 2: Add the specific listener with relevant options\nbarnowl.addListener(BarnowlHci, {}, BarnowlHci.SocketListener, {});\n```\n\n### Example: WiFi radio on computer with tcpdump installed\n\n```javascript\nconst Barnowl = require('barnowl');\nconst BarnowlTcpdump = require('barnowl-tcpdump'); // 1: Include the package\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.on(\"raddec\", (raddec) =\u003e { /* Handle the raddec */ });\n\n// 2: Add the specific listener with relevant options\nbarnowl.addListener(BarnowlTcpdump, {}, BarnowlTcpdump.SpawnListener, {});\n```\n\n### Example: reelyActive hardware \u0026 tcpdump\n\n__barnowl__ supports multiple simultaneous listeners and will mix decodings of the same transmission from different sources provided that the _enableMixing_ feature is enabled.  For instance, the reelyActive Owl-in-One combines a BLE and WiFi source.\n\n```javascript\nconst Barnowl = require('barnowl');\nconst BarnowlReel = require('barnowl-reel');       // 1: Include each of the\nconst BarnowlTcpdump = require('barnowl-tcpdump'); //    interface packages\n\nlet barnowl = new Barnowl({ enableMixing: true });\n\nbarnowl.on(\"raddec\", (raddec) =\u003e { /* Handle the raddec */ });\n\nlet uart = /* */; // In this case the uart is an emitter of 'data' events\n\n// 2: Add the specifics listener with relevant options\nbarnowl.addListener(BarnowlReel, {}, BarnowlReel.EventListener, { path: uart });\nbarnowl.addListener(BarnowlTcpdump, {}, BarnowlTcpdump.SpawnListener, {});\n```\n\n\nIs that owl you can do?\n-----------------------\n\nWhile __barnowl__ may suffice standalone for simple real-time applications, its functionality can be greatly extended with the following software packages:\n- [advlib](https://github.com/reelyactive/advlib) to decode the individual packets from hexadecimal strings into JSON\n- [barnacles](https://github.com/reelyactive/barnacles) to distribute the real-time data stream via APIs and more\n- [chimps](https://github.com/reelyactive/chimps) to process the spatial-temporal dynamics data stream\n\nThese packages and more are bundled together as the [Pareto Anywhere](https://github.com/reelyactive/pareto-anywhere) open source middleware suite, which includes a variety of __barnowl-x__ listeners, APIs and interactive web apps.\n\n\nOptions\n-------\n\n__barnowl__ supports the following options:\n\n| Property                   | Default | Description                         | \n|:---------------------------|:--------|:------------------------------------|\n| enableMixing               | false   | Mix together decodings from the same transmitter  |\n| mixingDelayMilliseconds    | 1000    | Maximum time for any decoding to spend in the mixing queue |\n| minMixingDelayMilliseconds | 5       | Minimum time to delay between subsequent queue managements |\n| encodeRaddecs              | false   | Output raddecs as hex strings rather than as JSON |\n| acceptFutureRaddecs        | true    | raddecs with future timestamps are adjusted to current time and accepted, else rejected |\n\nIn most use cases, _enableMixing_ should be set to _true_ except under extreme memory constraints and/or when absolutely no processing delay can be tolerated.  Mixing decodings into a single [raddec](https://github.com/reelyactive/raddec/) provides lossless compression and promotes efficient data distribution and processing.\n\n```javascript\nlet barnowl = new Barnowl({ enableMixing: true }); // Recommended\n```\n\n\n![barnowl logo](https://reelyactive.github.io/barnowl/images/barnowl-bubble.png)\n\n\nWhat's in a name?\n-----------------\n\nThe Barn Owl has the best hearing of any animal tested.  Since this middleware is effectively listening (via hardware 'ears') for all the wireless devices in a Smart Space, barnowl would seem a more than fitting name.  Moreover, [Wikipedia introduces the Barn Owl](https://en.wikipedia.org/wiki/Barn_owl) as \"the most widely distributed species of owl, and one of the most widespread of all birds\".  An ambitiously inspiring fact considering our vision for a global crowdsourced infrastructure of Wireless Sensor Networks in the Internet of Things (IoT).\n\nDon't think we can top that?  Well check out this quote: \"the barn owl is the most economically beneficial species to humans\".  Yes, [apparently](http://www.hungryowl.org/education/natural_history.html) the U.S. Fish and Wildlife Service is prepared to argue so.  _Too ambitious?_  Well, consider this quote from [Jeremy Rifkin](https://en.wikipedia.org/wiki/Jeremy_Rifkin): \"What makes the IoT a disruptive technology in the way we organize economic life is that it helps humanity reintegrate itself into the complex choreography of the biosphere, and by doing so, dramatically increases productivity without compromising the ecological relationships that govern the planet.\"\n\nCan a few hundred lines of server-side Javascript known as barnowl really live up to that?  Owl we know is it can tyto do its nest!\n\n\nProject History\n---------------\n\n__barnowl__ is [reelyActive](https://www.reelyactive.com)'s original open source package, which, when initially released in 2014, decoded wireless packets specifically from [reelceivers](https://www.reelyactive.com/products/gateways/#reelceiver).  As third-party hardware became available, and technologies such as Bluetooth Low Energy emerged as global standards, __barnowl__ evolved into the vendor-and-technology-agnostic middleware it is today. \n\n__barnowl__ v1.0.0 was released in January 2019, superseding all earlier versions, the latest of which remains available in the [release-0.4 branch](https://github.com/reelyactive/barnowl/tree/release-0.4) and as [barnowl@0.4.28 on npm](https://www.npmjs.com/package/barnowl/v/0.4.28).\n\n\nModular Architecture\n--------------------\n\n__barnowl__ is easily combined with the following complementary software modules:\n- [barnacles](https://github.com/reelyactive/barnacles)\n- [chimps](https://github.com/reelyactive/chimps)\n- [advlib](https://github.com/reelyactive/advlib)\n\nLearn more about the [reelyActive Open Source Software packages](https://reelyactive.github.io/diy/oss-packages/), all of which are bundled together as [Pareto Anywhere](https://github.com/reelyactive/pareto-anywhere) open source IoT middleware.\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) 2014-2024 [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%2Fbarnowl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freelyactive%2Fbarnowl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freelyactive%2Fbarnowl/lists"}