> For the complete documentation index, see [llms.txt](https://admin-things5.gitbook.io/things5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://admin-things5.gitbook.io/things5/device/manage-firmware/machine-variables.md).

# Machine Variables

Firmware distinctive variables for reading and writing values and parameters

## Variables and Firmware

Machine variables are essentially firmware properties, so you need to [create a firmware](/things5/device/manage-firmware/add.md) first to be able to manage its variables.

To access the firmware variables click on the firmware version to enter its details view.

<div align="left"><img src="https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-Mj9q_wOPFnQawtgCunY%2F-Mj9tD2rCWOVwQUqBaQY%2Fimage.png?alt=media&amp;token=72327547-71dd-4660-b7cc-19de86361253" alt=""></div>

## Add variables manually&#x20;

Open the firmware details page to manage firmware variables.\
Here you can add variables, one by one, from within dedicated tab by type: \
**Metrics**, **States**, **Events**, **Configuration**.\
\
Click **+ Add variable** button to perform this operation  (pic. below pos. 1)  &#x20;

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-MjE6KFcgvhnpjj9I_L_%2F-MjEB_3-kXy0kRHSLcjM%2Fimage.png?alt=media\&token=4909a662-b728-4ba9-a3b6-83ffa9bdb2ab)

## Add variables by csv file uploading

A faster and easier way to add machine variables is to import a csv file via the **import Variables** button.\
This csv file must contain the entire set of machine variables that firmware needs (pic. below pos 2)

{% hint style="danger" %}
**Pay attention**: every import operation erase old variables!
{% endhint %}

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-MjE6KFcgvhnpjj9I_L_%2F-MjEBo5Ru8mH1b_1sM89%2Fimage.png?alt=media\&token=d34c53fd-2e27-4889-be31-9b9c29632d0a)

{% hint style="info" %}
**Export Variables** will download the current variables in csv \
**Get Sample Data** will download a generic set of sample variables\
\
*More info about machine variables at* [*https://things5.readme.io/reference*](https://things5.readme.io/reference/getting-started-4#this-a-sample-variables-csv-attachment)
{% endhint %}

### Mark variables as HACCP

You may want to identify some variables as a HACCP report items.\
Flag the checkbox in Haccp column to include variable in this report.

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2F5lEG1IbpAwp3Pg9ub05Z%2Fimage.png?alt=media\&token=ab45637c-e5f0-4d2d-bb22-779962f92cda)

{% hint style="info" %}
To edit this attribute, the model of the firmware, must have the **"HACCP enabled**" checkbox checked! (see [Add new model](/things5/device/manage-models/add-new-model.md))
{% endhint %}

Variables may be configured to be included only when a particular condition is met, using the gear icon next to the checkbox:

* **Metric** variable can be visible always, never or only when a specific State is set
* **State** variable can be visible always, never or only when it assumes a particular value
* **Event** variable can be visible always or never *(no gear icon)*

![configuring a Metric variable to appear into HACCP report only when "IO\_Compressor\_status" value is "Stop"](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2F9oFLm6qskM7x5fAsrZHI%2Fimage.png?alt=media\&token=3d03e339-9831-4437-8358-85025fdd8584)

![configuring a State variable to appear into HACCP report only when its value is "Running"](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2FY1x7mXq6Ont3UgUIPzvE%2Fimage.png?alt=media\&token=fcafbe06-6e77-488f-b5d1-8207f84222bd)

### Set severity for Event variables

Event variables may have three different level of severity, changed with the drop-down menu: \ <mark style="color:red;">**alarm**</mark>, <mark style="color:yellow;">**warning**</mark> or <mark style="color:blue;">**info**</mark>. Severity is a mandatory field.

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2F860e2KzyMPsDCtUO6Ok2%2Fimage.png?alt=media\&token=790e24c9-4098-44b4-a774-a0bb9f46ec52)

#### Severity representation in the "Event log" tab

In the "Event log" section, severity level is shown by its icon, shown in the **Type** column

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2F6ADrJ0J5L725zn57IBnp%2Fimage.png?alt=media\&token=ff5587e2-f46b-4917-bc00-c1bdbf2cda5b)

#### Severity "alarm"

alarm-type events are extracted from the whole set of events and shown in the [overview](/things5/device/overview.md) page as "[latest alarms](/things5/device/overview.md#latest-alarm)" in last 24 hours by default

![](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2FVzejYBMWARwko6epyRJ3%2Fimage.png?alt=media\&token=9db4e435-7c6e-44a5-8697-e4b532b33d12)

### Sample CSV dataset

