{"id":21101173,"url":"https://github.com/crycode-de/node-radiohead-serial","last_synced_at":"2025-05-16T18:34:23.769Z","repository":{"id":42535745,"uuid":"323855378","full_name":"crycode-de/node-radiohead-serial","owner":"crycode-de","description":"Node.js bindings for the serial driver of the RadioHead library, useful to build reliable networks based on e.g. RS485 or radio.","archived":false,"fork":false,"pushed_at":"2024-04-26T13:38:37.000Z","size":562,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-09-28T00:17:00.973Z","etag":null,"topics":["nodejs","npm-package","radiohead"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crycode-de.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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":{"github":["crycode-de"],"custom":["https://www.paypal.me/petercrycode"]}},"created_at":"2020-12-23T09:11:45.000Z","updated_at":"2024-04-26T13:38:01.000Z","dependencies_parsed_at":"2024-04-26T14:50:17.680Z","dependency_job_id":null,"html_url":"https://github.com/crycode-de/node-radiohead-serial","commit_stats":{"total_commits":122,"total_committers":3,"mean_commits":"40.666666666666664","dds":0.3770491803278688,"last_synced_commit":"0a5b5d08fce59e179ef894e7f76318b0fe406387"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crycode-de%2Fnode-radiohead-serial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crycode-de%2Fnode-radiohead-serial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crycode-de%2Fnode-radiohead-serial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crycode-de%2Fnode-radiohead-serial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crycode-de","download_url":"https://codeload.github.com/crycode-de/node-radiohead-serial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225444760,"owners_count":17475353,"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":["nodejs","npm-package","radiohead"],"created_at":"2024-11-19T23:41:13.414Z","updated_at":"2024-11-19T23:41:14.307Z","avatar_url":"https://github.com/crycode-de.png","language":"TypeScript","funding_links":["https://github.com/sponsors/crycode-de","https://www.paypal.me/petercrycode"],"categories":[],"sub_categories":[],"readme":"# radiohead-serial\n\n[![NPM version](https://img.shields.io/npm/v/radiohead-serial.svg)](https://www.npmjs.com/package/radiohead-serial)\n[![Downloads](https://img.shields.io/npm/dm/radiohead-serial.svg)](https://www.npmjs.com/package/radiohead-serial)\n\n[![NPM](https://nodei.co/npm/radiohead-serial.png?downloads=true)](https://nodei.co/npm/radiohead-serial/)\n\n**Tests:** ![Test and Release](https://github.com/crycode-de/node-radiohead-serial/workflows/Test%20and%20Release/badge.svg)\n\nCommunication between some **RadioHead** nodes and **Node.js** using the *RH_Serial* driver and the *RHReliableDatagram* or *RHDatagram* manager of the RadioHead library.\n\nWith `radiohead-serial` you can build reliable networks based on serial hardware (e.g. RS485 or RS232) between multiple different devices like regular computers, minicomputers (e.g. Raspberry Pi) and microprocessors (e.g. Arduino). It is also possible to include radio hardware using a microprocessor (e.g. an Arduino nano) as a serial-radio gateway.\n\n[RadioHead](http://www.airspayce.com/mikem/arduino/RadioHead/) is a Packet Radio library for embedded microprocessors.\n\u003e RH_Serial works with RS232, RS422, RS485, RS488 and other point-to-point and multidropped serial connections, or with TTL serial UARTs such as those on Arduino and many other processors, or with data radios with a serial port interface. RH_Serial provides packetization and error detection over any hardware or virtual serial connection.\n\n\u003e RHReliableDatagram provides Addressed, reliable, retransmitted, acknowledged variable length messages.\n\nBased on RadioHead library *1.92 2019-07-14*.  \nShould also work together with newer versions of the RadioHead library.\n\nSince Version 3 this module is based on a TypeScript/JavaScript port of the native RadioHead library.\n\nThis module can be used on any Linux, Mac or Windows system, for example a Raspberry Pi with Raspbian or a regular computer.\n\n**Hint:** Version 5 of `radiohead-serial` requires Node.js version 16 or higher.\n\nCurrently tested with Node.js versions *16.x*, *18.x*, *20.x*.\n\n## Example scenario for using radiohead-serial\n\nThe radiohead-serial module is perfect if you want to build your own bus system based on for example RS485.\n\nAs a head station you can use a Raspberry Pi minicomputer with a USB-RS485 adapter.\nThe other nodes on the bus can be some microprocessors (e.g. ATMega8 or Arduino) with an TTL-RS485 converter (e.g. Max485) connected.\nIn addition using a serial-radio gateway is possible (see below).\n\n## Using other RadioHead drivers with a serial-radio gateway\n\nIf you want to use other RadioHead drivers (for example *RH_ASK*), you can simply use an Arduino nano ($2 to $10) as an serial gateway.\nOther microprocessors can be used too.\n\nConnect your radio hardware to the Arduino and upload the `rh_serial_ask_gateway` sketch. Some example sketches are included in the [*examples*](https://github.com/crycode-de/node-radiohead-serial/tree/master/examples) directory.\nThe Arduino will act as a gateway between the serial and the radio network.\n\nOptionally the gateway can filter messages, so that only a specific address range is transmitted through the radio network.\n\n## Installation\n\nTo install the latest version simply use:\n\n```sh\nnpm install radiohead-serial\n```\n\n## Examples\n\nThe examples blow can be found in the [*examples*](https://github.com/crycode-de/node-radiohead-serial/tree/master/examples) directory of this package together with TypeScript examples and a gateway Arduino sketch.\n\nThe examples assume a Linux system with two USB-RS485 adapters connected.\nThe A and B lines of the RS485 are connected between both adapters.\nYou can also use two machines with respectively one adapter.\n\nDepending on your system you may have to change the used ports (/dev/ttyUSB0) in the examples.\n\nIf you want to use ES6 style imports you can use\n\n```ts\nimport { RadioHeadSerial } from 'radiohead-serial';\n```\n\n### A server replying to messages sent by clients\n\n```js\n// Require the radiohead-serial module\nvar RadioHeadSerial = require('radiohead-serial').RadioHeadSerial;\n\n// Create an instance of the RadioHeadSerial class\nvar rhs = new RadioHeadSerial({\n  port: '/dev/ttyUSB0', // COM1 on Windows\n  baud: 9600,\n  address: 0x01\n});\n\n// Listen to the 'data' event for received messages\nrhs.on('data', function(message){\n  // Print the received message object\n  console.log('-\u003e recv:', message);\n\n  // Convert the decimal from address to hex\n  var sender = ('0' + message.headerFrom.toString(16)).slice(-2).toUpperCase();\n\n  // Print a readable form of the data\n  if(message.length \u003e 0){\n    console.log('-\u003e received ' + message.length + ' bytes from 0x' + sender + ': \"' + message.data.toString() + '\"');\n  }\n\n  // Create the answer for the client\n  var answer = new Buffer('Hello back to you, client!');\n\n  // Send the answer to the client\n  rhs.send(message.headerFrom, answer).then(function(){\n    // Message has been sent successfully\n    console.log('\u003c- sent to 0x' + sender + ': \"' + answer.toString() + '\" Raw:', answer);\n  }).catch(function(error){\n    // Error while sending the message\n    console.log('\u003c- ERROR', error);\n  });\n});\n\n// Print some info\nconsole.log('Server example running.');\nconsole.log('Now start the client example...');\n```\n\n### A client sending messages to a server\n\n```js\n// Require the radiohead-serial module\nvar RadioHeadSerial = require('radiohead-serial').RadioHeadSerial;\n\n// Create an instance of the RadioHeadSerial class\nvar rhs = new RadioHeadSerial({\n  port: '/dev/ttyUSB1', // COM2 on Windows\n  baud: 9600,\n  address: 0x02\n});\n\n// Listen on the 'data' event for received messages\nrhs.on('data', function(message){\n  // Print the received message object\n  console.log('-\u003e recv:', message);\n\n  // Convert the decimal from address to hex\n  var sender = ('0' + message.headerFrom.toString(16)).slice(-2).toUpperCase();\n\n  // Print a readable form of the data\n  if(message.length \u003e 0){\n    console.log('-\u003e received ' + message.length + ' bytes from 0x' + sender + ': \"' + message.data.toString() + '\"');\n  }\n});\n\n// Counter for the number of send messages\nvar sentCount = 0;\n\n// Function to send a message (calls itself with a timeout until five messages are sent)\nfunction sendData(){\n  // Create the data to be send to the server\n  var data = new Buffer('Hello server!');\n\n  // Send the data to the server\n  rhs.send(0x01, data).then(function(){\n    // Message has been sent successfully\n    console.log('\u003c- sent to 0x01: \"' + data.toString() + '\" Raw:', data);\n\n  }).catch(function(error){\n    // Error while sending the message\n    console.log('\u003c- ERROR', error);\n\n  }).finally(function(){\n    // After sending the message, even if failed\n    sentCount++;\n\n    // 5 times sent?\n    if(sentCount \u003c 5){\n      // Send a new message after 2 seconds\n      setTimeout(sendData, 2000);\n    }else{\n      // Close the SerialPort worker after 1 second and exit the client example\n      // Use the timeout before close() to receive the answer from the server\n      setTimeout(function(){\n        rhs.close().then(function(){\n          // The SerialPort is now closed\n          console.log('Client example done. :-)');\n        });\n      }, 1000);\n    }\n  });\n}\n\n// Trigger sending the first message\nsendData();\n\n// Print some info\nconsole.log('Client example running.');\nconsole.log('I\\'ll try to send hello to the Server five times...');\n```\n\n## APIv3\n\n*The current APIv3 uses **Events** and **Promises** and has some breaking changes against the old APIv1.*\n\nReceiving and sending of messages is always done asynchronous.\n\nTypeScript typings are included in the package.\n\n### RadioHeadSerial(options: RadioHeadSerialOptions)\n\n```ts\nconstructor (options: RadioHeadSerialOptions);\n```\n\nConstructor of the RadioHeadSerial class using an options object.\nLoads and initializes the RadioHead driver and manager.\n\n*This is the preferred way to create a new instance of the RadioHeadSerial class since v4.1.0*\n\n#### RadioHeadSerialOptions\n\n```ts\n{\n  port: string;\n  baud: number = 9600;\n  address: number = 1;\n  reliable: boolean = true;\n  autoInit: boolean = true;\n}\n```\n\nObject containing the options for a new RadioHeadSerial instance.\n\n* `port` - The serial port/device to be used for the communication. For example /dev/ttyUSB0 or COM1.\n* `baud` - *Optional* The baud rate to be used for the communication. Supported are 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400. (default 9600)\n* `address` - *Optional* The address of this node in the RadioHead network. Address range goes from 1 to 254. (default 1)\n* `reliable` - *Optional* false if RHDatagram should be used instead of RHReliableDatagram. (default true)\n* `autoInit` - *Optional*  false if the manager/serial port should not be initialized automatically. If false you have to call instance.init() manually. (default true)\n\n### RadioHeadSerial(port, baud, address, reliable)\n\n```ts\nconstructor (port: string, baud: number = 9600, address: number = 1, reliable: boolean = true);\n```\n\nConstructor of the RadioHeadSerial class using sinle arguments.\nLoads and initializes the RadioHead driver and manager.\n\n* `port` - The serial port/device to be used for the communication. For example /dev/ttyUSB0 or COM1.\n* `baud` - *Optional* The baud rate to be used for the communication. Supported are 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400. (default 9600)\n* `address` - *Optional* The address of this node in the RadioHead network. Address range goes from 1 to 254. (default 1)\n* `reliable` - *Optional* false if RHDatagram should be used instead of RHReliableDatagram. (default true)\n\n### rhs.init()\n\n```ts\ninit (): Promise\u003c{}\u003e;\n```\n\nInitializes the manager and the serial port if options.autoInit was false on construction of the class.  \nReturns a promise which will be resolved if the serial port is opened and the manager is initialized or rejected in case of an error.  \nMay be called multiple times to re-init the serial port on errors.\n\n### rhs.isInitDone()\n\n```ts\nisInitDone (): boolean;\n```\n\nReturns if the init is done (`true`) or not (`false`).\n\n### rhs.close()\n\n```ts\nclose (): Promise\u003c{}\u003e;\n```\n\nCloses the serial port.\nAfter close() is called, no messages can be received.\nReturns a promise which will be resolved if the serial port is closed.\n\n### rhs.send(to, data, length)\n\n```ts\nsend (to: number, data: Buffer, length?: number): Promise\u003c{}\u003e;\n```\n\nSends a message through the RadioHead network.\nReturns a Promise which will be resolved when the message has been sent, or rejected in case of an error.\n\n* `to` - Recipient address. Use 255 for broadcast messages.\n* `data` - Buffer containing the message to send.\n* `length` - *Optional* number of bytes to send from the buffer. If not given the whole buffer is sent. The maximum length is 60 bytes.\n\n### rhs.setAddress(address)\n\n```ts\nsetAddress (address: number): void;\n```\n\nSets the address of this node in the RadioHead network.\n\n* `address` - The new address. Address range goes from 1 to 254.\n\n### rhs.thisAddress()\n\n```ts\nthisAddress (): number;\n```\n\nReturns the address of this node.\n\n### rhs.setRetries(count)\n\n```ts\nsetRetries (count: number): void;\n```\n\nSets the maximum number of retries.\nDefaults to 3 at construction time.\nIf set to 0, each message will only ever be sent once.\n\n* `count` - New number of retries.\n\n### rhs.getRetries()\n\n```ts\ngetRetries (): number\n```\n\nReturns the currently configured maximum retries count.\n\n### rhs.setTimeout(timeout)\n\n```ts\nsetTimeout (timeout: number): void;\n```\n\nSets the minimum retransmit timeout in milliseconds.\nIf an ack is taking longer than this time, a message will be retransmitted.\nDefault is 200.\n\n* `timeout` - New timeout in milliseconds.\n\n### rhs.getRetransmissions()\n\n```ts\ngetRetransmissions (): number;\n```\n\nReturns the number of retransmissions we have had to send since starting or since the last call to resetRetransmissions().\n\n### rhs.resetRetransmissions()\n\n```ts\nresetRetransmissions (): void;\n```\n\nResets the count of the number of retransmissions to 0.\n\n### rhs.setPromiscuous(promiscuous)\n\n```ts\nsetPromiscuous (promiscuous: boolean): void;\n```\n\nTells the receiver to accept messages with any to address, not just messages addressed to this node or the broadcast address.\n\n* `promiscuous` - true if you wish to receive messages with any to address. (default false)\n\n### rhs.on('data', function(receivedData){ })\n\n```ts\nrhs.on('data', (message: RH_ReceivedMessage) =\u003e { /* do something */ });\n```\n\nThe `data` event is emitted for every received message and includes an object with the following information.\n\n* `data` - The received data as a Buffer.\n* `length` - The length of the received data.\n* `headerFrom` - The from address of the received message.\n* `headerTo` - The to address of the received message.\n* `headerId` - The id of the received message.\n* `headerFlags` - The flags of the received message.\n\n### rhs.on('error', function(err){ })\n\n```ts\nrhs.on('error', (err: Error) =\u003e { /* do something */ });\n```\n\nThe `error` event is emitted if there is an error with the driver.\n\n* `err` - The error.\n\n### rhs.on('close', function(){ })\n\n```ts\nrhs.on('close', () =\u003e { /* do something */ });\n```\n\nThe `close` event is emitted if the serial port is closed.\nThis may be intended by calling `rhs.close()` or caused by any port failure.\n\n### Exported Constants\n\n#### version\n\nThe actual version of the module.\n\n#### RH_SERIAL_MAX_MESSAGE_LEN = 60\n\nThe maximum supported message length.\nThis is the maximum size for a Buffer used for sending or receiving messages.\n\n## Advanced usage\n\n`radiohead-serial` also exports classes `RH_Serial`, `RHDatagram` and `RHReliableDatagram` and some additional constants.\nThey represent the same classes from the native RadioHead library.\nYou can use them to create custom implementations.\n\nFor more information see [ADVANCED_USAGE.md](https://github.com/crycode-de/node-radiohead-serial/blob/master/ADVANCED_USAGE.md)\n\n## License\n\nLicensed under GPL Version 2\n\nCopyright (c) 2017-2024 Peter Müller \u003cpeter@crycode.de\u003e (https://crycode.de/)\n\nThe RadioHead library is Copyright (C) 2008 Mike McCauley.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrycode-de%2Fnode-radiohead-serial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrycode-de%2Fnode-radiohead-serial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrycode-de%2Fnode-radiohead-serial/lists"}