rpi-io 1.1.4 → 1.2.0

package/README.md

@@ -1,5 +1,5 @@
 # rpi-io
-![Static Badge](https://img.shields.io/badge/rpi--io-_1.1.4_-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)
+![Static Badge](https://img.shields.io/badge/rpi--io-_1.2.x_-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.
@@ -24,7 +24,7 @@ By default rpi-io does not require specific configuration.
 
 If you want to use [hardware-based 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.
+- 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 showed in the examples below.
 
 ```shell
 # Examples of PWM configuration to add to/boot/firmware/config.txt
@@ -228,7 +228,7 @@ let currentValue = myInput.get();
 
 
 
-#### monitor(edge, callback)
+#### monitor(edge, callback, options)
 
 To monitor activities on some *in* GPIO and receive events in a callback function.
 
@@ -246,6 +246,9 @@ myButton.monitor("both", event => {
 
 - **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'}`
+- **options** *{Object}* Default value is `{bias: 'disable', bounce: 0}`
+    - `bias` To configure according your input connection. Supported value ares 'disable', 'pull-down' and 'pull-up'.
+    - `bounce` Delay in ms to filter callback on rebounce. Value between 0 and 1000. 0 means no filter.
 
 ##### Detected errors
 
@@ -273,7 +276,7 @@ console.log("servo position = 0°");
 
 ##### Parameters
 
-All time parameters are defined in nano-seconds (ns).
+All time parameters are defined in nanoseconds (ns).
 
 - **period** *{Number}* Time period in which [duty cycle](https://en.wikipedia.org/wiki/Pulse-width_modulation) varies.
 - **duty** *{Number}* Initial duty cycle.
@@ -331,6 +334,16 @@ servo.pwmDuty(1500000)
 
 
 ### Utility functions
+#### Rio.stopMonitoring()
+
+To stop monitoring subprocess when leaving your app script or in case of failure. This prevents having a runaway subprocess that could block a new call to the `monitor()` method.
+
+##### Example
+
+```javascript
+Rio.stopMonitoring()
+```
+
 #### Rio.config(gpio)
 
 To return configuration of some GPIO
@@ -379,7 +392,7 @@ console.log(Rio.version())
 
 #### Rio.os()
 
-To retrieve Rapsberry Pi OS info.
+To retrieve Raspberry Pi OS info.
 
 ##### Example
 
@@ -418,11 +431,15 @@ Rio.isSystemSupported() // See console below
 
 ## Benchmark
 
-The following table summarizes GPIO *set* average times with rpi-io v1.1.0 and various hardwares and OS.
+The following table summarizes GPIO *set* average times with rpi-io v1.1.0 and various hardware and OS.
+
+💡 If you can, stick to *Bookworm*: **rpi-io** has stability and performance issues with Trixie and libgpiod v2.2.1. I did not test libgpiod v1.6.3 on Trixie.
+
+|          | RPi 5B  | RPi 4B   | RPi Zero2  |
+|----------|---------|----------|------------|
+| Bookworm | 1.37 ms | 4.56 ms  | 9.07 ms    |
+| Trixie   | 3.82 ms | 11.29 ms | not tested |
+
 
-|          | RPi 5B  | RPi 4B     | RPi Zero2  |
-| -------- | ------- | ---------- | ---------- |
-| Bookworm | 1.37 ms | 4.56 ms    | 9.07 ms    |
-| Trixie   | 3.82 ms | not tested | not tested |
 ---
 

package/esm/rio.mjs

@@ -33,12 +33,8 @@ export class Rio {
     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
+    // Map of instances
+    static instances = new Map()
 
     // ---------------------------------------------------------------
     // GENERIC METHODS: constructor, disable
@@ -51,13 +47,18 @@ export class Rio {
      */
     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)
+        // Monitoring properties
+        this.watch = {
+            edge: "stop",
+            callback: false,
+            process: null
+        }
 
         // OS is not supported
         if (Rio.TESTED_OS.indexOf(this.os) === -1)
@@ -78,34 +79,19 @@ export class Rio {
         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)
+        // gpio is already defined
+        if (Rio.instances.has(gpio))
+            throw new Error("This gpio is already defined: " + gpio)
 
         // this.read, this.write, monArgs depending on gpiolib version
         switch (this.versionLib) {
             case "v1.6":
-                this.write = (value, time = 0) => {
+                this.write = (value) => {
                     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) => {
@@ -114,19 +100,6 @@ export class Rio {
                 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
         }
 
@@ -148,21 +121,26 @@ export class Rio {
             this.pathPwm = "/sys/class/pwm/" + this.pwm + "/"
             this.pathChannel = this.pathPwm + "pwm" + this.channel + "/"
         }
+        // Everything OK => Add this to instance list
+        Rio.instances.set(gpio, this)
+        log("new gpio instance created:", this.gpio)
     }
 
     /** --------------------------------------------------------------
      * @function disable
-     * @description Remove instance from Rio.used_gpios
+     * @description Remove instance from Rio.instances
      *              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")
+        if (Rio.instances.has(this.gpio)) {
             this.gpio = -1
+            this.watch.edge = "stop"
+            this.watch.callback = false
+            this.watch.process !== null ? this.watch.process.kill("SIGTERM") : false
+            Rio.instances.delete(this.gpio)
+            log("gpio", this.gpio, "has been disabled")
+        } else {
+            log("gpio", this.gpio, "is already disabled")
         }
     }
 
@@ -223,13 +201,112 @@ export class Rio {
         return result
     }
 
+    /** --------------------------------------------------------------
+     * @function monArgs
+     * @description Utility to take care gpiomon arguments according to libgpiod version
+     * @param {Array} gpios
+     * @param {Object} opt
+     * @return {Array}
+     */
+    #monArgs = (gpios, opt) => {
+        let args = []
+        switch (this.versionLib) {
+            case "v1.6":
+                args.push("-b") // line-buffered: output is flushed after every line
+                args.push("--bias=" + opt.bias)
+                args.push("--format=%o %e") // gpio, edge. Others: seconds(%s) and nanoseconds (%n)
+                args.push(Rio.RPI_CHIP)
+                return args.concat(gpios)
+            case "v2.2":
+                opt.bias === "disable" ? opt.bias = "disabled" : false
+                gpios = gpios.map(gpio => "GPIO" + gpio)
+                args.push("--bias")
+                args.push(opt.bias)
+                return args.concat(gpios)
+        }
+    }
+
+    /** --------------------------------------------------------------
+     * @function monData
+     * @description Utility to take care of gpiomon stdout data
+     * @param {String} data
+     * @return {Object}
+     */
+    #monData = data => {
+        switch (this.versionLib) {
+            case "v1.6":
+                const [gpioV1, edgeV1] = data.toString().trim().split(/\s+/)
+                return {
+                    gpio: gpioV1,
+                    edge: edgeV1
+                }
+            case "v2.2":
+                const [timeV2, edgeV2, gpioV2] = data.toString().trim().split(/\s+/)
+                return {
+                    time: timeV2,
+                    gpio: gpioV2.substring(5, 7),
+                    edge: edgeV2
+                }
+        }
+    }
+    /** --------------------------------------------------------------
+     * @function monCallback
+     * @description Utility to trigger callback from gpiomon stdout data
+     * @param {String} data
+     */
+    #monCallback = data => {
+        const eventData = this.#monData(data)
+        const now = new Date()
+        const delta = Math.max(1, now - this.monitoredEvent.latest) // delta is always > 0ms
+        const edge = eventData.edge === "1" ? "rising" : "falling"
+
+        // Bounce detected
+        if (delta <= this.bounceTime && edge === this.monitoredEvent.edge) {
+            log("bounce detected on gpio", this.gpio, edge, delta + "ms")
+        }
+        // Trigger callback according to edge requirement
+        else {
+            if (this.watch.enabled.indexOf(edge) !== -1)
+                this.watch.callback(edge, now)
+            // log("monitored event on gpio", this.gpio, edge,)
+        }
+
+        // Update latest monitored event
+        this.monitoredEvent.latest = now
+        this.monitoredEvent.edge = edge
+    }
+
     /** --------------------------------------------------------------
      * @function monitor
      * @description Wait for edge events
      * @param {String} edge {'stop', 'rising', 'falling' 'both'}
      * @param {Function} callback (edge, time)
+     * @param {Object} opt  - opt.bias {'disable','pull-up','pull-down'}
+     *                      - opt.bounce 0-1000
      */
-    monitor(edge, callback) {
+    monitor(edge, callback, opt) {
+
+        // Default and clean parameters
+        const defaultCallback = (edge, time) => {
+            log("gpio", this.gpio, "event:", edge, time)
+        }
+        const defopt = {
+            bias: "disable",
+            bounce: 0
+        }
+
+        callback === undefined ? callback = defaultCallback : false
+        opt = {...defopt, ...opt}
+        opt.bounce < 0 ? opt.bounce = 0 : false
+        opt.bounce > 1000 ? opt.bounce = 1000 : false
+        this.bounceTime = opt.bounce
+        this.monitoredEvent = {
+            latest: new Date(null),
+            edge: "none"
+        }
+
+        const biases = ["disable", "pull-up", "pull-down"]
+        biases.indexOf(opt.bias) === -1 ? opt.bias = "disable" : false
 
         if (this.gpio === -1)
             throw new Error("This instance is disabled")
@@ -237,47 +314,51 @@ export class Rio {
         if (this.type !== "in")
             throw new Error("Monitor is dedicated to 'in' instances")
 
-        // Update monitoring list
-        Rio.monitored[this.gpio] = {
-            edge: edge,
-            callback: callback
-        }
+        if (["stop", "rising", "falling", "both"].indexOf(edge) === -1)
+            throw new Error("Edge " + edge + "is not supported")
 
-        // Suspend current monitoring if any
-        if (Rio.monitoringProcess !== null) {
-            Rio.monitoringProcess.kill("SIGTERM")
-            Rio.monitoringProcess = null
-        }
+        if (typeof callback !== "function")
+            throw new Error("Callback is not a function")
 
-        // 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")
-        }
+        // First time the instance is monitored or has been stopped
+        if (this.watch === "stop") {
 
-        // 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())
-                    }
+            if (edge === "stop") {
+                trap("cannot stop an unstarted monitoring on gpio", this.gpio)
+            }
+            // Edge is in ["rising", "falling", "both"]
+            else {
+                this.watch = {
+                    edge: edge,
+                    enabled: edge === "both" ? ["rising", "falling"] : [edge],
+                    callback: callback,
+                    process: spawn("gpiomon", this.#monArgs([this.gpio], opt))
                 }
-            })
-            Rio.monitoringProcess.stderr.on("data", data => {
-                trap("gpiomon stderr:", Buffer.from(data).toString())
-            })
-        } else {
-            log("no more gpio to monitor")
+                this.watch.process.stdout.on("data", this.#monCallback)
+            }
+        }
+        // Instance is already monitored
+        else {
+            // Stop: Kill process and delete monitored data
+            if (edge === "stop") {
+                this.watch.process !== null ? this.watch.process.kill("SIGTERM") : false
+                this.watch.edge = "stop"
+                this.watch.enabled = []
+                this.watch.callback = false
+                this.watch.process = null
+                Rio.instances.set(this.gpio, this)
+                log("monitoring of gpio", this.gpio, "has been stopped")
+            }
+
+            // Kill process, update edge and callback, define new process
+            else {
+                this.watch.process !== null ? this.watch.process.kill("SIGTERM") : false
+                this.watch.edge = edge
+                this.watch.enabled = edge === "both" ? ["rising", "falling"] : [edge]
+                this.watch.callback = callback
+                this.watch.process = spawn("gpiomon", this.#monArgs([this.gpio], opt))
+                this.watch.process.stdout.on("data", this.#monCallback)
+            }
         }
     }
 
@@ -321,9 +402,9 @@ export class Rio {
 
         // Check duty cycle
         if (duty < this.dutyMin)
-            throw new Error("PWM duty", duty, " is lower than duty min", 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)
+            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)
 
@@ -450,10 +531,15 @@ Rio.version = () => {
  * @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")
+    Rio.instances.forEach((that) => {
+        if (that.watch.process !== null) {
+            that.watch.process.kill("SIGTERM")
+            that.watch.edge = "stop"
+            that.watch.callback = false
+            that.watch.process = null
+            log("monitoring of gpio", that.gpio, "has been stopped")
+        }
+    })
 }
 
 /** ------------------------------------------------------------------
@@ -505,8 +591,6 @@ Rio.os = () => {
  */
 Rio.isSystemSupported = () => {
 
-    const info = Rio.cpuInfo()
-
     // Test hardware
     if (/Raspberry Pi/i.test(Rio.cpuInfo()) === false) {
         trap("not a Raspberry Pi hardware")

package/esm/utl.mjs

@@ -1,7 +1,7 @@
 // -------------------------------------------------------------------
 // RPi GPIO CONTROL - UTILITIES
 // -------------------------------------------------------------------
-import {log,trap} from "./dev.mjs"
+import {log, trap} from "./dev.mjs"
 import {execSync, execFileSync, spawnSync} from "child_process"
 
 // -------------------------------------------------------------------
@@ -64,7 +64,7 @@ export const exeShell = cmd => {
  * @param {Array} args
  * @return {String} stdout or ""
  */
-export const exeFile = (file, args) => {
+export const exeFile = (file, args = []) => {
     try {
         return execFileSync(file, args, {
             stdio: "pipe",

package/history.md

@@ -1,8 +1,13 @@
-1.0.0 - Oct 23 2025
+1.2.0 - Nov 07, 2025
 ===================
-Initial release: *Bookworm*, libgpiod 1.63
+* New option parameter for method `monitor` to take care of bias and bounces.
+* Fixes and optimization
 
-1.1.0 - Oct 31 2025
+1.1.0 - Oct 31, 2025
 ===================
 * Added support libgpiod 2.2.1
-* Tested with *Trixie*
+* Tested with *Trixie*
+
+1.0.0 - Oct 23, 2025
+===================
+Initial release: *Bookworm*, libgpiod 1.63

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "rpi-io",
-  "version": "1.1.4",
-  "description": "Nodejs module to control Raspbbery Pi GPIO",
+  "version": "1.2.0",
+  "description": "Nodejs module to control Raspberry Pi GPIO",
   "keywords": [
     "raspberry",
     "gpio",
+    "libgpiod",
     "nodejs",
     "esm",
-    "pwm"
+    "output",
+    "input",
+    "monitor",
+    "pwm",
+    "bookworm",
+    "trixie"
   ],
   "homepage": "https://github.com/gdorbes/rpi-io#readme",
   "bugs": {

package/scr/test.js

@@ -84,19 +84,25 @@ function isNumber(str) {
             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)
-                })
+            const gpio1 = isNumber(process.argv[3])
+            const gpio2 = isNumber(process.argv[4])
+            let btn1, btn2
+            if (gpio1 > 0) {
+                btn1 = new Rio(gpio1, "in")
+                btn1.monitor("rising")
             }
+            if (gpio2 > 0) {
+                btn2 = new Rio(gpio2, "in")
+                btn2.monitor("falling", () => {
+                    log(gpio2, "falling")
+                }, {bias: "pull-down"})
+            }
+            setTimeout(() => {
+                btn1.monitor("stop")
+            }, 6000)
             break
         case "benchmark":
             const gpioOut = isNumber(process.argv[3])
@@ -138,7 +144,7 @@ function isNumber(str) {
             setTimeout(() => {
                 servo.pwmDuty(1500000)
                 log("servo position = 90°")
-            },2000)
+            }, 2000)
 
             // after 4s -> duty=1.5 ms
             setTimeout(() => {