rpi-io 2.2.3 → 3.0.0

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
-## [2.2.3] - 2026-007-06
+## [3.0.0] - 2026-07-18
 ### Added
-- Static function RIO.lineIsSupported(*line*)
-- Static function RIO.lineIsAvailable(*line*)
+- methods **pulseStart**(*count, edge, options*) and **pulseStop**() for output lines
+
+## [2.2.4] - 2026-07-06
+### Added
+- Static function **RIO.lineIsSupported**(*line*)
+- Static function **RIO.lineIsAvailable**(*line*)
 ### Changed
 - Fixes in License
 

package/README.md

@@ -1,7 +1,7 @@
 # rpi-io
-![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)
+![Static Badge](https://img.shields.io/badge/rpi--io-_3.y.z_-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.2.2. Latest update includes new static utility functions. More details in [CHANGELOG.md](CHANGELOG.md).
+Current version is 3.0.0. The latest update introduces pulse sequence management methods for output lines. See [CHANGELOG.md](CHANGELOG.md) and documentation folder.
 
 **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.
 
@@ -133,7 +133,7 @@ PLEASE NOTE: In all this document, GPIO line numbers are the BCM ones as defined
 
 ### *OUT* operations
 
-#### Example of LED control
+#### Examples of LED control
 ##### Diagram
 ```
 GPIO Pin (Output)
@@ -150,7 +150,7 @@ GPIO Pin (Output)
           ─
 ```
 
-##### Code example
+##### Simple write
 
 ```javascript
 // Import rpi-io module
@@ -169,6 +169,23 @@ setTimeout(()=>{
 }, 5000)
 ```
 
+Pulse sequence
+
+```js
+import {RIO} from "rpi-io"
+const myOutput = new RIO(17, "output", {value:0})
+
+// Slow pulse x10, ascending edge, w = 0.5 s, s = 0.5 s
+myOutput.pulseStart(10, "asc", {
+        pulseWidth: 500000,
+        spaceWidth: 500000
+    }).then(pulseStatus => {
+        console.log("pulse status stopped when completed:", pulseStatus)
+  		  // { elapsedMs: 9500.113291, pulsesCompleted: 10, stopped: false }
+        myOutput.close()
+    })
+```
+
 
 
 ### *IN* operations

package/addon/gpio.c

@@ -1,8 +1,7 @@
 // -------------------------------------------------------------------
-// RPI-IO: - gpio.c v38 - 2025-11-19
-// source: claude.ai/chat/f3139163-e976-47a4-8e46-01fee65686f2
-// -------------------------------------------------------------------
-
+// RPI-IO: - gpio.c v42 - 2026-07-16
+// Private source grd: https://claude.ai/chat/cf72d4ca-335a-410f-8d0d-c18d0c5a9f12
+// ------------------------------------------------------------------
 #include <node_api.h>
 #include <gpiod.h>
 #include <string.h>
@@ -45,12 +44,25 @@ typedef struct {
     pthread_t monitor_thread;
     napi_threadsafe_function tsfn;
     napi_ref callback_ref;
+
+    // Pour pulse() : empêche close()/finalize pendant un train en cours
+    // (opération exécutée dans le thread pool libuv via napi_async_work)
+    volatile int is_pulsing;
+    volatile int stop_requested; // positionné par close()/pulseStop() pour arrêter pulse() en cours
 } gpio_context_t;
 
+// Déclaration anticipée (définie plus loin, avec le reste du code de pulse()) :
+// utilisée par finalize_gpio ci-dessous.
+static int pulse_force_stop_and_wait(gpio_context_t *ctx, long timeout_ms);
+
 // Libérer les ressources GPIO
 static void finalize_gpio(napi_env env, void* finalize_data, void* finalize_hint) {
     gpio_context_t *ctx = (gpio_context_t*)finalize_data;
     if (ctx) {
+        // Si un pulse() tourne encore (handle GC sans close() explicite),
+        // on force son arrêt avant de libérer les ressources sous ses pieds.
+        pulse_force_stop_and_wait(ctx, 500);
+
         // Arrêter le monitoring si actif
         if (ctx->is_monitoring) {
             ctx->is_monitoring = 0;
@@ -745,6 +757,411 @@ static napi_value Read(napi_env env, napi_callback_info info) {
     return result;
 }
 
+// -------------------------------------------------------------------
+// Fonction: pulse(handle, count, widthUs, spacingUs, polarity)
+//
+// Génère un train de N impulsions sur une ligne déjà ouverte en sortie.
+// - count:      nombre d'impulsions
+// - widthUs:    largeur d'impulsion en microsecondes
+// - spacingUs:  espacement entre impulsions en microsecondes
+// - polarity:   1 = impulsion active à l'état HAUT (front montant)
+//               0 = impulsion active à l'état BAS (front descendant)
+//
+// Exécutée en tâche async_work dans le thread pool libuv pour ne pas
+// bloquer la boucle d'événements JS. Résout une Promise avec la durée
+// réelle écoulée (ms).
+// -------------------------------------------------------------------
+
+typedef struct {
+    napi_async_work work;
+    napi_deferred deferred;
+    gpio_context_t *ctx;
+
+    unsigned int count;
+    int64_t width_ns;
+    int64_t spacing_ns;
+    int polarity;      // 1 = actif haut, 0 = actif bas
+
+    double elapsed_ms;
+    unsigned int pulses_completed;
+    int stopped_early;  // 1 si interrompu par close()
+    int error_code;    // 0 = ok, sinon voir pulse_error_message()
+} pulse_work_t;
+
+// Plage acceptée pour widthUs/spacingUs, en microsecondes.
+// Le plafond (1h) est purement une garde-fou pratique : int64_t ne
+// déborde de toute façon pas avant des millénaires en nanosecondes,
+// mais une valeur aussi grande relève très probablement d'une erreur
+// de l'appelant (unité confondue ms/µs, notamment) plutôt qu'un vrai
+// besoin, et monopoliserait un thread du pool libuv inutilement.
+#define PULSE_MAX_US 3600000000LL // 1 heure en µs
+
+static const char* pulse_error_message(int code) {
+    switch (code) {
+        case 1: return "GPIO handle has been closed";
+        case 2: return "GPIO line is not configured as output";
+        case 3: return "Failed to set GPIO value during pulse train";
+        default: return "Unknown error during pulse()";
+    }
+}
+
+// Attente active de haute précision basée sur CLOCK_MONOTONIC.
+// Ne pas utiliser nanosleep()/usleep() ici : leur résolution/latence
+// réelle sur Linux (souvent >50-100µs de jitter) est insuffisante
+// pour des largeurs d'impulsion de quelques microsecondes.
+//
+// Découpée en tranches d'au plus PULSE_STOP_CHECK_NS pour que
+// stop_requested soit détecté rapidement même sur un long espacement,
+// sans quoi close() pourrait devoir attendre toute la durée restante.
+// Retourne 1 si l'attente a été interrompue par une demande d'arrêt.
+#define PULSE_STOP_CHECK_NS 2000000LL // 2 ms
+
+static int pulse_busy_wait_ns(int64_t ns, volatile int *stop_requested) {
+    if (ns <= 0) return 0;
+
+    struct timespec start, now;
+    clock_gettime(CLOCK_MONOTONIC, &start);
+
+    long long remaining_ns = ns;
+
+    while (remaining_ns > 0) {
+        long long slice_ns = remaining_ns < PULSE_STOP_CHECK_NS ? remaining_ns : PULSE_STOP_CHECK_NS;
+
+        // Recalcule la cible de fin de tranche à partir de maintenant
+        clock_gettime(CLOCK_MONOTONIC, &now);
+        long long slice_target_nsec = (long long)now.tv_nsec + slice_ns;
+        time_t slice_target_sec = now.tv_sec + (time_t)(slice_target_nsec / 1000000000LL);
+        slice_target_nsec %= 1000000000LL;
+
+        do {
+            clock_gettime(CLOCK_MONOTONIC, &now);
+        } while (now.tv_sec < slice_target_sec ||
+                 (now.tv_sec == slice_target_sec && now.tv_nsec < slice_target_nsec));
+
+        if (*stop_requested) {
+            return 1;
+        }
+
+        // Temps réellement écoulé depuis le début de l'attente totale
+        long long elapsed_ns = (long long)(now.tv_sec - start.tv_sec) * 1000000000LL +
+                                ((long long)now.tv_nsec - (long long)start.tv_nsec);
+        remaining_ns = ns - elapsed_ns;
+    }
+
+    return 0;
+}
+
+// Positionne la ligne à la valeur donnée. Retourne 0 si ok, <0 sinon.
+// Réutilise directement le handle déjà ouvert par openOutput() -
+// pas de réouverture de chip/ligne, pour une latence minimale.
+static int pulse_set_value(gpio_context_t *ctx, int value) {
+#ifdef LIBGPIOD_V2
+    enum gpiod_line_value gpio_value = value ? GPIOD_LINE_VALUE_ACTIVE : GPIOD_LINE_VALUE_INACTIVE;
+    return gpiod_line_request_set_value(ctx->request, ctx->offset, gpio_value);
+#else
+    return gpiod_line_set_value(ctx->line, value ? 1 : 0);
+#endif
+}
+
+// Demande l'arrêt d'un pulse() en cours et attend (bloquant, thread JS)
+// sa terminaison effective dans le thread du pool libuv, bornée par
+// timeout_ms par sécurité. Ne fait rien si aucun pulse() n'est en cours.
+// Retourne 1 si un train était effectivement en cours et a été arrêté,
+// 0 si rien n'était en cours.
+static int pulse_force_stop_and_wait(gpio_context_t *ctx, long timeout_ms) {
+    if (!ctx->is_pulsing) {
+        return 0;
+    }
+
+    // Vu depuis PulseExecute (thread pool libuv) toutes les 2 ms max
+    // pendant les attentes, et à chaque itération sinon.
+    ctx->stop_requested = 1;
+
+    struct timespec wait_start, now;
+    clock_gettime(CLOCK_MONOTONIC, &wait_start);
+
+    while (ctx->is_pulsing) {
+        usleep(200); // 0.2 ms - relâche le CPU, pas de busy-wait pur ici
+        clock_gettime(CLOCK_MONOTONIC, &now);
+        long elapsed_ms = (now.tv_sec - wait_start.tv_sec) * 1000L +
+                           (now.tv_nsec - wait_start.tv_nsec) / 1000000L;
+        if (elapsed_ms > timeout_ms) {
+            // Ne devrait jamais arriver (vérifications toutes les 2ms max
+            // côté PulseExecute). Filet de sécurité pour ne jamais bloquer
+            // indéfiniment l'appelant.
+            fprintf(stderr,
+                "rpi-io: warning - pulse() stop timed out after %ldms\n",
+                timeout_ms);
+            break;
+        }
+    }
+
+    ctx->stop_requested = 0;
+    return 1;
+}
+
+// Exécuté dans le thread pool libuv - jamais sur le thread JS principal
+static void PulseExecute(napi_env env, void* data) {
+    pulse_work_t *w = (pulse_work_t*)data;
+    gpio_context_t *ctx = w->ctx;
+
+    if (ctx->is_closed) {
+        w->error_code = 1;
+        return;
+    }
+    if (!ctx->is_output) {
+        w->error_code = 2;
+        return;
+    }
+
+    int active_value = w->polarity ? 1 : 0;
+    int idle_value = w->polarity ? 0 : 1;
+
+    struct timespec t0, t1;
+    clock_gettime(CLOCK_MONOTONIC, &t0);
+
+    unsigned int i;
+    for (i = 0; i < w->count; i++) {
+        if (ctx->stop_requested) {
+            w->stopped_early = 1;
+            break;
+        }
+
+        if (pulse_set_value(ctx, active_value) < 0) {
+            w->error_code = 3;
+            break;
+        }
+
+        if (pulse_busy_wait_ns(w->width_ns, &ctx->stop_requested)) {
+            w->stopped_early = 1;
+            // On coupe immédiatement l'impulsion avant de sortir
+            pulse_set_value(ctx, idle_value);
+            break;
+        }
+
+        if (pulse_set_value(ctx, idle_value) < 0) {
+            w->error_code = 3;
+            break;
+        }
+
+        if (i < w->count - 1) {
+            if (pulse_busy_wait_ns(w->spacing_ns, &ctx->stop_requested)) {
+                w->stopped_early = 1;
+                break;
+            }
+        }
+    }
+
+    // Sécurité : quelle que soit la raison de sortie, s'assurer que la
+    // ligne est bien au repos avant de rendre la main.
+    if (w->error_code == 0) {
+        pulse_set_value(ctx, idle_value);
+    }
+
+    w->pulses_completed = i < w->count ? i : w->count;
+
+    clock_gettime(CLOCK_MONOTONIC, &t1);
+    w->elapsed_ms = (double)(t1.tv_sec - t0.tv_sec) * 1000.0 +
+                    (double)(t1.tv_nsec - t0.tv_nsec) / 1e6;
+
+    // IMPORTANT: is_pulsing doit être remis à 0 ICI, dans le thread du
+    // pool libuv, et non dans PulseComplete (qui s'exécute sur le thread
+    // JS principal). close()/pulseStop() bloquent volontairement le
+    // thread JS en attendant is_pulsing == 0 : si ce flag n'était remis
+    // à 0 que par PulseComplete, on aurait un interblocage (le thread JS
+    // bloqué empêcherait sa propre boucle d'événements de déclencher
+    // PulseComplete).
+    ctx->is_pulsing = 0;
+}
+
+// Exécuté de retour sur le thread JS - résout ou rejette la Promise
+static void PulseComplete(napi_env env, napi_status status, void* data) {
+    pulse_work_t *w = (pulse_work_t*)data;
+
+    // Note: ctx->is_pulsing a déjà été remis à 0 par PulseExecute
+    // (voir commentaire à la fin de PulseExecute pour la raison).
+
+    if (status != napi_ok || w->error_code != 0) {
+        napi_value err;
+        const char *msg = (status != napi_ok)
+            ? "Async work failed"
+            : pulse_error_message(w->error_code);
+        napi_create_string_utf8(env, msg, NAPI_AUTO_LENGTH, &err);
+        napi_reject_deferred(env, w->deferred, err);
+    } else {
+        napi_value result, elapsed, completed, stopped;
+        napi_create_object(env, &result);
+        napi_create_double(env, w->elapsed_ms, &elapsed);
+        napi_create_uint32(env, w->pulses_completed, &completed);
+        napi_get_boolean(env, w->stopped_early, &stopped);
+
+        napi_set_named_property(env, result, "elapsedMs", elapsed);
+        napi_set_named_property(env, result, "pulsesCompleted", completed);
+        napi_set_named_property(env, result, "stopped", stopped);
+
+        napi_resolve_deferred(env, w->deferred, result);
+    }
+
+    napi_delete_async_work(env, w->work);
+    free(w);
+}
+
+static napi_value Pulse(napi_env env, napi_callback_info info) {
+    napi_status status;
+    size_t argc = 5;
+    napi_value args[5];
+    gpio_context_t *ctx = NULL;
+    int32_t count, polarity;
+    int64_t width_us, spacing_us;
+
+    status = napi_get_cb_info(env, info, &argc, args, NULL, NULL);
+    if (status != napi_ok || argc < 5) {
+        napi_throw_error(env, NULL,
+            "Expected (handle, count, widthUs, spacingUs, polarity) arguments");
+        return NULL;
+    }
+
+    status = napi_get_value_external(env, args[0], (void**)&ctx);
+    if (status != napi_ok || !ctx) {
+        napi_throw_error(env, NULL, "Invalid GPIO handle");
+        return NULL;
+    }
+
+    if (ctx->is_closed) {
+        napi_throw_error(env, NULL, "GPIO handle has been closed");
+        return NULL;
+    }
+
+    if (!ctx->is_output) {
+        napi_throw_error(env, NULL, "GPIO line is not configured as output");
+        return NULL;
+    }
+
+    if (ctx->is_pulsing) {
+        napi_throw_error(env, NULL, "A pulse() train is already in progress on this handle");
+        return NULL;
+    }
+
+    if (napi_get_value_int32(env, args[1], &count) != napi_ok || count <= 0) {
+        napi_throw_error(env, NULL, "Invalid count: must be a positive integer");
+        return NULL;
+    }
+    if (napi_get_value_int64(env, args[2], &width_us) != napi_ok ||
+        width_us < 0 || width_us > PULSE_MAX_US) {
+        napi_throw_error(env, NULL,
+            "Invalid widthUs: must be an integer in [0, 3600000000] (0 to 1h in microseconds)");
+        return NULL;
+    }
+    if (napi_get_value_int64(env, args[3], &spacing_us) != napi_ok ||
+        spacing_us < 0 || spacing_us > PULSE_MAX_US) {
+        napi_throw_error(env, NULL,
+            "Invalid spacingUs: must be an integer in [0, 3600000000] (0 to 1h in microseconds)");
+        return NULL;
+    }
+    if (napi_get_value_int32(env, args[4], &polarity) != napi_ok) {
+        napi_throw_error(env, NULL, "Invalid polarity: must be 0 or 1");
+        return NULL;
+    }
+
+    pulse_work_t *w = (pulse_work_t*)malloc(sizeof(pulse_work_t));
+    if (!w) {
+        napi_throw_error(env, NULL, "Memory allocation failed");
+        return NULL;
+    }
+    memset(w, 0, sizeof(pulse_work_t));
+
+    w->ctx = ctx;
+    w->count = (unsigned int)count;
+    w->width_ns = width_us * 1000LL;
+    w->spacing_ns = spacing_us * 1000LL;
+    w->polarity = polarity ? 1 : 0;
+
+    napi_value promise;
+    status = napi_create_promise(env, &w->deferred, &promise);
+    if (status != napi_ok) {
+        free(w);
+        napi_throw_error(env, NULL, "Failed to create promise");
+        return NULL;
+    }
+
+    napi_value resource_name;
+    napi_create_string_utf8(env, "GPIOPulse", NAPI_AUTO_LENGTH, &resource_name);
+
+    status = napi_create_async_work(env, NULL, resource_name,
+                                     PulseExecute, PulseComplete, w, &w->work);
+    if (status != napi_ok) {
+        free(w);
+        napi_throw_error(env, NULL, "Failed to create async work");
+        return NULL;
+    }
+
+    ctx->is_pulsing = 1;
+    ctx->stop_requested = 0;
+
+    status = napi_queue_async_work(env, w->work);
+    if (status != napi_ok) {
+        ctx->is_pulsing = 0;
+        napi_delete_async_work(env, w->work);
+        free(w);
+        napi_throw_error(env, NULL, "Failed to queue async work");
+        return NULL;
+    }
+
+    return promise;
+}
+
+// -------------------------------------------------------------------
+// Fonction: pulseStop(handle)
+//
+// Interrompt immédiatement un train d'impulsions en cours sur ce
+// handle, s'il y en a un. Contrairement à close(), le handle reste
+// ouvert et utilisable ensuite (write, read, ou un nouveau pulse()).
+//
+// Cas d'usage typique : butée de fin de course sur un moteur pas à
+// pas - un GPIO d'entrée en interruption (startMonitoring) appelle
+// pulseStop() sur le GPIO de pas pour arrêter net le mouvement.
+//
+// Fonction SYNCHRONE et BLOQUANTE (bornée à ~500ms de sécurité, mais
+// l'arrêt réel prend au maximum quelques millisecondes) : au retour,
+// la ligne est garantie au repos et plus aucune impulsion ne sera
+// émise. C'est volontaire : pour une butée de fin de course, le code
+// appelant a besoin de cette garantie avant de décider de la suite
+// (ex: inverser le sens de rotation) sans risque de course avec une
+// dernière impulsion encore en vol.
+//
+// Retourne un booléen : true si un train était en cours et a été
+// arrêté, false si rien n'était en cours (no-op).
+// -------------------------------------------------------------------
+static napi_value PulseStop(napi_env env, napi_callback_info info) {
+    napi_status status;
+    size_t argc = 1;
+    napi_value args[1];
+    gpio_context_t *ctx = NULL;
+
+    status = napi_get_cb_info(env, info, &argc, args, NULL, NULL);
+    if (status != napi_ok || argc < 1) {
+        napi_throw_error(env, NULL, "Expected handle argument");
+        return NULL;
+    }
+
+    status = napi_get_value_external(env, args[0], (void**)&ctx);
+    if (status != napi_ok || !ctx) {
+        napi_throw_error(env, NULL, "Invalid GPIO handle");
+        return NULL;
+    }
+
+    if (ctx->is_closed) {
+        napi_throw_error(env, NULL, "GPIO handle has been closed");
+        return NULL;
+    }
+
+    int was_stopped = pulse_force_stop_and_wait(ctx, 500);
+
+    napi_value result;
+    napi_get_boolean(env, was_stopped, &result);
+    return result;
+}
+
 // Fonction: close(handle)
 static napi_value Close(napi_env env, napi_callback_info info) {
     napi_status status;
@@ -771,6 +1188,10 @@ static napi_value Close(napi_env env, napi_callback_info info) {
         return result;
     }
 
+    // Force l'arrêt d'un pulse() en cours et attend sa terminaison réelle
+    // avant de libérer les ressources GPIO sous ses pieds.
+    pulse_force_stop_and_wait(ctx, 500);
+
     // Arrêter le monitoring si actif
     if (ctx->is_monitoring) {
         ctx->is_monitoring = 0;
@@ -854,6 +1275,16 @@ static napi_value Init(napi_env env, napi_value exports) {
         napi_set_named_property(env, exports, "read", fn);
     }
 
+    status = napi_create_function(env, NULL, 0, Pulse, NULL, &fn);
+    if (status == napi_ok) {
+        napi_set_named_property(env, exports, "pulse", fn);
+    }
+
+    status = napi_create_function(env, NULL, 0, PulseStop, NULL, &fn);
+    if (status == napi_ok) {
+        napi_set_named_property(env, exports, "pulseStop", fn);
+    }
+
     status = napi_create_function(env, NULL, 0, StartMonitoring, NULL, &fn);
     if (status == napi_ok) {
         napi_set_named_property(env, exports, "startMonitoring", fn);

package/documentation/api.md

@@ -84,6 +84,73 @@ myOuput.write(1)
 
 
 
+### pulseStart(count, edge, opt)
+
+To start a pulse sequence to "output" instance.
+
+#### Example
+
+```js
+import {RIO} from "rpi-io"
+const myOutput = new RIO(17, "output", {value:0})
+
+// Slow pulse x10, ascending edge, w = 0.5 s, s = 0.5 s
+myOutput.pulseStart(10, "asc", {
+        pulseWidth: 500000,
+        spaceWidth: 500000
+    }).then(pulseStatus => {
+        console.log("pulse status stopped when completed:", pulseStatus)
+  		  // { elapsedMs: 9500.113291, pulsesCompleted: 10, stopped: false }
+        myOutput.close()
+    })
+```
+
+#### Parameter(s)
+
+- **count** *{Number}* 
+- **edge** *{"asc'"|'"desc"}* Ascending or descendig edge
+- **options** *{Object}* Pulse options. See default values below
+
+```javascript
+{
+  pulseWidth: 10, // pulse width in µs
+  spaceWidth: 10  // space beween pulses in µs
+}
+```
+
+#### Return 
+
+*{Promise<{`elapsedMs`: number, `pulsesCompleted`: number, `stopped`: boolean}>}*
+
+
+
+### pulseStop()
+
+To stop a pulse sequence on an "output" instance. This function does not return an error is no pulse sequence is active.
+
+#### Example
+
+```js
+import {RIO, sleep} from "rpi-io"
+const myOutput = new RIO(17, "output", {value:1})
+
+// Fast pulse x1000, descending edge, w = 5µs, s = 5µs
+myOutput.pulseStart(1000, "desc", {
+        pulseWidth: 5,
+        spaceWidth: 5
+    }).then(pulseStatus => {
+        console.log("pulse status stopped when completed or stopped:", pulseStatus)
+        // { elapsedMs: 5.283217, pulsesCompleted: 456, stopped: true }
+  		  myOutput.write(0) // Reset line
+        myOutput.close()
+    })
+await sleep(5)
+myOutput.pulseStop() // Stop pulse train after 5ms
+
+```
+
+#### 
+
 ### read()
 
 To read value from "input" instance.

package/documentation/examples.md

@@ -5,6 +5,9 @@ To get familiar with the **rpi-io**, you might have a glance on examples and pla
 # Simple write
 node /your-project/node_modules/rpi-io/test/write.js
 
+# Pulse sequences
+node /your-project/node_modules/rpi-io/test/pulse.js
+
 # Read and monitor
 node /your-project/node_modules/rpi-io/test/read.js
 

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/esm/step.mjs

@@ -0,0 +1,212 @@
+// -------------------------------------------------------------------
+// RPI-IO: STEP MOTOR EXTENSION ⚠️ Work in Progress
+// -------------------------------------------------------------------
+import {RIO} from "./main.mjs";
+// -------------------------------------------------------------------
+// UTILITY FUNCTIONS
+/** ------------------------------------------------------------------
+ * @function tlog
+ * @description Timestamped console.log
+ */
+export function tlog() {
+    const date = new Date()
+    const nowMs = date.toLocaleTimeString() + "." + date.getMilliseconds().toLocaleString('en', {
+        minimumIntegerDigits: 3,
+        minimumFractionDigits: 0,
+        useGrouping: false
+    })
+    console.log.apply(console, Array.prototype.concat.apply([nowMs, "🔎 "], arguments))
+}
+
+/** ------------------------------------------------------------------
+ * @function wait
+ * @description Wait ms as a promise and optional tlog
+ * @param {Number} ms
+ * @param {Boolean} logWait
+ */
+export function wait(ms, logWait = true) {
+    logWait ? tlog("sleeping", ms, "ms") : false
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export class STEP {
+
+    static STATUS_MSG = {
+        0: "none",
+        1: "Unknown driver name",
+        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 ULN2003 sequence {'full','half'}",
+        200: "ok"
+    }
+    static ULN2003_MODE = ["half", "full"]
+    static ULN2003_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 = STEP.STATUS_MSG[code]
+        this.status.data = data
+    }
+
+    /** ------------------------------------------------------------------
+     * @method constructor
+     * @param {String} driver       // Supported driver name
+     * @param {Object} rios         // rpi-io Instance container depending on driver
+     * @param {Object} opt          // Options depending on driver
+     */
+    constructor(driver, rios, opt) {
+
+        const defopt = {
+            // Parameters for ULN2003
+            delay: 10,
+            sequence: "half"
+        }
+        opt = {...defopt, ...opt}
+
+        // Init instance construction status
+        this.status = {
+            code: 0,
+            msg: STEP.STATUS_MSG[0],
+            data: ""
+        }
+
+        // Test parameters depending on driver
+        switch (driver) {
+            case "uln2003":
+
+                // ERR11: At least one coil port rpi-io instance definition is missing
+                if (typeof rios.coilA === "undefined" || typeof rios.coilB === "undefined" || typeof rios.coilC === "undefined" || typeof rios.coilD === "undefined") {
+                    this.#setStatus(11, "")
+                    RIO.closeAll()
+                    return
+                }
+
+                // ERR12: At least one coil port rpi-io instance is not valid
+                try {
+                    rios.coilA.write(0)
+                    rios.coilB.write(0)
+                    rios.coilC.write(0)
+                    rios.coilD.write(0)
+                } catch (err) {
+                    this.#setStatus(12, "")
+                    RIO.closeAll()
+                    return
+                }
+
+                // ERR13: Wrong delay parameter value (0 ≤ d ≤ 1000)
+                if (typeof opt.delay !== "number" || opt.delay < 0 || opt.delay > 1000) {
+                    this.#setStatus(13, opt.delay)
+                    RIO.closeAll()
+                    return
+                }
+
+                // ERR14: Wrong ULN2003 sequence {'full','half'}
+                if (STEP.ULN2003_MODE.indexOf(opt.sequence) === -1) {
+                    this.#setStatus(14, opt.sequence)
+                    RIO.closeAll()
+                    return
+                }
+
+                // Test successfully completed  => Init properties
+                this.driver = "uln2003"
+                this.props = {
+                    a: rios.coilA,
+                    b: rios.coilB,
+                    c: rios.coilC,
+                    d: rios.coilD,
+                    sequence: STEP.ULN2003_STEPS[opt.sequence],
+                    len: STEP.ULN2003_STEPS[opt.sequence].length,
+                    delay: opt.delay,
+                    inc: 0,
+                    index: 0
+                }
+                this.#setStatus(200, "")
+                break
+            default:
+                this.#setStatus(1, driver)
+        }
+    }
+
+    /** ------------------------------------------------------------------
+     * @method rotate
+     * @description Rotate the motor a certain number of steps forward or backward.
+     *              A full rotation consists of 200 steps.
+     * @param {Number} steps
+     * @param {"forward"|"backward"} direction
+     * @param {Boolean} showStep
+     */
+    async rotate(steps, direction, showStep = false) {
+
+        switch (this.driver) {
+            case "uln2003":
+                this.props.inc = direction === "forward" ? 1 : -1
+
+                tlog("starting rotation:", steps, "steps", direction)
+
+                // Rotate
+                for (let i = 0; i < steps; i++) {
+                    const [a, b, c, d] = this.props.sequence[this.props.index]
+                    if (showStep) {
+                        tlog("rotation step:", i, [a, b, c, d])
+                    }
+                    this.props.a.write(a)
+                    this.props.b.write(b)
+                    this.props.c.write(c)
+                    this.props.d.write(d)
+
+                    this.props.index = ((this.props.index + this.props.inc) % this.props.len + this.props.len) % this.props.len
+                    await wait(this.props.delay, false)
+                }
+
+                // Disable coils
+                this.props.a.write(0)
+                this.props.b.write(0)
+                this.props.c.write(0)
+                this.props.d.write(0)
+        }
+    }
+
+    /** ------------------------------------------------------------------
+     * @method close
+     * @description Disable coils and close rpi-io instances used for step motor controller
+     */
+    close() {
+
+        switch (this.driver) {
+            case "uln2003":
+                this.props.a.write(0)
+                this.props.b.write(0)
+                this.props.c.write(0)
+                this.props.d.write(0)
+                this.props.a.close()
+                this.props.b.close()
+                this.props.c.close()
+                this.props.d.close()
+                tlog("ULN2003 controller closed")
+        }
+    }
+}
+
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/package.json

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

package/test/pulse.js

@@ -0,0 +1,43 @@
+// -------------------------------------------------------------------
+// TEST - Simple slow and fast pulse trains
+// -------------------------------------------------------------------
+import {RIO, traceCfg, log, sleep, ctrlC, lineNumber} from "../esm/main.mjs"
+
+(async () => {
+    traceCfg(2)
+
+    // Read line number from command line
+    const line = lineNumber(2)
+    if (line < 0) return
+
+    // Init output line and ctrl+c to close it
+    const led = new RIO(line, "output", {value: 0})
+    log("led:", led)
+    ctrlC(() => {
+        led.close()
+    })
+
+    // Slow pulse x10, ascending edge, w = 0.5 s, s = 0.5 s
+    const pulseStatus = await led.pulseStart(10, "asc", {
+        pulseWidth: 500000,
+        spaceWidth: 500000
+    })
+    log("pulse status stopped when completed:", pulseStatus)
+
+    // Fast pulse x1000, descending edge, w = 5µs, s = 5µs
+    led.write(1) // Init line according to edge
+    led.pulseStart(1000, "desc", {
+        pulseWidth: 5,
+        spaceWidth: 5
+    }).then(pulseStatus => {
+        log("pulse status stopped when stopped:", pulseStatus)
+        led.write(0) // Reset line
+        led.close()
+    })
+    await sleep(5)
+    led.pulseStop() // Stop pulse train after 5ms
+
+})()
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/test/read.js

@@ -5,6 +5,8 @@ import {RIO, traceCfg, log, sleep, ctrlC, lineNumber} from "../esm/main.mjs"
 
 (async () => {
     traceCfg(2)
+
+    // Read line number from command line
     const line = lineNumber(2)
     if (line < 0) return
 

package/test/step-motor.js

@@ -0,0 +1,59 @@
+// -------------------------------------------------------------------
+// RPI-IO: STEP MOTOR TEST SCRIPT ⚠️ Work in Progress
+// -------------------------------------------------------------------
+import {RIO} from "../esm/main.mjs";
+import {STEP, tlog} from "../esm/step.mjs"
+
+// Close any open rpi-io instance to prevent error
+RIO.closeAll()
+
+// Open step controller in half step mode => Half turn forward and backward => Close
+const motor28BYJH = new STEP("uln2003", {
+    coilA: new RIO(21, "output"),
+    coilB: new RIO(22, "output"),
+    coilC: new RIO(24, "output"),
+    coilD: new RIO(25, "output")
+}, {
+    delay: 0,
+    sequence: "half"
+})
+tlog("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 STEP("uln2003", {
+    coilA: new RIO(21, "output"),
+    coilB: new RIO(22, "output"),
+    coilC: new RIO(24, "output"),
+    coilD: new RIO(25, "output")
+}, {
+    delay: 4,
+    sequence: "full"
+})
+tlog("motor28BYJF creation status:", motor28BYJF.status)
+await motor28BYJF.rotate(1024, "forward", false)
+await motor28BYJF.rotate(1024, "backward", false)
+motor28BYJF.close()
+
+// A4988 drivers require one line per parameter as in the example below
+const a4988 = {
+    pulse: new RIO(5, "output"),
+    direction: new RIO(6, "output"),
+    enable: new RIO(26, "output")
+}
+
+// DM452 drivers require one line per parameter as in the example below
+const dm452 = {
+    pulse: new RIO(16, "output"),
+    direction: new RIO(17, "output"),
+    polarity: new RIO(27, "output")
+}
+
+// When done close all rpi-io instances
+RIO.closeAll()
+
+// -------------------------------------------------------------------
+// EoF
+// -------------------------------------------------------------------

package/test/write.js

@@ -6,6 +6,7 @@ import {RIO, traceCfg, log, sleep, ctrlC, lineNumber} from "../esm/main.mjs"
 (async () => {
     traceCfg(2)
 
+    // Read line number from command line
     const line = lineNumber(2)
     if (line < 0) return
 

package/esm/uln2003.mjs

@@ -1,115 +0,0 @@
-// -------------------------------------------------------------------
-// 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/test/exampleUln2003.js

@@ -1,103 +0,0 @@
-// -------------------------------------------------------------------
-// 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
-// -------------------------------------------------------------------