rpi-io 2.1.3 → 2.2.0

package/CHANGELOG.md

@@ -1,7 +1,13 @@
 # Changelog
-## [2.1.3] - 2026-06-04
+## [2.2.0] - 2026-007-06
+### Added
+- Static function RIO.lineIsSupported(*line*)
+- Static function RIO.lineIsAvailable(*line*)
+
+## [2.1.5] - 2026-06-05
 ### Changed
 - License MIT replaced by EUPL
+- Announcement as rpisquare.com module
 
 ## [2.1.1] - 2026-03-26
 ### Changed

package/README.md

@@ -1,7 +1,7 @@
 # rpi-io
-![Static Badge](https://img.shields.io/badge/rpi--io-_2.1.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)
+![Static Badge](https://img.shields.io/badge/rpi--io-_2.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)
 
-Current version is 2.1.3. More details in [CHANGELOG.md](CHANGELOG.md).
+Current version is 2.2.0. Latest update includes new static utility functions. More details in [CHANGELOG.md](CHANGELOG.md).
 
 **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.
 
@@ -15,6 +15,7 @@ Current version is 2.1.3. More details in [CHANGELOG.md](CHANGELOG.md).
     - 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.
 
+**rpi-io** is a key module of the solution [rpisquare.com](https://rpisquare.com) to control peripherals of remote Raspberry Pi devices.
 
 ## Prerequisites
 
@@ -339,7 +340,7 @@ import {RIO, sleep, ctrlC, } from "rpi-io"
 - [API reference guide](documentation/api.md)
 - [Benchmark](documentation/benchmark.md)
 
-## Licence
+## License
 
 [EUPL](https://interoperable-europe.ec.europa.eu/collection/eupl)
 

package/documentation/api.md

@@ -186,12 +186,47 @@ RIO.closeAll()
 
 Function to return current model of RPi.
 
+#### Example
+
 ```javascript
 import {RIO} from "rpi-io"
 console.log("model:", RIO.model())
 // Returns '5B', '4B', '3B', 'Zero2', 'Zero' or '' when unknown.
 ```
 
+
+
+### RIO.lineIsSupported(line)
+
+Function to test that RIO supports a GPIO line number
+
+#### Example
+
+```js
+import {RIO} from "rpi-io"
+
+console.log("line  1 is supported:", RIO.lineIsSupported(1)) // displays false
+console.log"line 17 is supported:", RIO.lineIsSupported(17)) // displays true
+```
+
+
+
+### RIO.lineIsAvailable(line)
+
+Function to test that RIO supports a GPIO line number and that is is not yet used
+
+```js
+import {RIO} from "rpi-io"
+
+RIO.closeAll() // Release any open instance
+console.log"line 17 is supported:", RIO.lineIsAvailable(17)) // displays true
+const led = new RIO(17, "output", {value: 0})
+log("line 17 is available:", RIO.lineIsAvailable(17)) // displays false
+RIO.closeAll()
+```
+
+
+
 ## Utilities
 
 ###  log(args)

package/esm/main.mjs

@@ -14,10 +14,9 @@ export {traceCfg, log, warn, sleep, ctrlC, lineConfig, lineNumber}
 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_STD = [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"
 
 // -------------------------------------------------------------------
@@ -345,6 +344,28 @@ export class RIO {
             return ""
         }
     }
+
+    /** ------------------------------------------------------------------
+     * @function RIO.lineIsSupported
+     * @description Check that line number is supported by RIO
+     * @param {Number} line
+     * @return {Boolean}
+     */
+    static lineIsSupported(line) {
+        return RPI_GPIO_ALL.indexOf(line) !== -1
+    }
+
+    /** ------------------------------------------------------------------
+     * @function RIO.lineIsAvailable
+     * @description Check that line number is supported and
+     *              not yet used in a RIO instance
+     * @param {Number} line
+     * @return {Boolean}
+     */
+    static lineIsAvailable(line) {
+        if (!RIO.lineIsSupported(line)) return false
+        return !RIO.instances.has(line)
+    }
 }
 
 // -------------------------------------------------------------------

package/esm/uln2003.mjs

@@ -0,0 +1,115 @@
+// -------------------------------------------------------------------
+// RPI-IO: ULN2003 STEP MOTORS CONTROL
+// -------------------------------------------------------------------
+
+import {RIO} from "./main.mjs";
+
+export class ULN2003 {
+
+    static RPi_GPIO_STD = [5, 6, 16, 17, 20, 21, 22, 23, 24, 25, 26, 27]
+    static RPi_GPIO_PWM = [12, 13, 18, 19]
+
+    /** ------------------------------------------------------------------
+     * @function isValidGpio
+     * @description Check if pin a valid multipurpose GPIO
+     * @param {Number} pin
+     * @return {Boolean}
+     */
+    static static isValidGpio(pin) {
+        return [...ULN2003.RPi_GPIO_STD, ...ULN2003.RPi_GPIO_PWM].GPIOS.includes(pin);
+    }
+
+    static MODE = ["half", "full"]
+    static STEPS = {
+        half: [
+            [1, 0, 0, 0],
+            [1, 1, 0, 0],
+            [0, 1, 0, 0],
+            [0, 1, 1, 0],
+            [0, 0, 1, 0],
+            [0, 0, 1, 1],
+            [0, 0, 0, 1],
+            [1, 0, 0, 1]
+        ],
+        full: [
+            [1, 0, 0, 1],
+            [1, 1, 0, 0],
+            [0, 1, 1, 0],
+            [0, 0, 1, 1]
+        ]
+    }
+
+
+    /** ------------------------------------------------------------------
+     * @method constructor
+     * @param {Array} pins - Array of 4 GPIO BCM port number e.g. [21,22,24,25]
+     * @param {Object} opt - Delay between steps and sequencing mode. See below
+     */
+    constructor(pins, opt) {
+
+        // Init options with default values and check validity
+        const defopt = {
+            // Delay between two steps in 1 ≤ ms ≤ 1000
+            delayMs: 10,
+            // Sequencing mode: 'full' or 'half' (default)
+            seqMode: ULN2003.MODE[0]
+        }
+        opt = {...defopt, ...opt}
+        opt.seqMode = opt.seqMode.toLowerCase()
+
+        //  Check if pins
+        pins.forEach(pin => {
+            if (!ULN2003.isValidGpio(pin)) {
+                throw new Error("Invalid pin number: " + pin)
+            }
+        })
+
+
+        rpiIoInstances.forEach(instance => {
+            if (!instance instanceof RIO) throw new Error("Invalid instance")
+            if (instance.mode !== "output") throw new Error("Invalid instance mode")
+        })
+
+        // Reset option values if not valid
+        if (ULN2003.MODE.indexOf(opt.seqMode) === -1) opt.seqMode = defopt.seqMode
+        if (typeof opt.delayMs !== "number" || opt.delayMs < 1 || opt.delayMs > 1000) opt.delayMs = defopt.delayMs
+
+
+        // Throw error if list of rpi-io instances is not valid: wrong number, wrong instance, wrong mode
+        if (!Array.isArray(rpiIoInstances) || rpiIoInstances.length !== 4) throw new Error("Invalid instance list.")
+        rpiIoInstances.forEach(instance => {
+            if (!instance instanceof RIO) throw new Error("Invalid instance")
+            if (instance.mode !== "output") throw new Error("Invalid instance mode")
+        })
+
+        // No option error here
+
+        this.coils = rpiIoInstances
+        this.sequence = ULN2003.STEPS[opt.seqMode]
+        this.len = this.sequence.length
+        this.delay = opt.delayMs
+        this.A = rpiIoInstances[0]
+        this.B = rpiIoInstances[1]
+        this.C = rpiIoInstances[2]
+        this.D = rpiIoInstances[0]
+        this.inc = 0
+        this.index = 0
+    }
+}
+
+const toto = new ULN2003()
+
+
+/** ------------------------------------------------------------------
+ * @method uln2003
+ * @description To control step motors based on ULN20003-like drivers.
+ *              This function used 4 rpi-io output instances to control
+ *              step motors back and forth.
+ * @param {Object} pins
+ * @param {Number}  steps     - Nombre de pas (entier > 0)
+ * @param {'fwd'|'rev'} dir  - Direction : 'fwd' = avant, 'rev' = arrière
+ */
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-io",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Nodejs module to control Raspberry Pi GPIO",
   "keywords": [
     "raspberry",

package/test/exampleUln2003.js

@@ -0,0 +1,103 @@
+// -------------------------------------------------------------------
+// TEST - ULN 2003
+// -------------------------------------------------------------------
+import {RIO, traceCfg, log, sleep, ctrlC, lineNumber} from "../esm/main.mjs"
+
+(async () => {
+    traceCfg(2)
+
+    // Init outputs
+    const pins = {
+        A: new RIO(21, 'output', {value: 0}),
+        B: new RIO(22, 'output', {value: 0}),
+        C: new RIO(24, 'output', {value: 0}),
+        D: new RIO(25, 'output', {value: 0}),
+    }
+
+    const HALF_STEP = [
+        [1, 0, 0, 0],
+        [1, 1, 0, 0],
+        [0, 1, 0, 0],
+        [0, 1, 1, 0],
+        [0, 0, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [1, 0, 0, 1],
+    ]
+
+    const FULL_STEP = [
+        [1, 0, 0, 1],
+        [1, 1, 0, 0],
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+    ]
+
+    /** ------------------------------------------------------------------
+     * @function write
+     * @param {Number} port
+     * @param {Number} value
+     */
+    const write = (port, value) => {
+        pins[port].write(value)
+    }
+
+    const reset = () => {
+        for (const [port, instance] of Object.entries(pins)) {
+            instance.write(0)
+        }
+    }
+
+    const test = async () => {
+        for (const [port, instance] of Object.entries(pins)) {
+            instance.write(1)
+            await sleep(500)
+            instance.write(0)
+            await sleep(500)
+        }
+    }
+
+    // Close ports on ctrl+c
+    ctrlC(() => {
+        reset()
+        RIO.closeAll();
+    })
+
+    /** --------------------------------------------------------------
+     * @function stepMotor
+     * @param {Object} opts
+     * @param {Number}  opts.steps     - Nombre de pas (entier > 0)
+     * @param {'fwd'|'rev'} opts.dir  - Direction : 'fwd' = avant, 'rev' = arrière
+     * @param {number}  opts.delayMs  - Délai entre deux pas en millisecondes (≥ 1)
+     * @param {'half'|'full'} [opts.mode='half'] - Mode de séquençage
+     * @returns {Promise<void>}
+     */
+    async function stepMotor({steps, dir = 'fwd', delayMs = 10, mode = 'half'}) {
+        const sequence = mode === 'half' ? HALF_STEP : FULL_STEP;
+        const len = sequence.length;
+        const inc = dir === 'fwd' ? 1 : -1;
+        let index = 0;
+
+        for (let i = 0; i < steps; i++) {
+            const [a, b, c, d] = sequence[index];
+            write('A', a);
+            write('B', b);
+            write('C', c);
+            write('D', d);
+            index = ((index + inc) % len + len) % len;
+            await sleep(delayMs);          // sleep() natif rpi-io
+        }
+
+        // Désactivation des bobines
+        write('A', 0);
+        write('B', 0);
+        write('C', 0);
+        write('D', 0);
+    }
+
+
+    await stepMotor({ steps: 1600, dir: 'rev', delayMs: 8 })
+
+})()
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/test/line-test.js

@@ -0,0 +1,16 @@
+// -------------------------------------------------------------------
+// TEST - line support and availability
+// -------------------------------------------------------------------
+import {RIO, traceCfg, log} from "../esm/main.mjs"
+
+traceCfg(2)
+log("line  1 is supported:", RIO.lineIsSupported(1))
+log("line 17 is supported:", RIO.lineIsSupported(17))
+log("line 17 is available:", RIO.lineIsAvailable(17))
+const led = new RIO(17, "output", {value: 0})
+log("new instance with line 17")
+log("line 17 is available:", RIO.lineIsAvailable(17))
+RIO.closeAll()
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/test/model.js

@@ -1,5 +1,5 @@
 // -------------------------------------------------------------------
-// TEST - Simple write
+// TEST - Retrive RPi model
 // -------------------------------------------------------------------
 import {RIO} from "../esm/main.mjs"