This is an old revision of the document!


SysFS

The SysFS driver is still under development. Please report any issues or feature requests.

Patron
Neuron
Axon

SysFS driver included in the kernel module for all Unipi units with I/O (except Unipi 1.1) provides easy file-based access to all inputs and outputs of the unit. Check the following examples to get started:

Set state of DO to 1

echo 1 > /sys/devices/platform/unipi_plc/io_group1/do_1_01/do_value

Read the state of DI

cat /sys/devices/platform/unipi_plc/io_group1/di_1_01/di_value

All IOs can be accessed similarly.

General information

I/O board name

The file is read-only and contains the name of the input and output board of the Unipi unit, with the number in the range [1-3] corresponding to the unit section.

Returns an error if it is a board with an unknown device ID and the corresponding board name cannot be obtained.

/run/unipi/io_group[1-3]/sys_board_name

I/O board serial number

The file is read-only and contains the serial number of the input and output board of the Unipi unit, with a number in the range [1-3] corresponding to the unit section.

If the serial number is not valid, it returns zero.

/run/unipi/io_group[1-3]/sys_board_serial

Firmware version

The file is read-only and contains the firmware version designation of the input and output board of the Unipi unit, with a number in the range [1-3] corresponding to the unit section. The firmware version number uses the following format: [0-9,A-F].[0-9,A-F][0-9,A-F].

If the version number is invalid, it returns an error.

/run/unipi/io_group[1-3]/firmware_version

UART configuration

The file allows both reading and writing and contains the settings of the serial ports available on the I/O board, with a number in the range [1-3] corresponding to the unit section.

If the I/O board does not have a serial port, the file is empty.

/run/unipi/io_group[1-3]/uart_config

UART queue length

The file is read-only and contains the number of received characters in the serial port buffer on the I/O board, with a number in the range [1-3] corresponding to the unit section.

If the I/O board does not have a serial port, the file is empty.

/run/unipi/io_group[1-3]/uart_queue_length

Storage life status

Files are read-only and contain storage status information.

The first file indicates the number of memory erase cycles used compared to the maximum [%].

/run/unipi_stats/cycles_used

The second file indicates the number of blocks [%] that are all right.

/run/unipi_stats/good_blocks

A third file is available for Neuron units indicating the number of power cycles with the current SD card.

/run/unipi_stats/power_cycles

If you have a supported SD card in Neuron unit, you can use the following files to find out the card manufacturer.

/run/unipi_stats/vendor_1
/run/unipi_stats/vendor_2
/run/unipi_stats/vendor_3

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/io_group[1-3]/di_[1-3]_[0-9][0-9]/di_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/io_group[1-3]/do_[1-3]_[0-9][0-9]/do_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/io_group1/ai_1_1/mode_ai_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/io_group[1-3]/ai_[1-3]_[1-9]/mode_ai_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/io_group[1-3]/ai_[1-3]_[1-9]/in_voltage0_raw

Reading current value on the AI:

The file is read-only and contains the measured current value in mA.

/run/unipi/io_group[1-3]/ai_[1-3]_[1-9]/in_current1_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/io_group[1-3]/ai_[1-3]_[1-9]/in_resistance2_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/io_group1/ao_1_1/mode_ao_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/io_group[1-3]/ao_[1-3]_[1-9]/out_voltage0_raw

Writing the current value to the AOR:

The file is write-only, and the required current value is entered in mA.

/run/unipi/io_group1/ao_1_1/out_current1_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/io_group1/ao_1_1/in_resistance2_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/io_group[1-3]/ro_[1-3]_[0-9][0-9]/ro_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/io_group[1-3]/leds/unipi:green:uled-x[0-9]/brightness

Specil 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/io_group[1-3]/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/io_group[1-3]/di_[1-3]_[0-9][0-9]/debounce

DirectSwitch

The DirectSwitch function is set on digital inputs, but its function is also linked to digital or relay outputs with the same designation. All DirectSwitch parameters can be set individually for each digital input of the selected section [1-3] of the unit. See the article on digital inputs for more information on this function.

