pigpio

The Gpio class is an EventEmitter that provides two ways to monitor state changes:

Interrupts

Best for: Low latency.

• enableInterrupt(edge[, timeout]): Enables interrupts. edge can be RISING_EDGE, FALLING_EDGE, or EITHER_EDGE. timeout is optional (ms).
• disableInterrupt(): Disables interrupts.
• Event: 'interrupt' is emitted. The level argument is the level read at the time of the interrupt. If a timeout expires, level is TIMEOUT (2).

Alerts

Best for: High frequency/detecting more changes.

• enableAlert(): Enables alerts. An event is emitted every time the state changes.
• disableAlert(): Disables alerts.
• Event: 'alert' is emitted. The level is the state (0 or 1) and tick is the microsecond timestamp since boot.
• Note: Alerts have higher latency than interrupts as they are queued and fired once per millisecond.

Glitch Filter

• glitchFilter(steady): Sets a filter that ignores level changes shorter than steady microseconds. This only affects 'alert' events.

const { Gpio } = require('pigpio');
const gpio = new Gpio(4, { mode: 'INPUT', edge: 'EITHER_EDGE' });

gpio.on('interrupt', (level) => {
  console.log(`Interrupt detected! Level: ${level}`);
});

// Using alerts with a glitch filter
gpio.glitchFilter(50); // Ignore changes shorter than 50us
gpio.enableAlert();
gpio.on('alert', (level, tick) => {
  console.log(`Alert! Level: ${level} at tick: ${tick}`);
});

The waveChain(chain) function allows you to transmit an ordered list of wave_ids combined with command codes to create complex sequences, loops, and delays.

Supported command codes (using 255 as the prefix):

• Loop Start (255 0): Identifies the start of a wave block for looping.
• Loop Repeat (255 1 x y): Loops the block x + y * 256 times.
• Delay (255 2 x y): Delays for x + y * 256 microseconds.
• Loop Forever (255 3): Loops the block indefinitely. This must be the last entry in the chain.

Note: Any hardware PWM started by hardwarePwmWrite will be cancelled when starting a chain.

const pigpio = require('pigpio');
const Gpio = pigpio.Gpio;

const outPin = 17;
const output = new Gpio(outPin, { mode: Gpio.OUTPUT });

let firstWaveForm =   [{ gpioOn: outPin, gpioOff: 0, usDelay: 10 }, { gpioOn: 0, gpioOff: outPin, usDelay: 10 }];
let secondWaveForm =  [{ gpioOn: outPin, gpioOff: 0, usDelay: 20 }, { gpioOn: 0, gpioOff: outPin, usDelay: 20 }];
let thirdWaveForm =   [{ gpioOn: outPin, gpioOff: 0, usDelay: 30 }, { gpioOn: 0, gpioOff: outPin, usDelay: 30 }];
let fourthWaveForm =  [{ gpioOn: outPin, gpioOff: 0, usDelay: 40 }, { gpioOn: 0, gpioOff: outPin, usDelay: 40 }];

pigpio.waveClear();
pigpio.waveAddGeneric(firstWaveForm);
let firstWaveId = pigpio.waveCreate();

pigpio.waveAddGeneric(secondWaveForm);
let secondWaveId = pigpio.waveCreate();

pigpio.waveAddGeneric(thirdWaveForm);
let thirdWaveId = pigpio.waveCreate();

pigpio.waveAddGeneric(fourthWaveForm);
let fourthWaveId = pigpio.waveCreate();

let chain = [
  firstWaveId,      // transmits firstWaveId
  secondWaveId,     // transmits secondWaveId
  firstWaveId,      // transmits again firstWaveId
  255, 2, 136, 19,  // delay for 5000 microseconds (136 + 19 * 256 = 5000)
  255, 0,           // marks the beginning of a new wave
  thirdWaveId,      // transmits thirdWaveId
  255, 1, 30, 0,    // repeats the waves since the last beginning mark 30 times (30 + 0 * 256 = 30)
  255, 0,           // marks the beginning of a new wave
  fourthWaveId,     // transmits fourthWaveId
  255, 3            // loops forever until waveTxStop is called
];

pigpio.waveChain(chain);
while (pigpio.waveTxBusy()) {}

By default, pigpio initializes and terminates the C library automatically when Gpio objects are created. However, if your Node.js application uses process.on() to register signal event handlers (like SIGINT), the automatic initialization will overwrite your handlers because Linux only allows one handler per signal.

To prevent this, you must manually manage the lifecycle:

1. Call pigpio.initialize() before registering any process.on signal handlers.
2. Call pigpio.terminate() inside your signal handler to ensure the library shuts down correctly.

Note: After calling terminate(), any existing pigpio objects can no longer be used.

const pigpio = require('pigpio');
const Gpio = pigpio.Gpio;

let led;
let iv;

// 1. Manually initialize before registering signal handlers
pigpio.initialize(); 

process.on('SIGINT', () => {
  // 2. Use terminate() inside the handler
  led.digitalWrite(0);
  pigpio.terminate(); 
  clearInterval(iv);
  console.log('Terminating...');
});

led = new Gpio(17, {mode: Gpio.OUTPUT});

iv = setInterval(() => {
  led.digitalWrite(led.digitalRead() ^ 1);
}, 1000);

Waveforms are created by adding a series of pulses to the current waveform buffer and then calling waveCreate().

1. Call waveClear() to reset the buffer.
2. Use waveAddGeneric(pulses) to add an array of pulse objects. Each pulse object must have:
   • gpioOn: GPIO number to turn on (use 0 to not change state).
   • gpioOff: GPIO number to turn off (use 0 to not change state).
   • usDelay: Pulse length in microseconds.
3. Call waveCreate() to get a waveId.
4. Use waveTxSend(waveId, waveMode) to transmit the waveform.
5. Use waveTxBusy() to poll for completion.
6. Call waveDelete(waveId) to clean up.

const pigpio = require('pigpio');
const Gpio = pigpio.Gpio;

const outPin = 17;
const output = new Gpio(outPin, { mode: Gpio.OUTPUT });
  
let waveform = [];

// Example: alternating pulses
for (let x = 0; x < 20; x++) {
  if (x % 2 == 1) {
    waveform.push({ gpioOn: outPin, gpioOff: 0, usDelay: x + 1 });
  } else {
    waveform.push({ gpioOn: 0, gpioOff: outPin, usDelay: x + 1 });
  }
}

pigpio.waveClear();
pigpio.waveAddGeneric(waveform);

let waveId = pigpio.waveCreate();

if (waveId >= 0) {
  pigpio.waveTxSend(waveId, pigpio.WAVE_MODE_ONE_SHOT);
}

while (pigpio.waveTxBusy()) {}

pigpio.waveDelete(waveId);