rpi-io 1.1.5 → 1.2.1

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.
@@ -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
 
@@ -403,7 +406,7 @@ console.log(Rio.os())
 
 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)
+#### Rio.logCfg(level)
 To set the level of console used in the module:
 
 - 0: no console
@@ -414,9 +417,9 @@ To set the level of console used in the module:
 
 ```javascript
 import {Rio} from "rpi-io";
-Rio.log(0)
+Rio.logCfg(0)
 Rio.isSystemSupported() // Nothing displayed in console
-Rio.log(2)
+Rio.logCfg(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
@@ -430,9 +433,13 @@ Rio.isSystemSupported() // See console below
 
 The following table summarizes GPIO *set* average times with rpi-io v1.1.0 and various hardware 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 |
+💡 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 |
+
+
 ---
 

package/esm/dev.mjs

@@ -9,11 +9,11 @@ let debug = {
 // -------------------------------------------------------------------
 // FUNCTIONS
 /** ------------------------------------------------------------------
- * @function now
+ * @function nowStr
  * @description Return timestamp as formatted string
  * @return {String}
  */
-export const now = () => {
+export const nowStr = () => {
     const date = new Date()
     return date.toLocaleTimeString() + "." + date.getMilliseconds().toLocaleString('en', {
         minimumIntegerDigits: 3,
@@ -29,7 +29,7 @@ export const now = () => {
  */
 export const log = function () {
     if (debug.log)
-        console.log.apply(console, Array.prototype.concat.apply([now(), "🔎 "], arguments))
+        console.log.apply(console, Array.prototype.concat.apply([nowStr(), "🔎 "], arguments))
 }
 
 /** ------------------------------------------------------------------
@@ -38,15 +38,15 @@ export const log = function () {
  */
 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"]))
+        console.log.apply(console, Array.prototype.concat.apply([nowStr(), "⚠️", "\x1b[38;2;255;80;0m", ...arguments, "\x1b[0m"]))
 }
 
 /** ------------------------------------------------------------------
- * @function cfgLog
+ * @function logCfg
  * @description Set log configuration
  * @param {Number} level    0: no log, 1: trap only, 2: trap and log
  */
-export const cfgLog = level => {
+export const logCfg = level => {
     debug = {
         log: false,
         trap: false

package/esm/rio.mjs

@@ -6,7 +6,7 @@
 import {spawn} from "child_process";
 import {writeFileSync, readFileSync} from "fs"
 import {exeFile, exeShell, wait} from "./utl.mjs"
-import {cfgLog, log, trap} from "./dev.mjs"
+import {logCfg, log, trap} from "./dev.mjs"
 
 // -------------------------------------------------------------------
 // CLASS RIO AND FURTHER
@@ -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")
@@ -544,10 +628,14 @@ Rio.isSystemSupported = () => {
     log("👍  Systems requirements for rpi-io are met")
     return true
 }
+/** ------------------------------------------------------------------
+ * @function Rio.logCfg
+ */
+Rio.logCfg = logCfg
 /** ------------------------------------------------------------------
  * @function Rio.log
  */
-Rio.log = cfgLog
+Rio.log = log
 // -------------------------------------------------------------------
 // EoF
 // -------------------------------------------------------------------

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,17 @@
-1.0.0 - Oct 23 2025
+1.2.1 - Nov 10, 2025
 ===================
-Initial release: *Bookworm*, libgpiod 1.63
+* Change utility API function name from `Rio.log` to `Rio.logCfg`.
 
-1.1.0 - Oct 31 2025
+1.2.0 - Nov 07, 2025
+===================
+* New option parameter for method `monitor` to take care of bias and bounces.
+* Fixes and optimization
+
+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,6 +1,6 @@
 {
   "name": "rpi-io",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "description": "Nodejs module to control Raspberry Pi GPIO",
   "keywords": [
     "raspberry",
@@ -8,6 +8,9 @@
     "libgpiod",
     "nodejs",
     "esm",
+    "output",
+    "input",
+    "monitor",
     "pwm",
     "bookworm",
     "trixie"

package/scr/test.js

@@ -1,7 +1,7 @@
 // -------------------------------------------------------------------
 // RPi GPIO CONTROL TEST SCRIPT
 // -------------------------------------------------------------------
-import {log, trap, now} from "../esm/dev.mjs"
+import {log, trap, nowStr} from "../esm/dev.mjs"
 import {ctrlC} from "../esm/utl.mjs"
 import {Rio} from "../esm/rio.mjs"
 
@@ -12,7 +12,7 @@ import {Rio} from "../esm/rio.mjs"
  * @param {String} txt
  */
 function info(cmd, txt) {
-    console.log(now(), "🔎", "\x1b[38;2;0;160;16m", cmd, "\x1b[0m", txt)
+    console.log(nowStr(), "🔎", "\x1b[38;2;0;160;16m", cmd, "\x1b[0m", txt)
 }
 
 /** ------------------------------------------------------------------
@@ -35,7 +35,7 @@ function isNumber(str) {
 // TOP LEVEL TEST
 // -------------------------------------------------------------------
 (function () {
-    Rio.log(2)
+    Rio.logCfg(2)
     ctrlC(Rio.stopMonitoring)
 
     if (process.argv.length < 3) {
@@ -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(() => {