{"id":14752,"library":"node-red-node-pi-gpio","title":"Pi GPIO for Node-RED","description":"The node-red-node-pi-gpio package provides a set of Node-RED nodes for interacting with the General Purpose Input/Output (GPIO) pins of a Raspberry Pi. Utilizing the `RPi.GPIO` Python library, it enables flow-based control and monitoring of digital and Pulse Width Modulation (PWM) outputs, as well as digital inputs. The current stable version is 2.0.7. Releases appear to follow a milestone-based cadence rather than a strict schedule, with major version updates incorporating new features or significant changes. Key differentiators include built-in support for mouse and keyboard input detection and direct integration into the Node-RED visual programming environment, simplifying hardware interaction for IoT and automation projects on Raspberry Pi devices. It specifically notes an alternative, `node-red-node-pi-gpiod`, for more accurate servo control, indicating this package is better suited for general purpose digital and basic PWM applications.","status":"active","version":"2.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/node-red/node-red-nodes","tags":["javascript","node-red","Pi","GPIO","PiGpio"],"install":[{"cmd":"npm install node-red-node-pi-gpio","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-node-pi-gpio","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-node-pi-gpio","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment for these nodes.","package":"node-red","optional":false}],"imports":[{"note":"This package provides nodes for Node-RED, not JavaScript symbols for direct `import` statements. Nodes are added to the Node-RED palette upon successful npm installation into the Node-RED user directory.","symbol":"Pi GPIO Input Node","correct":"Install via Node-RED palette manager or `npm i node-red-node-pi-gpio`"},{"note":"These nodes are accessed visually within the Node-RED flow editor after installation, appearing in the palette under the 'rpi gpio' category.","symbol":"Pi GPIO Output Node","correct":"Install via Node-RED palette manager or `npm i node-red-node-pi-gpio`"},{"note":"This node detects keyboard clicks and mouse button events directly from the hardware, bypassing application focus. Functionality may vary across different OS setups (YMMV).","symbol":"Pi GPIO Keyboard/Mouse Node","correct":"Install via Node-RED palette manager or `npm i node-red-node-pi-gpio`"}],"quickstart":{"code":"/*\n  This quickstart demonstrates how to install 'node-red-node-pi-gpio' and describes a basic Node-RED flow setup.\n  Since this is a Node-RED node package, direct JavaScript runtime usage is not applicable.\n  The instructions guide you through setting up a simple input-to-debug and inject-to-output flow in the Node-RED editor.\n*/\n\n// Step 1: Install the Node-RED node package.\n// You should run this command in your Node-RED user directory (typically ~/.node-red)\n// or use the 'Manage Palette' option within the Node-RED editor.\nconsole.log(\"Executing installation command:\\n  npm i node-red-node-pi-gpio\\n\");\n\n// After installation, restart Node-RED if prompted or if nodes do not appear in the palette.\nconsole.log(\"Installation complete. If nodes are not visible, restart Node-RED (e.g., 'node-red-start').\\n\");\n\n// Step 2: Configure a basic flow in the Node-RED editor (usually accessible at http://localhost:1880).\nconsole.log(\"--- Node-RED Flow Configuration Guide ---\");\nconsole.log(\"1. Drag an 'rpi gpio in' node from the palette onto your flow canvas.\");\nconsole.log(\"   - Double-click the 'rpi gpio in' node: Select a BCM GPIO number (e.g., 4) and configure pull-up/down resistors if needed.\");\nconsole.log(\"2. Drag a 'debug' node onto the canvas.\");\nconsole.log(\"   - Connect the output of the 'rpi gpio in' node to the input of the 'debug' node.\");\nconsole.log(\"   - When the state of GPIO 4 changes, you will see '0' or '1' in the debug sidebar.\");\nconsole.log(\"3. Drag an 'inject' node onto the canvas.\");\nconsole.log(\"   - Double-click the 'inject' node: Set 'Payload' to a number (e.g., 1 for digital high, or 50 for 50% PWM).\");\nconsole.log(\"4. Drag an 'rpi gpio out' node onto the canvas.\");\nconsole.log(\"   - Double-click the 'rpi gpio out' node: Select a BCM GPIO number (e.g., 17) and choose 'Digital output' or 'PWM output' mode.\");\nconsole.log(\"5. Connect the output of the 'inject' node to the input of the 'rpi gpio out' node.\");\nconsole.log(\"   - Clicking the 'inject' node's button will now set the state of GPIO 17.\");\nconsole.log(\"6. Click the 'Deploy' button in the Node-RED editor to activate your flow.\");\n\n// Note: On non-Raspbian systems, additional Python library and Udev rules setup is required. (Refer to warnings for details).\n","lang":"javascript","description":"Describes the installation process and guides a user through creating a basic Node-RED flow with Pi GPIO Input, Output, and Debug/Inject nodes."},"warnings":[{"fix":"Execute the following commands: `sudo apt-get install python-pip python-dev`, `sudo pip install RPi.GPIO`, `sudo addgroup gpio`, `sudo chown root:gpio /dev/gpiomem`, `sudo adduser $USER gpio`, `echo 'KERNEL==\"gpiomem\", NAME=\"%k\", GROUP=\"gpio\", MODE=\"0660\"' | sudo tee /etc/udev/rules.d/45-gpio.rules`, `sudo udevadm control --reload-rules && sudo udevadm trigger`.","message":"This package relies on the `RPi.GPIO` Python library and specific system permissions. On non-Raspbian operating systems (e.g., Ubuntu, Debian on a Pi), you *must* manually install `python-pip`, `python-dev`, the `RPi.GPIO` Python package, configure `udev` rules, and add your user to the `gpio` group. Failure to do so will result in GPIO access errors.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Consider using the `node-red-node-pi-gpiod` package instead, which leverages the `pigpiod` daemon for more precise hardware-timed PWM control suitable for servos.","message":"For applications requiring highly accurate or fine-grained servo control, this package's PWM mode may not be sufficient. The underlying `RPi.GPIO` library can have timing inaccuracies for demanding PWM tasks.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always cross-reference the BCM GPIO numbering for your Raspberry Pi model (e.g., using online pinout diagrams) to ensure you are configuring the intended physical pin.","message":"When configuring GPIO pins, ensure you are using the correct BCM GPIO number, not the physical pin number. The Node-RED configuration diagram shows pin numbers for reference, but the input field expects the Broadcom (BCM) GPIO numbering scheme.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For Digital mode, `msg.payload` should be `0`, `1`, `true`, or `false`. For PWM mode, `msg.payload` must be a number between `0` and `100` (representing percentage duty cycle). Use a Node-RED `range` node to scale inputs if necessary.","message":"The `rpi gpio out` node expects different `msg.payload` types depending on whether it's configured for Digital or PWM mode. Sending the wrong type or range can lead to unexpected behavior.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the Python `RPi.GPIO` library using `sudo pip install RPi.GPIO`. Ensure `python-pip` and `python-dev` are also installed (`sudo apt-get install python-pip python-dev`).","cause":"The Python `RPi.GPIO` library is not installed or not accessible to the user running Node-RED.","error":"Error: RPi.GPIO module not found"},{"fix":"Add the Node-RED user (or the user running Node-RED) to the `gpio` group and ensure correct `udev` rules are in place. Run: `sudo addgroup gpio`, `sudo chown root:gpio /dev/gpiomem`, `sudo adduser $USER gpio`, `echo 'KERNEL==\"gpiomem\", NAME=\"%k\", GROUP=\"gpio\", MODE=\"0660\"' | sudo tee /etc/udev/rules.d/45-gpio.rules`, then `sudo udevadm control --reload-rules && sudo udevadm trigger`. Replace `$USER` with the actual user Node-RED runs as.","cause":"The user running Node-RED lacks the necessary permissions to directly access the GPIO pins on the Raspberry Pi.","error":"Permission denied to /dev/gpiomem (or similar GPIO access error)"},{"fix":"For applications requiring high precision PWM (like servo control), switch to `node-red-node-pi-gpiod`. This package uses the `pigpiod` daemon for hardware-timed PWM, offering significantly better accuracy.","cause":"The `node-red-node-pi-gpio` package uses software-driven PWM which can be affected by system load and scheduling, leading to timing jitters.","error":"PWM output is erratic or inaccurate, especially with servos."}],"ecosystem":"npm"}