rpi-io 1.2.4 → 2.0.0

package/README.md

@@ -1,30 +1,109 @@
 # rpi-io
-![Static Badge](https://img.shields.io/badge/rpi--io-_1.2.x_-FF5500?style=flat) ![Static Badge](https://img.shields.io/badge/Nodejs-%3E_23-66cc33?logo=nodedotjs&logoColor=white) ![Static Badge](https://img.shields.io/badge/NPM-%3E_10-CC3534?logo=npm&logoColor=white) ![Static Badge](https://img.shields.io/badge/Raspberry_Pi-Zero2_4B_5B-C51A4A?logo=raspberrypi&logoColor=white) ![Static Badge](https://img.shields.io/badge/OS-Bookworm_Trixie-0D7AB9?style=flat)
+![Static Badge](https://img.shields.io/badge/rpi--io-_2.0.x_-FF5500?style=flat) ![Static Badge](https://img.shields.io/badge/Nodejs-%3E_23-66cc33?logo=nodedotjs&logoColor=white) ![Static Badge](https://img.shields.io/badge/NPM-%3E_10-CC3534?logo=npm&logoColor=white) ![Static Badge](https://img.shields.io/badge/Raspberry_Pi-Zero2_4B_5B-C51A4A?logo=raspberrypi&logoColor=white) ![Static Badge](https://img.shields.io/badge/OS-Bookworm_Trixie-0D7AB9?style=flat)
 
 
 **rpi-io** is a lite [ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules) module for **Node.js** to control **Raspberry Pi** GPIO: access (in, out), input event detection and [PWM](https://en.wikipedia.org/wiki/Pulse-width_modulation) peripheral control.
 
-**rpi-io** supports only recent versions of Raspberry and related OS and middlewares :
+**rpi-io** is designed for recent versions of Raspberry and related OS and middlewares. It has been tested in the following environments:
 
 - Raspberry Pi models: *RPi 5,* *RPi 4B* and *RPi Zero 2.*
 - Raspberry Pi OS (64-bit): Debian *Bookworm* and *Trixie*.
 - Middlewares (installed by default with OS distribution):
-  - 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.
+    - 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.
 
-## Installation 
 
-````shell
+
+## What's new with version 2
+
+|              | version 1    | version 2                |
+| ------------ | ------------ | ------------------------ |
+| Architecture | Full Node.js | Hybrid Node.js + C addon |
+| Performance  | Low          | High                     |
+
+⚠️ Given the new architecture, the v2 API is not compatible with the v1 one.
+
+
+
+## Prerequisites
+
+### libgpiod
+
+By default *libgpiod* is available with the latest Raspberry Pi OS distributions. If you want to install **rpi-io** with older - not tested - distributions, be sure it is installed.
+
+```bash
+sudo apt-get update
+sudo apt-get install -y libgpiod-dev gpiod
+```
+
+Then check the installed version
+
+```bash
+gpioinfo --version
+```
+
+### Compilation tools
+
+```bash
+sudo apt-get install -y build-essential python3
+```
+
+### Node.js
+
+Please make sure that you a recent version of Node.js (v23+) and NPM (v10+).
+
+
+
+## Installation
+
+**1. User rights**
+
+To run scripts without `sudo`, add your user to the `gpio` group.
+
+```bash
+sudo usermod -a -G gpio $USER
+```
+
+Then log out and log back in.
+
+**2. Install the module from your project main directory**
+
+````bash
+cd /your-project
 npm install rpi-io
 ````
 
-## Configuration
+**3.  Compile C addon from *rpi-io* directory**
 
-By default rpi-io does not require specific configuration.
+```bash
+cd /your-project/node_modules/rpi-io/
+npm install
+```
+
+If you meet errors during this step, stay in the same directory and check your environment.
+
+```bash
+npm run check
+```
+
+If you need to recompile the module when errors are fixed, stay in the same directory and the run the following scripts.
+
+```bash
+npm run clean
+npm run install
+```
+
+
+
+## Configuration for PWM-based peripherals
 
 If you want to use [hardware-based PWM](https://pinout.xyz/pinout/pwm) peripherals, some configuration is required:
 
-- Open the file  `/boot/firmware/config.txt` and add the required [dtoverlay](https://www.raspberrypi.com/documentation/computers/configuration.html#part3.1) configuration for PWM as showed in the examples below.
+- Edit the file  `/boot/firmware/config.txt` and add the required [dtoverlay](https://www.raspberrypi.com/documentation/computers/configuration.html#part3.1) configuration for PWM as showed in the examples below.
+
+```bash
+sudo nano /boot/firmware/config.txt
+```
 
 ```shell
 # Examples of PWM configuration to add to/boot/firmware/config.txt
@@ -48,408 +127,505 @@ pinctrl get 12
 # 12: a0    pd | lo // GPIO12 = PWM0_CHAN0
 pinctrl get 13
 # 13: a0    pd | lo // GPIO13 = PWM0_CHAN1
-pinctrl get 18
-# 18: no    pd | -- // GPIO18 = none
-pinctrl get 19
-# 19: no    pd | -- // GPIO19 = none
 ```
 
+
+
 ## Usage
 
-PLEASE NOTE: In all this document, GPIOs numbers are the BCM ones as defined in https://pinout.xyz/.
+PLEASE NOTE: In all this document, GPIO line numbers are the BCM ones as defined in https://pinout.xyz/.
 
 ### *OUT* operations
 
-#### LED control
+#### Example of LED control
+##### Diagram
+```
+GPIO Pin (Output)
+          │
+         ┌┴┐
+         │ │  Current-limiting resistor (220Ω or 330Ω)
+         └┬┘
+          │
+          ▼   ← LED (anode +)
+         ───
+          |   ← LED (cathode -)
+          |
+        ─────  GND (0V)
+          ─
+```
 
-![Connecting a LED to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-led.png)
+##### Code example
 
 ```javascript
 // Import rpi-io module
-import {Rio} from "rpi-io";
-// Define instance for OUT operation on some GPIO
-const led = new Rio(17, "out");
-// Turn the led on
-led.set(1);
-// Turn the led off
-led.set(0);
-```
+import {RIO} from "rpi-io"
 
-#### Active buzzer beep
+// Define instance for OUT operation on some GPIO e.g. 17 with initial value
+const led = new RIO(17, "output", {value: 0})
 
-`set` method has an optional *time* parameter to invert the command after some delay (ms). It may be useful to beep a buzzer.
-
-![Connecting an active buzzer to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-active-buzzer.png)
+// Turn the led on
+led.write(1)
 
-```javascript
-// Import rpi-io module
-import {Rio} from "rpi-io";
-// Define instance for OUT operation on some GPIO
-const buzzer = new Rio(23, "out");
-// Turn the buzzer on for 3 seconds
-buzzer.set(1, 3000);
+// Turn the led off after 5s and close the instance before leaving
+setTimeout(()=>{
+    led.write(0)
+    led.close()
+}, 5000)
 ```
 
+
+
 ### *IN* operations
 
 #### Getting button status and listening to input events
 
-![Connecting a pull-down button to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-pull-down-btn.png)
+##### Diagram of *pull-down* electronic circuit
+
+```
+VCC (3.3V)
+          │
+          ○  ← Switch/Button (open = not pressed)
+          │
+          ├──────────── GPIO Pin
+          │
+         ┌┴┐
+         │ │  Pull-down resistor (10kΩ typical)
+         └┬┘
+          │
+        ─────  GND (0V)
+          ─
+```
+
+##### Code example
 
 ```javascript
 // Import rpi-io module
-import {Rio} from "rpi-io";
+import {Rio, ctrlC} from "rpi-io"
 
-// Define instance for IN operation on some GPIO
-const button = new Rio(18, "in");
+// Define instance for IN operation on some GPIO e.g. 18
+const btn = new RIO(18, "input", {bias: "pull-down"})
 
-// Get the instant value of the button
-button.get(); // Return 0 (opened) or 1 (closed)
+// Close instance on script interrupt
+ctrlC(() => {
+    btn.close()
+})
 
-// Monitor button events ("rising, "falling" or "both")
-// and receive results in callback function
-button.monitor("both", (event) => {
-    // event.edge = "rising" or "falling"
-    // event.time = timestamp
-    console.log("event:", event.edge, event.time)
-});
-```
+// Instant read
+console.log("button value:", btn.read())
 
-### PWM operations with servo motor in hardware mode
+// Event monitoring for both edges ("rising"/"falling") with rebounce threshold (30)
+const callback = edge => {console.log("edge:", edge)}
+btn.monitoringStart(callback, "both", 30)
 
-REMINDER: PWM peripherals used in hardware mode need some specific [configuration](#Configuration).
+// Stop monitoring after 10s
+setTimeout(()=>{
+    btn.monitoringStop()
+}, 10000)
+```
 
-![PWM servo motor connected to Raspberry Pi GPIO XYZ](https://rpisquare.com/img/rpi-io-servo-motor.png)
+##### *Pull-up* variant
 
+```
+VCC (3.3V)
+          │
+         ┌┴┐
+         │ │  Pull-up resistor (10kΩ typical)
+         └┬┘
+          │
+          ├──────────── GPIO Pin
+          │
+          ○  ← Switch/Button (open = not pressed)
+          │
+        ─────  GND (0V)
+          ─
+```
 
 ```javascript
-// Import rpi-io module
-import {Rio} from "rpi-io";
-
-// Define instance for PWM operation on some PWM GPIO
-const servoMotor = new Rio(13, "pwm");
-
-// PWM servo motor parameters depends motor specifications.
-//     - period = 20,000,000 nano-seconds = 20 milli-seconds ~ frequency = 50 Hz
-//	   - duty cycle on start = 500,000 nano-seconds = 0.5 milli-seconds
-//		 - dutyMin = 0.5 ms ~ 0°
-//		 - dutyMax = 2.5 ms ~ 180°
-servoMotor.pwmInit(20000000, 500000, {
-    dutyMin: 500000,
-    dutyMax: 2500000
-});
-console.log("servo position = 0°");
-
-// Wait 2s then change duty cyle to 1.5 ms
-setTimeout(() => {
-    servo.pwmDuty(1500000);
-    console.log("servo position = 90°");
-}, 2000);
+const btn = new RIO(18, "input", {bias: "pull-up"})
 ```
 
-## API
-
-The **rpi-io** API is based on the class `Rio` with instance methods and static functions.
 
-### Constructor and generic methods
 
-####  Constructor - Rio(gpio, type)
+### PWM operations in hardware mode
 
-##### Example 
-```javascript
-import {Rio} from "rpi-io";
-const myOutput = new Rio(17, 'out');
-```
-##### Parameters
-- **gpio** *{Number}*  Must be one of the GPIO number as defined in [pinout.xyz](https://pinout.xyz). 
-- **type** *{String}* Must be one of the following values: 'in', 'out', 'pwm'.
-
-##### Detected errors
-- Operating system version is not supported
-- *libgpiod* version is not supported
-- **gpio** is not defined as GPIO in [pinout.xyz](https://pinout.xyz). 
-- **gpio** is already used by another instance.
-- **type** value is not recognized.
-- **type**='pwm' and **gpio** is not properly configured.
+#### Servo motor
 
+REMINDER: PWM peripherals used in hardware mode need some specific [configuration](#Configuration).
 
+##### Diagram for servo-motor *SG90*
+```
+                                    ┌─────────────────────┐
+                                    │                     │
+        External Power (5V)         │    Servo Motor      │
+              │                     │                     │
+              │    VCC (red)        │  ┌───────────────┐  │
+              ├────────────────────────┤               │  │
+              │                     │  │     Motor     │  │
+              │    GND (brown/black)│  └───────┬───────┘  │
+              ├────────────────────────────────┤          │
+              │                     │    ┌─────┴─────┐    │
+              │                     │    │   Gear    │    │
+              │                     │    │   Box     │    │
+              │                     │    └─────┬─────┘    │
+              │                     │     ─────┴─────     │
+              │                     │    ( Servo Arm )    │
+              │    Signal (orange)  │                     │
+ GPIO Pin ─────────────────────────────                   │
+   (PWM)                            │                     │
+              │                     └─────────────────────┘
+              │
+            ─────  Common GND ← Important: Pi GND must connect here
+              ─
+```
 
-####  Method - disable()
-To remove an instance from the list.
+##### Code example
 
-##### Example 
 ```javascript
-myOutput.disable();
+import {RIO, sleep, ctrlC, } from "rpi-io"
+
+(async () => {
+  
+    // Init pwm line (13) and set duty range in µs
+    const servo = new RIO(13, "pwm", {
+        period: 20000,  // 20,000,000 ns ~ 50 Hz
+        dutyMin: 500,   //    500,000 ns ~ 0.5 ms
+        dutyMax: 2500   //  2,500,000 ns ~ 2.5 ms
+    })
+    ctrlC(() => {
+        servo.close()
+    })
+
+    await sleep(2000)
+    servo.pwmDuty(50)
+    console.log("servo duty = 50%")     // ~ 0.5 + (0.5 * (2.5 ms - 0.5 ms)) = 1.5 ms
+    await sleep(2000)
+    servo.pwmDuty(100)
+    console.log("servo duty = 100%")    // ~ 0.5 + (1.0 * (2.5 ms - 0.5 ms)) = 2.5 ms
+    await sleep(2000)
+    servo.pwmDuty(0)
+    logconsole.logservo duty = 0%")      // ~ 0.5 + (0.0 * (2.5 ms - 0.5 ms)) = 0.5 ms
+    await sleep(2000)
+    servo.close()
+    console.log("servo closed")
+})()
 ```
 
-### Methods for instances where type='out'
-#### set(value, duration)
+##### Fade-in LED
 
-To set some *out* GPIO to 0 or 1.
+PWM can also be used for progressive LED light with the same electronic circuit as write operations. See example below.
 
-##### Example 
 ```javascript
-import {Rio} from "rpi-io";
-const myOutput = new Rio(17, 'out');
-myOutput.set(1, 3000);
+import {RIO, sleep, ctrlC, } from "rpi-io"
+(async () => {
+    // Init pwm line 12 and duty range in µs
+    const led = new RIO(12, "pwm", {
+        period: 1000,  // 1,000,000 ns ~ 1 KHz
+        dutyMin: 0,
+        dutyMax: 1000
+    })
+ 
+    ctrlC(() => {
+        led.close()
+    })
+
+    for (let i = 1; i < 101; i++) {
+        led.pwmDuty(i)
+        await sleep(30, false)
+    }
+    await sleep(2000, false)
+    led.pwmDuty(0)
+    led.close()
+    log("led closed")
+})()
 ```
-##### Parameters
-- **value** *{Number}* 0 or 1
-- **duration** *{Number}*  Time in ms. When defined, at the end of the defined time the output is inverted.
 
-##### Detected errors
-- Instance type is not 'out'.
-- Instance is disabled or undefined.
+### More examples
 
+To get familiar with the module, you might have a glance on examples and play with them with the GPIO lines of your own electronic circuit.
 
+```bash
+# Simple write
+node /your-project/node_modules/rpi-io/test/write.js
 
-### Methods for instances where type='in'
+# Read and monitor
+node /your-project/node_modules/rpi-io/test/read.js
 
-#### get()
+# LED fade-in on PWM line
+node /your-project/node_modules/rpi-io/test/pwm-led.js
 
-To read instant value of some *in* GPIO.
+# Servo-motor SG90 controlled by PWM
+node /your-project/node_modules/rpi-io/test/pwm-motor.js
 
-##### Example
+# Test duplicated instance error
+node /your-project/node_modules/rpi-io/test/duplicate-error.js
 
-```javascript
-import {Rio} from "rpi-io";
-const myInput = new Rio(18, 'in');
-let currentValue = myInput.get();
-```
+# Test close of all instances
+node /your-project/node_modules/rpi-io/test/close-all.js
 
-##### Returned value
-
-0 or 1
-
-##### Detected errors
+# Test GPIO line configuration
+node /your-project/node_modules/rpi-io/test/line-configuration.js
+```
 
-- Instance type is not 'in'.
-- Instance is disabled or undefined.
 
 
+## API
 
-#### monitor(edge, callback, options)
+The **rpi-io** API is based on the class `RIO` with instance methods.
 
-To monitor activities on some *in* GPIO and receive events in a callback function.
+### RIO class  and generic methods
 
+####  constructor RIO(line, mode, opt)
+To create instance according to parameters.
 ##### Example
-
 ```javascript
-import {Rio} from "rpi-io";
-const myButton = new Rio(18, 'in');
-myButton.monitor("both", event => {
-    console.log("event:", event.edge, event.time)
-});
+import {RIO} from "rpi-io"
+const myOutput = new RIO(17, "output")
 ```
+##### Parameter(s)
+- **line** *{Number}*  Must be one of the GPIO number as defined in [pinout.xyz](https://pinout.xyz). 
+- **mode** *{String}* Must be one of the following values: "output", "input", "pwm".
+- **opt** *{Object}* Various options depending on selected mode. See details and default values below.
 
-##### Parameters
+```javascript
+{
+  // output - Initial value
+  value: 0,
+  // input - Circuit bias: "disable", "pull-up", "pull-down"
+  bias: "disable",
+  // pwm - Delay time (ms) required on instance creation
+  //			 depending on device performance. If this value is
+  //       too small, the PWM instance creation fails.
+  //			 Can be reduced for latest RPi 5
+  //			 Must be increased for old RPi Zero.
+  exportTime: 100,
+  // pwm - period defined in μs. Default value is equivalent
+  //			 to a 50 Hz frequency.
+  period: 20000,
+  // pwm - dutyMin and dutyMax defines the duty cycle use range in µs
+  // 		   especially for servo-motors (See their specs!).
+  dutyMin: 0
+  dutyMax: 20000
+}
+```
 
-- **edge** *{String}* 'rising', 'falling' or 'both'. Any other value stops  instance monitoring.
-- **callback** *{Function}*  Callback function with one Object parameter for input events on instance e.g. `event = {edge: 'rising,' time: 'Thu Oct 30 2025 18:12:35 GMT+0100'}`
-- **options** *{Object}* Default value is `{bias: 'disable', bounce: 0}`
-    - `bias` To configure according your input connection. Supported value ares 'disable', 'pull-down' and 'pull-up'.
-    - `bounce` Delay in ms to filter callback on rebounce. Value between 0 and 1000. 0 means no filter.
+##### Return
 
-##### Detected errors
+*{Object}*  RIO instance
 
-- Instance type is not 'in'.
-- Instance is disabled or undefined.
 
 
+#### close()
+To close instance i.e.
 
-### Methods for instances where type='pwm'
-#### pwmInit(period, duty, options)
+- to prevent future use of the line with the current instance
+- to stop related monitoring process if any
+- to free PWM resources if any
 
-To initialize some *pwm* GPIO according to connected device specifications.
+To reuse a line when closed, a new instance must be created.
 
 ##### Example
 
 ```javascript
-import {Rio} from "rpi-io";
-const servoMotor = new Rio(13, "pwm");
-servoMotor.pwmInit(20000000, 500000, {
-    dutyMin: 500000,
-    dutyMax: 2500000
-});
-console.log("servo position = 0°");
+import {RIO} from "rpi-io"
+const myOutput = new RIO(17, "output")
+myOutput.close()
 ```
 
-##### Parameters
 
-All time parameters are defined in nanoseconds (ns).
 
-- **period** *{Number}* Time period in which [duty cycle](https://en.wikipedia.org/wiki/Pulse-width_modulation) varies.
-- **duty** *{Number}* Initial duty cycle.
-- **options** *{Object}*  
-  - **dutyMin** *{Number}* Default = 0. Minimum duty cycle (ns) as defined in connected device specifications. 
-  - **dutyMax** *{Number}* Default = 1,000,000,000. Maximum duty cycle (ns) as defined in connected device specifications. 
+#### write(value)
+
+To write some value to "output" instance.
+
+##### Example
+
+```javascript
+import {RIO} from "rpi-io"
+const myOutput = new Rio(17, "output")
+myOuput.write(1)
+```
 
-##### Detected errors
+##### Parameter(s)
 
-- Instance type is not 'pwm'.
-- Instance is disabled or undefined.
-- **period** is out-of-range [100, 1,000,000,000]
-- **duty** < **options.dutyMin**
-- **duty** > **options.dutyMax**
+- **value** *{Number}*  0 or 1
 
 
 
-#### pwmStop()
+#### read()
 
-To stop PWM modulation on some *pwm* GPIO.
+To read value from "input" instance.
 
 ##### Example
 
 ```javascript
-servoMotor.pwmStop()
+import {RIO} from "rpi-io"
+const myInput = new Rio(18, "input")
+const result = myInput.read()
 ```
 
-##### Detected errors
+##### Return
 
-- Instance type is not 'pwm'.
-- Instance is disabled or undefined.
+*{Number}*  0 or 1
 
 
 
-#### pwmDuty(time)
+#### monitoringStart(callback, edge, bounce)
 
-To update duty cycle of some *pwm* GPIO.
+To start event monitoring of "input" instance.
 
 ##### Example
 
 ```javascript
-servo.pwmDuty(1500000)
+import {RIO} from "rpi-io"
+const myButton = new Rio(18, "input")
+const callback = edge => {
+    console.log("edge:", edge)
+}
+myButton.monitoringStart(callback, "both", 30)
 ```
 
-##### Parameters
-
-- **time** *{Number}* Duty cycle (ns)
+##### Parameter(s)
 
-##### Detected errors
+- **callback** *{Function}*  Function triggered by input events where parameter is *edge* that can be either "rising" (input change from 0 to 1) or "falling" (input change from 1 to 0).
+- **edge** *{String}* Filter of monitored events: "rising", "falling", "both" (default value).
+- **bounce** *{Number}* Set thresold in ms to filter consecutive events of same type. Default value is 0.
 
-- Instance type is not 'pwm'.
-- PWM instance is not properly initialized.
-- **time** is out of range [dutyMin, dutyMax]
 
 
+#### monitoringStop()
 
-### Utility functions
-#### Rio.disableAll()
-
-To to disable all instances
+To stop event monitoring of "input" instance.
 
 ##### Example
 
 ```javascript
-Rio.disableAll()
+import {RIO} from "rpi-io"
+const myButton = new Rio(18, "input")
+const callback = 
+myButton.monitoringStart(edge => {console.log("edge:", edge)})
+// Stop monitoring after 10s
+setTimeout(() => {
+  myButton.monitoringStop()
+}, 10000)
 ```
 
-#### Rio.stopMonitoring()
 
-To stop monitoring subprocess when leaving your app script or in case of failure. This prevents having a runaway subprocess that could block a new call to the `monitor()` method.
+
+#### pwmDuty(percent)
+
+To change the *duty cycle* of a "pwm" instance. The parameter is defined as a percentage to compute a *duty cycle* based on the *dutyMin* and *dutyMax* values of instance definition.
 
 ##### Example
 
 ```javascript
-Rio.stopMonitoring()
+import {RIO} from "rpi-io"
+// Servo-motor instance
+const servo = new RIO(13, "pwm", {
+        exportTime: 100,
+        period: 20000,
+        dutyMin: 500,
+        dutyMax: 2500)
+
+// duty cycle = 50% between dutyMin and dutyMax
+servo.pwmDuty(50)
 ```
 
-#### Rio.config(gpio)
+##### Parameter(s)
 
-To return configuration of some GPIO
+- **percent** *{Number}*   0 ≤ percent ≤ 100
 
-##### Example
 
+
+### Utilities
+
+####  RIO.closeAll()
+Function to close all instances
+##### Example
 ```javascript
-import {Rio} from "rpi-io";
-console.log(Rio.config(13))
-// '13': 'pwm0_chan1'
+import {RIO} from "rpi-io"
+const led = new RIO(line1, "output", {value: 0})
+const btn = new RIO(line2, "input")
+RIO.closeAll()
+// led and btn are closed 
 ```
 
-#### Rio.info()
 
-Javascript equivalent of command `gpioinfo`.
 
-##### Example
+####  log(args)
 
-```javascript
-import {Rio} from "rpi-io";
-console.log(Rio.info())
-```
+Function similar to `console.log` but with timestamped prompt. Must be enabled or not by function `traceCfg` defined thereafter.
 
-#### Rio.detect()
+####  warn(args)
 
-Javascript equivalent of command `gpiodetect`.
+Function similar to `log` but colored and prefixed by sign ⚠️.
 
-##### Example
+####  traceCfg(level)
+
+Function to enable functions `log` and `warn`. 
+
+##### Example for log, warn and traceCfg
 
 ```javascript
-import {Rio} from "rpi-io";
-console.log(Rio.detect())
+import {traceCfg, log, warn} from "rpi-io"
+// traceCfg(0) => warn and log are disabled
+// traceCfg(1) => warn is enabled and log is disabled
+// traceCfg(2) => warn and log are enabled
+traceCfg(2)
+warn("This is important info") 
+log("This is useful info")
 ```
 
-#### Rio.version()
 
-To retrieve libgpiod version.
 
-##### Example
+####  sleep(time)
 
-```javascript
-import {Rio} from "rpi-io";
-console.log(Rio.version())
-// 'v1.6.3',
-```
+Similar to `setTimeout` but in async mode.
 
-#### Rio.os()
+####  ctrlC(function)
 
-To retrieve Raspberry Pi OS info.
+To run a callback function on ctrl+c event.
 
-##### Example
+##### Example for sleep and ctrlC
 
 ```javascript
-import {Rio} from "rpi-io";
-console.log(Rio.os())
-// {id: '12', name: 'Bookworm'}
+import {sleep, ctrlC} from "rpi-io"
+(async () => {
+    ctrlC(() => {
+        console.log("displayed on script interrupt")
+    })
+    await sleep(1000)
+    console.log("displayed after 10s")
+})()
 ```
 
-#### Rio.isSystemSupported()
 
-To check if device is supported by **rpi-io** (device, model, os, middleware). It returns  *true/false* and displays details in console.
 
-#### Rio.logCfg(level)
-To set the level of console used in the module:
 
-- 0: no console
-- 1: console only for errors and warnings (default).
-- 2: more logged data
+## Benchmark
 
-##### Example
+The following tables summarizes main operation times on various devices. Results are in micro-seconds (µs).
 
-```javascript
-import {Rio} from "rpi-io";
-Rio.logCfg(0)
-Rio.isSystemSupported() // Nothing displayed in console
-Rio.logCfg(2)
-Rio.isSystemSupported() // See console below
-// 08:15:16.506 🔎  👍  Hardware is Raspberry Pi
-// 08:15:16.539 🔎  👍  Raspberry Pi 5 Model B Rev 1.0 is supported
-// 08:15:16.543 🔎  👍  Bookworm OS is supported
-// 08:15:16.545 🔎  👍  libgpiod version v1.6.x is supported
-// 08:15:16.545 🔎  👍  Systems requirements for rpi-io are met
-```
+**PLEASE NOTE**: As PWM operations rely on files, performance of microSD cards installed on RPi may have a significant impact on results for `pwmDuty()`.
 
+**OS Bookworm with libgpiod v1.6.3**
 
-## Benchmark
+|                 | RPi 5B  | RPi 4B  | RPi Zero2 |
+| --------------- | ------- | ------- | --------- |
+| write           | 0.72 µs | 1.30 µs | 2,37 µs   |
+| read            | 1.32 µs | 1,09 µs | 1,90 µs   |
+| pwmDuty (1 KHz) | 15.6 µs | 25,6 µs | 48,4 µs   |
+
+**OS Trixie with libgpiod v2.2.1**
 
-The following table summarizes GPIO *set* average times with rpi-io v1.1.0 and various hardware and OS.
+|                 | RPi 5B       | RPi 4B  | RPi Zero2    |
+| --------------- | ------------ | ------- | ------------ |
+| write           | *not tested* | 1.20 µs | *not tested* |
+| read            | *not tested* | 1.37 µs | *not tested* |
+| pwmDuty (1 KHz) | *not tested* | 24,9 µs | *not tested* |
 
-💡 If you can, stick to *Bookworm*: **rpi-io** has stability and performance issues with Trixie and libgpiod v2.2.1. I did not test libgpiod v1.6.3 on Trixie.
 
-|          | RPi 5B  | RPi 4B   | RPi Zero2  |
-|----------|---------|----------|------------|
-| Bookworm | 1.37 ms | 4.56 ms  | 9.07 ms    |
-| Trixie   | 3.82 ms | 11.29 ms | not tested |
 
+## Licence
 
----
+MIT