gpio2

Export elegant API to control Raspberry Pi GPIO pins with Node.js. Provide both synchronous and asynchronous Promise API. Use interrupts to detect the state change of the GPIO pins and fire events what is much faster and more sensitive than file monitoring such as fs.watch or chokidar.

Installation

npm install gpio2

Usage

with ES5

require('gpio2').Gpio;

const pinIn = 'gpio21', //or 40
      pinOut = 32;

let gpio = new Gpio(portIn);

gpio.export(Gpio.DIR_IN, {
  debounceTimeout: 500
});

gpio.on('rising', function(e){
  console.log('rising', e);
});

with ES6

'use strict'

const Gpio = require("gpio2.js").Gpio;

const sleep = (millsec) => {
  console.log("sleep..." + millsec);
  return new Promise((resolve) => setTimeout(() => resolve(), millsec));
};

let gpio0 = new Gpio(40),
    gpio1 = new Gpio(32);

let main = async () => {
  await gpio1.export('in','falling');

  gpio1.watch(function(err, value){
    console.log('watched', gpio1.edge, gpio1.value, value);
  });

  await gpio0.export();

  while(1){
    await gpio0.toggleValue(); //make a signal changed per second.
    await sleep(1000);
  }
}

process.on("SIGINT", function(){
  gpio0.unexport();
  gpio1.unexport();

  console.log('shutdown!');
  process.exit(0);
});

main();

API

Class Gpio extends events.EventEmitter

Methods

• Gpio(pinNumber) - Constructor
• export([options]) - Export the GPIO to userspace
• unexport() - Unexport the GPIO
• setValue(value) - Set GPIO value asynchronously(returns a promise)
• getValue(value) - Get GPIO value asynchronously(returns a promise)
• toggleValue() - Change GPIO value asynchronously(returns a promise)

Properties

• value:0|1 - Set/Get GPIO value synchronously
• direction:string - The input/output direction of a GPIO pin
• activeLow:boolean - GPIO activeLow setting

Events

• rising - Triggering an event when GPIO signal rising
• falling - Triggering an event when GPIO signal falling
• change - Triggering an event when GPIO signal rising or falling

Constants

• Gpio.HIGH = 1;
• Gpio.LOW = 0;
• Gpio.DIR_IN = 'in';
• Gpio.DIR_OUT = 'out';
• Gpio.EDGE_NONE = 'none';
• Gpio.EDGE_RISING = 'rising';
• Gpio.EDGE_FALLING = 'falling';
• Gpio.EDGE_BOTH = 'both';

---

constructor

new Gpio(pin) creates a GPIO pin instance. The arguments pin can be a number (pin number) or a string starts with 'gpio' (gpio number):

let pin1 = new Gpio('gpio21'); //create gpio21

//equal to: let pin12 = new Gpio('gpio12');
let pin2 = new Gpio(32); //create #32 pin of Pi, which is gpio12

The pin number mapping to GPIO number as below:

+ 3.3v	1	2	+ 5v
I2C SDA / GPIO 2	3	4	+ 5v
I2C SCL / GPIO 3	5	6	Ground
Clock / GPIO 4	7	8	TX / GPIO 14
--	9	10	RX / GPIO 15
GPIO 17	11	12	GPIO 18
GPIO 27	13	14	--
GPIO 22	15	16	GPIO 23
+ 3.3V	17	18	GPIO 24
SPI MOSI / GPIO 10	19	20	--
SPI MISO / GPIO 9	21	22	GPIO 25
SPI SCLK / GPIO 11	23	24	SPI CE0 / GPIO 8
--	25	26	SPI CE1 / GPIO 7
Model A+ and Model B+ additional pins
ID_SD	27	28	ID_SC
GPIO 5	29	30	--
GPIO 6	31	32	GPIO 12
GPIO 13	33	34	--
GPIO 19	35	36	GPIO 16
GPIO 26	37	38	GPIO 20
--	39	40	GPIO 21

export([options])

Exports a GPIO to userspace.

• [options: object] Additional options.

  The options argument supports the following:

  • direction: A string specifying whether the GPIO should be configured as an input or output. The valid values are: 'in', 'out'..

  • activeLow: Specifies whether the values read from or written to the GPIO should be inverted. The interrupt generating edge for the GPIO also follow this this setting. The valid values for activeLow are true and false. Setting activeLow to true inverts. The default value is false.

  • debounceTimeout: Can be used to software debounce a button or switch using a timeout. Specified in milliseconds. The default value is 0.

unexport()

Unexports a GPIO from userspace and release all resources.

setValue(value)

Set a velue to a GPIO asynchronously. Returns a promise.

getValue(value)

Set a velue to a GPIO asynchronously. Returns a promise.

toggleValue()

Change GPIO value asynchronously. Returns a promise.

async function run(gpio){
    while(1){
        gpio.toggleValue(); //blink gpio value every 0.5 second to send a signal.
        sleep(500);
    }
}

value:0|1

Get or set a velue to a GPIO synchronously.

direction:string

The pin direction, pass either Gpio.DIR_IN for read mode or Gpio.DIR_OUT for write mode. Defaults to DIR_OUT.

activeLow: boolean

Specifies whether the values read from or written to the GPIO should be inverted. The interrupt generating edge for the GPIO also follow this this setting. The valid values for activeLow are true and false. Setting activeLow to true inverts. The default value is false.

---

events

If a pin is in direction of Gpio.DIR_IN. Three type of events can be fired when needed.

event:rising

When register listener to rising event the rising interrupt edges should be configured implictly and the GPIO will trigger the rising event.

gpio.on('rising', function(){
    console.log('A rising signal detected!');
});

event:falling

When register listener to falling event the falling interrupt edges should be configured implictly and the GPIO will trigger the falling event.

event:change

When register listener to change event the both(rising and falling) interrupt edges should be configured implictly and the GPIO will trigger the change event(on both rising and falling edges).

Note:

Registering events to rising and falling will implictly change the interrupt edges as well as unregistering events:

let gpio = new Gpio(40);
gpio.export(Gpio.DIR_IN);
assertEqual(gpio.edge, Gpio.EDGE_NONE); 
gpio.on('rising', function(){...});
assertEqual(gpio.edge, Gpio.EDGE_RISING); 
gpio.on('falling', function(){...});
assertEqual(gpio.edge, Gpio.EDGE_BOTH);
gpio.removeListener('rising');
assertEqual(gpio.edge, Gpio.EDGE_FALLING);
gpio.removeListener('falling'); 
assertEqual(gpio.edge, Gpio.EDGE_NONE);

Thanks

onoff - awesome API for GPIO access. A few codes are borrow from there.

rpi-gpio - first library I used to control my Raspberry Pi. Inspire me to create this project.

LICENSE

MIT