====== 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 {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}} **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. ===== 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 description ==== 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. where 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. where 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) ===== /* FIXME -> popis rozdílu mezi by-sys a by-slot */ ==== 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. /* **Soubor je pouze pro čtení** a obsahuje název desky vstupů a výstupu jednotky Unipi, přičemž číslo v rozsahu [1-3] odpovídá sekci jednotky. */ Returns error if the board has an unknown unit ID and it is not possible to determine the board name. /* Vrátí chybu, pokud se jedná o desku s neznámým ID zařízení a není možné získat odpovídající název desky. */ /* FIXME -> opravdu vrátí chybu, nebo bude prázdný?? */ /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. /* **Soubor je pouze pro čtení** a obsahuje sériové číslo desky vstupů a výstupu jednotky Unipi, přičemž číslo v rozsahu [1-3] odpovídá sekci jednotky. */ Returns zero if the serial number is not valid. /*Pokud sériové číslo není platné, vrátí nulu. */ /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]. /* **Soubor je pouze pro čtení** a obsahuje označení verze firmwaru desky vstupů a výstupu jednotky Unipi, přičemž číslo v rozsahu [1-3] odpovídá sekci jednotky. Číslo verze firmwaru používá následující formát: [0-9,A-F].[0-9,A-F][0-9,A-F]. */ Returns error if the firmware version is not valid. /* Pokud je číslo verze neplatné, vrátí chybu. */ /* FIXME -> opravdu vrátí chybu, nebo bude prázdný?? */ /run/unipi-plc/by-sys/iogroup[1-3]/firmware_version /* toto by tu mohlo být, ale je potřeba asi nějak obecně napsat, na který zařízeních ty soubory jsou (kde je uart) === UART konfigurace === **Soubor umožňuje čtení i zápis** a obsahuje nastavení sériových portů dostupných na desce vstupů a výstupů, přičemž číslo v rozsahu [1-3] odpovídá sekci jednotky. Pokud deska I/O neobsahuje sériový port, soubor je prázdný. /run/unipi-plc/by-sys/iogroup[1-3]/uart_config === UART délka fronty === **Soubor je pouze pro čtení** a obsahuje počet přijatých znaků ve vyrovnávací paměti sériového portu na desce vstupů a výstupů, přičemž číslo v rozsahu [1-3] odpovídá sekci jednotky. Pokud deska I/O neobsahuje sériový port, soubor je prázdný. /run/unipi-plc/by-sys/iogroup[1-3]/uart_queue_length /* */ === Storage health === **These files are read-only** and contain the information about health of the unit's storage. /* **Soubory jsou pouze pro čtení** a obsahují informace o stavu úložiště. */ The first file contains the **number of rewrite cycles of storage** [%] from defined maximum. \\ /* První soubor udává **počet cyklů přemazání paměti** oproti maximu [%]. \\ */ /run/unipi_stats/cycles_used The second file contains **number of healthy blocks** [%]. \\ /* Druhý soubor udává **počet bloků** [%], které jsou **v pořádku**. \\ */ /run/unipi_stats/good_blocks ---- Neuron units have a third file containing **number of unit starts** with the current SD card. \\ /* Pro jednotky Neuron je k dispozici třetí soubor indikující **počet startů jednotky** s aktuální SD kartou. */ /run/unipi_stats/power_cycles Additionally, if you have a supported SD card, it is possible to find the **SD card vendor**. /* V případě, že máte v Neuronu podporovanou SD kartu, je možno následujícími soubory zjistit **výrobce karty**. */ /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 [[en:hw:007-patron:description-of-io:01-description-of-di|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 [[en:hw:007-patron:description-of-io:02-description-of-do|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 [[en:automation:02-glossary:analog-inputs-hidden|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: |< 100% 30% 70%>| ^ 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: |< 100% 30% 70%>| ^ 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 === {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}} **Attention:** \\ You can read only one file according to [[#analog_input_mode_setting|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 [[en:automation:02-glossary:analog-outputs-hidden|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: |< 100% 30% 70%>| ^ 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). {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}} **Attention:** \\ You can write to one file only according to [[#analog_output_mode_setting|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/AO[1-3].[1-9]/out_current_input {{ :files:img_breakline.png?nolink |}} === 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 [[en:hw:007-patron:description-of-io:03-description-of-ro|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*/ /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 [[en:hw:007-patron:description-of-io:01-description-of-di#counter|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|watchdog_timeout]]**, the module processor automatically restarts (if enabled) and uses the saved [[#default_configuration|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 {{ :files:img_warning-line_b.png?nolink |}} {{:en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink|(!)}} **Warning**: \\ Immediately after enabling MWD (before **[[#watchdog_timeout|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 [[#i_o_section_restart|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 ==== {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}} **Attention:** \\ This method of enabling/disabling 1-Wire is removed on systems running Debian 13 and newer! To enable/disable the 1-Wire use the corresponding Modbus coil instead. Alternative method is to bind or unbind the bus. echo x-0018 | sudo tee /sys/bus/i2c/drivers/ds2482/unbind echo x-0018 | sudo tee /sys/bus/i2c/drivers/ds2482/bind Replace the x with number: 1 - Unipi Neuron 2 - Unipi Patron {{ :files:img_warning-line_b.png?nolink |}} {{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}} **Note:** \\ This file does not work on units without 1-Wire, Unipi 1.1 and Patron S207. After writing the value ''1'', the 1-Wire bus on the section is powered off. To enable the 1-Wire bus the value must be set to ''0''. The 1-Wire bus is enabled by default after start, i.e it's value is set to ''0''. **The file allows both reading and writing** and accepts values ''0'' and ''1''. /run/unipi-plc/by-sys/iogroup[1-3]/ow_power_off