Raspberry Pi OS (Debian) Kernel module for Iono Pi, the Raspberry Pi industrial PLC.
![Build tests [stable oldstable]](https://github.com/sfera-labs/iono-pi-kernel-module/actions/workflows/build-apt.yml/badge.svg){kind=icon}
![Build tests [firmware]](https://github.com/sfera-labs/iono-pi-kernel-module/actions/workflows/build-fw.yml/badge.svg){kind=icon}
For installation on Ubuntu read this.
Make sure your system is updated:
sudo apt update
sudo apt upgrade
If you are using Iono Pi with Raspberry Pi 4 and a 32-bit OS, add to /boot/firmware/config.txt the following line: [why?]
arm_64bit=0
Reboot:
sudo reboot
After reboot, install required tools:
sudo apt install git device-tree-compiler dkms linux-headers-$(uname -r)
Clone this repo:
git clone --depth 1 https://github.com/sfera-labs/iono-pi-kernel-module.git
cd iono-pi-kernel-module
This is the recommended mode. It automatically rebuilds and reinstalls the module when new kernel versions are installed.
Register, build and install with DKMS:
sudo dkms add .
sudo dkms build -m ionopi -v $(cat VERSION)
sudo dkms install -m ionopi -v $(cat VERSION)
Show
Use this only if you specifically want to install for the current running kernel version only.
make clean
make
sudo make install
Manual mode does not provide automatic rebuild on kernel upgrades.
Add to /boot/firmware/config.txt the following line:
dtoverlay=ionopi
If you want to use TTL1 as 1-Wire bus, add this line too:
dtoverlay=w1-gpio
The install process places 99-ionopi.rules, which sets owner group ionopi for sysfs entries. To access the sysfs interface without superuser privileges, create the group and add your user, e.g. for user "pi":
sudo groupadd ionopi
sudo usermod -a -G ionopi pi
Reboot:
sudo reboot
After installation, you will find the sysfs interface in the /sys/class/ionopi/ directory, which provides virtual files that can be read and/or written to, enabling easy monitoring and control of Iono Pi’s I/O and other functionalities.
From the shell, toggle a relay:
$ echo F > /sys/class/ionopi/relay/o1
Read the voltage on AI1:
$ cat /sys/class/ionopi/analog_in/ai1_mv
Or using Python:
f = open('/sys/class/ionopi/relay/o1', 'w')
f.write('F')
f.close()
print('Relay O1 switched')
f = open('/sys/class/ionopi/analog_in/ai1_mv', 'r')
val = f.read().strip()
f.close()
print('AI1: ' + val + ' mv')
The following paragraphs list all the available devices (directories) and files coresponding to Iono Pi's features.
| File | R/W | Value | Description |
|---|---|---|---|
| ai<N>_mv | R | <val> | Voltage value read on AI<N> in mV |
| ai<N>_raw | R | <val> | Raw value read from the ADC channel connected to AI<N> not converted |
Examples:
cat /sys/class/ionopi/analog_in/ai1_mv
cat /sys/class/ionopi/analog_in/ai2_raw
| File | R/W | Value | Description |
|---|---|---|---|
| di<N> | R | 1 | Digital input <N> high |
| di<N> | R | 0 | Digital input <N> low |
For each digital input, we also expose:
- the debounced state
- 2 debounce times in ms ("on" for high state and "off" for low state) with default value of 50ms
- 2 state counters ("on" for high state and "off" for low state)
The debounce times for each DI has been splitted in "on" and "off" in order to make the debounce feature more versatile and suited for particular application needs (e.g. if we consider digital input 1, and set its debounce "on" time to 50ms and its debounce "off" time to 0ms, we just created a delay-on type control for digital input 1 with delay-on time equal to 50ms).
Change in value of a debounce time automatically resets both counters.
The debounce state of each digital input at system start is UNDEFINED (-1), because if the signal on the specific channel cannot remain stable for a period of time greater than the ones defined as debounce "on" and "off" times, we are not able to provide a valid result.
| File | R/W | Value | Description |
|---|---|---|---|
| diN_deb(pollable) | R | 1 | Digital input N debounced value high |
| diN_deb(pollable) | R | 0 | Digital input N debounced value low |
| diN_deb(pollable) | R | -1 | Digital input N debounced value undefined |
| diN_deb_on_ms | RW | val | Minimum stable time in ms to trigger change of the debounced value of digital input N to high state. Default value=50 |
| diN_deb_off_ms | RW | val | Minimum stable time in ms to trigger change of the debounced value of digital input N to low state. Default value=50 |
| diN_deb_on_cnt | R | val | Number of times with the debounced value of the digital input N in high state. Rolls back to 0 after 4294967295 |
| diN_deb_off_cnt | R | val | Number of times with the debounced value of the digital input N in low state. Rolls back to 0 after 4294967295 |
| File | R/W | Value | Description |
|---|---|---|---|
| status | R/W | 0 | LED off |
| status | R/W | 1 | LED on |
| status | W | F | Flip LED's state |
| blink | W | <t> | LED on for <t> ms |
| blink | W | <t_on> <t_off> <rep> | LED blink <rep> times with <t_on>/<t_off> ms periods. E.g. "200 50 3" |
| File | R/W | Value | Description |
|---|---|---|---|
| o<N> | R/W | 0 | Relay O<N> open |
| o<N> | R/W | 1 | Relay O<N> closed |
| o<N> | W | F | Flip relay O<N>'s state |
| File | R/W | Value | Description |
|---|---|---|---|
| oc<N> | R/W | 0 | Open collector OC<N> open |
| oc<N> | R/W | 1 | Open collector OC<N> closed |
| oc<N> | W | F | Flip open collector OC<N>'s state |
| File | R/W | Value | Description |
|---|---|---|---|
| ttl<N>_mode | R/W | x | TTL <N> (1 - 4) line not controlled by kernel module |
| ttl<N>_mode | R/W | in | TTL <N> (1 - 4) line set as input |
| ttl<N>_mode | R/W | out | TTL <N> (1 - 4) line set as output |
| ttl<N> | R(/W) | 0 | TTL <N> (1 - 4) line low. Writable only in output mode |
| ttl<N> | R(/W) | 1 | TTL <N> (1 - 4) line high. Writable only in output mode |
TTL lines used by a Wiegand interface cannot be set to in or out mode while that interface is enabled.
Similarly, Wiegand interface enabling is denied when one of its TTL lines is configured in in or out mode.
You can use the TTL lines as Wiegand interfaces for keypads or card reader. You can connect up to two Wiegand devices using TTL1/TTL2 respctively fot the D0/D1 lines of the first device (w1) and TTL3/TTL4 for D0/D1 of the second device (w2).
| File | R/W | Value | Description |
|---|---|---|---|
| w<N>_enabled | R/W | 0 | Wiegand interface w<N> disabled |
| w<N>_enabled | R/W | 1 | Wiegand interface w<N> enabled |
| w<N>_data(pollable) | R | <ts> <bits> <data> | Latest data read from wiegand interface w<N>. The first number (<ts>) represents an internal timestamp of the received data, it shall be used only to discern newly available data from the previous one. <bits> reports the number of bits received (max 64). <data> is the sequence of bits received represnted as unsigned integer |
The following properties can be used to improve noise detection and filtering. The w<N>_noise property reports the latest event and is reset to 0 after being read.
| File | R/W | Value | Description |
|---|---|---|---|
| w<N>_pulse_width_max | R/W | <val> | Maximum bit pulse width accepted, in µs |
| w<N>_pulse_width_min | R/W | <val> | Minimum bit pulse width accepted, in µs |
| w<N>_pulse_itvl_max | R/W | <val> | Maximum interval between pulses accepted, in µs |
| w<N>_pulse_itvl_min | R/W | <val> | Minimum interval between pulses accepted, in µs |
| w<N>_noise | R | 0 | No noise |
| w<N>_noise | R | 10 | Fast pulses on lines |
| w<N>_noise | R | 11 | Pulses interval too short |
| w<N>_noise | R | 12/13 | Concurrent movement on both D0/D1 lines |
| w<N>_noise | R | 14 | Pulse too short |
| w<N>_noise | R | 15 | Pulse too long |
| File | R/W | Value | Description |
|---|---|---|---|
| serial_num | R | 9 1-byte HEX values | Secure element serial number |
You will find the list of connected 1-Wire sensors' IDs in /sys/bus/w1/devices/ with format 28-XXXXXXXXXXXX.
To get the measured temperature (in °C/1000) read the file temperature under the sensor's directory, e.g.:
$ cat /sys/bus/w1/devices/28-XXXXXXXXXXXX/temperature
24625