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.
Note:
To use 1-Wire on a Unipi unit with Base OS, you must install and configure OWFS. If the OS has Evok preinstalled, OWFS will be 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-plc/by-sys/DO1.1/value
Setting the DO to the closed state:
echo 1 > /run/unipi-plc/by-sys/DO1.1/value
DI status reading:
cat /run/unipi-plc/by-sys/DI1.1/value
Status reading of all first section DI's:
cat /run/unipi-plc/by-sys/DI1.*/value
Status reading of all available DI units:
cat /run/unipi-plc/by-sys/DI[1-3].*/value
Sysfs interface description
The sysfs includes: I/O access allowing access IOs of Unipi hardware
Note:
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.
Note:
To identify the device please use unipiid API.
Information about model and serial number was previously included in sysfs, but from Debian 13 the identification of the device was moved to unipiid.
Inputs and outputs (I/O)
General Information
I/O Board Name
The file is read-only and contains the name of the I/O board in given section [1-3] of the unit.
Returns error if the board has an unknown unit ID and it is not possible to determine the board name.
/run/unipi-plc/by-sys/iogroup[1-3]/sys_board_name
I/O Board Serial number
The file is read-only and contains the serial number of the I/O board in given section [1-3] of the unit.
Returns zero if the serial number is not valid.
/run/unipi-plc/by-sys/iogroup[1-3]/sys_board_serial
Firmware version
The file is read-only and contains the firmware version of the I/O board in given section [1-3] of the unit. The firmware version number is represented in following format: [0-9,A-F].[0-9,A-F][0-9,A-F].
Returns error if the firmware version is not valid.
/run/unipi-plc/by-sys/iogroup[1-3]/firmware_version
Storage health
These files are read-only and contain the information about health of the unit's storage.
The first file contains the number of rewrite cycles of storage [%] from defined maximum.
/run/unipi_stats/cycles_used
The second file contains number of healthy blocks [%].
/run/unipi_stats/good_blocks
Neuron units have a third file containing number of unit starts with the current SD card.
/run/unipi_stats/power_cycles
Additionally, if you have a supported SD card, it is possible to find the SD card vendor.
/run/unipi_stats/vendor_1 /run/unipi_stats/vendor_2 /run/unipi_stats/vendor_3
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/AI[1-3].[1-9]/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
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
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_input
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_input
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_input
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/AO[1-3].[1-9]/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).
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_input
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/AO[1-3].[1-9]/out_current_input
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/AO[1-3].[1-9]/in_resistance_input
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/ULED[1-3].[1-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 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
Watchdog boot
The file indicates if the last boot of the section was triggered by MWD.
The file allows both reading and writing and after reading the value does not reset to 0. To detect consecutive MWD restarts the value must be set to 0 before next MWD restart.
/run/unipi-plc/by-sys/iogroup[1-3]/was_watchdog
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
Enable/disable 1-Wire bus
Note:
This method is not sysfs, but uses standard linux APIs.
Note:
This file does not work on units without 1-Wire, Unipi 1.1 and Patron S207.
Power off the bus and unbind the bus.
echo x-0018 | sudo tee /sys/bus/i2c/drivers/ds2482/unbind Replace the x with number: 1 - Unipi Neuron 2 - Unipi Patron
Power on the bus and bind the bus.
echo x-0018 | sudo tee /sys/bus/i2c/drivers/ds2482/bind Replace the x with number: 1 - Unipi Neuron 2 - Unipi Patron
Alternative method is is to enable/disable the 1-Wire using the corresponding Modbus coil instead.