Here below a sample set of data for machine variables. File is available [here](https://drive.google.com/file/d/1QeF8nCMIxDvu6n2eHUdK6nL6naAgQ04l/view)

![hh:mm:ss read more about this format here below on Available Unit of Measurement](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mgf4wby1nhNas9J0n_V%2Fuploads%2FydqqDqLUoMWW7WkD2BWi%2Fimage.png?alt=media\&token=ef81f467-5dc8-40bf-a5e4-22907cc1562c)

{% hint style="info" %}
**ui\_unit** is optional and it is required only when one is different from the other.
{% endhint %}

#### What is every column fo&#x72;**?**

Columns are for specific purpose and can have specific type and value of data

<table><thead><tr><th width="150">Field </th><th width="150">Type </th><th>Description</th><th width="150">Value (can be)</th><th data-hidden></th></tr></thead><tbody><tr><td>name </td><td>string</td><td>name of the variable</td><td>any </td><td></td></tr><tr><td>type </td><td>string</td><td>variable type</td><td>string, integer, float</td><td></td></tr><tr><td>unit </td><td>string</td><td>original data unit of measure</td><td>One of the available UM</td><td></td></tr><tr><td>ui_unit</td><td>string</td><td>display unit of measure</td><td>One of the available UM</td><td></td></tr><tr><td>writable</td><td>boolean</td><td>when value is "true", variable can be written</td><td>true , false</td><td></td></tr><tr><td>min </td><td><p>integer, </p><p>float</p></td><td>the minimum value the variable can assume</td><td>a number</td><td></td></tr><tr><td>max </td><td><p>integer, </p><p>float</p></td><td>the maximum value the variable can assume</td><td>a number</td><td></td></tr><tr><td>category </td><td>string</td><td>used only for configuration variables.<br><em>It's used on the frontend to group variables together like "Settings" and "General" grouping</em></td><td>any </td><td></td></tr><tr><td>source</td><td>string</td><td>name of the asset</td><td>metrics, states, events, configuration</td><td></td></tr><tr><td>severity</td><td>string</td><td>event severity level</td><td>alert, warning, info</td><td></td></tr></tbody></table>

####

#### Available Unit of Measurement

Beside the most common measurement units, we also provide some special ones to allow data to be sent in such a "custom" form.&#x20;

A modbus workaround for example, consist to multiply a value by 10 to get the tenth part of the measure: that means that the value 123 represents the real value 12,3

These special ones are:

<table><thead><tr><th width="150.76199929655726">Simbol</th><th width="448.93217331915196">System behavior</th><th data-hidden></th></tr></thead><tbody><tr><td>hh:mm:ss</td><td>value is read as a number of seconds, <br>and is printed as a time string using the format hh:mm:ss</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>1/10 °C</td><td>value is read as a number of tenths of a Celsius degree and <br>is printed divided by 10 to represent a <br>number of Celsius degree e.g. 123 °C/10 is 12,3 °C</td><td></td></tr><tr><td>1/10 °F</td><td>value is read as a number of tenths of a Fahrenheit degree and <br>is printed divided by 10 to represent a<br>number of Fahrenheit degree e.g. 541 °F/10 is 54,1 °F</td><td></td></tr><tr><td>1/10 K</td><td>value is read as a number of tenths of Kelvin and <br>is printed divided by 10 to represent a <br>number of Kelvin e.g. 2854 K/10 is 285,45 K</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>1/10 pH</td><td>value is read as a number of tenths of ph and <br>is printed divided by 10 to represent a <br>number of ph e.g. 67 ph/10 is 6,7 ph</td><td></td></tr><tr><td>1/100 pH</td><td>value is read as a number of tenths of ph and <br>is printed divided by 100 to represent a <br>number of ph e.g. 678 ph/100 is 6,78 ph</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>1/10 V</td><td>value is read as a number of tenths of Voltand <br>is printed divided by 10 to represent a <br>number of Volt e.g. 123 V/10 is 12,3 V</td><td></td></tr><tr><td>1/10 kW</td><td>value is read as a number of tenths of kW and <br>is printed divided by 10 to represent a <br>number of kW e.g. 123 kW/10 is 12,3 kW</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>1/10 bar</td><td>value is read as a number of tenths of bar and <br>is printed divided by 10 to represent a <br>number of bar e.g. 123 bar/10 is 12,3 bar</td><td></td></tr><tr><td>1/10 barg</td><td>value is read as a number of tenths of barg and <br>is printed divided by 10 to represent a <br>number of barg e.g. 12 barg/10 is 1,2 barg</td><td></td></tr><tr><td>1/100 barg</td><td>value is read as a number of tenths of barg and <br>is printed divided by 100 to represent a <br>number of barg e.g. 123 barg/100 is 1,23 barg</td><td></td></tr></tbody></table>

### Examples of UM usage

#### Celsius degrees ( °C )

![when Things5 read the number 13 as number of Celsius degrees ](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-Mj4zWuQ4PZzC-yjl_To%2F-Mj5Cz_fPPDwppSNRQqN%2Fimage.png?alt=media\&token=ba11c59f-c2e0-446b-b8ea-9d1b780f8ce2)

#### Tenths of a Celsius degree ( 1/10 °C )

![when Things5 read the number 13 as number of tenths of a Celsius degree](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-Mj4zWuQ4PZzC-yjl_To%2F-Mj5D3LV0JmsmeR6IY08%2Fimage.png?alt=media\&token=cb81c803-dad4-4c3e-9a2a-b3c49f6595c5)

#### Time string ( hh:mm:ss )&#x20;

![when Things5 read the number 12882 as a number of seconds](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-Mj5DJ1SvonSrwJ9SbuX%2F-Mj8c1LIYm79hjgxy6X9%2Fimage.png?alt=media\&token=b55ca7fe-0a13-4e18-b966-afd71898e4c2)

![when Things5 read the number 12882 as a "hh:mm:ss" time representation](https://887564422-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Mgf4wby1nhNas9J0n_V%2F-Mj5DJ1SvonSrwJ9SbuX%2F-Mj8cDnbt2D0_wh8VaDk%2Fimage.png?alt=media\&token=45d84120-aef2-4c74-88a0-102b19987626)

## Label translations

All four examples here above are shown with labels ("temperature setpoint" and "Time Tracker") that are different from relative variable name (temp and onLineTimeCounter). To do so, you must set translations [uploading a translation file](/things5/device/manage-firmware/translations-file.md) in where you tell Things 5 how to show any variable name or variable value depending on user interface language preferences.\
\
Follow instructions in "[Variables translations](/things5/device/manage-firmware/translations-file.md)" guide's section.&#x20;