SysFS
The SysFS driver is part of the kernel module for Unipi units with inputs and outputs and provides easy file-based access to all inputs and outputs.
Iris
Patron
Neuron
To use 1-Wire on a Unipi unit with OpenSource OS, you must install and configure OWFS. In the case of an OS with EVOK, OWFS is already installed.
Do not install OWFS for Mervis OS! It uses an alternative method to work with 1-Wire and collisions could occur.
Check the following examples of reading and writing I/O to get started:
All files within SysFS can be accessed in the same way.
DO status reading:
cat /run/unipi/io_group1/do_1_01/do_value
Setting the DO to the closed state:
echo 1 > /run/unipi/io_group1/do_1_01/do_value
DI status reading:
cat /run/unipi/io_group1/di_1_01/di_value
Status reading of all first section DI's:
cat /run/unipi/io_group1/di_[1-3]_[0-9][0-9]/di_value
Status reading of all available DI units:
cat /run/unipi/io_group[1-3]/di_[1-3]_[0-9][0-9]/di_value
SysFS interface description
Starting from Debian 11, the SysFS comprises two main parts:
- unipi_id containing all available static information about the platform hardware
- I/O access allowing access IOs of Unipi hardware
The Unipi SysFS is a subsystem that operates through standard files and is automatically managed by both the Linux kernel module and userspace tools. The main goal is to provide a straightforward interface for quick evaluation and writing short (not only) shell scripts without any SW dependencies.
For production deployment, we recommend using the Modbus TCP interface, which offers more capabilities and is more powerful. It is also a standard component of the standard (pre-installed) software bundle on all Unipi units.
Since Sysfs files are scattered throughout the filesystem, we strongly recommend accessing them through the directory:
/run/unipi-plc
which serves as a sort of directory containing symbolic links to all individual components.
unipi_id
API version
Similarly, like most of the other APIs, SysFS can also be a subject of change in the future. Therefore, verifying the API version before any usage by a user application is strictly recommended.
/run/unipi-plc/unipi-id/api_version
Content example:
1.1
Product desription
Overall single-file summary of the product (Unipi PLC) in human-readable format.
/run/unipi-plc/unipi-id/product_description
Content example:
Product model: S167 Product version: 1.1 Product serial: 00000667 SKU: 2020028 Options: 0x00 Platform family: Patron (7) Platform series: 0xFF RAW platform ID: 0xFF07
To get and use just a single value from this list, you do not have to parse the whole complex file - use single-value files as a shorthand:
/run/unipi-plc/unipi-id/product_model
/run/unipi-plc/unipi-id/product_serial
/run/unipi-plc/unipi-id/platform_family
/run/unipi-plc/unipi-id/platform_id
Mainboard description
The mainboard is a key part of every Unipi PLC. Contains own EEPROM memory storing all information about itself and the whole unit.
/run/unipi-plc/unipi-id/mainboard_description
Content example:
Model: Mainboard Version: 1.2 Serial: 00000515 ID: 0x07D0 Nvmem: /sys/bus/nvmem/devices/2-00571/nvmem
To get mainboard type only, parsing of this file is not necessary - simply use this shorthand:
/run/unipi-plc/unipi-id/mainboard_id
Card description
Some Unipi platforms use a plug-in slot system. Every slot can host one custom-defined type of card. Similarly, as the mainboard, every card contains EEPROM memory storing information.
/run/unipi-plc/unipi-id/card_description.<xx>
where <xx> placeholder is the number of the slot.
Content example for slot number 12:
Model: IM205 Version: 1.0 Serial: 00000080 ID: 0x0079 Nvmem: /sys/bus/nvmem/devices/plcid12/nvmem Slot: 12
To get only card ID as a single value, this file can be used:
/run/unipi-plc/unipi-id/card_id.<xx>
where <xx> placeholder is the number of the slot.
Fingerprint
To reliably detect if the hardware configuration of the Unipi PLC has been changed, the fingerprint value can be used. This can occur when e.g. a new card is inserted into a slot. The fingerprint value is a unique hash and is computed during every boot.
/run/unipi-plc/unipi-id/fingerprint
Content example:
fcc85af4c8573f82cdd9a30bb27b4536dd68c8d6
Inputs and outputs (I/O)
Digital inputs
Used to read the status of the selected input in the given section [1-3] of the unit. For more information, including voltage levels for log.0/1 detection, see the article on digital inputs.
The file is read-only and if it contains the value 0, a logic value of 0 is detected on the digital input. If it contains the value 1, a logic value of 1 is detected.
/run/unipi-plc/by-sys/DI[1-3]_[0-9][0-9]/value
Digital outputs
Used to read/set the status of the selected transistor output in the given section [1-3] of the unit. For more information see the article on digital outputs.
The file allows both reading and writing and if it contains the value 0, the digital output is open. If it contains the value 1, it is closed. Writing a value to this file will change the state (closed/open) of the output according to the given rule.
/run/unipi-plc/by-sys/DO[1-3]_[0-9][0-9]/value
Analog Inputs
Following files are used to set AI mode and read the analog value of selected input in given section of the unit [1–3]. For more technical details, wiring and other information see the Analog Inputs article.
Analog input mode setting
Section 1 AI mode setting (except some units, eg. S5xx):
The file allows both reading and writing and the input mode is set depending on the value it contains.
/run/unipi-plc/by-sys/AI1.1/mode_voltage_current
Input can be set to two modes according to the following table:
| Value | AI Mode |
|---|---|
| 0 | Voltage 0–10V |
| 1 | Current 0–20mA |
Sections 2,3 AI mode settings (and some units, eg. S5xx):
The file allows both reading and writing and the input mode is set depending on the value it contains.
/run/unipi-plc/by-sys/AI[1-3]_[1-9]/mode_voltage_current_resistance
Input can be set to six modes according to the following table:
| Value | AI Mode |
|---|---|
| 0 | Off |
| 1 | Voltage 0–10V |
| 2 | Voltage 0–2.5V |
| 3 | Current 0–20mA |
| 4 | Resistance (three conductors) 0–1960 Ohm |
| 5 | Resistance (two conductors) 0–100 kOhm |
Reading from analog inputs
Note:
You can read only one file according to set input mode.
Reading voltage value on the AI :
The file is read-only and contains the measured voltage value in mV.
/run/unipi-plc/by-sys/AI[1-3]_[1-9]/in_voltage_raw
Reading current value on the AI:
The file is read-only and contains the measured current value in mA.
/run/unipi-plc/by-sys/AI[1-3]_[1-9]/in_current_raw
Reading resistance value on the AI (only sections 2,3 and some units, eg. S5xx):
The file is read-only and contains the measured resistance value in Ohms .
/run/unipi-plc/by-sys/AI[1-3]_[1-9]/in_resistance_raw
Analog Outputs
Following files are used to set AO mode and to read/set analog value of output in the given section [1-3] of the unit, the AOR output in the first section can also read the resistance. For more technical details, wiring and other information see the Analog Outputs article.
Analog output mode setting
AO mode setting (section 1 only, except some units, eg. S5xx):
The file allows both reading and writing and the output mode is set depending on value it contains
/run/unipi-plc/by-sys/AO1.1/mode_voltage_current_resistance
Output can be set to three modes according to the following table:
| Value | AOR Mode |
|---|---|
| 0 | Voltage 0–10 V |
| 1 | Current 0–20 mA |
| 2 | Resistance 0–2 kOhm |
Writing to analog outputs
Voltage mode is available on any analog output, but current mode only on the AOR output (section 1 only, except some units eg. S5xx).
Note:
You can write to one file only according to set output mode.
Writing the voltage value to the AO/AOR:
The file is write-only, and the required voltage value is entered in mV.
/run/unipi-plc/by-sys/AO[1-3]_[1-9]out_voltage_raw
Writing the current value to the AOR:
The file is write-only, and the required current value is entered in mA.
/run/unipi-plc/by-sys$ cat AO1.1/out_current_raw
Reading from analog output
It is also possible to read the resistance value on the special analog output AOR (section 1 only, except some units, eg. S5xx).
Reading the resistance value from AOR output:
The file is read-only and contains the measured resistance value in Ohms.
/run/unipi-plc/by-sys/AO1.1/in_resistance_raw
Relay outputs
Used to read/set the status of the selected output relay in the given section [1-3] of the unit. For more information see the article on relay outputs.
The file allows both reading and writing and if it contains the value 0, the relay output is open. If it contains the value 1, it is closed. Writing a value to this file will change the state (open/closed) of the output according to the given rule.
/run/unipi-plc/by-sys/RO[1-3]_[0-9][0-9]/value
User LEDs
Used to read/set the status of the selected user LED of the given section [1-3] of the unit.
The file allows both reading and writing and if it contains the value 0, the LED is off. If it contains a value greater than or equal to 1, the LED is lit. Writing a value to this file will change the state (on/off) of the LED according to the given rule.
/run/unipi-plc/by-sys/iogroup1/30840000.spi:unipispi@0:iogroup1:led/leds/unipi:green:uled-x[0-9]/brightness
Special I/O functions
Counter
A counter function is available for each digital input of Unipi units. See the article on digital inputs for more information on this function.
The file allows reading and writing and contains the total number of pulses in the range 0-4294967295 detected by the digital input of the given section [1-3] of the unit. Writing a value to a file sets the selected counter to the desired value. You can reset the counter by entering the value 0.
/run/unipi-plc/by-sys/DI[1-3]_[0-9][0-9]/counter
Debounce
The Debounce function is used for input flash repression on the digital input. This file contains time in hundreds of µs (if its value is 10, it corresponds to 1 ms). During this set time, the response to a change in the value at the input is ignored to prevent accidental switching of the input due to induction on the cabling, etc. The setting is available for each individual input of the selected section [1-3] of the unit.
The file allows both reading and writing. It contains the value 50 at the factory settings, which corresponds to a time of 5 ms. A value of 0 means that the debounce function is disabled.
/run/unipi-plc/by-sys/DI[1-3]_[0-9][0-9]/debounce
Advanced I/O boards settings
Master Watchdog
The Master Watchdog (MWD) function continuously monitors commands from the application running on the unit. If no commands are detected during the defined time watchdog_timeout, the module processor automatically restarts (if enabled) and uses the saved default configuration. This function ensures that a safe configuration is set in case of emergency situations, eg. controller failure, communication interruption, or software problems, in order to prevent damage to controlled devices or danger to persons.
Watchdog state
Writing 1 to this file enables MWD.
In addition to reading MWD state, it is also possible to write to the file.
/run/unipi-plc/by-sys/iogroup[1-3]/master_watchdog_enable
Warning:
Immediately after enabling MWD (before watchdog_timeout expires) it is necessary to save the default configuration, otherwise MWD will react and restart the I/O section, thus loading the saved default configuration where MWD is still disabled.
Watchdog boot
The file indicates if the last boot of the section was triggered by MWD.
/run/unipi-plc/by-sys/iogroup[1-3]/was_watchdog
Watchdog timeout
The default value is 2500, the maximum possible value is 65535 and the minimum timeout value is strongly recommended to be higher than 100.
The file allows both reading and writing and contains the value in ms.
/run/unipi-plc/by-sys/iogroup[1-3]/master_watchdog_timeout
Default Configuration
After writing the value 1 the current configuration of the section is saved in its persistent memory. When the device is power cycled or sections are restarted, the saved configuration is loaded and used.
The file is write-only and then automatically resets to 0.
/run/unipi-plc/by-sys/iogroup[1-3]/save_nvram
I/O section restart
After writing the value 1, the whole section restarts, similarly to power cycling the device.
The file is write-only and then automatically resets to 0.
/run/unipi-plc/by-sys/iogroup[1-3]/reboot
