@isimnz/gpiox

# API @iiot2k/gpiox Raspberry Pi gpiox library. The @iiot2k/gpiox driver uses the gpio character devices interface (V2) from the Linux operating system. The driver is loaded on call with ```require("@iiot2k/gpiox");``` On 64bit OS the driver ***gpiox_arm64.node*** is loaded. On 32bit OS the driver ***gpiox_arm32.node*** is loaded. To prevent mermory leaks, if the driver is unloaded function ```deinit_gpio``` is called for all pins. ## Error function ```error_text()``` ***return:*** ```<string>``` error text after call function. ## pin Parameter The Raspberry Pi has gpio pins from GPIO2 to GPIO27. Valid ```pin``` parameter values are 2..27. ## mode Parameter Each gpio pin can be assigned a function. The following table shows the different modes with ```mode``` parameter. |Constant|State-0|State-1|function| |:--|:--|:--|:--| |GPIO_MODE_INPUT_NOPULL|ground|+3.3V|floating input| |GPIO_MODE_INPUT_PULLDOWN|open/ground|+3.3V|pulldown resistor input| |GPIO_MODE_INPUT_PULLUP|open/+3.3V|ground|pullup resistor input| |GPIO_MODE_OUTPUT|ground|+3.3V|output| |GPIO_MODE_OUTPUT_SOURCE|Hi-Z|+3.3V|output source| |GPIO_MODE_OUTPUT_SINK|Hi-Z|ground|output sink| |GPIO_MODE_PWM|ground|+3.3V|pwm output pulse| |GPIO_MODE_PWM_REALTIME|ground|+3.3V|pwm output pulse in realtime| |GPIO_MODE_COUNTER_NOPULL|ground|+3.3V|floating input counter| |GPIO_MODE_COUNTER_PULLDOWN|open/ground|+3.3V|pulldown resistor input counter| |GPIO_MODE_COUNTER_PULLUP|open/+3.3V|ground|pullup resistor input counter| |GPIO_MODE_SENSOR|ground|Hi-Z|output sink| Floating input/output is used when the pin is connected to another pin. Input voltages more than +3.3V can destroy the input. Hi-Z refers to an output signal state in which the signal is not being driven. Please do not init gpio pins with special functions (i2c, spi, uart..). GPIO output current is limited. Use ULN2803A (low switch) or [TBD62783](https://toshiba.semicon-storage.com/eu/semiconductor/product/linear-ics/transistor-arrays/detail.TBD62783APG.html) (high switch) for drive output. ## GPIO Initialization functions > ### Initializes the gpio with the mode. ```init_gpio(pin, mode, setval)``` ***pin:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_INPUT... or GPIO_MODE_OUTPUT... ***setval:*** ```<integer>``` or ```<boolean>``` ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The ***setval*** parameter sets the **debounce time** in us for inputs, and can set to 0 for disable debounce. For outputs ***setval*** parameter sets initial state (0/1) of ```true/false```. Only inputs and outputs can be init. > ### Changes the mode of gpio. ```change_gpio(pin, mode, setval)``` ***pin:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_INPUT... or GPIO_MODE_OUTPUT... ***setval:*** ```<integer>``` or ```<boolean>``` ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The pin must be initialized with **init_gpio()**. The ***setval*** parameter sets the **debounce time** in us for inputs, and can set to 0 for disable debounce. For outputs ***setval*** parameter sets initial state (0/1) of ```true/false```. Only mode of inputs and outputs can be changed. > ### Deinitializes the gpio and releases all resources. ```deinit_gpio(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. Stops also watch, blink, pwm, and counter thread. ## GPIO Watch functions ## edge Parameter The ```edge``` parameter sets the watch direction of inputs. |Constant|Value|Function| |:--|:--|:--| |GPIO_EDGE_RISING|0|check for change from 0 to 1| |GPIO_EDGE_FALLING|1|check for change from 1 to 0| |GPIO_EDGE_BOTH|2|check for change from 0 to 1 or 1 to 0| > ### Watch the gpio input for changes. ```watch_gpio(pin, mode, debounce, edge, callback)``` ***pin:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_INPUT... ***debounce:*** ```<integer>``` 0.. ***edge:*** ```<integer>``` GPIO_EDGE_... ***callback:*** ```<function> (state, edge, pin)``` - **state** ```<integer>``` 0/1, - **edge** ```<integer>``` GPIO_EDGE_RISING or GPIO_EDGE_FALLING. - **pin** ```<integer>``` 2..27. ***return:*** ```<number>``` ```0/1``` actual input state, ```undefined``` on error. The ***debounce*** parameter sets the **debounce time** in us for inputs, and can set to 0 for disable debounce. The ***callback*** function is called if input state changes. ## GPIO Input/Output functions > ### Gets gpio state as boolean. ```get_gpio(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```false/true```, ```undefined``` on error. The pin must be initialized as input or output. > ### Gets gpio state as number. ```get_gpio_num(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<integer>``` 0/1, ```undefined``` on error. The pin must be initialized as input or output. > ### Sets gpio state of output. ```set_gpio(pin, value)``` ***pin:*** ```<integer>``` 2..27 ***value:*** ```<integer>``` 0/1 or ```<boolean>``` ```true/false``` ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The pin must be initialized as output. > ### Toggle gpio output. ```toggle_gpio(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The pin must be initialized as output. > ### Blink gpio output. ```blink_gpio(pin, period)``` ***pin:*** ```<integer>``` 2..27 ***period:*** ```<integer>``` 100.. (ms) ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The pin must be initialized as output. Call with ***period*** of 0 stops blinking. > ### Stop blinking gpio output. ```stop_blink_gpio(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The pin must be initialized as output. Call of ```toggle_gpio``` or ```set_gpio``` stops also blinking. ## Pulse Wide Modulation (PWM) Functions Pulse Wide Modulation pulse is generated on output. PWM can be used for example to adjust the brightness of LEDs. Because PWM is generated with software, the accuracy of dutycycle is accurate up to approximately 800Hz. For better accuracy use mode **GPIO_MODE_PWM_REALTIME**. In **GPIO_MODE_PWM_REALTIME** mode the CPU load is higher. 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. > ### Init pwm and sets frequency and dutycycle. ```init_pwm(pin, mode, frequency_hz, dutycycle)``` ***pin:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_PWM... ***frequency_hz:*** ```<integer>``` 1..45000 (Hz) ***dutycycle:*** ```<integer>``` 0..100 (%) ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. Starts pwm engine. > ### Sets pwm frequency and dutycycle. ```set_pwm(pin, frequency_hz, dutycycle)``` ***pin:*** ```<integer>``` 2..27 ***frequency_hz:*** ```<integer>``` 1..45000 (Hz) ***dutycycle:*** ```<integer>``` 0..100 (%) ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. Function ```init_pwm``` must be called before. > ### Gets pwm frequency. ```get_pwm_frequency(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<integer>``` 1..45000 (Hz), ```undefined``` on error. > ### Gets pwm dutycycle. ```get_pwm_dutycycle(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** 0..100 (%), ```undefined``` on error. |Constant|Value|Function| |:--|:--|:--| |DUTY_MIN|0|min. duty cycle| |DUTY_MAX|100|max. duty cycle| |FREQ_MIN|1|min. frequency| |FREQ_MAX|45000|max. frequency| ## High Speed Counter Functions Implements high speed software counter. Counts on each **edge** changes of input up/down. Optional can be assign a reset and output hardware pin. ## cnt_mode Parameter The ```cnt_mode``` parameter sets the count direction of counter. |Constant|Value|Function| |:--|:--|:--| |C_UP|0|counts up to ```counter_high```| |C_DOWN|1|counts down to zero| > ### Init counter pin. ```init_counter_pin(pin, mode, debounce, edge)``` ***pin:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_COUNTER... ***debounce:*** ```<integer>``` 0.. ***edge:*** ```<integer>``` GPIO_EDGE_... ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The ***debounce*** parameter sets the **debounce time** in us for inputs, and can set to 0 for disable debounce. The counter pin must init before call ```init_counter```. > ### Init counter reset pin. ```init_counter_reset_pin(pin, pin_reset, mode, debounce, edge)``` ***pin:*** ```<integer>``` 2..27 ***pin_reset:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_INPUT... ***debounce:*** ```<integer>``` 0.. ***edge:*** ```<integer>``` GPIO_EDGE_... ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The ***debounce*** parameter sets the **debounce time** in us for inputs, and can set to 0 for disable debounce. On ***edge:*** of pin the counter is reset. Parameter ```pin``` is the counter pin used in ```init_counter_pin```. The counter reset pin should init before call ```init_counter```. > ### Init counter output pin. ```init_counter_output_pin(pin, pin_output, mode)``` ***pin:*** ```<integer>``` 2..27 ***pin_output:*** ```<integer>``` 2..27 ***mode:*** ```<integer>``` GPIO_MODE_OUTPUT... ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. Parameter ```pin``` is the counter pin used in ```init_counter_pin```. Output pin is set if counter is on limit. The counter output pin should init before call ```init_counter```. > ### Init counter. ```init_counter(pin, counter_high, cnt_mode, callback)``` ***pin:*** ```<integer>``` 2..27 ***counter_high:*** ```<integer>``` 1..4294967294 ***cnt_mode:*** ```<integer>``` **C_UP**, **C_DOWN** ***callback:*** ```<function> (counter, on_limit, cnt_mode, counter_high, pin)``` - **counter** ```<integer>``` 0..4294967294. - **on_limit** ```<boolean>``` true if counter on limit - ***cnt_mode:*** ```<integer>``` **C_UP**, **C_DOWN** - ***counter_high:*** ```<integer>```1..4294967294 - **pin** ```<integer>``` 2..27. ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The ```callback``` function is called on any counter changes. Starts counter engine. Resets also counter (see reset_counter). > ### Sets counter. ```set_counter(pin, counter_high, cnt_mode)``` ***pin:*** ```<integer>``` 2..27 ***counter_high:*** ```<integer>``` 1..4294967294 ***cnt_mode:*** ```<integer>``` **C_UP**, **C_DOWN** ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. Resets also counter (see reset_counter). > ### Resets counter. ```reset_counter(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. cnt_mode = **C_UP**: counter is set to 0. cnt_mode = **C_DOWN**: counter is set to ```counter_high```. > ### Gets counter value. ```get_counter(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<integer>``` counter value (0..4294967294), ```undefined``` on error > ### Gets counter_high value. ```get_counter_high(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<integer>``` ```counter_high``` value (1..4294967294), ```undefined``` on error > ### Gets counter mode. ```get_counter_mode(pin)``` ***pin:*** ```<integer>``` 2..27 ***return :*** ```<integer>``` **C_UP**, **C_DOWN**, ```undefined``` on error > ### Check if counter is on limits. ```is_counter_onlimit(pin)``` ***pin:*** ```<integer>``` 2..27 ***return :*** ```<boolean>``` ```true/false```, ```undefined``` on error cnt_mode = **C_UP**: returns ```true``` when counter is equal ***counter_high***. cnt_mode = **C_DOWN**: returns ```true``` when counter is equal 0. |Constant|Value|Function| |:--|:--|:--| |COUNTER_MIN|0|min. counter value| |COUNTER_MIN_HIGH|1|min. ```counter_high``` value| |COUNTER_MAX|4294967294|max. counter value| ## Temperature Sensors with 1-wire protocol The functions reads the DS18B20 sensor temperature. You can connect multiple sensors in parallel. It is important that a 4.7k pullup resistor is connected. The library does not support the parasite mode. Please do not activate the 1-wire subsystem of the raspberry pi. For high-performance reading, all sensors must have set to the same resolution. ## res Parameter The ```res``` (resolution) parameter sets the resolution of ds18b20 sensors. |Constant|Value|Resolution|Conversion Time|Temp. Steps| |:--|:--|:--|:--|:--| |RES_SENSOR_9|0|9 bit|94ms|0.5°| |RES_SENSOR_10|1|10 bit|187ms|0.25°| |RES_SENSOR_11|2|11 bit|375ms|0.125°| |RES_SENSOR_12|3|12 bit|750ms|0.0625°| > ### Init all sensors to resolution. ```init_sensor(pin, res)``` ***pin:*** ```<integer>``` 2..27 ***res:*** ```<integer>``` RES_SENSOR_.. ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. > ### Scans all sensors. ```scan_sensor(pin, callback)``` ***pin:*** ```<integer>``` 2..27 ***callback:*** ```<function> (ret)``` - **ret** ```<boolean>``` ```true``` on ok, ```false``` on error. The sensor id's are stored in an internal list. ```scan_sensor_sync(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<boolean>``` ```true``` on ok, ```false``` on error. The sensors id's are stored in an internal list. > ### List all sensors. ```list_sensor(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<string array>``` list of sensors id in format 28-HHHHHHHHHHHH (hex), ```undefined``` on error. List the sensor id's in internal list. ```scan_sensor``` must be called before. > ### Get sensor count. ```get_sensor_count(pin)``` ***pin:*** ```<integer>``` 2..27 ***return:*** ```<integer>``` number of sensors, ```undefined``` on error. Get sensor count in internal list. ```scan_sensor``` must be called before. > ### Read all sensors. ```read_sensor(pin, fh, callback)``` ***pin:*** ```<integer>``` 2..27 ***fh:*** ```<boolean>``` ```false:``` output is celsius, ```true:``` output is fahrenheit. ***callback:*** ```<function> (data)``` - **data** ```<number array>``` temperature of sensors, ```undefined``` on error. Reads all sensors stored in internal list. ```scan_sensor``` must be called before. ```read_sensor_sync(pin, fh)``` ***pin:*** ```<integer>``` 2..27 ***fh:*** ```<boolean>``` ```false:``` output is celsius, ```true:``` output is fahrenheit. ***return:*** ```<number array>``` temperature of sensors, ```undefined``` on error. Reads all sensors stored in internal list. ```scan_sensor``` must be called before. > ### Read one sensor. ```read_one_sensor(pin, id, fh, callback)``` ***pin:*** ```<integer>``` 2..27 ***id:*** ```<string>``` id of sensor in format 28-HHHHHHHHHHHH (hex). ***fh:*** ```<boolean>``` ```false:``` output is celsius, ```true:``` output is fahrenheit. ***callback:*** ```<function> (data)``` - **data** ```<number>``` temperature of sensor, ```undefined``` on error. The sensor is read independently of the internal list. ```read_one_sensor_sync(pin, id, fh)``` ***pin:*** ```<integer>``` 2..27 ***id:*** ```<string>``` id of sensor in format 28-HHHHHHHHHHHH (hex). ***fh:*** ```<boolean>``` ```false:``` output is celsius, ```true:``` output is fahrenheit. ***return:*** ```<number>``` temperature of sensor, ```undefined``` on error. The sensor is read independently of the internal list.