{"id":13454272,"url":"https://github.com/fivdi/pigpio","last_synced_at":"2025-05-15T14:07:08.412Z","repository":{"id":43441904,"uuid":"44207099","full_name":"fivdi/pigpio","owner":"fivdi","description":"Fast GPIO, PWM, servo control, state change notification and interrupt handling with Node.js on the Raspberry Pi","archived":false,"fork":false,"pushed_at":"2023-01-23T21:44:55.000Z","size":1782,"stargazers_count":956,"open_issues_count":9,"forks_count":89,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-27T22:33:45.349Z","etag":null,"topics":["gpio","hc-sr04","interrupt","iot","javascript","motor","nodejs","pwm","raspberry-pi","servo"],"latest_commit_sha":null,"homepage":"","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/fivdi.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","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":"2015-10-13T21:52:06.000Z","updated_at":"2025-03-31T17:49:55.000Z","dependencies_parsed_at":"2023-02-10T05:16:12.375Z","dependency_job_id":null,"html_url":"https://github.com/fivdi/pigpio","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivdi%2Fpigpio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivdi%2Fpigpio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivdi%2Fpigpio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivdi%2Fpigpio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fivdi","download_url":"https://codeload.github.com/fivdi/pigpio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253146402,"owners_count":21861395,"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":["gpio","hc-sr04","interrupt","iot","javascript","motor","nodejs","pwm","raspberry-pi","servo"],"created_at":"2024-07-31T08:00:52.495Z","updated_at":"2025-05-15T14:07:03.403Z","avatar_url":"https://github.com/fivdi.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Packages","Repository","包","目录","Hardware"],"sub_categories":["Hardware","硬件"],"readme":"[![Build Status](https://app.travis-ci.com/fivdi/pigpio.svg?branch=master)](https://app.travis-ci.com/github/fivdi/pigpio)\n[![npm Version](http://img.shields.io/npm/v/pigpio.svg)](https://www.npmjs.com/package/pigpio)\n[![Downloads Per Month](http://img.shields.io/npm/dm/pigpio.svg)](https://www.npmjs.com/package/pigpio)\n[![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)\n\n# pigpio\n\nA wrapper for the [pigpio C library](https://github.com/joan2937/pigpio) to\nenable fast GPIO, PWM, servo control, state change notification and interrupt\nhandling with **Node.js** on the Raspberry Pi Zero, 1, 2, 3 or 4.\n\npigpio supports Node.js versions 10, 12, 14, 15 and 16.\n\n## Contents\n\n * [Features](#features)\n * [Installation](#installation)\n * [Usage](#usage)\n   * [Pulse an LED with PWM](#pulse-an-led-with-pwm)\n   * [Buttons and Interrupt Handling](#buttons-and-interrupt-handling)\n   * [Servo Control](#servo-control)\n   * [Measure Distance with a HC-SR04 Ultrasonic Sensor](#measure-distance-with-a-hc-sr04-ultrasonic-sensor)\n   * [Determine the Width of a Pulse with Alerts](#determine-the-width-of-a-pulse-with-alerts)\n   * [Debounce a Button](#debounce-a-button)\n   * [Generate a waveform](#generate-a-waveform)\n   * [Sending a wavechain](#sending-a-wavechain)\n * [API Documentation](#api-documentation)\n * [Limitations](#limitations)\n * [Troubleshooting](#troubleshooting)\n * [Related Packages](#related-packages)\n\n## Features\n\n * Digital IO\n   * Up to 3.5 million digital reads per second \u003csup\u003e*)\u003c/sup\u003e\n   * Up to 2.5 million digital writes per second \u003csup\u003e*)\u003c/sup\u003e\n * PWM on any of GPIOs 0 through 31\n   * Multiple frequencies and duty cycle ranges supported\n * Servo control on any of GPIOs 0 through 31\n   * Jitter free\n * Alerts when any of GPIOs 0 through 31 change state\n   * The time of the state change is available accurate to a few microseconds\n * Notification streams for monitoring state changes on any of GPIOs 0 through 31 concurrently\n   * The time of the state changes are available accurate to a few microseconds\n * Low latency interrupt handlers\n   * Handle up to 20000 interrupts per second \u003csup\u003e*)\u003c/sup\u003e\n * Read or write up to 32 GPIOs as one operation with banked GPIO\n * Trigger pulse generation\n * Pull up/down resistor configuration\n * Waveforms to generate GPIO level changes (time accurate to a few µs)\n\n*) On a Raspberry Pi 4 Model B running Raspberry Pi OS 2021-03-04 (Buster\n10.8) with pigpio v3.3.1, Node.js v16.0.0 and V79 of the pigpio C library.\n\n## Installation\n\n#### Step 1 - Install the pigpio C library\n\nThe [pigpio C library](https://github.com/joan2937/pigpio) is a prerequisite\nfor the pigpio Node.js module.\n\nRun the following command to determine which version of the pigpio C library\nis installed:\n\n```\npigpiod -v\n```\n\nFor the Raspberry Pi Zero, 1, 2 and 3 V41 or higher of the pigpio C library is\nrequired. For the Raspberry Pi 4 V69 or higher is required.\n\nIf the pigpio C library is not installed or if the installed version is too\nold, the latest version can be installed with the following commands:\n\n```\nsudo apt-get update\nsudo apt-get install pigpio\n```\n\nAlternative installation instructions for the pigpio C library can be found\n[here](http://abyz.me.uk/rpi/pigpio/download.html).\n\n**Warning:** The pigpio C library contains a number of utilities. One of these\nutilities is pigpiod which launches the pigpio C library as a daemon. This\nutility should not be used as the pigpio Node.js package uses the C library\ndirectly.\n\n#### Step 2 - Install the pigpio Node.js package\n\n```\nnpm install pigpio\n```\n\n## Usage\n\nAssume there's an LED connected to GPIO17 (pin 11) and a momentary push button\nconnected to GPIO4 (pin 7).\n\n\u003cimg src=\"https://raw.githubusercontent.com/fivdi/pigpio/master/example/led-button.png\"\u003e\n\n#### Pulse an LED with PWM\n\nUse PWM to pulse the LED connected to GPIO17 from fully off to fully on\ncontinuously.\n\n```js\nconst Gpio = require('pigpio').Gpio;\n\nconst led = new Gpio(17, {mode: Gpio.OUTPUT});\n\nlet dutyCycle = 0;\n\nsetInterval(() =\u003e {\n  led.pwmWrite(dutyCycle);\n\n  dutyCycle += 5;\n  if (dutyCycle \u003e 255) {\n    dutyCycle = 0;\n  }\n}, 20);\n```\n\n#### Buttons and Interrupt Handling\n\nTurn the LED connected to GPIO17 on when the momentary push button connected to\nGPIO4 is pressed. Turn the LED off when the button is released.\n\n```js\nconst Gpio = require('pigpio').Gpio;\n\nconst led = new Gpio(17, {mode: Gpio.OUTPUT});\nconst button = new Gpio(4, {\n  mode: Gpio.INPUT,\n  pullUpDown: Gpio.PUD_DOWN,\n  edge: Gpio.EITHER_EDGE\n});\n\nbutton.on('interrupt', (level) =\u003e {\n  led.digitalWrite(level);\n});\n```\n\n#### Servo Control\n\nContinuously move a servo connected to GPIO10 clockwise and anti-clockwise.\n\n\u003cimg src=\"https://raw.githubusercontent.com/fivdi/pigpio/master/example/servo.png\"\u003e\n\n```js\nconst Gpio = require('pigpio').Gpio;\n\nconst motor = new Gpio(10, {mode: Gpio.OUTPUT});\n\nlet pulseWidth = 1000;\nlet increment = 100;\n\nsetInterval(() =\u003e {\n  motor.servoWrite(pulseWidth);\n\n  pulseWidth += increment;\n  if (pulseWidth \u003e= 2000) {\n    increment = -100;\n  } else if (pulseWidth \u003c= 1000) {\n    increment = 100;\n  }\n}, 1000);\n```\n\n#### Measure Distance with a HC-SR04 Ultrasonic Sensor\n\nThe `trigger` function can be used to generate a pulse on a GPIO and alerts can\nbe used to determine the time of a GPIO state change accurate to a few\nmicroseconds. These two features can be combined to measure distance using a\nHC-SR04 ultrasonic sensor.\n\n\u003cimg src=\"https://raw.githubusercontent.com/fivdi/pigpio/master/example/distance-hc-sr04.png\"\u003e\n\n```js\nconst Gpio = require('pigpio').Gpio;\n\n// The number of microseconds it takes sound to travel 1cm at 20 degrees celcius\nconst MICROSECDONDS_PER_CM = 1e6/34321;\n\nconst trigger = new Gpio(23, {mode: Gpio.OUTPUT});\nconst echo = new Gpio(24, {mode: Gpio.INPUT, alert: true});\n\ntrigger.digitalWrite(0); // Make sure trigger is low\n\nconst watchHCSR04 = () =\u003e {\n  let startTick;\n\n  echo.on('alert', (level, tick) =\u003e {\n    if (level == 1) {\n      startTick = tick;\n    } else {\n      const endTick = tick;\n      const diff = (endTick \u003e\u003e 0) - (startTick \u003e\u003e 0); // Unsigned 32 bit arithmetic\n      console.log(diff / 2 / MICROSECDONDS_PER_CM);\n    }\n  });\n};\n\nwatchHCSR04();\n\n// Trigger a distance measurement once per second\nsetInterval(() =\u003e {\n  trigger.trigger(10, 1); // Set trigger high for 10 microseconds\n}, 1000);\n```\n\n#### Determine the Width of a Pulse with Alerts\n\nAlerts can be used to determine the time of a GPIO state change accurate to a\nfew microseconds. Typically, alerts will be used for GPIO inputs but they can\nalso be used for outputs. In this example, the `trigger` method is used to\npulse the LED connected to GPIO17 on for 15 microseconds once per second.\nAlerts are used to measure the length of the pulse.\n\n```js\n// Assumption: the LED is off when the program is started\n\nconst Gpio = require('pigpio').Gpio;\n\nconst led = new Gpio(17, {\n  mode: Gpio.OUTPUT,\n  alert: true\n});\n\nconst watchLed = () =\u003e {\n  let startTick;\n\n  // Use alerts to determine how long the LED was turned on\n  led.on('alert', (level, tick) =\u003e {\n    if (level == 1) {\n      startTick = tick;\n    } else {\n      const endTick = tick;\n      const diff = (endTick \u003e\u003e 0) - (startTick \u003e\u003e 0); // Unsigned 32 bit arithmetic\n      console.log(diff);\n    }\n  });\n};\n\nwatchLed();\n\n// Turn the LED on for 15 microseconds once per second\nsetInterval(() =\u003e {\n  led.trigger(15, 1);\n}, 1000);\n```\n\nHere's an example of the typical output to the console:\n\n```\n15\n15\n15\n15\n15\n15\n20\n15\n15\n15\n15\n```\n\n#### Debounce a Button\nThe GPIO glitch filter will prevent alert events from being emitted if the\ncorresponding level change is not stable for at least a specified number of\nmicroseconds. This can be used to filter out unwanted noise from an input\nsignal. In this example, a glitch filter is applied to filter out the contact\nbounce of a push button.\n\n![Button debounce circuit](example/button-debounce.png)\n\n```js\nconst Gpio = require('pigpio').Gpio;\n\nconst button = new Gpio(23, {\n  mode: Gpio.INPUT,\n  pullUpDown: Gpio.PUD_UP,\n  alert: true\n});\n\nlet count = 0;\n\n// Level must be stable for 10 ms before an alert event is emitted.\nbutton.glitchFilter(10000);\n\nbutton.on('alert', (level, tick) =\u003e {\n  if (level === 0) {\n    console.log(++count);\n  }\n});\n```\n\n#### Generate a waveform\n\nWaveforms can be used to time and execute Gpio level changes with an accuracy up to 1 microsecond. The following example generates a waveform that starts with a 1µs pulse, then has a 2µs pause, followed by a 3µs pulse and so on.\nThe waveform definition is a simple Array where each entry is an object with the properties gpioOn, gpioOff and usDelay.\n\nThe basic workflow to generate and execute waveforms is as follows:\n\nFirst, we usually clear previous wave entries with the `waveClear` method.\nThen we can add pulses with the `waveAddGeneric` method to the cleared waveform.\nWe then create a waveId by calling the `waveCreate` method.\nTo execute the waveform, we call the `waveTxSend` method.\nOnce the wave is sent, we can delete the wave by calling the `waveDelete` method.\n\n```js\nconst pigpio = require('pigpio');\nconst Gpio = pigpio.Gpio;\n\nconst outPin = 17;\n\nconst output = new Gpio(outPin, {mode: Gpio.OUTPUT});\n\noutput.digitalWrite(0);\npigpio.waveClear();\n\nlet waveform = [];\n\nfor (let x = 0; x \u003c 20; x++) {\n  if (x % 2 === 1) {\n    waveform.push({ gpioOn: outPin, gpioOff: 0, usDelay: x + 1 });\n  } else {\n    waveform.push({ gpioOn: 0, gpioOff: outPin, usDelay: x + 1 });\n  }\n}\n\npigpio.waveAddGeneric(waveform);\n\nlet waveId = pigpio.waveCreate();\n\nif (waveId \u003e= 0) {\n  pigpio.waveTxSend(waveId, pigpio.WAVE_MODE_ONE_SHOT);\n}\n\nwhile (pigpio.waveTxBusy()) {}\n\npigpio.waveDelete(waveId);\n```\n#### Sending a wavechain\n\nThe `waveChain` method allows you to chain multiple waveforms together.\nA chain is basically just an array with several waveId's. However you can insert different modifiers as described [here](https://github.com/fivdi/pigpio/blob/master/doc/global.md#wavechainchain).\n\nIn the example the `chain` consists of two waves. The first waveform is transmitted normally, then the second waveform is repeated 3 times.\n```js\nconst pigpio = require('pigpio');\nconst Gpio = pigpio.Gpio;\n\nconst outPin = 17;\nconst output = new Gpio(outPin, {mode: Gpio.OUTPUT});\n\noutput.digitalWrite(0);\npigpio.waveClear();\n\nlet firstWaveForm = [];\nlet secondWaveForm = [];\n\nfor (let x = 0; x \u003c 10; x++) {\n  if (x % 2 === 0) {\n    firstWaveForm.push({ gpioOn: outPin, gpioOff: 0, usDelay: 10 });\n  } else {\n    firstWaveForm.push({ gpioOn: 0, gpioOff: outPin, usDelay: 10 });\n  }\n}\n\npigpio.waveAddGeneric(firstWaveForm);\nlet firstWaveId = pigpio.waveCreate();\n\nfor (let x = 0; x \u003c 10; x++) {\n  if (x % 2 === 0) {\n    secondWaveForm.push({ gpioOn: outPin, gpioOff: 0, usDelay: 20 });\n  } else {\n    secondWaveForm.push({ gpioOn: 0, gpioOff: outPin, usDelay: 20 });\n  }\n}\n\npigpio.waveAddGeneric(secondWaveForm);\nlet secondWaveId = pigpio.waveCreate();\n\nif (firstWaveId \u003e= 0 \u0026\u0026 secondWaveId \u003e= 0) {\n  let chain = [firstWaveId, 255, 0, secondWaveId, 255, 1, 3, 0];\n  pigpio.waveChain(chain);\n}\n\nwhile (pigpio.waveTxBusy()) {}\n\npigpio.waveDelete(firstWaveId);\npigpio.waveDelete(secondWaveId);\n```\n\n## API Documentation\n\n### Classes\n\n- [Gpio](https://github.com/fivdi/pigpio/blob/master/doc/gpio.md) - General Purpose Input Output\n- [GpioBank](https://github.com/fivdi/pigpio/blob/master/doc/gpiobank.md) - Banked General Purpose Input Output\n- [Notifier](https://github.com/fivdi/pigpio/blob/master/doc/notifier.md) - Notification Stream\n\n### pigpio Module\n\n- [Global](https://github.com/fivdi/pigpio/blob/master/doc/global.md) - Module Globals\n\n### Configuring pigpio\n\n- [Configuration](https://github.com/fivdi/pigpio/blob/master/doc/configuration.md) - pigpio configuration\n\n## Limitations\n\n * The pigpio Node.js package is a wrapper for the\n   [pigpio C library](https://github.com/joan2937/pigpio). A limitation of the\n   pigpio C library is that it can only be used by a single running process.\n * The pigpio C library and therefore the pigpio Node.js package requires\n   root/sudo privileges to access hardware peripherals.\n   \n## Troubleshooting\nIf you have a problem with the library, before you remove it from your code and start trying something else, please check the [troubleshooting page](https://github.com/fivdi/pigpio/blob/master/doc/troubleshooting.md) first. Some problems are solvable and documented.\n\n## Related Packages\n\nHere are a few links to other hardware specific Node.js packages that may be of interest.\n\n- [onoff](https://github.com/fivdi/onoff) - GPIO access and interrupt detection\n- [i2c-bus](https://github.com/fivdi/i2c-bus) - I2C serial bus access\n- [spi-device](https://github.com/fivdi/spi-device) - SPI serial bus access\n- [mcp-spi-adc](https://github.com/fivdi/mcp-spi-adc) - Analog to digital conversion with the MCP3002/4/8, MCP3202/4/8 and MCP3304\n- [pigpio-dht](https://github.com/depuits/pigpio-dht) - Implements logic to read DHT11 or DHT22/AM2302 temperature and relative humidity sensor\n- [pigpio-mock](https://github.com/deepsyx/pigpio-mock) - A pigpio mock library for development on your local machine\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivdi%2Fpigpio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffivdi%2Fpigpio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivdi%2Fpigpio/lists"}