{"id":19072913,"url":"https://github.com/sombriks/node-libgpiod","last_synced_at":"2025-02-28T00:14:14.343Z","repository":{"id":39341576,"uuid":"322395352","full_name":"sombriks/node-libgpiod","owner":"sombriks","description":"libgpiod node bindings","archived":false,"fork":false,"pushed_at":"2024-08-31T06:18:44.000Z","size":304,"stargazers_count":31,"open_issues_count":7,"forks_count":10,"subscribers_count":4,"default_branch":"main-1x","last_synced_at":"2025-02-20T23:11:10.377Z","etag":null,"topics":["libgpiod","linux","nodejs","raspberrypi","raxdarock"],"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/sombriks.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":{"github":["sombriks","noctarius","dmitrydvorkin"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2020-12-17T19:40:31.000Z","updated_at":"2025-01-22T20:50:04.000Z","dependencies_parsed_at":"2023-11-21T15:29:24.894Z","dependency_job_id":"cc0a57f9-ce1e-480e-8657-49e68c0ea2d3","html_url":"https://github.com/sombriks/node-libgpiod","commit_stats":{"total_commits":78,"total_committers":4,"mean_commits":19.5,"dds":"0.20512820512820518","last_synced_commit":"8af9cc59b8ccc7461a38478e2c5bbd7b025daa7e"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sombriks%2Fnode-libgpiod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sombriks%2Fnode-libgpiod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sombriks%2Fnode-libgpiod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sombriks%2Fnode-libgpiod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sombriks","download_url":"https://codeload.github.com/sombriks/node-libgpiod/tar.gz/refs/heads/main-1x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241077884,"owners_count":19905746,"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":["libgpiod","linux","nodejs","raspberrypi","raxdarock"],"created_at":"2024-11-09T01:44:42.757Z","updated_at":"2025-02-28T00:14:14.315Z","avatar_url":"https://github.com/sombriks.png","language":"C++","funding_links":["https://github.com/sponsors/sombriks","https://github.com/sponsors/noctarius","https://github.com/sponsors/dmitrydvorkin"],"categories":[],"sub_categories":[],"readme":"# [node-libgpiod][repo]\n\nNative nodejs bindings for [libgpiod][libgpiod]\n\n[![npm](https://img.shields.io/npm/v/node-libgpiod?style=plastic)](https://www.npmjs.com/package/node-libgpiod)\n[![Build Status](https://github.com/sombriks/node-libgpiod/actions/workflows/node-test.yml/badge.svg?branch=main-1x)](https://github.com/sombriks/node-libgpiod/actions/workflows/node-test.yml)\n[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n## Requirements / Dependencies\n\n- libgpiod **1.x** (and devel headers)\n- nodejs (and devel headers)\n- linux (tested on fedora 33 running on raspberry pi model 3 B+ and rasp pi os on zero w)\n- c/c++ development tools\n\n## How to use into your project\n\nFirst install libgpiod and node development packages, if not installed yet:\n\n### RPM based\n\n```bash\n# fedora\nsudo dnf install libgpiod libgpiod-devel libgpiod-utils nodejs-devel\n```\n\n```bash\n# openSUSE\nsudo zypper in libgpiod libgpiod-devel libgpiod-utils nodejs-devel\n```\n\n### DEB based\n\n```bash\n# debian and its variants\nsudo apt install gpiod libgpiod2 libgpiod-dev libnode-dev\n```\n\nThen just add it as a regular nodejs dependency:\n\n```bash\nnpm i node-libgpiod\n```\n\n[node-gyp][node-gyp] will do the rest for you.\n\n## Tested platforms\n\n- [raspberry pi model 3 B+][rpi3b+] (64 bits, 1GB ram) running fedora\n- [raspberry pi zero w][rpi3zw] (32 bits, 512MB ram) running rasp pi os\n- [LTPPxG2][LTPPx62] with sp7021 SoC (32 bits, 512MB ram) running Yocto\n- [ROCK 5A][ROCK5A] (64 bits, 2GB ram), running debian\n- [ROCK 3C][ROCK3C] (64 bits, 2GB ram), running d\n\nTechnically speaking it should work with [any modern vanilla kernel][libgpiod]\nand **libgpiod 1.x**.\n\n## What about libgpiod 2.x?\n\nWe're still working on [libgpiod 2.x][libgpiod-2x]\n\n## Status\n\nWe already are able to read and write pins!\n\nHere goes the sample blink led hello-world.js:\n\n```javascript\nconst { version, Chip, Line } = require(\"node-libgpiod\");\n\nglobal.chip = new Chip(0);\nglobal.line = new Line(chip, 17); // led on GPIO17\nlet count = 10;\n\nconsole.log(version());\nline.requestOutputMode();\n\nconst blink = () =\u003e {\n  if(count){\n    line.setValue(count-- % 2);\n    setTimeout(blink,1000);\n  } // else line.release(); \n  // not needed, libgpiod releases resources on process exit  \n};\n\nsetTimeout(blink,1000);\n```\n\nAnother example:\n\n```javascript\nconst { version, Chip, Line } = require(\"node-libgpiod\");\nconst express = require(\"express\");\n\nconst app = express();\n// avoid chip and line being gc-collected\napp.chip = new Chip(0);\napp.line = new Line(app.chip, 17); // led on GPIO17\n\nconsole.log(version());\napp.line.requestOutputMode();\n\napp.get(\"/on\", (req,res) =\u003e {\n  app.line.setValue(1);\n  res.send(\"it's on\");\n});\n\napp.get(\"/off\", (req,res) =\u003e {\n  app.line.setValue(0);\n  res.send(\"it's off\");\n});\n\napp.listen(3000);\nconsole.log(\"running\");\n```\n\nSee our [testcases][test-suite] for more information\n\nSee [node-libgpiod-examples][examples]\nfor more sample code\n\n## known issues\n\n- libgpiod 2.x series is around the corner, and its API is incompatible with 1.x\n  the [2.x branch][libgpiod-2x] (under development) will handle 2.x while 0.x\n  and 1.x will support libgpiod 1.x series.\n\n- gpio character device needs [special udev rules][udev-rules] in order\n  to belong to a special group so non-root users could access it freely\n\n  ```bash\n  # /etc/udev/rules.d/85-gpiochip.rules \n  KERNEL==\"gpiochip*\", SUBSYSTEM==\"gpio\", MODE=\"0660\", GROUP=\"wheel\"\n  ```\n\n- libgpiod must be installed in the system correctly with development headers\n  otherwise npm install will fail.\n- inside libgpiod 1.x series there is a set of new flags created on 1.5.x\n  version around 2019 and they where no back ported to previous ones libgpiod\n  releases. Your build might break because of this, we're working on solve this.\n- node will garbage collect Chip and Line too early on certain cases. When\n  writing the samples, the following error kept being thrown:\n\n  ```bash\n  /home/sombriks/git/sample-node-libgpiod/index2.js:12\n      line.setValue(count-- % 2);\n          ^\n\n  Error: Unable to set value for this line\n      at Timeout.blink [as _onTimeout] (/home/sombriks/git/sample-node-libgpiod/index2.js:12:10)\n      at listOnTimeout (internal/timers.js:554:17)\n      at processTimers (internal/timers.js:497:7)\n  ```\n\n  It occurs because main module body was already evaluated and finished while\n  interval/timeout function still active, but has no local reference for Chip or\n  Line instances.\n  Therefore, v8 thinks that those objects can be garbage-collected releasing the\n  underlying resources, giving us the error.\n  To avoid this, make sure your objects will be present on function scope:\n\n  ```javascript\n  const { version, Chip, Line } = require(\"node-libgpiod\");\n\n  const chip = new Chip(0);\n  const line = new Line(chip, 17); // led on GPIO17\n  let count = 20;\n\n  console.log(version());\n  line.requestOutputMode();\n\n  const blink = function () {\n    // avoid early gc\n    this.chip = chip\n    this.line = line\n    if(count){\n      line.setValue(count-- % 2);\n      setTimeout(blink,500);\n    }\n  };\n\n  setTimeout(blink,500);\n  ```\n\n  Or, probably it is even better to create you chip and line instances globally:\n\n  ```javascript\n  global.mychip = new Chip(0);\n  global.line1 = new Line(chip, 17);\n  ```\n\n## Roadmap\n\n- [X] basic read/write\n- [X] basic instant read/write\n- [X] Chip/Line abstractions\n- [ ] GPIO monitoring callbacks\n- [ ] Bulk read/write\n- [ ] Complete API parity with underlying C/C++ library\n\nAll features present on libgpiod eventually will be added to node bindings, then\nthe node package will finally enter in 1.x series.\n\nAlso see our [changelog][changelog] and [project updates][project-updates] for \ndetails.\n\n## Functionality parity\n\nThis is the api parity table:\n\n| Description                                  | Scope         | C/C++                          | Node                  |\n|----------------------------------------------|---------------|--------------------------------|-----------------------|\n| get line's instant value                     | Miscellaneous | gpiod_ctxless_get_value        | getInstantLineValue   |\n| set line's instant value                     | Miscellaneous | gpiod_ctxless_set_value        | setInstantLineValue   |\n| get number of lines in a chip                | Chip          | gpiod_chip_num_lines           | getNumberOfLines      |\n| get chip name                                | Chip          | gpiod_chip_name                | getChipName           |\n| get chip label                               | Chip          | gpiod_chip_label               | getChipLabel          |\n| get line/pin offset number                   | Line          | gpiod_line_offset              | getLineOffset         |\n| get line/pin name                            | Line          | gpiod_line_name                | getLineName           |\n| get line/pin value                           | Line          | gpiod_line_get_value           | getValue              |\n| set line/pin value                           | Line          | gpiod_line_set_value           | setValue              |\n| get line consumer                            | Line          | gpiod_line_consumer            | getLineConsumer       |\n| set line for input (read)                    | Line          | gpiod_line_request_input       | requestInputMode      |\n| set line for input with [flags][input-flags] | Line          | gpiod_line_request_input_flags | requestInputModeFlags |\n| set line for output (write)                  | Line          | gpiod_line_request_output      | requestOutputMode     |\n| release the line                             | Line          | gpiod_line_release             | release               |\n\n## Other implementations\n\nThose are other notable libgpiod wrapper implementations:\n\n### Official C++ binding\n\n- https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/tree/bindings/cxx?h=v1.6.x\n\n### Official Python binding\n\n- https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/tree/bindings/python?h=v1.6.x\n\n### Golang binding\n\n### Rust binding\n\n## Contributing\n\nThis is open source, i am willing to evaluate PR's :sunglasses:\n\n[repo]: https://github.com/sombriks/node-libgpiod\n[libgpiod]: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/\n[node-gyp]: https://www.npmjs.com/package/node-gyp\n[rpi3b+]: https://www.raspberrypi.com/products/raspberry-pi-3-model-b-plus/\n[rpi3zw]: https://www.raspberrypi.com/products/raspberry-pi-zero-w/\n[LTPPx62]: https://tibbo.com/store/tps/ltpp3g2.html\n[ROCK5A]: https://radxa.com/products/rock5/5a\n[ROCK3C]: https://radxa.com/products/rock3/3c\n[libgpiod-2x]: https://github.com/sombriks/node-libgpiod/tree/main-2x\n[test-suite]: test\n[examples]: https://github.com/sombriks/node-libgpiod-examples\n[udev-rules]: https://blog.oless.xyz/post/fedorarpigpio/#udev\n[changelog]: docs/CHANGELOG.md\n[project-updates]: https://github.com/sombriks/node-libgpiod/discussions/31\n[input-flags]: ./lib/line-flags.js","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsombriks%2Fnode-libgpiod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsombriks%2Fnode-libgpiod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsombriks%2Fnode-libgpiod/lists"}