@iiot2k/gpiox v1.5.1

@iiot2k/gpiox

Raspberry Pi GPIO Driver.

Installation

npm install @iiot2k/gpiox

Main Functions

• Loads GPIO driver depends on platform.
• Gets GPIO input state.
• Sets GPIO output state.
• Generates Pulse Wide Modulation (PWM) on GPIO output.
• Counts GPIO input pulses.

Particularities

• Used precompiled driver for 32bit or 64bit.
• This library works on Raspberry Pi with 32bit or 64bit OS.
• Tested on

  Raspberry Pi 3 (bullseye) Raspberry Pi 4 (bookworm) Raspberry Pi 5 (bookworm)

Example

// example turns output pin 20 on and after 3000ms off
"use strict";

const gpiox = require("@iiot2k/gpiox");

gpiox.load_driver();

gpiox.init_pin(20, gpiox.GPIO_MODE_OUTPUT, 0);

gpiox.set_pin(20, true);

setTimeout(() => {
    gpiox.set_pin(20, false);
    gpiox.deinit_pin(20);
}, 3000);

More examples are on examples folder.

Pin Parameter

The Raspberry Pi has GPIO pins from GPIO2 to GPIO27. Valid pin parameter values are 2..27. The GPIO pin can be occupied by an alternative function (e.g. UART, I2C, SPI..). Check with raspi-config for alternate functions on GPIO. Therefore, overwriting of function may result in malfunction.

Mode Parameter

The mode parameter can have the following values:

const gpiox = require("@iiot2k/gpiox");

gpiox.GPIO_MODE_INPUT_NOPULL     // floating input
gpiox.GPIO_MODE_INPUT_PULLDOWN   // input with pulldown resistor
gpiox.GPIO_MODE_INPUT_PULLUP     // input with pullup resistor
gpiox.GPIO_MODE_OUTPUT           // output
gpiox.GPIO_MODE_PWM              // pwm output
gpiox.GPIO_MODE_COUNTER_NOPULL   // floating counter input
gpiox.GPIO_MODE_COUNTER_PULLDOWN // counter input with pulldown resistor
gpiox.GPIO_MODE_COUNTER_PULLUP   // counter input with pullup resistor

Floating input is used when the pin is connected to another pin. On pulldown resistor for a logical true, the input must be connected to +3.3V. On pullup resistor for a logical true, the input must be connected to gound. Input voltages more than +3.3V can destroy the input.

Debounce Parameter

Debouncing is removing unwanted input noise from buttons, switches or other user input. The debounce time is given in microseconds and depends on the switch used. Can be set to zero for outputs and no debounce function.

Initialization Functions

load_driver() Loads the GPIO driver according to the platform. This function must always be called at startup. On 64bit platform the driver rpi_gpiox_arm64.node is loaded. On 32bit platform the driver rpi_gpiox_arm32.node is loaded. On error false is returned.

check_pin(pin, mode) Checks whether the pin is available or initialized with the mode. False is returned if the pin is already initialized with a different mode.

init_pin(pin, mode, debounce_us) Initializes the pin with the mode. The debounce_ms parameter sets the debounce time in us for inputs. On error false is returned.

deinit_pin(pin) Deinitializes the pin and releases all resources. Stops also pwm and counter engine. Must be called at the end of the Node.js program.

Digital Functions

get_pin(pin) Gets the pin state of the GPIO input. The pin must be initialized with the following modes: GPIO_MODE_INPUT_NOPULL GPIO_MODE_INPUT_PULLDOWN GPIO_MODE_INPUT_PULLUP True or False is returned. On error undefined is returned.

set_pin(pin, value) Sets the pin state of the GPIO output. Parameter value can be True/False. The pin must be initialized with the following modes: GPIO_MODE_OUTPUT On error false is returned.

Pulse Wide Modulation (PWM) Functions

Pulse Wide Modulation is generated with software on output. PWM can be used, for example, to adjust the brightness of LEDs. The on+off time is 1/frequency (e.g. 1/100Hz = 10ms). Dutycycle means the % time for on. For example dutycycle 75% on 100Hz is 7.5ms on and 2.5ms off time. A dutycycle of 0% turns output off. A dutycycle of 100% turns output on.

set_pwm(pin, frequency_hz, dutycycle) Sets pwm frequency_hz and dutycycle on pin. Starts pwm engine if not startet. The pin must be initialized with the following modes: GPIO_MODE_PWM Parameter frequency_hz can be 2..1000 (Hz). Parameter dutycycle can be 0..100 (%). On error false is returned.

High Speed Counter Functions

The counter counts up to counter_high when cnt_down=false, and counts down to zero when cnt_down=true. Counts on each change of input state from false to true.

set_counter(pin, counter_high, cnt_down) Sets high speed counter. Starts pwm engine if not startet. Resets also high speed counter. Parameter counter_high can be 1..4294967294. Parameter cnt_down can be false for count up, true for count down. The pin must be initialized with the following modes: GPIO_MODE_COUNTER_NOPULL GPIO_MODE_COUNTER_PULLDOWN GPIO_MODE_COUNTER_PULLUP On error false is returned.

reset_counter(pin) Resets high speed counter If cnt_down is true counter is set to counter_high. If cnt_down is false counter is set to 0. On error false is returned.

get_counter(pin) Gets high speed counter value (0..4294967294). On error undefined is returned.

is_counter_onlimit(pin) Check if high speed counter is on limits. cnt_down = false: returns true when counter is equal counter_high. cnt_down = true: returns true when counter is equal zero. On error undefined is returned.