Debian:

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 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/DI[1-3].[0-9][0-9]/value

Status reading of all available DI units:

cat /run/unipi-plc/by-sys/DI[1-3].[0-9][0-9]/value

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_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/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_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/AO1.1/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/AO1.1/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/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