rpi-io 1.2.3 → 2.0.0

package/binding.gyp

@@ -0,0 +1,33 @@
+{
+  "targets": [
+    {
+      "target_name": "gpio",
+      "sources": [ "addon/gpio.c" ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "libraries": [
+        "-lgpiod",
+        "-lpthread"
+      ],
+      "cflags": [
+        "-Wall",
+        "-Wno-implicit-function-declaration",
+        "-Wno-incompatible-pointer-types",
+        "-O2",
+        "-std=gnu99"
+      ],
+      "defines": [
+        "<!@(sh -c 'chmod +x script/detect-gpiod-version.sh 2>/dev/null; bash script/detect-gpiod-version.sh 2>/dev/null || echo LIBGPIOD_V2')"
+      ],
+      "conditions": [
+        ["OS=='linux'", {
+          "libraries": [
+            "-lgpiod",
+            "-lpthread"
+          ]
+        }]
+      ]
+    }
+  ]
+}

package/esm/_util.mjs

@@ -0,0 +1,122 @@
+// -------------------------------------------------------------------
+// RPI-IO: Nodejs tools and utilities
+// -------------------------------------------------------------------
+import {execSync} from "child_process"
+import {spawnSync} from "node:child_process"
+
+// -------------------------------------------------------------------
+// DEV UTILITIES
+// -------------------------------------------------------------------
+let debug = {
+    trace: false,
+    warn: true
+}
+/** ------------------------------------------------------------------
+ * @function traceCfg
+ * @description Set log configuration
+ * @param {Number} level    0: no log, 1: warn only, 2: warn and log
+ */
+export const traceCfg = level => {
+    debug = {
+        trace: false,
+        warn: false
+    }
+    level > 1 ? debug.trace = true : false
+    level > 0 ? debug.warn = true : false
+}
+
+/** ------------------------------------------------------------------
+ * @function nowStr
+ * @description Return timestamp as formatted string
+ * @return {String}
+ */
+const nowStr = () => {
+    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.trace)
+        console.log.apply(console, Array.prototype.concat.apply([nowStr(), "🔎 "], arguments))
+}
+
+/** ------------------------------------------------------------------
+ * @function warn
+ * @description Colored log for error messages ⚠️ nodejs only ~ CSS color #F50
+ */
+export const warn = function () {
+    if (debug.warn)
+        console.log.apply(console, Array.prototype.concat.apply([nowStr(), "⚠️", "\x1b[38;2;255;80;0m", ...arguments, "\x1b[0m"]))
+}
+
+/** ------------------------------------------------------------------
+ * @function sleep
+ * @description Wait before continuing
+ * @param {Number} ms
+ * @param {Boolean} track
+ */
+export const sleep = (ms, track = true) => {
+    track ? log("sleeping", ms, "ms") : false
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** ------------------------------------------------------------------
+ * @function wait
+ * @description Wait before continuing (sync blocking mode)
+ * @param {Number} ms
+ */
+export const wait = ms => {
+    log("waiting", ms, "ms")
+    spawnSync("sleep", [ms / 1000])
+}
+
+/** ------------------------------------------------------------------
+ * @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)
+    })
+}
+
+/** ------------------------------------------------------------------
+ * @function lineConfig
+ * @description Return line configuration
+ * @param {Number} line
+ * @return {String}
+ */
+export const lineConfig = line => {
+    const stdout = execSync("pinctrl get " + line, {stdio: "pipe", encoding: "utf8"}).trim().split(/\s+/)
+    return stdout[stdout.length - 1].toLowerCase()
+}
+
+/** ------------------------------------------------------------------
+ * @function lineNumber
+ * @param {Number} nth
+ * @return {Number}
+ */
+export const lineNumber = nth => {
+    const arg = parseInt(process.argv[nth])
+    if (typeof arg !== "number" || arg !== arg) {
+        warn("Line number expected as argument")
+        return -1
+    }
+    return arg
+}
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/esm/main.mjs

@@ -0,0 +1,307 @@
+// -------------------------------------------------------------------
+// RPI-IO: Nodejs GPIO control module
+// -------------------------------------------------------------------
+import {createRequire} from "node:module"
+import {writeFileSync} from "node:fs"
+import {traceCfg, log, warn, sleep, ctrlC, lineConfig, lineNumber, wait} from "./_util.mjs"
+
+export {traceCfg, log, warn, sleep, ctrlC, lineConfig, lineNumber}
+// -------------------------------------------------------------------
+//  CONSTANTS + VARIABLES
+// -------------------------------------------------------------------
+const require = createRequire(import.meta.url)
+const ADDON = require("../build/Release/gpio.node")
+const CHIPNAME = "/dev/gpiochip0"
+const RPi_GPIO_STD = [4, 5, 6, 16, 17, 20, 21, 22, 23, 24, 25, 26, 27]
+const RPi_GPIO_PWM = [12, 13, 18, 19]
+const RPI_GPIO_ALL = [...RPi_GPIO_STD, ...RPi_GPIO_PWM]
+const RPI_CHIP = "gpiochip0"
+const PWM_CHIP = "pwmchip0"
+
+// -------------------------------------------------------------------
+// CLASS RIO & METHODS
+/** ------------------------------------------------------------------
+ * @class RIO
+ * @classDesc Generic class manage GPIO lines
+ * @return {String}
+ */
+export class RIO {
+
+    static instances = new Map()
+
+    /** ------------------------------------------------------------------
+     * @method constructor
+     * @param {Number} line - BCM number
+     * @param {String} mode - "input", "output", "pwm"
+     * @param {Object} opt - misc options depending on mode
+     */
+    constructor(line, mode, opt) {
+
+        const defopt = {
+            // output
+            value: 0, // Initial value
+            // input, output
+            bias: "disable", // "disable", "pull-up", "pull-down"
+            // pwm
+            exportTime: 100,
+            period: 20000, // μs ~50Hz
+            dutyMin: 0, // μs
+            dutyMax: 20000 // µs
+        }
+        opt = {...defopt, ...opt}
+
+        if (RPI_GPIO_ALL.indexOf(line) === -1)
+            throw new Error("This line is not supported: " + line)
+
+        // line is already defined
+        if (RIO.instances.has(line))
+            throw new Error("This line is already defined: " + line)
+
+        this.line = line
+        this.handle = null
+        this.mode = mode
+        this.value = opt.value
+        this.bias = opt.bias
+        this.closed = false // Instance status
+        this.monitoring = false // Monitoring status
+        this.config = lineConfig(this.line) // Required for pwm
+        this.pwmExported = false
+        this.pwmEnabled = false
+
+        switch (this.mode) {
+            case "output":
+                this.handle = ADDON.openOutput(CHIPNAME, line, this.value, opt.bias)
+                break
+            case "input":
+                this.handle = ADDON.openInput(CHIPNAME, line, opt.bias)
+                break
+            case "pwm":
+                if (RPi_GPIO_PWM.indexOf(line) === -1)
+                    throw new Error("This line is not supported for PWM: " + line)
+
+                if (this.config.indexOf("pwm") === -1)
+                    throw new Error("This line is not setup as PWM (see README)")
+
+                if (opt.period < 0.1 || opt.period > 1000000)
+                    throw new Error("PWM period is out of range (100ns - 1s)")
+
+                // Normalize PWM values in ns
+                this.period = opt.period * 1000
+                this.dutyMin = Math.max(0, opt.dutyMin * 1000)
+                this.dutyMax = Math.min(this.period, opt.dutyMax * 1000)
+
+                // PWM channel: 0 or 1
+                this.pwmChannel = this.config.slice(-1)
+                this.pwmPath = "/sys/class/pwm/" + PWM_CHIP + "/"
+                this.pwmPathChannel = this.pwmPath + "pwm" + this.pwmChannel + "/"
+
+                log("pwm channel", this.pwmChannel, "normalized data (period, duty min, duty max):", this.period, this.dutyMin, this.dutyMax)
+
+                // Export channel
+                writeFileSync(this.pwmPath + "export", this.pwmChannel)
+                this.pwmExported = true
+                wait(opt.exportTime) // Customization required for RPi Zero
+
+                // Set period, reset duty and enable
+                try {
+                    writeFileSync(this.pwmPathChannel + "period", String(this.period))
+                    writeFileSync(this.pwmPathChannel + "duty_cycle", String(this.dutyMin))
+                    writeFileSync(this.pwmPathChannel + "enable", "1")
+                    this.pwmEnabled = true
+
+                } catch (err) {
+                    warn("pwm start error:", err)
+                    warn("consider increasing option exportTime for this device ")
+                    this.pwmStop()
+                }
+
+                break
+            default:
+                throw new Error("undefined mode")
+        }
+
+        // Everything OK => Add this to instance list
+        RIO.instances.set(line, this)
+    }
+
+    /** ------------------------------------------------------------------
+     * @method close
+     * @description To close line and free resources
+     */
+    close() {
+        if (this.closed) {
+            warn("this instance is already closed")
+            return
+        }
+
+
+        // Stop monitoring if active
+        if (this.monitoring)
+            this.monitoringStop()
+
+        // Free C resources and reset handle
+        if (this.handle) {
+            ADDON.close(this.handle)
+            this.handle = null
+        }
+
+        // Stop PWM if required
+        if (this.mode === "pwm")
+            this.pwmStop()
+
+        // Delete from instance list et reset flag
+        RIO.instances.delete(this.line)
+        this.closed = true
+        log("line", this.line, "is closed")
+    }
+
+    /** ------------------------------------------------------------------
+     * @method write
+     * @description Write value to GPIO line
+     * @param {Number}  value
+     */
+    write(value) {
+
+        if (this.closed)
+            throw new Error("GPIO handle has been closed")
+
+        if (this.mode !== "output")
+            throw new Error("Cannot write to this GPIO mode:", this.mode)
+
+        if ([0, 1].indexOf(value) === -1)
+            throw new Error("Value must be either 0 or 1")
+
+        ADDON.write(this.handle, value)
+    }
+
+    /** ------------------------------------------------------------------
+     * @method read
+     * @description Read value from GPIO line
+     * @return {Number} 0,1
+     */
+    read() {
+        if (this.closed)
+            throw new Error("GPIO handle has been closed")
+
+        if (this.mode !== "input")
+            throw new Error("Cannot read from this GPIO mode:", this.mode)
+
+        return ADDON.read(this.handle)
+    }
+
+    /** ------------------------------------------------------------------
+     * @method monitoringStart
+     * @description Monitor input GPIO line events (rising/falling)
+     * @param {Function} callback 0,1
+     * @param {String} edge
+     * @param {Number} bounce
+     */
+    monitoringStart(callback, edge = "both", bounce = 0) {
+        if (this.closed)
+            throw new Error("GPIO handle has been closed")
+
+        if (this.mode !== "input")
+            throw new Error("Cannot read from this GPIO mode:", this.mode)
+
+        if (this.monitoring)
+            throw new Error("Monitoring already started")
+
+        bounce < 0 ? bounce = 0 : false
+        bounce > 1000 ? bounce = 1000 : false
+        this.latestEvent = {
+            time: new Date(null),
+            edge: "none"
+        }
+
+        ADDON.startMonitoring(this.handle, value => {
+            const evt = value === 1 ? "rising" : "falling"
+            const now = new Date()
+            const delta = Math.max(1, now - this.latestEvent.time) // delta is always > 0ms
+
+            // Bounce detected
+            if (delta <= bounce && evt === this.latestEvent.edge) {
+                log("bounce detected on gpio", this.line, evt, delta + "ms")
+            }
+            // Callback of required events
+            else {
+                if (typeof callback === "function" && (edge === "both" || edge === evt)) {
+                    callback(evt)
+                }
+            }
+            // Update latest event
+            this.latestEvent = {
+                time: now,
+                edge: evt
+            }
+        })
+        this.monitoring = true
+    }
+
+    /** ------------------------------------------------------------------
+     * @method monitoringStop
+     * @description Stop event monitoring
+     */
+    monitoringStop() {
+        if (this.closed)
+            return
+
+        if (this.monitoring) {
+            ADDON.stopMonitoring(this.handle)
+            this.monitoring = false
+        }
+    }
+
+    /** --------------------------------------------------------------
+     * @method pwmStop
+     * @description Stop PWM modulation
+     */
+    pwmStop() {
+
+        if (this.mode !== "pwm")
+            throw new Error("This line is not configured as PWM")
+
+        if (this.pwmEnabled) {
+            writeFileSync(this.pwmPathChannel + "enable", "0")
+            this.pwmEnabled = false
+        }
+
+        if (this.pwmExported) {
+            writeFileSync(this.pwmPath + "unexport", this.pwmChannel)
+            this.pwmExported = false
+        }
+    }
+
+    /** --------------------------------------------------------------
+     * @method pwmDuty
+     * @description Change PWM duty cycle
+     * @param {Number} percent 0 <= percent  <= 100
+     */
+    pwmDuty(percent) {
+
+        if (this.mode !== "pwm")
+            throw new Error("This line is not configured as PWM")
+
+        if (!this.pwmEnabled || !this.pwmExported)
+            throw new Error("Duty of PWM line " + this.line + " cannot be updated")
+
+        if (percent < 0 || percent > 100 || typeof percent !== "number") {
+            throw new Error("Duty value (%) of PWM line" + this.line + " is not valid")
+        }
+
+        writeFileSync(this.pwmPathChannel + "duty_cycle", (this.dutyMin + ((percent / 100) * (this.dutyMax - this.dutyMin))).toString())
+    }
+
+    /** ------------------------------------------------------------------
+     * @method RIO.closeAll
+     * @description Static method to close all instances
+     */
+    static closeAll() {
+        for (const [line, instance] of RIO.instances) {
+            instance.close()
+        }
+    }
+}
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/history.md

@@ -1,3 +1,10 @@
+
+2.0.0 - Nov 26, 2025
+===================
+* New hybrid architecture Javascript + C addon to improve performances
+* New API
+* Fixes
+
 1.2.2 - Nov 10, 2025
 ===================
 * Change utility API function name from `Rio.log` to `Rio.logCfg`.

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "rpi-io",
-  "version": "1.2.3",
+  "version": "2.0.0",
   "description": "Nodejs module to control Raspberry Pi GPIO",
   "keywords": [
     "raspberry",
+    "raspberry-pi",
     "gpio",
     "libgpiod",
     "nodejs",
     "esm",
+    "napi",
     "output",
     "input",
     "monitor",
     "pwm",
+    "linux",
     "bookworm",
-    "trixie"
+    "trixie",
+    "iot",
+    "embedded"
   ],
   "homepage": "https://github.com/gdorbes/rpi-io#readme",
   "bugs": {
@@ -25,14 +30,56 @@
   },
   "license": "MIT",
   "author": "Guillaume DORBES",
-  "type": "module",
   "engines": {
     "npm": ">=10.0.0",
     "node": ">=23.0.0"
   },
-  "main": "./esm/rio.mjs",
-  "exports": "./esm/rio.mjs",
+  "main": "esm/main.mjs",
+  "exports": "./esm/main.mjs",
+  "type": "module",
   "scripts": {
-    "test": "node ./scr/test.js"
+    "preinstall": "chmod +x script/*.sh 2>/dev/null || true",
+    "install": "node-gyp rebuild",
+    "postinstall": "echo 'Installation complete!'",
+    "clean": "node-gyp clean",
+    "configure": "node-gyp configure",
+    "//---- Shell scripts ----": "To check environment and libgpiod version",
+    "check": "bash script/check-env.sh",
+    "detect-version": "bash script/detect-gpiod-version.sh",
+    "//---- Javascript scripts ----": "Misc examples and tests",
+    "line-write": "node ./test/write.js",
+    "line-read": "node ./test/read.js",
+    "line-pwm-led": "node ./test/pwm-led.js",
+    "line-pwm-motor": "node ./test/pwm-motor.js",
+    "benchmark-write": "node ./test/benchmark-write.js",
+    "benchmark-read": "node ./test/benchmark-read.js",
+    "benchmark-pwm": "node ./test/benchmark-pwm.js",
+    "test-close": "node ./test/close-all.js",
+    "test-instance": "node ./test/duplicate-error.js",
+    "test-line": "node ./test/line-configuration.js"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm",
+    "arm64"
+  ],
+  "dependencies": {
+    "node-addon-api": "^7.0.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^10.0.0"
+  },
+  "gypfile": true,
+  "binary": {
+    "napi_versions": [
+      3,
+      4,
+      5,
+      6,
+      7,
+      8
+    ]
   }
-}
+}