Raspberry Pi GPIO

The GpioPin class provides a simple and safe way to control the General Purpose Input/Output (GPIO) pins on a Raspberry Pi. GPIO pins are the physical pins on the Pi that allow you to control electronic components like LEDs, read data from buttons and sensors, and interact with the physical world.

Important: This class only works when your application is running on a Raspberry Pi. It will not work on a standard PC or server. You can use the isAccessible() static function to check if the hardware is compatible before trying to create a pin.

Each pin can be configured as either an input (to read data) or an output (to send signals).

Output: Used to turn things on and off. For example, sending a 1 (high) signal to turn on an LED, or a 0 (low) signal to turn it off.
Input: Used to read the state of a component. For example, checking if a button is pressed (1) or not pressed (0). Inputs can also be configured with internal "pull-up" or "pull-down" resistors to prevent a "floating" state.

Static Functions

isAccessible

Checks if the GPIO hardware is accessible on the system. This is the best way to determine if your application is running on a compatible Raspberry Pi and has the correct permissions to control the pins.

Output

Returns true if GPIO pins can be used, otherwise returns false.

Constructor and Member Functions

create

This is the constructor. It creates, configures, and reserves a single GPIO pin for use. You must provide the pin number (using BCM numbering) and its intended direction.

Parameters

options: An object containing all configuration settings for the pin.
- gpio: (Required) The BCM pin number you want to control (e.g., 17).
- direction: (Required) Specifies how the pin will be used.
  - 'out': Output pin, initialized to a low state (0).
  - 'in': Input pin.
  - 'high': Output pin, initialized to a high state (1).
  - 'low': Same as 'out'.
- pullUpDown: (Optional) For input pins, activates an internal resistor. Defaults to 'none'.
  - 'pullup': Pulls the pin's default state to high (1). Recommended for buttons where pressing the button connects it to ground (0).
  - 'pulldown': Pulls the pin's default state to low (0).
- edge: (Optional) For input pins, specifies which signal change should trigger an onChange event. Defaults to 'rising'.
  - 'rising': Triggers on a change from low to high (0 -> 1).
  - 'falling': Triggers on a change from high to low (1 -> 0).
  - 'both': Triggers on any change.
- debounceTimeout: (Optional) For input pins, specifies a time in milliseconds (e.g., 50) to wait for the signal to stabilize. This is highly recommended for physical buttons to prevent a single press from registering multiple times.
- activeLow: (Optional) Inverts the pin's logic. If true, writing 1 sets the pin to low voltage, and 0 sets it to high voltage. Defaults to false.

Example 1: Basic Output Pin (LED)

This configures GPIO pin 17 as a standard output pin, ready to turn an LED on or off.

# options
gpio: 17
direction: 'out'

Example 2: Input Pin (Button)

This configures GPIO pin 22 as an input for a button. It uses an internal pullup resistor (meaning the pin will read 1 by default) and a debounceTimeout of 50ms. The edge is set to 'falling', so onChange events will only fire when the button is pressed (changing the signal from 1 to 0).

# options
gpio: 22
direction: 'in'
pullUpDown: 'pullup'
edge: 'falling'
debounceTimeout: 50

Output

Returns a new GpioPin instance. You must use this instance to call all the member functions listed below (like write, read, etc.).

getPinNumber

Gets the BCM pin number that this instance is controlling.

getDirection

Gets the configured direction for this pin (e.g., 'in' or 'out').

isDisposed

Checks if the pin has been disposed (released). A disposed pin can no longer be used.

Output

Returns true if the pin has been released, otherwise false.

write

Asynchronously writes a value to an output pin. This is the non-blocking, recommended way to write a value.

Parameters

value: The digital value to write: 0 (low) or 1 (high).

Example

# value
1

writeSync

Synchronously writes a value to an output pin. This function will block all other execution until the write is complete. Use this with caution; the write (async) function is generally preferred.

Parameters

value: The digital value to write: 0 (low) or 1 (high).

Example

# value
0

read

Asynchronously reads the current value of an input pin. This is the non-blocking, recommended way to read a value.

Output

Returns the pin's current value, 0 (low) or 1 (high).

readSync

Synchronously reads the current value of an input pin. This function will block all other execution until the read is complete. Use this with caution; the read (async) function is generally preferred.

Output

Returns the pin's current value, 0 (low) or 1 (high).

onChange

Subscribes to value changes on an input pin. The listener flow you provide will be executed every time the pin's value changes in a way that matches the edge configuration set in the create constructor.

Parameters

listener: The flow to execute when the event fires.

Input to your Listener Flow: When this event fires, your listener flow will receive an object with two keys:
err: An error object if one occurred (usually null).
value: The new value of the pin (0 or 1).

removeAllListeners

Removes all listener flows that were previously attached to this pin instance via onChange().

dispose

Releases the GPIO pin, making it available for other processes to use. Once a pin is disposed, you can no longer use its instance to read, write, or listen for events.

Last updated 15 hours ago