DirectSwitch enable

The file allows both reading and writing and if it contains the value 0, the DirectSwitch function is disabled. If it contains the value 1, the function is enabled. Writing a value to this file will change the state (enabled/disabled) of the DirectSwitch function according to the given rule.

/run/unipi/io_group[1-3]/di_[1-3]_[0-9][0-9]/direct_switch_enable
DirectSwitch polarity

The file allows both reading and writing and if it contains the value 1, the DirectSwitch function (if enabled) sets the output to the state corresponding to the negated value of the input. If it contains the value 0, the state of the output is the same as the value at the input. Writing a value to this file sets the polarity (match/negation) of the DirectSwitch function according to the given rule.

/run/unipi/io_group[1-3]/di_[1-3]_[0-9][0-9]/direct_switch_polarity
DirectSwitch toggle

The file allows both reading and writing and if it contains the value 1, the DirectSwitch function (if enabled) changes the state of the output with each rising edge on the input, while the DirectSwitch polarity setting is ignored. If it contains the value 0, the toggle function is disabled. Writing a value to this file will change the state (enabled/disabled) of the toggle function according to the given rule.

/run/unipi/io_group[1-3]/di_[1-3]_[0-9][0-9]/direct_switch_toggle

PWM - pulse width modulation

PWM can only be set for digital outputs. In order to use the PWM function, the digital output value must be set to 0. See the article on digital outputs the article on digital outputs for more information on this function.


The length of one Tc cycle is set using the PWM Prescale and PWM Cycle values. The calculation is described by the following formula:

The PWM cycle value has a direct effect on the resolution of the PWM cycle according to the following formula:

resolution = PWM_cycle + 2

It follows that if the value of the PWM cycle is 1, the resolution is equal to 3. So we can set three values of the duty cycle - 0%, 50%, and 100%. Where the calculation allows it, it is advisable to set the PWM cycle to the highest possible value.

The PWM clock runs at 48 MHz by default, so the permissible PWM frequencies range from 24 MHz to ~ 0.0111 Hz. It should be noted that in the upper level of this range, the PWM square wave will be relatively irregular, due to the time for which the transistors change their state.

PWM duty cycle

The PWM duty-cycle setting is available individually for each digital output of the selected section [1-3] of the unit.

The file allows both reading and writing and values in the range 0-65535 can be written to it. However, the correct duty cycle values are in the range 0-100 [%], the setting of the higher value will always be evaluated as 100 [%].

/run/unipi/io_group[1-3]/do_[1-3]_[0-9][0-9]/pwm_duty_cycle
PWM cycle

The PWM cycle frequency setting is common to all digital outputs of the selected section [1-3] of the unit, and changing the setting of one output will affect all files.

The file allows both reading and writing and may contain values in the range 0-65535.

/run/unipi/io_group[1-3]/do_[1-3]_[0-9][0-9]/pwm_frequency_cycle
PWM prescale

The PWM prescale setting is common to all digital outputs of the selected section [1-3] of the unit, and changing the setting of one output will affect all files.

The file allows both reading and writing and may contain values in the range 0-65535.

/run/unipi/io_group[1-3]/do_[1-3]_[0-9][0-9]/pwm_prescale

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 status

The file value indicates several MWD states, that can occur simultaneously. Each state is indicated by one bit, where:

  • bit 0 indicates, whether MWD is enabled (1 = enabled)
  • bit 1 indicates, whether the section has been restarted by the MWD function
  • bit 2 indicates, whether a watchdog_timeout has elapsed since the last communication

In addition to reading MWD states, it is also possible to write to the file for enabling/disabling MWD. Enabling the function is done by writing 1 to this file and disabling it by writing 0.

/run/unipi/io_group[1-3]/watchdog_status

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/io_group[1-3]/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/io_group[1-3]/save_initial_state

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/io_group[1-3]/reboot_group