{"id":18285534,"url":"https://github.com/ludiazv/node-nrf24","last_synced_at":"2025-04-05T07:32:25.259Z","repository":{"id":93984921,"uuid":"119454286","full_name":"ludiazv/node-nrf24","owner":"ludiazv","description":"nRF24 (nrf24l01/nrfl24l01+) radios in the nodejs way","archived":false,"fork":false,"pushed_at":"2023-04-24T12:56:04.000Z","size":192,"stargazers_count":40,"open_issues_count":11,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-18T10:48:35.539Z","etag":null,"topics":["linux","nodejs","nrf24","nrf24l01","orangepi","radio","raspberry","rf24"],"latest_commit_sha":null,"homepage":"","language":"C++","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/ludiazv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.buymeacoffee.com/boros"]}},"created_at":"2018-01-29T23:15:47.000Z","updated_at":"2024-11-23T07:29:13.000Z","dependencies_parsed_at":"2024-06-19T11:14:49.961Z","dependency_job_id":"e7ef4826-3ec8-4e85-866b-0ba8ba386bb7","html_url":"https://github.com/ludiazv/node-nrf24","commit_stats":{"total_commits":146,"total_committers":5,"mean_commits":29.2,"dds":0.6027397260273972,"last_synced_commit":"4987a0bbafc2834e8783dd612ebae305a20e7993"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ludiazv%2Fnode-nrf24","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ludiazv%2Fnode-nrf24/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ludiazv%2Fnode-nrf24/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ludiazv%2Fnode-nrf24/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ludiazv","download_url":"https://codeload.github.com/ludiazv/node-nrf24/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305879,"owners_count":20917201,"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":["linux","nodejs","nrf24","nrf24l01","orangepi","radio","raspberry","rf24"],"created_at":"2024-11-05T13:17:00.300Z","updated_at":"2025-04-05T07:32:20.234Z","avatar_url":"https://github.com/ludiazv.png","language":"C++","funding_links":["https://www.buymeacoffee.com/boros"],"categories":[],"sub_categories":[],"readme":"\n# nrf24 - RF24 Radios in the node way\n\n[![GitHub issues](https://img.shields.io/github/issues/ludiazv/node-nrf24.svg)](https://github.com/ludiazv/node-nrf24/issues)\n![Build](https://github.com/ludiazv/node-nrf24/actions/workflows/build.yml/badge.svg)\n![npm](https://img.shields.io/npm/v/nrf24)\n![node](https://img.shields.io/node/v/nrf24)\n![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/ludiazv/node-nrf24)\n\n\n\nThis module enable __nodejs__ (using javascript syntactic sugar) to manage __nRF24L01(+)__ radios on linux-based one board computers (RaspberryPi,OrangePi,BeagleBone,Edison,CHIP...). Wide support for SBCs is provided by the *RF24 library* supporting Generic Linux devices with SPIDEV, MRAA, RPi native via BCM* chips, WiringPi or using LittleWire.\n\nThis module is based on the outstanding C++ library optimized by @tmrh20. Please consult the project documentation **nRF24** [here](http://nrf24.github.io/RF24/) for additional details.\n\nThis project has a sister project to enable __Node-RED__ to use __nRF24L01(+)__ radios in a seamless way with visual flow programming. Check out the repository [here](https://github.com/ludiazv/node-red-contrib-nrf24).\n\n__nRF24L01__ present several problems when connected using long wires and poorly regulated power sources. To avoid this kind of problems is recommended to use break-out boards. For standard Pi-like\ncomputers [this Hat/pHat](https://www.tindie.com/products/11790/) enable a simple hardware integration with minimal configuration. Full documentation of this openHw project can be consulted [here](https://github.com/ludiazv/borosRF2).\n\n**BorosRF2 hat:**\n\n![image](https://github.com/ludiazv/borosRF2/blob/master/media/all.jpg?raw=true)\n\n\nIf you **like** this project and want to support **the development and maintenance** please consider a donation.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/boros\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-white.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n## Overview\n\nThis nodejs add-on has the following features:\n\n1. Basic \u0026 streaming __RF24__ radio support.\n2. Create a __RF24Mesh__ network as master or Join to a *RF24Mesh* as node.\n3. Provide a __RF24Gateway__ directly on nodeJs to provide TCP/IP connectivity for your radios. *[In development]*\n\n## Installation\n\n### Prerequisites:\n\n### Nodejs version\nThe module requires node js version \u003e=12. This requeriment can change as nodejs new versions of are released.\n\n#### SPI enabled \u0026 Gpio Access\nIn order to communicate with the radio linux kernel need to have SPI enabled and direct access to board GPIOs. In some distributions SPI interface is disabled by default so it's needed to be enabled.\n\nIn Rpi Raspbian it can be done using ``raspi-config`` or modifying `` /boot/config.txt ``. Check [here](https://www.raspberrypi.org/documentation/hardware/raspberrypi/spi/README.md) for more details.\nFor Rpi DietPi (recommended distribution for headless projects) the procedure is similar but using the ``/DietPi/config.txt``.\n\nGpio access require access to ``sysfs`` under the path ``/sys/class/gpio/``. In common linux distributions simply adding the user executing the nodejs application to the ``gpio`` group\ncheck ``usermod``to do it.\n\nIn Rpi alternatives based on armbian such OrangePi, NaoPi,... please consult armbian documentation [here](https://docs.armbian.com/Hardware_Allwinner_overlays/).\n\n\nFor other SBCs or distributions consult who to activate SPI and Gpios.\n\nIf using Spidev driver (see below) the user executing the nodejs application need to have access to the /dev/spidevX.X files. This can be done in typical distribution adding the user to the ``spi`` group.\n\n#### A working nRF24L01(+) radio\n\nA *nRF24L01(+)* radio must be wired to your system and tested for connection. RF24* libs have several testing examples that can be use for for that purpose.\n\nAn example of wiring for an OrangePi Zero(using SPI 1 bus) and Rpi (using SPI 0 bus) is show in the following table:\n\n| PIN NRF24L01 | OrangePi Zero Pin    |\n| -------------- | ------------------ |\n| 1 GND          |  opi-gnd (25)      |\n| 2 VCC          |  opi-3v3 (17)      |\n| 3 CE           |  opi-PA6 (7) (selectable)  |\n| 4 CSN\t         |  opi-spi1cs0 (24)  |\n| 5 SCK\t         |  opi-spi1Sck (14)  |\n| 6 MOSI\t       |  opi-spi1Mosi (19) |\n| 7 MISO       |  opi-spi1Miso (16) |\n| 8 IRQ          |  not connected / optional  |\n\n\n\n| PIN\tNRF24L01\t| RPI\tRPi -P1 Connector |\n| ------------- | --------------------- |\n| 1 GND\t       | rpi-gnd\t(25) |\n| 2 VCC\t      | rpi-3v3\t(17) |\n| 3 CE\t       | rpi-gpio22\t(15) |\n| 4 CSN\t       | rpi-gpio8\t(24) |\n| 5 SCK\t       | rpi-sckl\t(23) |\n| 6 MOSI\t     | rpi-mosi\t(19) |\n| 7 MISO\t     | rpi-miso\t(21) |\n| 8 IRQ\t\t     |  not connected  / optional |\n\nUnderstand your wiring is critical for hardware initialization as there are not hardware discovery mechanism implemented in the library.\n\nFor better performance and lower CPU usage is recommended to connect also the __PIN 8 (IRQ line)__ an additional GPIO line. Check-out the ``config`` API addtional information about IRQ management. \n\n### Install the nrf24 package\n\nUse NPM as with other modules:\n```bash\ncd \u003cyour project\u003e\nnpm install nrf24 --save\n```\nThis will add nrf24 to your project and save the dependence in your __package.json__. \n\nStarting from version ```0.2-beta``` the module is build with prebuild versions for stable lts versions of nodejs for armv7(32bit) and armv8 (64bit) platforms.\n\n__disclaimer:__ This package is a C++ native add-on that may require compilation on your linux system. Please assure that you have the proper \"build-essential\",\"base-devel\" packages installed according to your linux distribution.\n\nBy default the packages install will build the node module with **SPIDEV** driver. If other driver is preferred the install command must provide the ``env`` variable ``DRIVER=\u003cdriver\u003e`` before the npm install command. For example if the driver to use is ``RPi`` install command is:\n\n```bash\nDRIVER=RPi npm install nrf24 --save\n```\n\nThis may not work for some available drivers. The only tested DRIVER is **SPIDEV**.\n\n\n## Usage\n\n### Basic RF24\nEnable **nodejs** have basic communication over __nRF24L01(+)__ radios in a simple javascript code:\n\n```javascript\n...\nconst nrf24=require(\"nrf24\"); // Load de module\n// or\nimport * as nrf24 from 'nrf24'; // Load with import notation notation.\n\n// Init the radio\nvar rf24= new nrf24.nRF24(\u003cCE gpio\u003e,\u003cCS gpio\u003e);\nrf24.begin();\n// Configure the radio\nrf24.config({\n  PALevel: nrf24.RF24_PA_LOW,\n  DataRate: nrf24.RF24_1MBPS,\n  ... // Other config\n});\n\n// Register Reading pipes\nvar pipe=rf24.addReadPipe(\"0x65646f4e31\",true) // listen in pipe \"0x65646f4e31\" with AutoACK enabled.\n...\n//up to 5 pipes can be configured\n\n// Register callback for reading\nrf24.read( function(data,n) {\n  // when data arrive on any registered pipe this function is called\n  // data -\u003e JS array of objects with the follwing props:\n  //     [{pipe: pipe id, data: nodejs with the data },{ ... }, ...]\n  // n -\u003e number elements of data array    \n},function(isStopped,by_user,error_count) {\n  // This will be if the listening process is stopped.\n});\n\n...\n\n// Sending data over the radio\nvar data=Buffer.from(\u003cyour data\u003e); // Create a node buffer for sending data\nrf24.useWritePipe(\"0x72646f4e31\",true); // Select the pipe address to write with Autock\nrf24.write(data); // send the data in sync mode\n\n...\n// Async write with callback\nrf24.write(data,function(success,...){\n  // Callback after sending data\n});\n\n...\n// If you want to stop listening\nrf24.stopRead();\n...\n// If you want to abort pending async writes\nrf24.stopWrite();\n\n\n// Finally to assure that object is destroyed\n// and memory freed destroy must be called.\nrf24.destroy();\n\n\n```\n\n### Streaming data\nThe maximun payload of NRF24 radios is 32 bytes. In order to transmit or recive streams bigger buffers of data the module offers some helpers for this operations. \n\nStreaming data can be acomplished by using stream function:\n```javascript\nrf24.changeWritePipe(true,2048); // Set max stream size to 2Kb\n\nvar big_buffer=Buffer.from(\u003cdata_up_to_2K\u003e);\nrf24.stream(big_buffer,function(success,tx_ok,tx_bytes,tx_req,frame_size,aborted) {\n  if(success) console.log(\"Stream ok\");\n  else {\n    console.log(\"Transfered:\"+tx_bytes+ \" total:\" + tx_req + \" OK-\u003e\" + tx_ok);\n  }\n});\n```\n\nReceiving streaming data:\n\nReceiving streaming data do not require special function. ``read()``function will receive the incoming frames. To improve perfomance incoming frames from the transmitter can be merged into a single buffer. The library will try to merge incoming frames and send then to the ```read() callback``` but is not guarteed that frames will be merged. User can configure maximun frames that are possible to merge by calling ```changeReadPipe()```\n\n```javascript\nrf24.changeReadPipe(pipenr,false,10); // Wil merge up to 10 frames with out \n\n```\n\n### Peformance\n\nStarting form version 1.0-beta the improvement of perfomance is significant. To archive better maximun performance **IRQ** line must be configured.\n\nCheck this [this](https://github.com/ludiazv/node-nrf24/blob/master/PERFORMANCE.md) page to check a baseline performed that can be archived with the library.\n\n### Failure handling\nDue to wrong wiring / weak signal quality or faulty hardware the module can detect when the radio is in a inconsistent status and is not able to transmit. User can check via ```hasFailure()``` API if this condition has been detected. Recovery of this situation could require to change wiring or improve power/decoupling for the radio module or simply change the radio module. \n\n__experimental__: Recovery of faulty hardware is supported in a experimental way by reseting the radio. If a radio is failing randomly but it perform well the user can call ```restart()``` API to reset the radio. All configuration will be restarted acording to user. Faliures can be only detected after writing.\n\n### RF24Mesh\n\nTODO documentation\n....\n\n### RF24RF24Gateway\n\nTODO documentation\n....\n\n\n## API\n\n### RF24 API\n\nThe module offer a simplified and basic functionality of the nRF24 library. Only basic operations are supported. Features such DynamicPayloads, AckPayloads, ... are not supported.\n\n#### RF24(ce,cs,spi_speed=10000000) constructor\nCreate RF24 object that match the wiring. ce and cs values will vary depending on your\nhardware and build o RF24 libs. Please refer to R24libs documentation [here](http://tmrh20.github.io/RF24/RPi.html)\nfor your specific case.\n\n*Parameters:*\n\n| Param | description |\n| ----- | ----------- |\n| ce    | GPIO # for CE pin |\n| cs    | SPI Chip Select pin. For SPIDEV the mapping is (a * 10 + b)  for /dev/spideva.b |\n| spi_speed | Speed of the SPI interface in Hz. Defaults to 10000000 (10Mhz) |\n\nBoth parameters are mandatory. Constructor must be called with __new__ keyword to create a new RF24 object, otherwise thiscall will produce an exception.\n\nCE could be any available GPIO , CS pins on the contrary need to be pins that are configured in the kernel as part of the SPI interface.\n\n*Example:*\n```javascript\n// For RPI\nvar rf24=new nrf24.nRF24(22,0); // Rpi SPI0 with CE in PIN 15/GPIO 22 and CS0\n\n// for SPIDEV\nvar rf24=new nrf24.nRF24(6,10); // OrangePi SPI1 CE=PA06 and CS=\u003ca\u003e*10+\u003cb\u003e for /dev/spidev\u003ca\u003e.\u003cb\u003e\n\n```\n*Returns*: RF24 Object\n\n*Throws:*: TypeError Exception if the parameters CS or CE are invalid.\n\n#### destroy() Explicit destructor\nDestroy the object __This method must be called__ if its needed to reclaim the memory and resources. If there is any pending reads on the reading queue or pending async writes will be cancelled.\n\n*Example:*\n\n```javascript\nlet rf24=new nrf24.nRF24(22,0);\n...\n// Do radio work\n\nrf24.destroy(); // After this call the GC will reclaim the object if needed.\n// The object will become unusable at this point.\n```\n\n*Returns*: none.\n*Throws:*: none.\n\n#### begin(print_debug=false)\nAfter the creation of the object it is required to call to begin. If begin initializes the hardware for transmitting an receiving.\n\n*Parameters:*\n\n| Param | description |\n| ----- | ----------- |\n| print_debug (optional)    | true/false prints RF24 debug information in stdout (it will be useful for debugging  purposes). default=false |\n\n*Example:*\n\n```javascript\nvar rf24=new nrf24.nRF24(22,0);\nrf24.begin();\n\n```\n\n*returns:* true/false success\n\n*throws:* nothing\n\n\n#### config(options,print_details=false)\nConfigure the radio with some generally used configuration parameters. This function must be called after calling begin().\n\n*Parameters:*\n A sole parameter options is passed for configuration. options must be javascript object with the following properties:\n\n| Property | description (valid values) | Default Value |\n| -----    | ----------- | ------------- |\n| PALevel  | Transmission power (MIN, LOW, HIGH, MAX) | MIN |\n| EnableLna| Enable LNA amplifier if the radio module has it | true |\n| DataRate | Speed of transmission bps (2MBPS,1MBPS,250KB)            | 1MBPS |\n| Channel  | Radio Channel (1-127)  | 76 |\n| CRCLength| Length of CRC checksum for data integrity checking (8bit,16bit, disabled)  | CRC 16 bit  |\n| retriesCount  |  Number of transmission retries (0-15)   | 5 |\n| retriesDelay   | Time (n+1)*250us to wait between transmission retries (0-15) | 15 |\n| PayloadSize  | Size of the radio frame (1-32)  | 32 |\n| AddressWidth  | Radio Pipes address size (3,4,5)  | 5  |\n| AutoAck  | Use Built-in ack true/false | true |\n| Irq | Gpio number of IRQ line (if negative IRQ line is not ussed) | -1 |\n| PollBaseTime | If IRQ is not used this the reference time in us for polling reads (\u003e4000) | 35000 |\n| TxDelay | Grace time peridod when switching from listening to writing mode in us (\u003e4) | 250 |\n\nAll options Property are **optional**. Default values described above are used if not present in the options object. If any parameter is not valid default values for the parameters are used instead.\n\nnode-rf24 exports some constants to help to define:\n\n| Item | Values |\n| ---- | ------ |\n| Speed | RF24_1MBPS, RF24_2MBPS,RF24_250KBPS |\n| Power Level  |  RF24_PA_MIN,RF24_PA_LOW,RF24_PA_HIGH,RF24_PA_HIGH, RF24_PA_MAX ,RF24_PA_ULTRA |\n| CRC Checking  | RF24_CRC_DISABLED,RF24_CRC_8,RF24_CRC_16  |\n\n__note__: 250KBPS seed is only available in nRF24L01+ variant. If your radio is a nRF24L01 this speed option will not work.\n\n__note__: PA_ULTRA is the same as RF24_PA_MAX starting form version 0.1.6 for comaptibility reasons with previous versions.\n\nThe power levels correspond to the following output levels respectively:\n\nNRF24L01: -18dBm (MIN), -12dBm(LOW),-6dBM(HIGH), and 0dBm(MAX), EnableLna affects modules with LNA\n\nSI24R1:\n- 6dBm (MIN), 0dBm (LOW), 3dBm(HIGH)  and 7dBm(MAX) with EnableLna = true\n- 12dBm (MIN),-4dBm (LOW), 1dBm(HIGH) and 4dBm(MAX) with EnableLna = false\n\n\n\nThe second parameter ``print_details`` is optional boolean to show in stdout the configuration of the radio after config is executed. This is useful for debugging.\n\n*Example:*\n\n```javascript\nrf24.begin();\n/* set Powe Level to maximum, set transfer speed to 250KBPS and on channel 101 */\nvar conf={\n  PALevel:nrf24.RF24_PA_MAX,\n  DataRate: nRF24.RF24_250KBPS,\n  Channel: 101\n};\nrf24.config(conf); // Configuration will be applied.\n\n```\n\n*Returns:* nothing\n\n*Throws:* Syntax Error exception if errors of on parameters are found.\n\n#### present()\nCheck if radio is connected. This function must be called after begin to work properly.\n\n*parameters*: none.\n\n*Example:*\n```javascript\nrf24.begin();\nconsole.log(\"Radio connected:\" + rf24.present()); // Prints true/false if radio is connected.\n\n```\n*Returns*: true/false (if radio is connected)\n\n*Throws*: nothing.\n\n#### isP()\nCheck if the connected radio is nRF24L01+ variant.This function must be called after begin to work properly.\n\n*parameters*: none.\n\n*Example:*\n```javascript\nrf24.begin();\nconsole.log(\"Is + Variant:\" + rf24.isP()); // Prints true/false if radio is + Variant\n\n```\n*Returns*: true/false (if radio is + variant)\n\n*Throws*: nothing.\n\n#### powerUp() / powerDown()\nDisable/enable radio saving energy when not in use. By Default after ```begin()```the radio will be powered up. Note that no information can be received or transmitted but in exchange the power consumption of the radio will be less than 1uA(sleep mode).\n\nNote that if you are listening for radio frames via ```read()``` API you must call ```stopRead()``` before put the radio to sleep. Conversely if there are pending async writes the API ``stopWrite()`` must be called before the radio can be powered down.\n\n\n*parameters*: none.\n\n*Example:*\n```javascript\nrf24.begin();\n// radio is UP\nrf24.powerDown();\n// Radio is asleep\n...\nrf24.read(...);\n// After registeting reading callbacks radio will remain allwayson\n...\nrf24.stopRead();\nrf24.stopWrite();\nrf24.powerDown();\n// Radio is asleep\n\n```\n*Returns*: nothing.\n\n*Throws*: nothing.\n\n#### addReadPipe(addr,auto_ack=default value)\nBefore being able to receive any frame a **reading pipe** must be registered. A reading pipe is a one-way address-based radio tunnel that need to be used by the transmitter to communicate with the receiver. In a typical radio communication the receiver will 'listen' on a predefined pipe address and the transmitter will 'send' to the same predefined address.\n\nFor a two-way communication to be possible the transmitter reading pipe needs to be the same to the receiver writing pipe and vice versa. This two cross-pipe configuration enable seamless two-way transmissions.\n\nnRF24 library provide 5 available reading pipes to listen numbered from 1 to 5.\n\n\u003e__caveat__:\n\u003e First Reading pipe registered can have any valid address (pipe 1). Pipes 2-5 addresses __must__ have the same first bytes equal to the 1st reading pipe and can only change the last byte of the address.\n\n\n\n*parameters*:\n\n| parameter | description |\n| --------- | ----------- |\n| addr      | a **string** with the hexadecimal format \"0x#######\". If the radio is configured with AddressWidth=5 the string must have 12 char. if AddressWidth=4 10 chars and if AddressWidth=3 8 chars. |\n| auto_ack (optional) | true/false nRF24 support to send ACK to the transmitter by the hardware. |\n\nif auto_ack is not provided the default value provided in *config* will be used.\n\n*Example*:\n```javascript\nrf24.begin();\nvar pipenr=rf24.addReadPipe(\"0xABCD11FF55\");\nif(pipenr==-1) console.log(\"Error!!!\");\nelse console.log(\"Pipe opened\" + pipenr);\n...\n\n```\n*Returns*: (number) -1= No pipe is available. 1-5 number of pipe opened to read.\n\n*Throws*: SyntaxError if parameters are invalid.\n\n\n#### removeReadPipe(pipenr)\nDeregister a pipe to read from. This function can be used to reconfigure close reading pipes registered with addReadPipe.\n\n*parameters*:\n\n| parameter | description |\n| --------- | ----------- |\n| pipenr    | pipe number descriptor returned by addReadPipe   |\n\n*returns:* nothing\n\n*throws:* SyntaxError if parameters are invalid.\n\n#### changeReadPipe(pipenr,auto_ack,maxmerge)\nChange the configuration of the a reading pipe. It should be called after ``addReadPipe`` **only**.\n\n*parameters*:\n\n| parameter | description |\n| --------- | ----------- |\n| pipenr    | pipe number descriptor returned by addReadPipe   |\n| auto_ack  | true/false nRF24 support to send ACK to the transmitter by the hardware. |\n| maxmerge  | Maximum number of frames to merge in a single read event on the pipe. |\n\n maxmerge is special parameter that can be used in streaming use cases. This parameter inform the reading loop that the user will accept *merging* consecutive frames on the pipe (up to the maximum number of frames specified). __Note__ that this value is maximum value and do not guaranteed that the incoming frames will be merged.\n\n*example:*\n\n```javascript\n\nvar pipenr=rf24.addReadPipe(\"0xABCD11FF55\");\nif(pipenr\u003e0) {\n   rf24.changeReadPipe(pipenr,false,10);\n   // Disble Ack and allow the libray to merge up to 10 consecutive frames on the pipe.\n}\n\n\n```\n\n *returns:* nothing.\n\n *throws:* SyntaxError if parameters are not valid.\n\n#### read(rcv_callback,stop_callback)\nRegister async callback for receiving information over the radio. This will enable the radio to receive frames from other radios. Reading pipes registered via addReadPipe will be used.\n\n__Note:__ Have in mind that read callback is unique for all pipes and is not possible to register several call-backs. If read is called multiple times only the first one will used. To register another callback ```stop_read()``` must be called and then another call to ```read()``` will be successful.\n\n*parameters*:\n\n| parameter | description |\n| --------- | ----------- |\n| rcv_callback  |  function(array data, int items)  that will called back on reception of any valid frame from the radio.|\n| stop_callback   | function(bool stopped,bool by_user, int error_count) that will be called back when by some reason we have stopped listening.    |\n\nboth parameters are mandatory.\n\n\u003e __caveat__: This API has change from previous verions. Now it allow to perform only one callback for all pending packets at once. This will increase the performance of the library reducing the number of callbacks to the js userland.\n\n*example*:\n\n```javascript\nrf24.begin();\nvar pipe1=rf24.addReadPipe(\"0xABCD11FF55\");\nvar pipe2=rf24.addReadPipe(\"0xABCD11FF56\");\n\nrf24.read( function (data,items) {\n  for(var i=0;i\u003citems;i++) {\n    if(data[i].pipe==pipe1) {\n      // received from 0xABCD11FF55\n      // data[i].data will contain a buffer with the data\n    ...\n  }else if (data[i].pipe == pipe2) {\n    // rcv from 0xABCD11FF56\n    }\n  }\n},\nfunction(stop,by_user,err_count) {\n  ...\n});\n\n```\n\n*returns*: nothing\n\n*Throws:*: SyntaxError if parameters are invalid.\n\n#### stopRead()\nStop listening for radio frames from the radio. This function is intended halt any further reading, however, as read mechanism is async it is possible that any pending read is delivered to reading callback. After successful halt of reading operation a ``` stop_callback ``` will be called, at this point no further frames will be received in ```rcv_callback ```.\n\nThis function will take more than 200ms to complete blocking your JS code. Therefore it should be used mainly to shut down communication not being designed for switching purposes.\n\nThis function is also called automatically upon object destruction.\n\n__Note: To send frames is NOT needed to stop reading.__\n\n*parameters:* none.\n\n*example:*\n\n```javascript\n...\nrf24.read( ... , ... );\n\n// At this point rcv_callback is called once a frame is received.\n\n...\n// other code\n...\n\n// Stop reading\nrf24.stopRead();\n\n```\n\n*returns:* nothing.\n\n*throws:* nothing.\n\n#### useWritePipe(addrs,auto_ack=default_value)\nDefine the output pipe to write to. __nRF24L01__ have only one output pipe with\npipe number *0*. This call is the counter part of *addReadPipe* in the transmitter side.\nAll comments about pipes explained there applies also to this pipe.\n\n*parameters*:\n\n| parameter | description |\n| --------- | ----------- |\n| addr      | a **string** with the hexadecimal format \"0x#######\". If the radio is configured with AddressWidth=5 the string must have 12 char. if AddressWidth=4 10 chars and if AddressWidth=3 8 chars. |\n| auto_ack (optional) | true/false nRF24 support to wait to ACK from the transmitter by the hardware. |\n\nif auto_ack is used the default value provided in *config* will be used.\n\n*Example*:\n\n```javascript\nrf24.begin();\nrf24.useWritePipe(\"0xABCD11FF55\");\n...\nrf24.write(...) // This will be written to '0xABCD11FF55'\n\n```\n\n*Returns*: nothing\n\n*Throws*: SyntaxError if parameters are invalid.\n\n#### changeWritePipe(auto_ack,stream_maxsize)\nChanges write pipe configuration. This API **must** be called after ``useWritePipe``.\n\n*parameters*:\n\n| parameter | descripton |\n| --------- | ---------- |\n| auto_ack  | true/false nRF24 support to wait to ACK from the transmitter by the hardware |\n| stream_maxsize | Maximum size in bytes of buffer in stream mode.\n\nThe maximum buffer is reset to a default value of ``1204`` bytes after calling to ``useWritePipe`` so to change it this function must be called every time the writting pipe is changed. Note also that the ``write()`` function ignores the parameter ``stream_maxsize`` and it will be only applicable using the ``stream()`` API (see below).\n\n*returns*: Nothing\n\n*throws:* SyntaxError if parameters are invalid.\n\n#### write(buffer,wr_callback *optional*)\nSend data over the radio in sync or async mode. If sync mode used ``wr_callback`` function must not be provided but the execution of JS code will block until transfer is finished. This could take up to 4ms for a 32 byte frame that could be acceptable or not depending on the use-case.\n\n*parameters*:\n\n| parameter | description |\n| ----------| ----------- |\n| buffer    | node js buffer with the data to transmit. |\n| wr_callback| callback function for async write |\n\nif buffer size is \u003e Payload size the call will not fail but only the bytes in the buffer that fit in one frame will be transmitted.\n\nwr_callback is a regular js callaback with the following parameters:\n- success: true/false\n- tx_ok: number of frames transmitted ok.\n- tx_bytes: number of bytes transmitted ok.\n- tx_req: number of frames requested to transmit.\n- frame_size: size of the frame in bytes\n- abort: true/false if the transmission was aborted by user.\n\n*example*:\nsync mode:\n\n```javascript\nif(rf24.write(Buffer.from(\u003cdata\u003e)))\n    console.log(\"WR OK!\");\nelse\n    console.log(\"Failed!\");\n\n```\n\nasyc mode:\n\n```javascript\nrf24.write(Buffer.from(\u003cdata\u003e),function(success,...){\n  if(success) console.log(\"WR OK!\"); else console.log(\"Failed!\");\n});\n```\n\n*returns*: true/false success for sync write.\n           true/false async job successfully created.\n\n*throws*: SyntaxError if parameters are invalid.\n\n#### stream(buffer,wr_callback)\nStream has the same semantics of write but it has its differences:\n\n- Stream can send bigger buffers. Up to the size defined in ``stream_maxsize`` parameter of the ``changeWritePipe`` API call.\n- Stream is async **only**.\n- If auto ACK is enabled if any frame in the stream failed(after predefined retries) the whole buffer will be fail. This mean that the receiver will receive frames until the first fail.\n\n*parameters:*\n\n| parameters | description |\n| ---------- | ----------- |\n| buffer     | nodejs buffer with the data. If buffer is bigger than ``stream_maxsize`` the call will not fail but only the ``stream_maxsize`` will be transmitted. |\n| wr_callback | callback function for async write |\n\n``wr_callback`` has the same specification of write function.\n\n*example*:\n```javascript\nrf24.changeWritePipe(true,2048); // Set max stream size to 2Kb\nvar big_buffer=Buffer.from(\u003cdata_up_to_2K\u003e);\nrf24.stream(big_buffer,function(success,tx_ok,tx_bytes,tx_req,frame_size,aborted) {\n  if(success) console.log(\"Stream ok\");\n  else {\n    console.log(\"Transfered:\"+tx_bytes+ \" total:\" + tx_req + \" OK-\u003e\" + tx_ok);\n  }\n});\n```\n\n*returns*: true/false async job successfully created.\n\n*throws*: SyntaxError if parameters are invalid.\n\n#### stopWrite()\nAbort any pending async write. If the transmission has been already started the write will not be aborted, only pending writes.\n\nIf write is aborted by the parameter ``abort`` in the write/stream callback functions will be ``true``.\n\n*returns*: Nothing.\n*throws*: Nothing.\n\n#### hasFailure()\nGet a boolenan indicator if failure has been detected in the radio. (**This is experimental feautre**)\n\n*returns*: true/false \n*throws*: Nothing\n\n### restart()\nReinit the radio maintaining the configuration and open pipes. Calling this funcion after detecting a failure may reset the de radio\nand enable graceful recovery of comunications. (**This is experimental feature**)\n\n*returns*: nothing\n*throws*: nothing\n\n#### getStats(*optional* pipe)\nGet internal transfer stats. *#* represents the number of frames received or transmitted.\n\nIf pipe is not provided the follwing object is returned:\n```javascript\nrf24.getStats();\n// =\u003e { TotalRx: # , TotalTx_Ok: # , TotalTx_Err: # , PipesRx:[#,#,...] , Failure: # }\n\n```\n\nif pipe=0 the stats retuned are those of the writing pipe with the follwing format:\n```javascript\nrf24.getStats(0);\n//=\u003e{  TotalTx_Ok: # ,TotalTx_Err: # }\n```\nif pipe \u003e0 \u0026\u0026 \u003c5 a number with the number of frames received is returned.\n```javascript\nrf24.getStats(pipe)\n// =\u003e #\n```\n\n*returns*: number of frames recevied if pipe\u003e1, if pipe=0 or not provided object with the stats.\n\n*throws*: Nothing.\n\n#### resetStats(*optional* pipe)\nReset to 0 internal transfer stats. if pipe is not selected all stats will be\ncleared.\n\n| parameter | description |\n| ----------| ----------- |\n|  pipe | pipe nr to reset if not set all pipes will be cleared. pipe=0 write pipe / pipe=RF24_FAILURE_STAT reset failure counter  |\n\n*returns*: nothing.\n*throws*: nothing.\n\n## RF24Mesh API\n\nTODO\n\n## RF24Gateway API\n\nTODO\n\n\n# TODO\n\n- ~~Assure RF24Lib is built with FAILURE_HANDLING~~\n- ~~Implement FAILURE_HANDLING auto-recovery.~~\n- ~~Implement FAILURE stats.~~\n- ~~Test bindings~~\n- ~~Migrate to NAN \u003e2.8 to support queued async msg passing.~~\n- ~~Implement setWriteAck for write pipe.~~\n- ~~Change build script to not install globally the libraries (.so) in the system and link them locally inside the package (rpath)~~\n- Implement MeshStats and non blocking behavior for begin,nodeID and Send.\n- Remove try_abort hack on mesh and gateway.\n- Refactor Mesh for async only API\n- Document Mesh\n- Document Gateway.\n- ~~Get rid off try_abort hack (pending nRF24 lib release)~~\n- ~~Benchmark transfer speeds.~~\n- Implement CPU-friendly streaming (pending nRF24 lib release)\n- ~~Implement IRQ management.~~\n- ~~Benchmark IRQ performance.~~ -\u003e Will respond on 300-400us basis. (1-2 retries)\n- ~~Implement traffic stats~~\n- ~~Update base RF24 library to new verions (1.3.3 \u0026 1.3.4 do not work)\n- ~~Distribute arm32 \u0026 arm64 prebuilds with prebuidify~~\n\n# Change log\n\n- V0.2.0-beta\n  - Bump base library versions to RF24_VERSION=\"v1.4.2\", RF24N_VERSION=\"v1. 0.16\" and RF24M_VERSION=\"v1.1.6\" \n  - optimize configuration function.\n  - Now requires nodejs \u003e=12.\n  - Includes precompiled binaries for Node 12,14,16 in platforms arm32 \u0026 arm64.\n\n- v0.1.6-beta\n  - Bump of base libraries to version 1.3.9 (RF24), 1.0.13 (RF24N) , 1.1.3(RF24M) #20\n  - Speed of SPI interface is now configurable in the constructor. #15\n  - Now the module is tested to compile against node versions 10, 12, 14 on arm32 and arm64 environments.\n  - Fix compilation on node version 8 \n  - Added EnableLna for better support radio boards with amplifiers and Si24R1 clones.\n  - Some doc improvements\n\n- v0.1.5-beta\n  - Now RFLibs are linked statically avoiding to install library system-wide.\n  - Improved documentation + added experimental support for autoRecovery.\n  - Now the library is compatible and tested with node lts versions: 8 , 10 , 12\n  - Added travis automatic build to test compilation in all supported node versions.\n  - Fixes in v8 data conversion using isolates and Nan helpers.\n  - As nan-marshal is not updated the module do not depend on this module anymore: Nan-marshal code is include with the project as a header file and has been adpated to have compativility with node 10 and 12.\n- v0.1.4-beta\n  - Fix build pull request #14\n- v0.1.2-beta\n  - Bump to version of mesh library to 1.0.7 (#12)\n- v0.1.1-beta\n  - Documentation improvements\n  - Compilation of RFLibs to specific releases to assure stability\n  - Force compilitation of RF24Lib with FAILURE_HANDLING activated.\n  - Refactor IRQ management.\n  - Added new Api ```hasFailure```\n  - ```getStats``` \u0026 ```resetStats``` report failure detection stats.\n- v0.1.0-beta\n  - Documentation improvements.\n  - Make nrf24 objects persistent with Ref(). Added destroy() method to Unref() and free object.\n  - IRQ Line support.\n  - Implement basic RF24 statistics.\n  - Polling time can be configured via ``config``\n  - Configure TxDelay via ``config``\n  - Implement async write and steam write.\n  - __This Release include breaking changes in read API__\n\n\n- v0.0.0-alpha4\n  - Documentation improvements.\n  - Basic RF24 additional Testing\n  - Migrated to NAN 2.10.0: Async workers now are queued so no data loss in nodejs.\n  - Cleaned RF24Mesh for after testing.\n  - Test/Example modification to arduino RF24 common pins.\n  - Added License\n\n\n- v0.0.0-alpha3\n  - Include bindings package to resolve package name\n  - Basic RF24 Working stable.\n  - RF24Mesh in testing.\n  - RF24Gateway in development.\n\n\n- v0.0.0-alpha1 \u0026 2 versions: Initial implementation of Basic Radio.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fludiazv%2Fnode-nrf24","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fludiazv%2Fnode-nrf24","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fludiazv%2Fnode-nrf24/lists"}