{"id":15362970,"url":"https://github.com/daawesomep/node-upb","last_synced_at":"2026-02-14T07:30:49.317Z","repository":{"id":24293218,"uuid":"27688313","full_name":"DaAwesomeP/node-upb","owner":"DaAwesomeP","description":"Generate and decode UPB (Universal Powerline Bus) commands","archived":false,"fork":false,"pushed_at":"2021-07-02T18:09:55.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-30T01:36:55.382Z","etag":null,"topics":["home-automation","javascript","library","nodejs","upb"],"latest_commit_sha":null,"homepage":"https://www.npmjs.org/package/upb","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaAwesomeP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-07T23:05:36.000Z","updated_at":"2021-07-02T18:09:58.000Z","dependencies_parsed_at":"2022-08-22T06:20:08.641Z","dependency_job_id":null,"html_url":"https://github.com/DaAwesomeP/node-upb","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaAwesomeP%2Fnode-upb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaAwesomeP%2Fnode-upb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaAwesomeP%2Fnode-upb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaAwesomeP%2Fnode-upb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaAwesomeP","download_url":"https://codeload.github.com/DaAwesomeP/node-upb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245550599,"owners_count":20633874,"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":["home-automation","javascript","library","nodejs","upb"],"created_at":"2024-10-01T13:04:24.936Z","updated_at":"2026-02-14T07:30:49.289Z","avatar_url":"https://github.com/DaAwesomeP.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"node-upb [![Gitter chat](https://img.shields.io/gitter/room/DaAwesomeP/node-upb.js.svg?maxAge=2592000\u0026style=flat-square)](https://gitter.im/DaAwesomeP/node-upb)\n========\n[![npm](http://img.shields.io/npm/v/upb.svg?style=flat-square)](https://www.npmjs.org/package/upb) [![npm](http://img.shields.io/npm/dm/upb.svg?style=flat-square)](https://www.npmjs.org/package/upb) [![bower](http://img.shields.io/bower/v/upb.svg?style=flat-square)](https://github.com/DaAwesomeP/node-upb) [![david](https://img.shields.io/david/DaAwesomeP/node-upb.svg?style=flat-square)](https://david-dm.org/DaAwesomeP/node-upb) [![Travis](https://img.shields.io/travis/DaAwesomeP/node-upb.svg?maxAge=2592000\u0026style=flat-square)](https://travis-ci.org/DaAwesomeP/node-upb) [![Coveralls](https://img.shields.io/coveralls/DaAwesomeP/node-upb.svg?maxAge=2592000\u0026style=flat-square)](https://coveralls.io/github/DaAwesomeP/node-upb) [![license](http://img.shields.io/npm/l/upb.svg?style=flat-square)](https://github.com/DaAwesomeP/node-upb/blob/master/LICENSE)\n---\nA NodeJS, Bower, browser, AMD, and CommonJS (that includes RequireJS) library that generates and decodes UPB (Universal Powerline Bus) commands. **If you are looking for the CLI program that uses this, then please see [upb-cli](https://github.com/DaAwesomeP/upb-cli/).**\n\n**This has only been tested with Simply Automated switches!** While probably won't harm your device (it is sending control commands, not core commands), I'm not sure what will happen when this is used with other branded switches (like PCS).\n\n## Installation\n\n### Node\nInstall it to your project folder:\n```bash\nnpm install upb\n```\nThen include it in your file:\n```javascript\nvar upb = require(\"upb\");\n```\n\n### Browser\nEither download the package via [Bower](http://bower.io/) (package named `upb`) or download the [latest release](https://github.com/DaAwesomeP/node-upb/releases/latest) and include it in your page:\n```html\n\u003cscript type=\"text/javascript\" src=\"upb.js\"\u003e\u003c/script\u003e\n```\nUse it with the `upb` object. The examples below should work fine. There is a minified version in the `/dist/` folder or available for download from the releases page.\n\n## Usage\n\n### generate(command)\nThe function takes a JSON object input as `command` and returns a promise withg a new JSON object with more data (including the generated command) as the first argument of the callback function.\n\n**If you plan on making your own serial implementation using this, remember to put the PIM in message mode first and to proceed each UPB command with the ASCII #20 character and to end it with the ASCII #13 character.** Also, the PIM will automatically send the correct number of commands based on `sendx`. So, `sendTime` is only useful for displaying commands and not sending them.\n\n**Example:**\n```javascript\nupb.generate({\n  network: 21, \t\t\t\t// Required - Set Network ID. Use 0 for the global network (controls all devices)\n  id: 4,\t\t\t\t\t// Required - Set link or device ID\n  type: \"device\",\t\t\t// Required - Set whether to control a link or device\n  source: 255,\t\t\t\t// Optional - Set PIM source ID. Defaults to 255, which is almost always fine.\n  cmd: \"goto\",\t\t\t\t// Required - Set the command to send. You may also use the command numbers associated with those commands.\n  level: 75,\t\t\t\t// Optional - Set the level (percent). Accepts values 0 through 100. Required with goto and fade start. Only applies to goto, fadeStart, fadeStop, and toggle. Otherwise this will be ignored.\n  rate: 5,\t\t\t\t\t// Optional - Set the fade rate (seconds). Use false for instant on. Only applies to goto, fadeStart, and toggle. Otherwise  this will be ignored. Defaults to device settings.\n  channel: false, \t\t\t// Optional - Set the channel to use. Use false for default. Only applies to goto, fadeStart, blink, and toggle. Otherwise this will be ignored. Only works on some devices. Defaults to off (command not sent).\n  sendx: 2,\t\t\t\t\t// Optional - Set the number of times to send the command. Accepts numbers 1 through 4. Defaults to 1.\n  sendTime: 1,\t\t\t\t// Optional - Send the number of time this command is sent out of the total (sendx). NOTE: THE PIM WILL AUTOMATICALLY SEND THE CORRECT NUMBER OF COMMANDS! So, this is only useful for displaying commands and not sending them. Accepts numbers 1 through 4. Cannot be greater than sendx. Defaults to 1.\n  ackPulse: false,\t\t\t// Optional - Request an acknowledge pulse. Defaults to false.\n  idPulse: false, \t\t\t// Optional - Request an ID pulse. Defaults to false.\n  ackMsg: true,  \t\t\t// Optional - Request an acknowledge message. Defaults to false.\n  powerlineRepeater: false,\t// Optional - Request for the command to go through a powerline repeater. Set or numbers 1, 2, 4, or false. Defaults to false.\n  blinkRate: 255,\t\t\t// Optional - Set the blink rate (unknown unit). USE CAUTION WITH LOW NUMBERS! I am not sure what unit this is in. Accepts values 1 through 255. Required for blink. Only applies to blink. Otherwise this will be ignored.\n  toggleCount: 0,\t\t\t// Optional - Set the toggle count. Required for toggle. Only applies to toggle. Otherwise this will be ignored.\n  toggleRate: 5\t\t\t\t// Optional - Set the toggle rate. Only applies to toggle. Otherwise this will be ignored. Defaults to 0.5.\n}).then(function(commandNew) {\n  console.log(commandNew.generated);\t\t\t// 09441504FF224B0529\n  console.log(JSON.stringify(commandNew));\n  // {\"source\":255,\"sendx\":\"2\",\"ackPulse\":false,\"idPulse\":false,\"ackMsg\":true,\"powerlineRepeater\":false,\"sendTime\":1,\"network\":\"21\",\"id\":\"4\",\"type\":\"device\",\"cmd\":\"goto\",\"level\":\"75\",\"rate\":\"5\",\"ctrlWord\":{\"byte1\":0,\"byte2\":9,\"byte3\":4,\"byte4\":4},\"words\":9,\"hex\":{\"network\":\"15\",\"id\":\"4\",\"source\":\"ff\",\"msg\":\"22\",\"level\":\"4b\",\"rate\":\"5\",\"ctrlWord\":{\"byte1\":\"0\",\"byte2\":\"9\",\"byte3\":\"4\",\"byte4\":\"4\",\"fullByte1\":\"09\",\"fullByte2\":\"44\"}},\"msg\":22,\"generated\":\"09441504FF224B0529\",\"checksum\":\"29\"}\n}, function(err) {\n  throw err;\n});\n```\n\n### decode(command, callback)\nThe function takes a string input as `command` and returns a JSON object with data (including the original command) as the first argument of the callback function. The second argument of the callback function is for errors. **This does not verify the checksum.** However, it will throw errors for other problems in the command.\n\n**Example:**\n```javascript\nupb.decode('09441504FF224B0529').then(function(commandNew) {\n  console.log(JSON.stringify(commandNew));\n  // {\"source\":255,\"sendx\":2,\"sendTime\":1,\"ackPulse\":false,\"idPulse\":false,\"ackMsg\":true,\"powerlineRepeater\":0,\"hex\":{\"ctrlWord\":{\"fullByte1\":\"09\",\"fullByte2\":\"44\",\"byte1\":\"0\",\"byte2\":\"9\",\"byte3\":\"4\",\"byte4\":\"4\"},\"network\":\"15\",\"id\":\"04\",\"source\":\"FF\",\"msg\":\"22\",\"level\":\"4B\",\"rate\":\"05\"},\"generated\":\"09441504FF224B0529\",\"ctrlWord\":{\"byte1\":0,\"byte2\":9,\"byte3\":4,\"byte4\":4},\"type\":\"device\",\"words\":9,\"network\":21,\"id\":4,\"msg\":\"22\",\"cmd\":\"goto\",\"checksum\":\"29\",\"level\":75,\"rate\":5}\n}, function(err) {\n  throw err;\n});\n```\n\n### validCommands\nAn array of valid commands\n\n**Example:**\n```javascript\nconsole.log(JSON.stringify(upb.validCommands));\n// [20,\"20\",\"activate\",21,\"21\",\"deactivate\",22,\"22\",\"goto\",23,\"23\",\"fadeStart\",24,\"24\",\"fadeStop\",25,\"25\",\"blink\",26,\"26\",\"indicate\",27,\"27\",\"toggle\",30,\"30\",\"reportState\",31,\"31\",\"storeState\",80,\"80\",\"ackResponse\",85,\"85\",\"setupTimeReport\",86,\"86\",\"deviceStateReport\",87,\"87\",\"deviceStatusReport\",90,\"90\",\"registerValuesReport\",91,\"91\",\"RAMvaluesReport\",92,\"92\",\"rawDataReport\",93,\"93\",\"heartbeatReport\",143,\"143\",\"deviceSignatureReport\"]\n```\n\n### commands\nAn object of all commands\n\n**Example:**\n```javascript\nconsole.log(upb.commands);\n/* { activate: 20,\n     deactivate: 21,\n     goto: 22,\n     fadeStart: 23,\n     fadeStop: 24,\n     blink: 25,\n     indicate: 26,\n     toggle: 27,\n     reportState: 30,\n     storeState: 31,\n     ackResponse: 80,\n     setupTimeReport: 85,\n     deviceStateReport: 86,\n     deviceStatusReport: 87,\n     registerValuesReport: 90,\n     RAMvaluesReport: 91,\n     rawDataReport: 92,\n     heartbeatReport: 93,\n     deviceSignatureReport: 143 } */\n```\n\n### defaultCommand\nAn object with the optional defaults.\n\n**Example:**\n```javascript\nconsole.log(JSON.stringify(upb.defaultCommand));\n// {\"source\":255,\"sendx\":1,\"sendTime\":1,\"ackPulse\":false,\"idPulse\":false,\"ackMsg\":false,\"powerlineRepeater\":0}\n```\n\n## More Information\n\nI got most of the information the last three items listed on this Simply Automated page: [Tech Specs](http://www.simply-automated.com/tech_specs/). I also experimented with my serial terminal to see responses of other switches.\n\n - **UPB System Description** - This PDF describes all parts of the UPB protocol.\n - **UPB Command Wizard - Software** - This program lets you build commands with a wizard/GUI and see the result. It does not actually send the command, but it is very valuable for understanding the commands without reading too much of the above PDF.\n - **UPB Powerline Interface Module (PIM) - Description** - This PDF contains information about the PIM. It shows serial specifications (4800 baud 8-n-1) and PIM responses. It look me a while to figure out that the PIM always responds with `PE` whenever a command is not prefixed by the #20 character.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaawesomep%2Fnode-upb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaawesomep%2Fnode-upb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaawesomep%2Fnode-upb/lists"}