How to Use Node.js on Raspberry Pi 5 for GPIO Hardware Control

If you want to know how to use Node.js on Raspberry Pi for hardware control in 2026, the rules have changed. With the release of the Raspberry Pi 5 and the shift to Raspberry Pi OS Bookworm (Kernel 6.1+), the legacy sysfs GPIO interface (/sys/class/gpio) is disabled by default. This means older, popular libraries like onoff will silently fail or throw permission errors. To reliably control hardware, you must use a library that interfaces directly with the Pi 5’s new RP1 southbridge chip via memory mapping or the pigpiod daemon.

This guide targets the Raspberry Pi 5 (4GB variant) running Node.js 20 LTS, using the pigpio npm package to drive digital I/O and hardware PWM.

The Decision Path: Choosing Your Pi and GPIO Library

Before wiring a single LED, you need to select the right software stack. The Node.js GPIO ecosystem is fragmented, and picking the wrong library for your OS version will cost you hours of debugging.

Hardware Parts List and Pin Mapping

The Pi 5 draws more peak current than the Pi 4, especially during boot and when driving external loads. Do not use old phone chargers; brownouts will cause the RP1 chip to reset your GPIO states randomly.

Spec Sheet & Parts List

Pin Mapping Table

The Pi 5 uses the RP1 southbridge, but the physical header remains backward-compatible. We use BCM GPIO numbering in Node.js, not physical pin numbers.

Step-by-Step: OS Prep and Node.js Installation

Before writing code, we must prepare the Bookworm OS environment and compile the C++ bindings required by pigpio.

1. Flash the OS: Use Raspberry Pi Imager to flash Raspberry Pi OS (64-bit, Bookworm) to your microSD. Enable SSH and set your username/password in the advanced settings.
2. Update the System: SSH into the Pi and run:

   sudo apt update && sudo apt upgrade -y

3. Install Build Tools: The pigpio npm package requires compiling C code via node-gyp.

   sudo apt install -y build-essential python3 pigpio

4. Install Node.js 20 LTS: Use the official NodeSource setup script.

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt install -y nodejs

5. Enable the pigpiod Daemon: While the npm package can talk directly to memory, using the daemon prevents memory-access crashes if your script throws an unhandled exception.

   sudo systemctl enable pigpiod
   sudo systemctl start pigpiod

6. Initialize Project:

   mkdir pi5-node-gpio && cd pi5-node-gpio
   npm init -y
   npm install pigpio

The Code: Digital I/O with Error Handling

This script targets BCM GPIO 17 (Physical Pin 11). It blinks an LED for 10 seconds, then gracefully cleans up the pin state on exit. It includes robust error handling to catch initialization failures.

// pi5-blink.js
'use strict';

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

// --- PIN DEFINITIONS ---
// Always use BCM numbering, not physical header numbers
const LED_PIN = 17; 

// --- HARDWARE INITIALIZATION ---
let led;
try {
  // Initialize pigpio library (connects to pigpiod daemon)
  pigpio.configureClock(10, pigpio.CLOCK_PCM);
  
  // Define the pin as an output, initially LOW
  led = new Gpio(LED_PIN, {
    mode: Gpio.OUTPUT,
    pullUpDown: Gpio.PUD_DOWN,
    alert: false
  });
  
  console.log(`[SUCCESS] GPIO ${LED_PIN} initialized.`);
} catch (err) {
  console.error(`[FATAL] Failed to initialize GPIO ${LED_PIN}:`, err.message);
  console.error('Check if pigpiod is running: sudo systemctl status pigpiod');
  process.exit(1);
}

// --- MAIN LOOP ---
let state = false;
const intervalId = setInterval(() => {
  try {
    state = !state;
    led.digitalWrite(state ? 1 : 0);
    console.log(`LED State: ${state ? 'ON' : 'OFF'}`);
  } catch (err) {
    console.error('[ERROR] Write failed:', err.message);
    clearInterval(intervalId);
    cleanup();
  }
}, 500);

// Stop after 10 seconds
setTimeout(() => {
  clearInterval(intervalId);
  cleanup();
}, 10000);

// --- GRACEFUL CLEANUP ---
function cleanup() {
  console.log('[INFO] Cleaning up GPIO states...');
  try {
    if (led) {
      led.digitalWrite(0);
      // Release the pin back to the system
      led.reset(); 
    }
  } catch (err) {
    console.error('[WARN] Cleanup error:', err.message);
  }
  process.exit(0);
}

// Handle Ctrl+C (SIGINT) to prevent pin lockups
process.on('SIGINT', cleanup);
process.on('SIGTERM', cleanup);

Run the script with node pi5-blink.js. If you used the daemon approach, you do not need sudo, which is a massive security win for IoT deployments.

Debugging: Exact Error Strings and the First 3 Checks

When hardware code fails, it rarely fails silently. Here are the exact error strings you will see, ranked by likelihood, and how to fix them.

1. Error: "Error: pigpio error -8, GPIO operation not permitted"

• Cause: You are trying to access a pin that is currently reserved by the system (like the UART TX/RX pins on GPIO 14/15) or the pigpiod daemon lacks permissions.
• Fix: Verify you are using a standard GPIO pin (like 17, 27, or 22). If using direct memory mapping instead of the daemon, you must run the script with sudo.

2. Error: "Error: Cannot find module 'pigpio'" or "node-gyp rebuild" fails

• Cause: The C++ bindings failed to compile during npm install. This happens if build-essential or python3 is missing, or if you are on an unsupported Node.js version (e.g., Node 21 odd-release).
• Fix: Run sudo apt install build-essential python3, delete node_modules, and run npm install pigpio again. Stick to Node 20 LTS.

3. Error: "Error: pigpio error -2003, bad socket port"

• Cause: The Node.js script cannot communicate with the pigpiod daemon over the local socket.
• Fix: The daemon crashed or isn't running. Restart it with sudo systemctl restart pigpiod.

Extending or Simplifying the Build

Once you have digital I/O working, you will inevitably want to scale the project. Here is how to adapt this stack.

How to Simplify (Downgrade to Pi 4)

If the Pi 5's $60 price point and 27W power requirement are overkill for a simple sensor node, downgrade to a Raspberry Pi 4 Model B (2GB). You can keep the exact same pigpio code, but you gain the option to use the much simpler onoff library if you flash the older Bullseye OS. For a battery-powered, single-sensor node, a Raspberry Pi Pico W ($6) running MicroPython is a vastly superior, lower-power choice than a full Linux SBC.

How to Extend (Add I2C Sensors and PWM)

To add an environmental sensor like the BME280, do not use pigpio for I2C. Instead, install the i2c-bus npm package. The Pi 5's RP1 chip handles I2C beautifully at 400kHz.

npm install i2c-bus

For hardware PWM (e.g., driving a 5V PC fan via a MOSFET), pigpio shines. Replace the digitalWrite loop with:

// Hardware PWM on GPIO 18 (Physical Pin 12)
const fanPin = new Gpio(18, {mode: Gpio.OUTPUT});
// Set frequency to 25kHz, duty cycle to 50% (500,000 microseconds out of 1,000,000)
fanPin.hardwarePwm(25000, 500000); 

By anchoring your stack to the Raspberry Pi 5 and the pigpio daemon, you bypass the deprecated kernel interfaces and secure a reliable, high-performance foundation for any Node.js hardware project you build this year.