{"id":15065086,"url":"https://github.com/guymcswain/pigpio-client","last_synced_at":"2025-04-10T03:53:51.866Z","repository":{"id":45343703,"uuid":"95818189","full_name":"guymcswain/pigpio-client","owner":"guymcswain","description":"A nodejs client for pigpio socket interface.","archived":false,"fork":false,"pushed_at":"2025-02-04T20:32:34.000Z","size":224,"stargazers_count":29,"open_issues_count":13,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T03:53:46.023Z","etag":null,"topics":["gpio","i2c","pigpio","pwm","raspberrypi","serial","servo","waveforms"],"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/guymcswain.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-29T20:45:15.000Z","updated_at":"2025-02-04T20:32:38.000Z","dependencies_parsed_at":"2024-06-19T06:14:47.962Z","dependency_job_id":"10003c8e-f32c-4d32-bcec-8cfbaecde4a1","html_url":"https://github.com/guymcswain/pigpio-client","commit_stats":{"total_commits":116,"total_committers":5,"mean_commits":23.2,"dds":"0.11206896551724133","last_synced_commit":"0e54b1c66ad6b466ab745f2ba60892163dcfa9fa"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guymcswain%2Fpigpio-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guymcswain%2Fpigpio-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guymcswain%2Fpigpio-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guymcswain%2Fpigpio-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guymcswain","download_url":"https://codeload.github.com/guymcswain/pigpio-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248155000,"owners_count":21056542,"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","i2c","pigpio","pwm","raspberrypi","serial","servo","waveforms"],"created_at":"2024-09-25T00:33:35.645Z","updated_at":"2025-04-10T03:53:51.848Z","avatar_url":"https://github.com/guymcswain.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pigpio-client\nPigpio-client exposes the socket interface APIs of the pigpio library using nodejs.  This allows you to connect to a Raspberry Pi, running \nremotely or local, and manipulate its GPIO pins with javascript.  The pigpio socket interface is described more fully [here:](http://abyz.me.uk/rpi/pigpio/sif.html)\n\nNew in **v1.5.2** \n* Add Trigger API\n\n#### Installing and Running pigpio daemon\nA guide for installing and running pigpiod along with other useful information can be found in the [wiki](https://github.com/guymcswain/pigpio-client/wiki/Install-and-configure-pigpiod)\n\n### pigpio-client usage example\n```javascript\nconst pigpio = require('pigpio-client').pigpio({host: 'raspberryHostIP'});  \n\nconst ready = new Promise((resolve, reject) =\u003e {\n  pigpio.once('connected', resolve);\n  pigpio.once('error', reject);\n});\n\nfunction wait(ms) {\n  return new Promise(resolve =\u003e setTimeout(resolve, ms));\n}\n\nready.then(async (info) =\u003e {\n  // display information on pigpio and connection status\n  console.log(JSON.stringify(info,null,2));\n\n  // get events from a button on GPIO 17\n  const button = pigpio.gpio(17);\n  await button.modeSet('input');\n  button.notify((level, tick)=\u003e {\n    console.log(`Button changed to ${level} at ${tick} usec`)\n  });\n\n  // control an LED on GPIO 4\n  const led = pigpio.gpio(4);\n  await led.modeSet('output');\n  await led.write(1);  // turn on LED\n  await wait(500);\n  await led.write(0);  // turn off\n  await wait(500);\n\n  // use waves to blink the LED rapidly (toggle every 100ms)\n  await led.waveClear();\n  await led.waveAddPulse([[1, 0, 100000], [0, 1, 100000]]);\n  const blinkWave = await led.waveCreate();\n  led.waveChainTx([{loop: true}, {waves: [blinkWave]}, {repeat: true}]);\n\n  // wait for 10 sec, stop the waves\n  await wait(10000);\n  await led.waveTxStop();\n}).catch(console.error);\n```\nAll APIs accept error-first callback as an optional last argument, and also return\na promise (and thus can be safely used with async/await).\nDepending on the presence of a callback argument, errors returned by pigpio are delivered in \ntwo ways:  Methods called without a callback emit 'error' events.  Methods called \nwith a callback are supplied an `Error` object as the first argument returned.  \nArguments to callback are: `(error, response)` unless otherwise noted.\n\n### Constructors\n**`PigpioClient.pigpio(options)`**:\nConstruct a pigpio object and connect it to `options.host`.\n  \nOptions have the following properties:\n- host: \u003cstring\u003e The remote IP address to host running pigpio daemon.  Defaults \nto 'localhost'.\n- port: \u003cnumber\u003e The port used to configure pigpiod.  Default is 8888.\n- pipelining: \u003cboolean\u003e DEPRECATED. Configures internal socket communications.\n- timeout: \u003cnumber\u003e The network socket timeout in minutes. Default is 0. *Timeout* \nenables automatic retries to connect to the server after any socket error is \nencountered. During the timeout period, connection will be retried every 5 seconds. \nAn 'error' event will be emitted after the timeout period expires. After connection \nis established, if keep-alive packets are not received from the server within \n*timeout* minutes, the network sockets will be closed and a 'disconnected' event \nemitted.  If *timeout* is used, it is recommended to set its value to \u003e 1 minute. \nAlso recommended is to use V68 of pigpio library.  \n\n**`pigpio.gpio(gpio_pin)`** Return a gpio object set to the Broadcom GPIO number \nspecified by gpio_pin. An error will be thrown if gpio_pin is not a valid user GPIO.  \n\n**`pigpio.serialport(rx,tx,dtr)`**  Return a serialport object constructed from GPIO \npins for rx, tx and dtr.  Rx and Tx may use the same pin for a loop-back.  DTR pin \nis optional.  An error will be thrown if the pins are not valid user GPIO.  Constructing\na serialport object will clear all waveforms.\n\n## Events\n**`'connected'`**  Emitted after both command and notification sockets are connected \nto pigpiod.  An 'info' object is passed to the handler.  You should wait for this \nevent before attempting to construct other objects - gpio, serialport.\n\n**`'disconnected'`**  Emitted when the socket connections are closed, for any reason, \nor when no pigpio keep-alive packet is received within *timeout\u003e0* minutes.  \n\n**`'error'`**  Error objects are passed to the 'error' event handler unless a callback \nwas provided when invoking an API.  Pigpio errors have the `name` property set to \n`PigpioError` and a `code` and `message` property set corresponding the numeric value \nreturned by the socket interface.  For pigpio-client specific APIs, the error `name` \nis set to `PigpioClientError`.\n  \n\n## Methods\nNote: Unless otherwise stated, all references to gpio pin numbers use **Broadcom numbering**.\n### pigpio methods\n\n**`pigpio.getInfo(cb)`**  Returns useful information about rpi hardware and pigpiod.  \n\n**`pigpio.getCurrentTick(cb)`** Return current timer tick in microseconds.  [`gpioTick`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioTick)   \n\n**`pigpio.readBank1(cb)`**  Returns levels of GPIO bits 31-0.  [`gpioRead_Bits_0_31`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioRead_Bits_0_31)  \n\n**`pigpio.end(cb)`**  Ends socket communications.  Callback is invoked on `'disconnected'` event.  \n\n**`pigpio.destroy()`**  DEPRECATED.  Invokes socket.destroy() on both network sockets.  \n\n**`pigpio.connect()`**  Re-establishes communication with server after being disconnected.  \n\n**`pigpio.i2cOpen(bus, address, callback)`**  Return a handle for communication \nwith a device attached to a bus on the I2C peripheral.  `bus==0` uses (Broadcom) \ngpio 0 and 1, while `bus==1` use gpio 2 and 3 for SDA and SCL respectively.  `address` takes values 1-127.\n\n**`pigpio.i2cClose(handle, callback)`**  Close the I2C device associated with handle.\n\n**`pigpio.i2cReadDevice(handle, count, callback)`**  Read count bytes from the i2c \ndevice referred by handle.  Returns tuple (error, count, data).  `error` is 0 on \nsuccess or an error code.  `count` is the number of bytes read.  `data` is a buffer.\n\n**`pigpio.i2cWriteDevice(handle, data, callback)`**  Write data to the i2c device \nreferred by handle.  `data` is a byte array or utf8 string.  Returns 0 if \nOK, otherwise an error code.  \n\n**`pigpio.bscI2C(address, data, callback)`**  Transfer data to/from the BSC I2C \nslave peripheral using gpio 18 (SDA) and 19 (SCL).  The data bytes (if any) are \nwritten to the BSC transmit FIFO and the bytes in the BSC receive FIFO are \nreturned.  The depth of the FIFO is 32 bytes.\n\nThis function is not available on the BCM2711 (e.g. as used in the Pi4B).  \n\n`address` is a non-zero 7-bit i2c address the slave device will respond to.  \nIf `address` is 0, the BSC peripheral is turned off and gpio 18/19 are reset to \ninput mode.  \n\n`data`, optional, is a byte array or utf8 string up to 512 bytes.  \n\nThe return value is a byte array containing: A byte-count byte followed by 4 \nstatus bytes followed by the data bytes read from the RX FIFO.\n\nThe `EVENT_BSC` event is emitted when data is available to read from the BSC I2C \ndevice.\n\n\n### gpio basic methods\n**`gpio.modeSet(mode, cb)`**  Sets the gpio mode to be input or output.  The mode \nargument must be `string` with a value of `'input'`, `'in'`, `'output'` or `'out'`.\nThe optional callback is invoked with either `null` argument on success or `error` \non failure.\n\n**`gpio.trigger(len, level, cb)`**  Send a trigger pulse to a GPIO. The GPIO is set \nto `level` for `len` microseconds. The optional callback is invoked with either \n`null` argument on success or `error` on failure.\n\n**`gpio.modeGet(cb)`**  Returns the mode of gpio as argument to callback. [`gpioGetMode`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioGetMode)  \n\n**`gpio.pullUpDown(pud, cb)`**  pud=2: set pullup resistor, pud=1: set pulldown\nresistor, pud=0: clear resistor setting.[`gpioSetPullUpDown`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioSetPullUpDown)  \n\n**`gpio.read(cb)`**  Returns the gpio pin level as argument to callback.  \n\n**`gpio.write(level, cb)`**  Sets the gpio output level to on (1) or off (0). If \nPWM or servo pulses are active on the gpio they are switched off. [`gpioWrite`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWrite)  \n\n**`gpio.analogWrite(dutyCycle, cb)`**  Set the PWM dutycycle (0-255) on the gpio.  Caution: \nThis will stop all waveform generation. [`gpioPWM`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioPWM).  \n\n**`gpio.hardwarePWM(frequency, dutyCycle, callback)`**  Set the hardware PWM dutycycle (0-1000000) on the gpio. Only works with pins that support hardware PWM (12,13,18,19); max two channels available. PWM frequency is also specified - not likely to work above 30MHz though. Caution: \nThis will stop all waveform generation. [`gpioHardwarePWM`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioHardwarePWM).  \n\n**`gpio.setServoPulsewidth(pulseWidth, cb)`** Starts servo pulses on gpio. Pulsewidth can be set to 0 (off) and from 500 (most anti-clockwise) to 2500 (most clockwise). Be aware that you can damage your servo when setting a too high pulseWidth. A value of 1500 (mid-point) is a good starting point to check range of your servo. [`gpioServo`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioServo)  \n\n**`gpio.getServoPulsewidth(cb)`** Returns the pulsewidth of gpio as argument to callback. [`gpioGetServoPulsewidth`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioGetServoPulsewidth)  \n\n### gpio waveform methods\n**`gpio.waveClear(cb)`** Clear all waveforms (release DMA control blocks, reset wave IDs). [`gpioWaveClear`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveClear)  \n\n**`gpio.waveCreate(cb)`** Returns the wave id of waveform created from previous calls \nto `waveAddPulse` or `waveAddSerial`.  [`gpioWaveCreate`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveCreate)    \n\n**`gpio.waveBusy(cb)`**  Returns 1 if wave is still transmitting, otherwise 0. [`gpioWaveTxBusy`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveTxBusy)  \n\n**`gpio.waveNotBusy(interval, callback)`**  Invokes `callback` when waveform ends. \nPolls waveform status at interval msec.  Defaults to 25msec.  \n\n**`gpio.waveAddPulse([Pulse_t], cb)`** Add array of *Pulse_t* to gpio of current \nwaveform.  *Pulse_t* is a tuple [1, 0, delay] for positive pulse, [0, 1, delay] \nfor negative pulse width = delay. [`gpioWaveAddGeneric`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveAddGeneric).  \n\n**`gpio.waveChainTx([{loop:x}, {waves: [wids]}, {delay:y}, {repeat:z}], cb)`**\n[`gpioWaveChain`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveChain)   \nTransmit a chain of waves represented by array of wave IDs `[wids]`.  The chain can have **loop**s, be separated by **delay**s and **repeat**ed by inclusion of option objects.  \n  * loop : x, begins a loop.  x can be anything\n  * delay: y, insert of delay of y=0 to 65535 microseconds \n  * repeat: z, repeat loop z=0 to 65535 times or forever if z=**true** \n\n**`gpio.waveSendSync(wid, cb)`**  Synchronizes `wid` to the currently active \nwaveform. [`gpioWaveTxSend` with mode set to PI_WAVE_MODE_ONE_SHOT_SYNC.](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveTxSend)    \n\n**`gpio.waveSendOnce(wid, cb)`**  Send the wave id, `wid`, one time. [`gpioWaveTxSend` with mode set to PI_WAVE_MODE_ONE_SHOT.](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveTxSend)  \n\n**`gpio.waveTxAt(cb)`**  Return currently active wave id, no wave being transmitted \n(9999) or wave not found (9998). [`gpioWaveTxAt`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveTxAt)  \n\n**`gpio.waveTxStop(cb)`**  Aborts the transmission of the current waveform.\nThis function is intended to stop a waveform started in repeat mode. [`waveTxStop`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveTxStop)  \n\n**`gpio.waveDelete(wid, cb)`**  Delete the wave id `wid`. [`gpioWaveDelete`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveDelete)  \n\n*Note:  `waveClear`, `waveCreate` and `waveBusy` are not gpio specific.  These methods \nare made available to the gpio object for convenience and as a reminder that only \na single waveform can be active.*  \n*Note: `waveBusy` and `waveNotBusy` return status are global indication of waveform state - not specific to gpio!*  \n\n### gpio notification methods\n**`gpio.notify(callback)`** Registers the notification function `callback`.  `callback` \nis invoked whenever the gpio state changes.  Arguments to `callback` are *level* \nand *tick* where *tick* represents the system's time since boot.  \n\n**`gpio.endNotify(cb)`**  Unregisters the notification on gpio. For convenience, \na null *tick* value is sent - useful for stream objects that wrap the notifier callback.  \n\n**`gpio.glitchSet(steady, cb)`** Sets a glitch filter (0-300000) on gpio in microseconds. Only effects notifications.\n[`gpioGlitchFilter`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioGlitchFilter)  \n\n### gpio bit\\_bang\\_serial methods  \n**`gpio.serialReadOpen(baudRate, dataBits, cb)`** - [`gpioSerialReadOpen`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioSerialReadOpen)   \n\n**`gpio.serialRead(count, cb)`**  Returns cb(null, length, buf). *buf* is Uint8Array\nof length *length*. [`gpioSerialRead`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioSerialRead)  \n\n**`gpio.serialReadClose(cb)`**  \u003cadd text\u003e[`gpioSerialReadClose`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioSerialReadClose)  \n\n**`gpio.serialReadInvert(mode, cb)`**  Mode is 'invert' || 'normal'. [`gpioSerialReadInvert`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioSerialReadInvert)  \n\n**`waveAddSerial(baud,bits,delay,data,cb)`**  - [`gpioWaveAddSerial`](http://abyz.me.uk/rpi/pigpio/cif.html#gpioWaveAddSerial)\n\n### serialport methods \n##### Experimental, these APIs may change in the future.  \n**`serialport.open(baudrate,databits,cb)`**  Argument *baudRate* must be a number\nfrom 50 to 250000.  Argument *dataBits* must be a number from 1 to 32. If the rx gpio \nis already open for bit-bang serial read the method will close the gpio and then\nre-open it.  \n\n**`serialport.read(size, cb)`**  *size* is an optional argument representing the \nnumber of bytes to read. If not specified, all the data in pigpio's cyclic buffer \nis returned (up to 8192 bytes).  Returns *cb(null, data)* where data is a utf8 \nstring.  If the serialport is not open, returns *cb(null)*.  \n\n**`serialport.write(data)`**  *data* is utf8 string or Uint8Buffer.  The *data* is\nbuffered then sent out in chunk sizes that fit the available waveform resources.\nReturns the number of bytes remaining in the buffer.  If the serialport is not open,\nreturns -1.  Any pigpio errors occurring during write will be thrown to limit the\npossibility of data corruption.\n\n**`serialport.close(cb)`**  Close serialport.  \n\n**`serialport.end(cb)`**  Closes rx gpio for bb_serial_read and changes gpios tx and\ndtr mode to input.  \n\n### Environment Variables for Debugging\nEnvironment variables can be set to display messages from pigpio-client to assist \nin troubleshooting your application.  DEBUG='pigpio' will enable status messages. \nFor tracing the all socket communication use: PIGPIO=1.\n```\nDEBUG='pigpio' node myApp.js\n```\n\n### Issues/Requests/Questions\nhttps://github.com/guymcswain/pigpio-client/issues\n\n\n#### Limitations\nOnly a single instance of serialport is supported.  **\u003c=1.1.x**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguymcswain%2Fpigpio-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguymcswain%2Fpigpio-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguymcswain%2Fpigpio-client/lists"}