rpi-io 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Guillaume DORBES
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,438 @@
+# rpi-io
+![Static Badge](https://img.shields.io/badge/rpi--io-_1.1_-FF5500?style=flat) ![Static Badge](https://img.shields.io/badge/Nodejs-%3E_23-66cc33?logo=nodedotjs&logoColor=white) ![Static Badge](https://img.shields.io/badge/NPM-%3E_10-CC3534?logo=npm&logoColor=white) ![Static Badge](https://img.shields.io/badge/Raspberry_Pi-Zero2_4B_5B-C51A4A?logo=raspberrypi&logoColor=white) ![Static Badge](https://img.shields.io/badge/OS-Bookworm_Trixie-0D7AB9?style=flat)
+
+
+**rpi-io** is a lite [ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules) module for **Node.js** to control **Raspberry Pi** GPIO: access (in, out), input event detection and [PWM](https://en.wikipedia.org/wiki/Pulse-width_modulation) peripheral control.
+
+**rpi-io** supports only recent versions of Raspberry and related OS and middlewares :
+
+- Raspberry Pi models: *RPi 5,* *RPi 4B* and *RPi Zero 2.*
+- Raspberry Pi OS (64-bit): Debian *Bookworm* and *Trixie*.
+- Middlewares (installed by default with OS distribution):
+  - Input/Output - [libgpiod](https://libgpiod.readthedocs.io/en/stable/) v1.6.3 (*Bookworm*) and v2.2.1 (*Trixie*)
+  - PWM - [sysfs](https://en.wikipedia.org/wiki/Sysfs) interface.
+
+## Installation
+
+````shell
+npm install rpi-io
+````
+
+## Configuration
+
+By default rpi-io does not require specific configuration.
+
+If you want to use [hardware-base PWM](https://pinout.xyz/pinout/pwm) peripherals, some configuration is required:
+
+- Open the file  `/boot/firmware/config.txt` and add the required [dtoverlay](https://www.raspberrypi.com/documentation/computers/configuration.html#part3.1) configuration for PWM as showned in the examples below.
+
+```shell
+# Examples of PWM configuration to add to/boot/firmware/config.txt
+# Default one-channel config: GPIO 18 as channel 0
+[all]
+dtoverlay=pwm
+# Default two-channel config: GPIO 18 as channel 0 and GPIO 19 as channel 1
+[all]
+dtoverlay=pwm-2chan
+# Custom two-channel config: GPIO 12 as channel 0 and GPIO 13 as channel 1
+[all]
+dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4
+```
+
+- Reboot the Raspberry Pi.
+- Test the PWM configuration.
+
+```shell
+# Testing PWM configuration after reboot
+pinctrl get 12
+# 12: a0    pd | lo // GPIO12 = PWM0_CHAN0
+pinctrl get 13
+# 13: a0    pd | lo // GPIO13 = PWM0_CHAN1
+pinctrl get 18
+# 18: no    pd | -- // GPIO18 = none
+pinctrl get 19
+# 19: no    pd | -- // GPIO19 = none
+```
+
+## Usage
+
+PLEASE NOTE: In all this document, GPIOs numbers are the BCM ones as defined in https://pinout.xyz/.
+
+### *OUT* operations
+
+#### LED control
+
+![Connecting a LED to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-led.png)
+
+```javascript
+// Import rpi-io module
+import {Rio} from "rpi-io";
+// Define instance for OUT operation on some GPIO
+const led = new Rio(17, "out");
+// Turn the led on
+led.set(1);
+// Turn the led off
+led.set(0);
+```
+
+#### Active buzzer beep
+
+`set` method has an optional *time* parameter to invert the command after some delay (ms). It may be useful to beep a buzzer.
+
+![Connecting an active buzzer to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-active-buzzer.png)
+
+```javascript
+// Import rpi-io module
+import {Rio} from "rpi-io";
+// Define instance for OUT operation on some GPIO
+const buzzer = new Rio(23, "out");
+// Turn the buzzer on for 3 seconds
+buzzer.set(1, 3000);
+```
+
+### *IN* operations
+
+#### Getting button status and listening to input events
+
+![Connecting a pull-down button to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-pull-down-btn.png)
+
+```javascript
+// Import rpi-io module
+import {Rio} from "rpi-io";
+
+// Define instance for IN operation on some GPIO
+const button = new Rio(18, "in");
+
+// Get the instant value of the button
+button.get(); // Return 0 (opened) or 1 (closed)
+
+// Monitor button events ("rising, "falling" or "both")
+// and receive results in callback function
+button.monitor("both", (event) => {
+    // event.edge = "rising" or "falling"
+    // event.time = timestamp
+    console.log("event:", event.edge, event.time)
+});
+```
+
+### PWM operations with servo motor in hardware mode
+
+REMINDER: PWM peripherals used in hardware mode need some specific [configuration](#Configuration).
+
+![PWM servo motor connected to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-servo-motor.png)
+
+
+```javascript
+// Import rpi-io module
+import {Rio} from "rpi-io";
+
+// Define instance for PWM operation on some PWM GPIO
+const servoMotor = new Rio(13, "pwm");
+
+// PWM servo motor parameters depends motor specifications.
+//     - period = 20,000,000 nano-seconds = 20 milli-seconds ~ frequency = 50 Hz
+//	   - duty cycle on start = 500,000 nano-seconds = 0.5 milli-seconds
+//		 - dutyMin = 0.5 ms ~ 0°
+//		 - dutyMax = 2.5 ms ~ 180°
+servoMotor.pwmInit(20000000, 500000, {
+    dutyMin: 500000,
+    dutyMax: 2500000
+});
+console.log("servo position = 0°");
+
+// Wait 2s then change duty cyle to 1.5 ms
+setTimeout(() => {
+    servo.pwmDuty(1500000);
+    console.log("servo position = 90°");
+}, 2000);
+```
+
+## API
+
+The **rpi-io** API is based on the class `Rio` with instance methods and static functions.
+
+### Constructor and generic methods
+
+####  Constructor - Rio(gpio, type)
+
+##### Example 
+```javascript
+import {Rio} from "rpi-io";
+const myOutput = new Rio(17, 'out');
+```
+##### Parameters
+- **gpio** *{Number}*  Must be one of the GPIO number as defined in [pinout.xyz](pinout.xyz). 
+- **type** *{String}* Must be one of the following values: 'in', 'out', 'pwm'.
+
+##### Detected errors
+- Operating system version is not supported
+- *libgpiod* version is not supported
+- **gpio** is not defined as GPIO in [pinout.xyz](pinout.xyz). 
+- **gpio** is already used by another instance.
+- **type** value is not recognized.
+- **type**='pwm' and **gpio** is not properly configured.
+
+
+
+####  Method - disable()
+To remove an instance from the list.
+
+##### Example 
+```javascript
+myOutput.disable();
+```
+
+### Methods for instances where type='out'
+#### set(value, duration)
+
+To set some *out* GPIO to 0 or 1.
+
+##### Example 
+```javascript
+import {Rio} from "rpi-io";
+const myOutput = new Rio(17, 'out');
+myOutput.set(1, 3000);
+```
+##### Parameters
+- **value** *{Number}* 0 or 1
+- **duration** *{Number}*  Time in ms. When defined, at the end of the defined time the output is inverted.
+
+##### Detected errors
+- Instance type is not 'out'.
+- Instance is disabled or undefined.
+
+
+
+### Methods for instances where type='in'
+
+#### get()
+
+To read instant value of some *in* GPIO.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+const myInput = new Rio(18, 'in');
+let currentValue = myInput.get();
+```
+
+##### Returned value
+
+0 or 1
+
+##### Detected errors
+
+- Instance type is not 'in'.
+- Instance is disabled or undefined.
+
+
+
+#### monitor(edge, callback)
+
+To monitor activities on some *in* GPIO and receive events in a callback function.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+const myButton = new Rio(18, 'in');
+myButton.monitor("both", event => {
+    console.log("event:", event.edge, event.time)
+});
+```
+
+##### Parameters
+
+- **edge** *{String}* 'rising', 'falling' or 'both'. Any other value stops  instance monitoring.
+- **callback** *{Function}*  Callback function with one Object parameter for input events on instance e.g. `event = {edge: 'rising,' time: 'Thu Oct 30 2025 18:12:35 GMT+0100'}`
+
+##### Detected errors
+
+- Instance type is not 'in'.
+- Instance is disabled or undefined.
+
+
+
+### Methods for instances where type='pwm'
+#### pwmInit(period, duty, options)
+
+To initialize some *pwm* GPIO according to connected device specifications.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+const servoMotor = new Rio(13, "pwm");
+servoMotor.pwmInit(20000000, 500000, {
+    dutyMin: 500000,
+    dutyMax: 2500000
+});
+console.log("servo position = 0°");
+```
+
+##### Parameters
+
+All time parameters are defined in nano-seconds (ns).
+
+- **period** *{Number}* Time period in which [duty cycle](https://en.wikipedia.org/wiki/Pulse-width_modulation) varies.
+- **duty** *{Number}* Initial duty cycle.
+- **options** *{Object}*  
+  - **dutyMin** *{Number}* Default = 0. Minimum duty cycle (ns) as defined in connected device specifications. 
+  - **dutyMax** *{Number}* Default = 1,000,000,000. Maximum duty cycle (ns) as defined in connected device specifications. 
+
+##### Detected errors
+
+- Instance type is not 'pwm'.
+- Instance is disabled or undefined.
+- **period** is out-of-range [100, 1,000,000,000]
+- **duty** < **options.dutyMin**
+- **duty** > **options.dutyMax**
+
+
+
+#### pwmStop()
+
+To stop PWM modulation on some *pwm* GPIO.
+
+##### Example
+
+```javascript
+servoMotor.pwmStop()
+```
+
+##### Detected errors
+
+- Instance type is not 'pwm'.
+- Instance is disabled or undefined.
+
+
+
+#### pwmDuty(time)
+
+To update duty cycle of some *pwm* GPIO.
+
+##### Example
+
+```javascript
+servo.pwmDuty(1500000)
+```
+
+##### Parameters
+
+- **time** *{Number}* Duty cycle (ns)
+
+##### Detected errors
+
+- Instance type is not 'pwm'.
+- PWM instance is not properly initialized.
+- **time** is out of range [dutyMin, dutyMax]
+
+
+
+### Utility functions
+#### Rio.config(gpio)
+
+To return configuration of some GPIO
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+console.log(Rio.config(13))
+// '13': 'pwm0_chan1'
+```
+
+#### Rio.info()
+
+Javascript equivalent of command `gpioinfo`.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+console.log(Rio.info())
+```
+
+#### Rio.detect()
+
+Javascript equivalent of command `gpiodetect`.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+console.log(Rio.detect())
+```
+
+#### Rio.version()
+
+To retrieve libgpiod version.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+console.log(Rio.version())
+// 'v1.6.3',
+```
+
+#### Rio.os()
+
+To retrieve Rapsberry Pi OS info.
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+console.log(Rio.os())
+// {id: '12', name: 'Bookworm'}
+```
+
+#### Rio.isSystemSupported()
+
+To check if device is supported by **rpi-io** (device, model, os, middleware). It returns  *true/false* and displays details in console.
+
+#### Rio.log(level)
+To set the level of console used in the module:
+
+- 0: no console
+- 1: console only for errors and warnings (default).
+- 2: more logged data
+
+##### Example
+
+```javascript
+import {Rio} from "rpi-io";
+Rio.log(0)
+Rio.isSystemSupported() // Nothing displayed in console
+Rio.log(2)
+Rio.isSystemSupported() // See console below
+// 08:15:16.506 🔎  👍  Hardware is Raspberry Pi
+// 08:15:16.539 🔎  👍  Raspberry Pi 5 Model B Rev 1.0 is supported
+// 08:15:16.543 🔎  👍  Bookworm OS is supported
+// 08:15:16.545 🔎  👍  libgpiod version v1.6.x is supported
+// 08:15:16.545 🔎  👍  Systems requirements for rpi-io are met
+```
+
+
+
+## Additional information 
+
+### Benchmark
+
+The following table summarizes GPIO *set* average times with rpi-io v1.1.0 and various hardwares and OS.
+
+|          | RPi 5B  | RPi 4B     | RPi Zero2   |
+| -------- | ------- | ---------- | ----------- |
+| Bookworm | 1.37 ms | 4.56 ms    | 9.07 ms     |
+| Trixie   | 3.82 ms | not tested | not tested. |
+
+
+
+### Keywords
+
+**raspberry pi rpi gpio pwm nodejs esm**
+
+---
+

package/esm/dev.mjs

@@ -0,0 +1,59 @@
+// -------------------------------------------------------------------
+// RPi GPIO CONTROL - DEV TOOLS
+// -------------------------------------------------------------------
+let debug = {
+    log: false,
+    trap: true
+}
+
+// -------------------------------------------------------------------
+// FUNCTIONS
+/** ------------------------------------------------------------------
+ * @function now
+ * @description Return timestamp as formatted string
+ * @return {String}
+ */
+export const now = () => {
+    const date = new Date()
+    return date.toLocaleTimeString() + "." + date.getMilliseconds().toLocaleString('en', {
+        minimumIntegerDigits: 3,
+        minimumFractionDigits: 0,
+        useGrouping: false
+    })
+}
+
+/** ------------------------------------------------------------------
+ * @function log
+ * @description Global customized timestamped console.log
+ *              Requires global variable 'debug'
+ */
+export const log = function () {
+    if (debug.log)
+        console.log.apply(console, Array.prototype.concat.apply([now(), "🔎 "], arguments))
+}
+
+/** ------------------------------------------------------------------
+ * @function trap
+ * @description Colored log for error messages ⚠️ nodejs only ~ CSS color #F50
+ */
+export const trap = function () {
+    if (debug.trap)
+        console.log.apply(console, Array.prototype.concat.apply([now(), "⚠️", "\x1b[38;2;255;80;0m", ...arguments, "\x1b[0m"]))
+}
+
+/** ------------------------------------------------------------------
+ * @function cfgLog
+ * @description Set log configuration
+ * @param {Number} level    0: no log, 1: trap only, 2: trap and log
+ */
+export const cfgLog = level => {
+    debug = {
+        log: false,
+        trap: false
+    }
+    level > 1 ? debug.log = true : false
+    level > 0 ? debug.trap = true : false
+}
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/esm/rio.mjs

@@ -0,0 +1,553 @@
+// -------------------------------------------------------------------
+// JS GPIO API: IN, OUT, PWM
+// Source: https://libgpiod.readthedocs.io/en/stable/gpio_tools.html
+// Details: man gpiodetect
+// -------------------------------------------------------------------
+import {spawn} from "child_process";
+import {writeFileSync, readFileSync} from "fs"
+import {exeFile, exeShell, wait} from "./utl.mjs"
+import {cfgLog, log, trap} from "./dev.mjs"
+
+// -------------------------------------------------------------------
+// CLASS RIO AND FURTHER
+/** ------------------------------------------------------------------
+ * @class RIO
+ * @classDesc Raspberry IO
+ * @param {Number} gpio
+ */
+export class Rio {
+
+    // ---------------------------------------------------------------
+    // CONSTANTS AND VARIABLES AND FUNCTIONS
+    // ---------------------------------------------------------------
+    // Tested system environments: model, os, libgpiod
+    static TESTED_MODELS = ["Raspberry Pi 5 Model B Rev 1.0"]
+    static TESTED_OS = ["Bookworm", "Trixie"]
+    static TESTED_LIBGPIOD = ["v1.6.3", "v2.2.1"]
+
+    // Lists of supported GPIOs. Reference GPIO: pinout.xyz
+    static RPi_GPIO_CORE = [4, 5, 6, 16, 17, 20, 21, 22, 23, 24, 25, 26, 27]
+    static RPi_GPIO_PWM = [12, 13, 18, 19]
+    static RPI_GPIOS = [...Rio.RPi_GPIO_CORE, ...Rio.RPi_GPIO_PWM]
+    static RPI_CHIP = "gpiochip0"
+    static PWM_CHIP = "pwmchip0"
+    static TYPES = ["in", "out", "pwm"]
+
+    // List of used GPIOs
+    static used_gpios = []
+    // Object list of monitored inputs
+    static monitored = {}
+    // Current monitoring process
+    static monitoringProcess = null
+
+    // ---------------------------------------------------------------
+    // GENERIC METHODS: constructor, disable
+    /** --------------------------------------------------------------
+     * @function constructor
+     * @description
+     * @param {Number} gpio
+     * @param {String} type - {'in', 'out', 'pwm'}
+     * @return {Object}
+     */
+    constructor(gpio, type) {
+
+        this.chip = Rio.RPI_CHIP
+        this.gpio = gpio
+        this.gpioStr = this.gpio.toString()
+        this.gpioName = "GPIO" + this.gpioStr
+        this.type = type
+        this.os = Rio.os().name
+        this.versionLib = Rio.version().substring(0, 4)
+
+        // OS is not supported
+        if (Rio.TESTED_OS.indexOf(this.os) === -1)
+            throw new Error("This OS is not supported: " + this.os)
+
+        // libgpiod is not supported
+        const foundLib = Rio.TESTED_LIBGPIOD.find(testedVersion => {
+            return this.versionLib === testedVersion.substring(0, 4)
+        })
+        if (!foundLib)
+            throw new Error("This version of libgpiod is not supported: " + this.versionLib)
+
+        // Unknown type
+        if (Rio.TYPES.indexOf(type) === -1)
+            throw new Error("This type is not supported: " + gpio)
+
+        // gpio is not supported
+        if (Rio.RPI_GPIOS.indexOf(gpio) === -1)
+            throw new Error("This gpio is not supported: " + gpio)
+
+        // gpio is already used
+        if (Rio.used_gpios.indexOf(gpio) !== -1)
+            throw new Error("This gpio is already used: " + gpio)
+
+        // this.read, this.write, monArgs depending on gpiolib version
+        switch (this.versionLib) {
+            case "v1.6":
+                this.write = (value, time = 0) => {
+                    exeFile("gpioset", [Rio.RPI_CHIP, this.gpioStr + "=" + value])
+                }
+                this.read = () => {
+                    return exeFile("gpioget", [Rio.RPI_CHIP, this.gpioStr])
+                }
+                this.monArgs = gpios => {
+                    let args = []
+                    args.push("-b") // line-buffered: output is flushed after every line
+                    args.push("--format=%o %e") // gpio, edge. Others: seconds(%s) and nanoseconds (%n)
+                    args.push(Rio.RPI_CHIP)
+                    args = args.concat(gpios)
+                    return args
+                }
+                this.monData = data => {
+                    const [gpio, edge] = data.toString().trim().split(/\s+/)
+                    return {
+                        gpio: gpio,
+                        edge: edge
+                    }
+                }
+                break
+            case "v2.2":
+                this.write = (value, time = 0) => {
+                    exeFile("gpioset", ["-t" + time, this.gpioName + "=" + value])
+                }
+                this.read = () => {
+                    return exeFile("gpioget", ["--numeric", this.gpioName])
+                }
+                this.monArgs = gpios => {
+                    gpios = gpios.map(gpio => "GPIO" + gpio)
+                    let args = []
+                    args = args.concat(gpios)
+                    return args
+                }
+                this.monData = data => {
+                    const [time, edge, gpio] = data.toString().trim().split(/\s+/)
+                    return {
+                        gpio: gpio.substring(5,7),
+                        edge: edge
+                    }
+                }
+                break
+        }
+
+        // pwm specific cases
+        if (type === "pwm") {
+
+            // gpio is not supported for PWM
+            if (Rio.RPi_GPIO_PWM.indexOf(gpio) === -1) {
+                throw new Error("PWM gpio must be one of " + Rio.RPi_GPIO_PWM)
+            }
+
+            // gpio is not setup for PWM
+            const thisConfig = Rio.config(gpio)
+            if (thisConfig.indexOf("pwm") === -1)
+                throw new Error("This gpio is not setup as PWM (see README)")
+
+            this.channel = thisConfig.slice(-1)
+            this.pwm = Rio.PWM_CHIP
+            this.pathPwm = "/sys/class/pwm/" + this.pwm + "/"
+            this.pathChannel = this.pathPwm + "pwm" + this.channel + "/"
+        }
+    }
+
+    /** --------------------------------------------------------------
+     * @function disable
+     * @description Remove instance from Rio.used_gpios
+     *              Set this.gpio = -1
+     */
+    disable() {
+        const i = Rio.used_gpios.indexOf(this.gpio)
+        if (this.gpio === -1 || i === -1) {
+            log("gpio", this.gpio, "is already disabled")
+        } else {
+            Rio.used_gpios.splice(i, 1)
+            log("gpio", this.gpio, "has been disabled")
+            this.gpio = -1
+        }
+    }
+
+    // ---------------------------------------------------------------
+    // OUTPUT METHODS: set
+    /** --------------------------------------------------------------
+     * @function set
+     * @description Set gpio to 1 or 0
+     *              Then invert when duration time is <> 0
+     * @param {Number} value
+     * @param {Number} duration ms
+     */
+    set(value = 0, duration = 0) {
+
+        if (this.gpio === -1)
+            throw new Error("This instance is disabled")
+
+        if (this.type !== "out")
+            throw new Error("Set is dedicated to 'out' instances")
+
+        if ([0, 1].indexOf(value) === -1)
+            throw new Error("Value must be either 0 or 1")
+
+        if (duration === 0) {
+            this.write(value)
+            log("set gpio", this.gpio, "to", value)
+        }
+        // Optional timer
+        else {
+            this.write(value)
+            log("set gpio", this.gpio, "to", value)
+            setTimeout(() => {
+                const valueStop = Math.abs(value - 1)
+                this.write(valueStop)
+                log("set gpio", this.gpio, "to", valueStop)
+            }, duration)
+        }
+    }
+
+    // ---------------------------------------------------------------
+    // INPUT METHODS
+    /** --------------------------------------------------------------
+     * @function get
+     * @description Get gpio value (0/1)
+     */
+    get() {
+        if (this.gpio === -1)
+            throw new Error("This instance is disabled")
+
+        if (this.type !== "in")
+            throw new Error("Get is dedicated to 'in' instances")
+
+        const str = this.read()
+
+        let result
+        str.length === 0 ? result = -1 : result = parseInt(str.replace(/\r?\n|\r/, ""))
+        log("get gpio", this.gpio, "value:", result)
+        return result
+    }
+
+    /** --------------------------------------------------------------
+     * @function monitor
+     * @description Wait for edge events
+     * @param {String} edge {'stop', 'rising', 'falling' 'both'}
+     * @param {Function} callback (edge, time)
+     */
+    monitor(edge, callback) {
+
+        if (this.gpio === -1)
+            throw new Error("This instance is disabled")
+
+        if (this.type !== "in")
+            throw new Error("Monitor is dedicated to 'in' instances")
+
+        // Update monitoring list
+        Rio.monitored[this.gpio] = {
+            edge: edge,
+            callback: callback
+        }
+
+        // Suspend current monitoring if any
+        if (Rio.monitoringProcess !== null) {
+            Rio.monitoringProcess.kill("SIGTERM")
+            Rio.monitoringProcess = null
+        }
+
+        // Default stop command => Remove current gpio from monitoring list
+        if (["rising", "falling", "both"].indexOf(edge) === -1) {
+            delete Rio.monitored[this.gpio]
+            log("gpio", this.gpio, "is no longer being monitored")
+        }
+
+        // If monitored list is not empty => relaunch gpiomon
+        const list = Object.keys(Rio.monitored)
+        if (list.length > 0) {
+            Rio.monitoringProcess = spawn("gpiomon", this.monArgs(list))
+            Rio.monitoringProcess.stdout.on("data", data => {
+                // Retrieve event data
+                const evd = this.monData(data)
+                const that = Rio.monitored[parseInt(evd.gpio)]
+                if (typeof that.callback === "function") {
+                    if (evd.edge === "1") {
+                        if (that.edge === "rising" || that.edge === "both")
+                            that.callback("rising", new Date())
+                    } else {
+                        if (that.edge === "falling" || that.edge === "both")
+                            that.callback("falling", new Date())
+                    }
+                }
+            })
+            Rio.monitoringProcess.stderr.on("data", data => {
+                trap("gpiomon stderr:", Buffer.from(data).toString())
+            })
+        } else {
+            log("no more gpio to monitor")
+        }
+    }
+
+    // ---------------------------------------------------------------
+    // PWM METHODS
+    // PLEASE NOTE - Commands to unlock a channel:
+    //        pwm channel 0: echo 0 > /sys/class/pwm/pwmchip0/unexport
+    //        pwm channel 0: echo 1 > /sys/class/pwm/pwmchip0/unexport
+    /** --------------------------------------------------------------
+     * @function pwmInit
+     * @description Start PWM modulation
+     * @param {Number} period in ns
+     * @param {Number} duty cycle in ns
+     * @param {Object} opt
+     */
+    pwmInit(period = 20000000, duty = 0, opt) {
+
+        // Stop on wrong type
+        if (this.type !== "pwm")
+            throw new Error("This GPIO is not configured as PWM")
+
+        // Stop disabled device
+        if (this.gpio === -1)
+            throw new Error("This instance is disabled")
+
+        // Set default options
+        const defopt = {
+            dutyMin: 0,
+            dutyMax: 1000000000, // 1s
+        }
+        opt = {...defopt, ...opt}
+
+        this.period = period
+        this.duty = duty
+        this.dutyMin = Math.max(0, opt.dutyMin)
+        this.dutyMax = Math.min(period, opt.dutyMax)
+
+        // Check period
+        if (this.period < 100 || this.period > 1000000000)
+            throw new Error("PWM period is out of range (100ns - 1s")
+
+        // Check duty cycle
+        if (duty < this.dutyMin)
+            throw new Error("PWM duty", duty, " is lower than duty min", this.dutyMin)
+        if (duty > this.dutyMax)
+            throw new Error("PWM duty", duty, " is upper than duty max", this.dutyMax)
+
+        log("channel", this.channel, "normalized PWM data (period, duty, duty min, duty max):", this.period, this.duty, this.dutyMin, this.dutyMax)
+
+        // Export channel, then set period, duty cycle and enable
+        writeFileSync(this.pathPwm + "export", this.channel)
+        this.exported = true
+
+        try {
+            wait(100)
+            writeFileSync(this.pathChannel + "period", String(this.period))
+            writeFileSync(this.pathChannel + "duty_cycle", String(this.duty))
+            writeFileSync(this.pathChannel + "enable", "1")
+            this.enabled = true
+
+        } catch (err) {
+            trap("pwm start error:", err)
+            this.pwmStop()
+        }
+    }
+
+    /** --------------------------------------------------------------
+     * @function pwmStop
+     * @description Stop PWM modulation
+     */
+    pwmStop() {
+
+        if (this.type !== "pwm")
+            throw new Error("This GPIO is not configured as PWM")
+
+        // Disable signal then unexport channel
+        writeFileSync(this.pathChannel + "enable", "0")
+        this.enabled = false
+        writeFileSync(this.pathPwm + "unexport", this.channel)
+        this.exported = true
+    }
+
+    /** --------------------------------------------------------------
+     * @function pwmDuty
+     * @description Change PWM duty cycle
+     * @parameter {Number} time
+     */
+    pwmDuty(time) {
+
+        // Not PWM
+        if (this.type !== "pwm")
+            throw new Error("This GPIO is not configured as PWM")
+
+        // Not initialized
+        if (!this.enabled || !this.exported) {
+            trap("PWM duty cycle cannot be update if port is not exported and enabled")
+            return
+        }
+
+        // Out of range
+        this.duty = time
+        if (typeof this.duty !== "number" || this.duty < this.dutyMin) {
+            this.duty = this.dutyMin
+            trap("duty cycle forced to", this.dutyMin)
+        }
+        if (typeof this.duty !== "number" || this.duty > this.dutyMax) {
+            this.duty = this.dutyMax
+            trap("duty cycle forced to", this.dutyMax)
+        }
+
+        writeFileSync(this.pathChannel + "duty_cycle", this.duty.toString())
+    }
+}
+
+// -------------------------------------------------------------------
+// STATIC METHODS
+/** ------------------------------------------------------------------
+ * @function Rio.config
+ * @description Return GPIO configuration
+ * @param {Number} gpio
+ * @return {String}
+ */
+Rio.config = gpio => {
+    const a = exeShell("pinctrl get " + gpio).trim().split(/\s+/)
+    return a[a.length - 1].toLowerCase()
+}
+/** ------------------------------------------------------------------
+ * @function Rio.configs
+ * @description Return GPIO configuration for all supported GPIO
+ * @return {Object}
+ */
+Rio.configs = () => {
+    let configs = {}
+    Rio.RPI_GPIOS.forEach(gpio => {
+        configs[gpio] = Rio.config(gpio)
+    })
+    log("gpio configs:", configs)
+    return configs
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.info
+ * @description Exec gpioinfo
+ * @return {Object}
+ */
+Rio.info = () => {
+    return exeFile("gpioinfo", [Rio.RPI_CHIP])
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.detect
+ * @description Exec gpiodetect
+ * @return {Object}
+ */
+Rio.detect = () => {
+    return exeFile("gpiodetect")
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.version
+ * @description Return libgpiod version
+ * @return {Object}
+ */
+Rio.version = () => {
+    return exeFile("gpiodetect", ["-v"]).split("\n").shift().substring(22).trim()
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.stopMonitoring
+ * @description Stop monitoring of all inputs
+ */
+Rio.stopMonitoring = () => {
+    Rio.monitoringProcess !== null ? Rio.monitoringProcess.kill("SIGTERM") : false
+    Rio.monitored = {}
+    Rio.monitoringProcess = null
+    log("gpio monitoring stopped")
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.cpuInfo
+ * @description Read '/proc/cpuinfo' and store it for further call
+ * @return {String}
+ */
+Rio.cpuInfo = () => {
+    if (typeof Rio.cpuInfo.value === "undefined") {
+        try {
+            Rio.cpuInfo.value = readFileSync("/proc/cpuinfo", "utf8")
+        } catch (err) {
+            trap("catched error opening '/proc/cpuinfo:", err)
+            Rio.cpuInfo.value = ""
+        }
+    }
+    return Rio.cpuInfo.value
+}
+
+/** ------------------------------------------------------------------
+ * @function Rio.os
+ * @description Return OS ID and name
+ * @return {Object} {id: '12', name: 'Bookworm'}
+ */
+Rio.os = () => {
+    const strOs = exeShell("cat /etc/os-release")
+    if (strOs.length > 0) {
+        const lines = strOs.split("\n")
+        const info = {}
+        lines.forEach(line => {
+            const [key, value] = line.split("=")
+            if (key && value) {
+                info[key] = value.replace(/"/g, "");
+            }
+        })
+        let res = {
+            id: info["VERSION_ID"],
+            name: info["VERSION_CODENAME"]
+        }
+        res.name = res.name.substring(0, 1).toUpperCase() + res.name.substring(1);
+        return res
+    }
+}
+/** ------------------------------------------------------------------
+ * @function Rio.isSystemSupported
+ * @description Check if all hardware and software requirements are
+ *              satisfied to run the RPI-IO module
+ * @return {Boolean}
+ */
+Rio.isSystemSupported = () => {
+
+    const info = Rio.cpuInfo()
+
+    // Test hardware
+    if (/Raspberry Pi/i.test(Rio.cpuInfo()) === false) {
+        trap("not a Raspberry Pi hardware")
+        return false
+    }
+    log("👍  Hardware is Raspberry Pi")
+
+    // Test model
+    const line = Rio.cpuInfo().split("\n").find(str => str.indexOf("Model") !== -1)
+    const model = line.split(":")[1].trim()
+    if (Rio.TESTED_MODELS.indexOf(model) === -1) {
+        trap("model not tested:", model)
+        return false
+    }
+    log("👍 ", model, "is supported")
+
+    // Test OS
+    const thisOs = Rio.os()
+    if (Rio.TESTED_OS.indexOf(thisOs.name) === -1) {
+        trap("OS not tested:", thisOs.name, thisOs.id)
+        return false
+    }
+    log("👍 ", thisOs.name, "OS is supported")
+
+    // Test libgpiod version x.y
+    const gpiodVersion = Rio.version().substring(0, 4)
+    const foundLib = Rio.TESTED_LIBGPIOD.find(testedVersion => {
+        return gpiodVersion === testedVersion.substring(0, 4)
+    })
+    if (!foundLib) {
+        trap("libgpiod version not tested:", gpiodVersion)
+        return false
+    }
+    log("👍  libgpiod version", gpiodVersion + ".x", "is supported")
+    log("👍  Systems requirements for rpi-io are met")
+    return true
+}
+/** ------------------------------------------------------------------
+ * @function Rio.log
+ */
+Rio.log = cfgLog
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/esm/utl.mjs

@@ -0,0 +1,100 @@
+// -------------------------------------------------------------------
+// RPi GPIO CONTROL - UTILITIES
+// -------------------------------------------------------------------
+import {log,trap} from "./dev.mjs"
+import {execSync, execFileSync, spawnSync} from "child_process"
+
+// -------------------------------------------------------------------
+// JS UTILITIES
+/** ------------------------------------------------------------------
+ * @function sleep
+ * @description Wait before continuing
+ * @param {Number} ms
+ */
+export const sleep = ms => {
+    log("sleeping", ms, "ms")
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** ------------------------------------------------------------------
+ * @function ctrlC
+ * @description Intercept ctrl+c then exec callback
+ * @param {Function} callback
+ */
+export const ctrlC = callback => {
+    process.on("SIGINT", () => {
+        log("ctrl+c pressed")
+        typeof callback === "function" ? callback() : false
+        process.exit(0)
+    })
+}
+
+// -------------------------------------------------------------------
+// NODEJS UTILITIES
+/** ------------------------------------------------------------------
+ * @function exeShell
+ * @description Async run command in Linux shell
+ * @param {String} cmd
+ * @return {String} stdout or ""
+ */
+export const exeShell = cmd => {
+    try {
+        return execSync(cmd, {
+            stdio: "pipe",
+            encoding: "utf8",
+        })
+    } catch (err) {
+        if (err.code) {
+            // Spawning child process failed
+            trap("execFileSync error code", err.code)
+        } else {
+            // Child was spawned but exited with non-zero exit code
+            // Error contains any stdout and stderr from the child
+            const {stdout, stderr} = err
+            trap({stdout, stderr})
+        }
+        return ""
+    }
+}
+
+/** ------------------------------------------------------------------
+ * @function exeFile
+ * @description Async run executable file
+ * @param {String} file
+ * @param {Array} args
+ * @return {String} stdout or ""
+ */
+export const exeFile = (file, args) => {
+    try {
+        return execFileSync(file, args, {
+            stdio: "pipe",
+            encoding: "utf8",
+        })
+    } catch (err) {
+        if (err.code) {
+            // Spawning child process failed
+            trap("execFileSync error code", err.code)
+        } else {
+            // Child was spawned but exited with non-zero exit code
+            // Error contains any stdout and stderr from the child
+            const {stdout, stderr} = err
+            trap({stdout, stderr})
+        }
+        return ""
+    }
+}
+
+/** ------------------------------------------------------------------
+ * @function wait
+ * @description Wait before continuing (sync blocking mode)
+ * @param {Number} ms
+ */
+export const wait = ms => {
+    log("waiting", ms, "ms")
+    spawnSync("sleep", [ms / 1000])
+}
+
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/history.md

@@ -0,0 +1,8 @@
+1.0.0 - Oct 23 2025
+===================
+Initial release: *Bookworm*, libgpiod 1.63
+
+1.1.0 - Oct 31 2025
+===================
+* Added support libgpiod 2.2.1
+* Tested with *Trixie*

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "rpi-io",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Nodejs module to control Raspbbery Pi GPIO",
   "keywords": [
     "raspberry",
     "gpio",
-    "nodejs"
+    "nodejs",
+    "esm",
+    "pwm"
   ],
   "homepage": "https://github.com/gdorbes/rpi-io#readme",
   "bugs": {
@@ -15,11 +17,16 @@
     "type": "git",
     "url": "git+https://github.com/gdorbes/rpi-io.git"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "Guillaume DORBES",
   "type": "module",
-  "main": "index.mjs",
+  "engines" : {
+    "npm" : ">=10.0.0",
+    "node" : ">=23.0.0"
+  },
+  "main": "./esm/rio.mjs",
+  "exports": "./esm/rio.mjs",
   "scripts": {
-    "test": "test.js"
+    "test":"node ./scr/test.js"
   }
 }

package/scr/test.js

@@ -0,0 +1,162 @@
+// -------------------------------------------------------------------
+// RPi GPIO CONTROL TEST SCRIPT
+// -------------------------------------------------------------------
+import {log, trap, now} from "../esm/dev.mjs"
+import {ctrlC} from "../esm/utl.mjs"
+import {Rio} from "../esm/rio.mjs"
+
+/** ------------------------------------------------------------------
+ * @function info
+ * @description Colored log for info messages  Node.js only ~ CSS color #F50
+ * @param {String} cmd
+ * @param {String} txt
+ */
+function info(cmd, txt) {
+    console.log(now(), "🔎", "\x1b[38;2;0;160;16m", cmd, "\x1b[0m", txt)
+}
+
+/** ------------------------------------------------------------------
+ * @function isNumber
+ * @description Test if param is number
+ * @param {String} str
+ * @return {Number}
+ */
+function isNumber(str) {
+    const num = parseInt(str)
+    if (typeof num !== "number" || num !== num) {
+        trap("<gpio_number> is not a number or not defined")
+        return -1
+    } else {
+        return num
+    }
+}
+
+// -------------------------------------------------------------------
+// TOP LEVEL TEST
+// -------------------------------------------------------------------
+(function () {
+    Rio.log(2)
+    ctrlC(Rio.stopMonitoring)
+
+    if (process.argv.length < 3) {
+        trap("Arguments are missing! Type 'help' to display list of commands.")
+        return
+    }
+    let gpio
+    switch (process.argv[2]) {
+        case "help":
+            info("help", "To display this list.")
+            info("detect", "To display gpio chipsets")
+            info("lines", "To display gpiochip0 lines")
+            info("version", "To display libgpiod version")
+            info("system", "To test if your system (hw,sw, mw) meets the tested requirements.")
+            info("config", "To display gpio system configuration.")
+            info("out <gpio_number>", "To define a gpio as 'out' and set it to 1 for 5s.")
+            info("in <gpio_number>", "To define a gpio as 'in' to display its value ")
+            info("monitor <gpio_number>", "To define a gpio as 'in' to monitor events until ctrl+c.")
+            info("pwm <gpio_number>", "Test SG90~like servo from 0° to 180° i.e. period=20ms, duty-cycle-range=0.5-2.5ms")
+            info("benchmark <gpio_out> <gpio_in>", "Displays elapsed time of 1000 write + read operations")
+            break
+        case "version":
+            log("libgpiod version:", Rio.version())
+            break
+        case "detect":
+            log("chipsets:", Rio.detect())
+            break
+        case "lines":
+            log("lines:", Rio.info())
+            break
+        case "system":
+            Rio.isSystemSupported()
+            break
+        case "config":
+            Rio.configs()
+            break
+        case "out":
+            gpio = isNumber(process.argv[3])
+            if (gpio > 0) {
+                const led = new Rio(gpio, "out")
+                led.set(1, 5000)
+            }
+            break
+        case "in":
+            gpio = isNumber(process.argv[3])
+            if (gpio > 0) {
+                const btn = new Rio(gpio, "in")
+                btn.get()
+                /*  btn.monitor("both", (event, time) => {
+                      log("event", event)
+                  }) */
+            }
+            break
+        case "monitor":
+            gpio = isNumber(process.argv[3])
+            if (gpio > 0) {
+                const btn = new Rio(gpio, "in")
+                btn.monitor("both", (event) => {
+                    log("event", event)
+                })
+            }
+            break
+        case "benchmark":
+            const gpioOut = isNumber(process.argv[3])
+            const gpioIn = isNumber(process.argv[4])
+            let len = 1000
+            if (gpioOut > 0) {
+                const led = new Rio(gpioOut, "out")
+                const start1 = new Date()
+                while (len--) {
+                    led.write(1)
+                }
+                const stop1 = new Date()
+                const time1 = Math.abs(stop1 - start1)
+                log("Elapsed time for 1000 write ops:", time1, "ms")
+            }
+            len = 1000
+            if (gpioIn > 0) {
+                const btn = new Rio(gpioIn, "in")
+                const start2 = new Date()
+                while (len--) {
+                    btn.read()
+                }
+                const stop2 = new Date()
+                const time2 = Math.abs(stop2 - start2)
+                log("Elapsed time for 1000 read  ops:", time2, "ms")
+            }
+            break
+        case "pwm":
+            const servo = new Rio(isNumber(process.argv[3]), "pwm")
+
+            // 50hz, 0.5 ms
+            servo.pwmInit(20000000, 500000, {
+                dutyMin: 500000,
+                dutyMax: 2500000
+            })
+            log("servo position 0°")
+
+            // after 2s -> duty=1.5 ms
+            setTimeout(() => {
+                servo.pwmDuty(1500000)
+                log("servo position = 90°")
+            },2000)
+
+            // after 4s -> duty=1.5 ms
+            setTimeout(() => {
+                servo.pwmDuty(2500000)
+                log("servo position = 180°")
+            }, 4000)
+
+            // after 5s -> stop
+            setTimeout(() => {
+                servo.pwmStop()
+                log("servo stopped")
+            }, 5000)
+            break
+        default:
+            trap("Unknown command: Type 'test help' to display list of commands.")
+    }
+})()
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------