rpi-io 2.2.4 → 3.1.0

package/documentation/stepper-motor.md

@@ -0,0 +1,192 @@
+# Stepper Motor Extensions
+
+Using the basic **rpi-io** methods for output  lines (*write*, *pulseStart*, *pulseStop*), it is easy to drive stepper motors, ranging from simple hobbyist motors (e.g., 28BYJ-48) to those designed for robotics and industrial applications, such as the NEMA series (e.g., NEMA 17, 23...) using some hardware driver (e.g. DMA542).
+
+To facilitate this type of use, since version 3.1 **rpi-io** has included two stepper motor controller classes:
+
+- The *StepperUnipolar* class is intended for stepper motors without a hardware driver.
+- The *StepperBipolar* class is intended for stepper motors with a hardware driver such as the DM542.
+
+
+
+## class StepperUnipolar
+
+### Electronic wiring example
+
+![](https://rpisquare.com//img/stepper-unipolar.png)
+
+PLEASE NOTE:
+
+- **GND is shared** — the Pi's GND and the ULN2003's GND must be tied together even if you power the motor from a separate supply, or the signals won't have a common reference.
+
+- **Power source for VCC**: for light loads the Pi's 5V pin can drive the ULN2003/motor directly, but the 28BYJ-48 can draw enough current that it's safer to power VCC from a separate 5V supply, keeping only GND common with the Pi.
+
+- The four GPIO pins (17, 18, 27, 22) are just a common convention — any four free GPIO pins work, as long as your code (e.g. via `RPi.GPIO` or `gpiozero`) references the pins you actually wired.
+
+- The ULN2003 board's output side connects to the motor with its keyed 5-pin connector — it only fits one way, so no wiring decisions needed there.
+
+
+
+### Example
+
+See test [script](https://github.com/gdorbes/rpi-io/blob/master/test/stepper-motor-unipolar.js).
+
+```js
+import {StepperUnipolar, RIO, traceCfg, log, warn, sleep} from "../extensions/stepper-unipolar.mjs"
+
+traceCfg(2)
+
+// Open step controller in half step mode => Half turn forward and backward => Close
+const motor28BYJH = new StepperUnipolar(new RIO(21, "output"), new RIO(22, "output"), new RIO(24, "output"), new RIO(25, "output"), "half", 0)
+log("motor28BYJH creation status:", motor28BYJH.status)
+await motor28BYJH.rotate(2048, "forward", false)
+await motor28BYJH.rotate(2048, "backward", false)
+motor28BYJH.close()
+
+// Open step controller in full step mode => Half turn forward and backward => Close
+const motor28BYJF = new StepperUnipolar(new RIO(21, "output"), new RIO(22, "output"), new RIO(24, "output"), new RIO(25, "output"), "full", 4)
+log("motor28BYJF creation status:", motor28BYJF.status)
+await motor28BYJF.rotate(1024, "forward", false)
+await motor28BYJF.rotate(1024, "backward", false)
+motor28BYJF.close()
+```
+
+
+
+### API
+
+#### constructor StepperUnipolar(coilA, coilB, coilC, coilD, mode, delay)
+
+**Parameter(s)**
+
+- **coilA** *{Object}* **rpi-io** instance for Coil A
+
+- **coilB** *{Object}* **rpi-io** instance for Coil B
+
+- **coilC** *{Object}* **rpi-io** instance for Coil C
+
+- **coilD** *{Object}* **rpi-io** instance for Coil D
+
+- ##### **mode** *{'half','full'}* sequence mode: half step or full step
+
+- **delay** *{Number}* delay in ms between steps
+
+
+
+**Return** *{Object}* StepperUnipolar instance
+
+
+
+#### rotate(steps, direction, showStep)
+
+**Parameter(s)**
+
+- **steps** *{Number}* 
+- **direction** *{'forward'|'backward"'* 
+- **showStep** *{Boolean}* ** to display step in console (default = false)
+
+**Return** *{Promise}* 
+
+
+
+#### close()
+
+To disable coils and close rpi-io instances.
+
+
+
+## class StepperBipolar
+
+### Electronic wiring example
+
+![](https://rpisquare.com//img/stepper-bipolar.png)
+
+PLEASE NOTE:
+
+- **The junction dot** is where the Pi's 5V pin splits into two wires, tying PUL+ and DIR+ together onto one common rail.
+
+- **STEP and DIR switch low to trigger**, since GPIO pulls PUL- or DIR- down relative to the shared +5V. 
+
+- **Voltage margin is tight**: the Pi's GPIO output high is 3.3V, but the common rail here is 5V, giving only ~1.7V across the optocoupler when "off" — close to some optocouplers' turn-off threshold. Many builds get away with this, but if you see erratic stepping consider using a Darlington array (e.g. ULN2003) between RPi and DM542.
+
+- **ENA+/ENA-** would follow the same common-anode pattern if you wire it — tied into the same 5V junction, with a GPIO pin driving ENA- low to enable.
+
+
+
+### Example
+
+See test [script](https://github.com/gdorbes/rpi-io/blob/master/test/stepper-motor-bipolar.js).
+
+```js
+import {StepperBipolar, RIO, traceCfg, log, warn, sleep, ctrlC} from "../extensions/stepper-bipolar.mjs"
+
+traceCfg(2)
+
+ctrlC(() => {
+    RIO.closeAll()
+})
+
+// Open output lines GPIO21 and GPIO22
+const pul = new RIO(21, "output", {value: 0})
+const dir = new RIO(22, "output", {value: 0})
+
+// Create Bipolar Stepper Motor instance
+const bipolar = new StepperBipolar(pul, dir, "desc", 10)
+
+// Start rotating full turn (depending on hardware driver settings)
+bipolar.rotate(25600, "forward").then(stepped => {
+    log("stepped:", stepped)
+    // Reset and close lines
+    pul.write(0)
+    dir.write(0)
+    pul.close()
+    dir.close()
+})
+
+// Stop rotation after 200ms
+await sleep(200)
+log("stop rotation")
+bipolar.stop()
+```
+
+
+
+### API
+
+#### constructor StepperBipolar(pul, dir, edge, width)
+
+**Parameter(s)**
+
+- **pul** *{Object}* **rpi-io** instance for pulse pin
+
+- **dir** *{Object}* **rpi-io** instance for direction pin
+
+- ##### **edge** *{'desc','asc'}* pulse active edge: descending or ascending
+
+- **width** *{Number}* pulse width and space between two edges in µs 
+
+**Return** *{Object}* StepperBipolar instance
+
+
+
+#### rotate(steps, direction)
+
+**Parameter(s)**
+
+- **steps** *{Number}* 
+- **direction** *{'forward'|'backward"'* 
+- **showStep** *{Boolean}* ** to display step in console (default = false)
+
+**Return** *{Promise<{elapsedMs: number, pulsesCompleted: number, stopped: boolean}>}* 
+
+
+
+#### stop()
+
+To interrupt an ongoing pulse sequence if one is in progress.
+
+
+
+#### close()
+
+To disable *pul* and *dir* rpi-io instances.

package/esm/log.mjs

@@ -1,58 +1,48 @@
 // -------------------------------------------------------------------
 // RPI-IO: Custom console.log
 // -------------------------------------------------------------------
-let debug = {
-    trace: false,
-    warn: true
+const noop = function () {
 }
-
+export let log = noop
+export let warn = noop
 /** ------------------------------------------------------------------
  * @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)
+    const nowStr = () => {
+        const date = new Date()
+        return date.toLocaleTimeString() + "." + date.getMilliseconds().toLocaleString('en', {
+            minimumIntegerDigits: 3,
+            minimumFractionDigits: 0,
+            useGrouping: false
+        })
+    }
+    const timeStamped = function () {
         console.log.apply(console, Array.prototype.concat.apply([nowStr(), "🔎 "], arguments))
-}
+    }
+    const timeColored = function () {
+        console.log.apply(console, Array.prototype.concat.apply([nowStr(), "⚠️ ", "\x1b[38;2;255;80;0m", ...arguments, "\x1b[0m"]))
+    }
 
-/** ------------------------------------------------------------------
- * @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"]))
+    switch (level) {
+        case 2:
+            warn = timeColored
+            log = timeStamped
+            break
+        case 1:
+            warn = timeColored
+            log = noop
+            break
+        default:
+            warn = noop
+            log = noop
+    }
 }
 
+
 // -------------------------------------------------------------------
 // EoF
 // -------------------------------------------------------------------

package/esm/main.mjs

@@ -104,7 +104,7 @@ export class RIO {
                     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)")
+                    throw new RangeError("PWM period is out of range (100ns - 1s)")
 
                 // Normalize PWM values in ns
                 this.period = opt.period * 1000
@@ -190,7 +190,7 @@ export class RIO {
             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")
+            throw new RangeError("Value must be either 0 or 1")
 
         ADDON.write(this.handle, value)
     }
@@ -306,12 +306,65 @@ export class RIO {
             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")
+            throw new RangeError("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 pulseStart
+     * @description Start a train of N pulses on an output GPIO line
+     * @param {Number} count        - Number of pulses
+     * @param {"asc"|"desc"} edge   - ascending/descending edge
+     * @param {Object} opt          - See pulse properties belows
+     * @return {Promise<{elapsedMs: number, pulsesCompleted: number, stopped: boolean}>}
+     */
+    pulseStart(count, edge, opt) {
+
+        const edges = ["desc", "asc"]
+        const defopt = {
+            pulseWidth: 10, // Pulse width in µs
+            spaceWidth: 10, // Space width between pulses in µs
+        }
+        opt = {...defopt, ...opt}
+
+
+        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 (!Number.isInteger(count) || count <= 0) {
+            throw new RangeError("Count must be a positive integer")
+        }
+
+        if (edges.indexOf(edge) === -1) {
+            throw new RangeError("Invalid edge value")
+        }
+
+        if (!Number.isFinite(opt.pulseWidth) || opt.pulseWidth < 0) {
+            throw new RangeError("pulseWidth must be a non-negative number")
+        }
+        if (!Number.isFinite(opt.spaceWidth) || opt.spaceWidth < 0) {
+            throw new RangeError("spaceWidth must be a non-negative number")
+        }
+
+        return ADDON.pulse(this.handle, count, Math.round(opt.spaceWidth), Math.round(opt.spaceWidth), edge === edges[0] ? 0 : 1)
+    }
+
+    /** --------------------------------------------------------------
+     * @method pulseStop
+     * @description Immediately interrupts an ongoing pulse sequence if one is in progress.
+     *              Synchronous and blocking (a few ms max in practice), the handle remains open and usable afterwards.
+     *              Upon return, the line is guaranteed to be idle—no pulses remain in flight.
+     * @return {Boolean} true if a sequence was in progress and was stopped.
+     */
+    pulseStop() {
+        return ADDON.pulseStop(this.handle)
+    }
+
     // -------------------------------------------------------------------
     // STATIC FUNCTIONS
     /** ------------------------------------------------------------------

package/extensions/stepper-bipolar.mjs

@@ -0,0 +1,131 @@
+// -------------------------------------------------------------------
+// RPI-IO: BIPOLAR STEPPER MOTOR EXTENSION
+// -------------------------------------------------------------------
+import {RIO, traceCfg, log, warn, sleep, ctrlC} from "../esm/main.mjs"
+
+export {RIO, traceCfg, log, warn, sleep, ctrlC}
+
+/** ------------------------------------------------------------------
+ * @class StepperBipolar
+ * @description Class definition for Bipolar Stepper motors.
+ * Bipolar stepper motors (e.g. NEMA 17 or 23) require hardware driver
+ * such as DM542 or equilavent depending on motor power
+ */
+export class StepperBipolar {
+
+    static STATUS_MSG = {
+        0: "none",
+        11: "pul or dir rpi-io instance definition is missing",
+        12: "At least one rpi-io instance is not valid",
+        13: "Wrong edge {'asc','desc'}",
+        14: "Wrong pulse width (5 ≤ p ≤ 10,000,000)",
+        200: "ok"
+    }
+
+    static EDGES = ["desc", "asc"]
+
+    // Private method: Update instance status
+    #setStatus(code, data) {
+        this.status.code = code
+        this.status.msg = StepperBipolar.STATUS_MSG[code]
+        this.status.data = data
+    }
+
+    /** ------------------------------------------------------------------
+     * @method constructor
+     * @param {Object} pul           // rpi-io output instance for pulse pin
+     * @param {Object} dir           // rpi-io output instance for direction pin
+     * @param {"desc"|"asc"} edge    // pulse active edge: descending or ascending
+     * @param {Number} width         // pulse width and space between two edges in µs
+     */
+    constructor(pul, dir, edge, width) {
+
+        // Init instance construction status
+        this.status = {
+            code: 0,
+            msg: StepperBipolar.STATUS_MSG[0],
+            data: ""
+        }
+
+        // ERR11: pul or pir rpi-io instance definition is missing
+        if (typeof pul === "undefined" || typeof dir === "undefined") {
+            this.#setStatus(11, "")
+            RIO.closeAll()
+            return
+        }
+
+        // ERR12: At least one coil port rpi-io instance is not valid
+        try {
+            pul.write(0)
+            dir.write(0)
+        } catch (err) {
+            this.#setStatus(12, "")
+            RIO.closeAll()
+            return
+        }
+
+        // ERR13: Wrong edge {'asc','desc'}
+        if (StepperBipolar.EDGES.indexOf(edge) === -1) {
+            this.#setStatus(13, edge)
+            RIO.closeAll()
+            return
+        }
+
+        // ERR14: Wrong pulse width (5 ≤ p ≤ 10,000,000)
+        if (typeof width !== "number" || width < 5 || width > 10000000) {
+            this.#setStatus(14, width)
+            RIO.closeAll()
+            return
+        }
+
+        // Test successfully completed  => Init properties
+        this.ioPulse = pul
+        this.ioDir = dir
+        this.edge = edge
+        this.width = width
+        this.#setStatus(200, "")
+    }
+
+    /** ------------------------------------------------------------------
+     * @method rotate
+     * @description Rotate the motor a certain number of steps forward or backward.
+     *              Full rotation depends on hardware driver settings.
+     * @param {Number} steps
+     * @param {"forward"|"backward"} direction
+     * @return {Promise<{elapsedMs: number, pulsesCompleted: number, stopped: boolean}>}
+     */
+    async rotate(steps, direction) {
+
+        // Set direction
+        this.ioDir.write("forward" ? 1 : 0)
+
+        // Start rotation
+        log("starting rotation:", steps, "steps", direction)
+        return await this.ioPulse.pulseStart(steps, this.edge, {
+            pulseWidth: this.width,
+            spaceWidth: this.width,
+        })
+    }
+
+    /** ------------------------------------------------------------------
+     * @method stop
+     * @description Immediately interrupts an ongoing pulse sequence if one is in progress.
+     */
+    stop() {
+        this.ioPulse.pulseStop()
+    }
+
+    /** ------------------------------------------------------------------
+     * @method close
+     * @description Disable pul and dir rpi-io instances used for this step motor controller
+     */
+    close() {
+        this.ioPulse.close
+        this.ioDir.close
+        log("Bipolar controller closed")
+    }
+}
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/extensions/stepper-unipolar.mjs

@@ -0,0 +1,172 @@
+// -------------------------------------------------------------------
+// RPI-IO: UNIPOLAR STEPPER MOTOR EXTENSION
+// -------------------------------------------------------------------
+import {RIO, traceCfg, log, warn, sleep} from "../esm/main.mjs"
+
+export {RIO, traceCfg, log, warn, sleep}
+
+/** ------------------------------------------------------------------
+ * @class StepperUnipolar
+ * @description Class definition for Unipolar Stepper motors.
+ * Unipolar stepper motors (e.g. 28BYJ-48) are directly controlled by  RPi using
+ * a Darlington Transistor Array (e.g. ULN2003)
+ */
+export class StepperUnipolar {
+
+    static STATUS_MSG = {
+        0: "none",
+        11: "At least one coil port rpi-io instance definition is missing",
+        12: "At least one coil port rpi-io instance is not valid",
+        13: "Wrong delay parameter value (0 ≤ d ≤ 1000)",
+        14: "Wrong Unipolar sequence {'full','half'}",
+        200: "ok"
+    }
+    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]
+        ]
+    }
+
+    // Private method: Update instance status
+    #setStatus(code, data) {
+        this.status.code = code
+        this.status.msg = StepperUnipolar.STATUS_MSG[code]
+        this.status.data = data
+    }
+
+    /** ------------------------------------------------------------------
+     * @method constructor
+     * @param {Object} coilA         // rpi-io output instance for CoilA
+     * @param {Object} coilB         // rpi-io output instance for CoilB
+     * @param {Object} coilC         // rpi-io output instance for CoilC
+     * @param {Object} coilD         // rpi-io output instance for CoilD
+     * @param {"half"|"ful"} mode    // Full or half step sequence
+     * @param {Number} delay         // Delay between steps in ms
+     */
+    constructor(coilA, coilB, coilC, coilD, mode = "half", delay = 10) {
+
+        // Init instance construction status
+        this.status = {
+            code: 0,
+            msg: StepperUnipolar.STATUS_MSG[0],
+            data: ""
+        }
+
+        // ERR11: At least one coil port rpi-io instance definition is missing
+        if (typeof coilA === "undefined" || typeof coilB === "undefined" || typeof coilC === "undefined" || typeof coilD === "undefined") {
+            this.#setStatus(11, "")
+            RIO.closeAll()
+            return
+        }
+
+        // ERR12: At least one coil port rpi-io instance is not valid
+        try {
+            coilA.write(0)
+            coilB.write(0)
+            coilC.write(0)
+            coilD.write(0)
+        } catch (err) {
+            this.#setStatus(12, "")
+            RIO.closeAll()
+            return
+        }
+
+        // ERR13: Wrong delay parameter value (0 ≤ d ≤ 1000)
+        if (typeof delay !== "number" || delay < 0 || delay > 1000) {
+            this.#setStatus(13, delay)
+            RIO.closeAll()
+            return
+        }
+
+        // ERR14: Wrong mode {'full','half'}
+        if (StepperUnipolar.MODE.indexOf(mode) === -1) {
+            this.#setStatus(14, mode)
+            RIO.closeAll()
+            return
+        }
+
+        // Test successfully completed  => Init properties
+        this.coils = {
+            a: coilA,
+            b: coilB,
+            c: coilC,
+            d: coilD,
+        }
+        this.sequence = StepperUnipolar.STEPS[mode]
+        this.len = this.sequence.length
+        this.delay = delay
+        this.index = 0
+        this.increment = 0
+        this.#setStatus(200, "")
+    }
+
+    /** ------------------------------------------------------------------
+     * @method rotate
+     * @description Rotate the motor a certain number of steps forward or backward.
+     *              Full rotation depends on selected mode.
+     * @param {Number} steps
+     * @param {"forward"|"backward"} direction
+     * @param {Boolean} showStep
+     */
+    async rotate(steps, direction, showStep = false) {
+
+        this.increment = direction === "forward" ? 1 : -1
+
+        log("starting rotation:", steps, "steps", direction)
+
+        // Rotate
+        for (let i = 0; i < steps; i++) {
+            const [a, b, c, d] = this.sequence[this.index]
+            if (showStep) {
+                log("rotation step:", i, [a, b, c, d])
+            }
+            this.coils.a.write(a)
+            this.coils.b.write(b)
+            this.coils.c.write(c)
+            this.coils.d.write(d)
+
+            this.index = ((this.index + this.increment % this.len + this.len) % this.len)
+            await sleep(this.delay, false)
+        }
+
+        // Disable coils
+        this.coils.a.write(0)
+        this.coils.b.write(0)
+        this.coils.c.write(0)
+        this.coils.d.write(0)
+    }
+
+    /** ------------------------------------------------------------------
+     * @method close
+     * @description Disable coils and close rpi-io instances used for this step motor controller
+     */
+    close() {
+        this.coils.a.write(0)
+        this.coils.b.write(0)
+        this.coils.c.write(0)
+        this.coils.d.write(0)
+        this.coils.a.close()
+        this.coils.b.close()
+        this.coils.c.close()
+        this.coils.d.close()
+        log("Unipolar controller closed")
+    }
+}
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpi-io",
-  "version": "2.2.4",
+  "version": "3.1.0",
   "description": "Nodejs module to control Raspberry Pi GPIO",
   "keywords": [
     "raspberry",
@@ -18,7 +18,11 @@
     "bookworm",
     "trixie",
     "iot",
-    "embedded"
+    "embedded",
+    "motor",
+    "stepper",
+    "motor control",
+    "stepper motor"
   ],
   "homepage": "https://github.com/gdorbes/rpi-io#readme",
   "bugs": {