====== unipiid ======

This interface can be used to identify the device. The identification information given by the API is read directly from HW. To read any information it is necessary to have **root privileges**.

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
If a user without root privileges needs access to information from this API, then the information is accessible for that user only using /run/unipi-plc/unipi-id path. See [[#create_or_refresh_files_in_run_unipi-plc_unipi-id_path|Create or refresh files in /run/unipi-plc/unipi-id path]].
</WRAP>
</WRAP>

Help for this API can be shown by this command:
<code>unipiid</code>

Help example:
<code>
Usage:
    unipiid -d     - create and populate directory /run/unipi-plc/unipi-id
    unipiid NAME   - show value of parameter name
    unipiid mainboard_description attr [opt] - show list/value of optional parameters

Where NAME can be:
    product_description   product_model   product_model_full
    product_version       product_serial  product_code
    product_family        product_options
    platform_family       platform_id
    mainboard_description mainboard_id
    uboard_id
    api_version
</code>

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
This interface can be used only in systems running Debian 13 and newer.
</WRAP>
</WRAP>

===== API version =====
Like most of the other APIs, unipiid can also be subject to change in the future. __Therefore, comparing the API version before any usage by a user application is strictly recommended.__ 
<code>
unipiid api_version
</code>

Content example:
<code>
2
</code>

===== Product description =====
Overall summary of the product (Unipi PLC) in human-readable format.

<code>
unipiid product_description
</code>

Content example:
<code>
Product model:   E413
Product version: 1.0
Product serial:  1260244349
SKU:             2025058
Options:         0x02

Platform family: Edge (6)
Platform series: 0x06
RAW platform ID: 0x0606
</code>

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:

<code>
unipiid product_model
</code>
<code>
unipiid product_serial
</code>
<code>
unipiid platform_family
</code>
<code>
unipiid platform_id
</code>

===== Full product model =====
Product model with more detailed information about HW configuration.
Description of the contents is in the main page for each product. Example for [[en:hw:004-edge#part_number_description|Unipi Edge]].
This can sometimes be the same as //product_model//.

<code>unipiid product_model_full</code>

Content example:
<code>
E4130SW43200-M1
</code>

===== Product code =====
Uniquely identifies the device. It consists of #SKU;Product model full_Product version;Product serial#.
The same string is contained in the 2D code (data matrix) on the manufacturing label on the device.

<code>unipiid product_code</code>

Content example:
<code>
#2025058;E4130SW43200-M1_1.0;1260244349#
</code>


===== Mainboard description =====
The mainboard is a key part of every Unipi PLC. The mainboard contains its own EEPROM memory storing all information about itself and the whole unit.

<code>
unipiid mainboard_description
</code>

Content example:
<code>
Model:   Mainboard
Version: 4C
Serial:  00000548
ID:      0x00CC
Nvmem:   /sys/bus/i2c/devices/1-0057/eeprom
</code>

To get mainboard type only, parsing of this file is not necessary - simply use this shorthand:
<code>
unipiid mainboard_id
</code>

===== Upper board =====
Upper board identification. It returns an identification number only if an upper board is contained in the device.

<code>
unipiid uboard_id
</code>

Content example:
<code>
00e0
</code>

===== 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.

<code>
unipiid fingerprint
</code>

Content example:
<code>
fcc85af4c8573f82cdd9a30bb27b4536dd68c8d6
</code>


===== Create or refresh files in /run/unipi-plc/unipi-id path =====
Calling this will create or refresh data inside files in /run/unipi-plc/unipi-id. Text files with the information itself will be created in that directory. The identification information in these files is accessible even without root privileges.

<code>
unipiid -d
</code>

Files in /run/unipi-plc/unipi-id:
<code>
$ ls -l /run/unipi-plc/unipi-id/
total 60
-rw-r--r-- 1 root root   1 Jul 16 09:19 api_version
-rw-r--r-- 1 root root  40 Jul 16 09:19 fingerprint
-rw-r--r-- 1 root root 109 Jul 16 09:19 mainboard_description
-rw-r--r-- 1 root root   4 Jul 16 09:19 mainboard_id
-rw-r--r-- 1 root root   1 Jul 16 09:19 platform_family
-rw-r--r-- 1 root root   4 Jul 16 09:19 platform_id
-rw-r--r-- 1 root root  37 Jul 16 09:19 product_code
-rw-r--r-- 1 root root 191 Jul 16 09:19 product_description
-rw-r--r-- 1 root root   4 Jul 16 09:19 product_family
-rw-r--r-- 1 root root   5 Jul 16 09:19 product_model
-rw-r--r-- 1 root root  13 Jul 16 09:19 product_model_full
-rw-r--r-- 1 root root   2 Jul 16 09:19 product_options
-rw-r--r-- 1 root root  10 Jul 16 09:19 product_serial
-rw-r--r-- 1 root root   3 Jul 16 09:19 product_version
-rw-r--r-- 1 root root   4 Jul 16 09:19 uboard_id
</code>