Import variables: CSV file structure
The import function in the data source configurator is, together with the export function, built to easily and effortlessly copy variables from one device to another. Additionally, you can use the import function to prepare variables in a CSV file and load them all at once into your configurator.
This article explains the structure of the CSV file and the syntax of the corresponding settings. Despite the fact that every protocol is structured in it’s own way (i.e. Siemens S7 works with Data Blocks and OPC-UA doesn’t) a uniform file structure is applied for all protocols.
How to: export and import variables
View any of the protocol-specific guides about the actual steps of exporting and importing a CSV file.
CSV file structure
The structure of the CSV file needs to be correct for the import function to work properly. The headers (first row) of column 1-9 should look like this:
| Identifier | Name | Address | Type | Width | Signed | Max string length | Factor | Unit |
|---|
Each column represents a different setting and these are all explained below. Easily navigate to the desired section by pressing the corresponding header above.
Tip: an easy templateYou can quickly and easily create a template by first creating a single variable using X4 Remote interface and then exporting this variable to a CSV file, or download an empty template here:download_csv_l-blue.png.
Identifier
This variable ensures that every data source and variable in the your company remains unique, even when you give multiple variables the same name. An identifier only has to be unique for a certain data-source. Two different data-sources in the same company can have the same identifiers and can therefore import the same CSV-file.
Name
You can name the variables freely. It is advised to enter a very brief description of the variable (i.e. weight, temperature zone #1, emergency stop section B5).
Address
The address is protocol specific, since every protocol has it’s own structure, and is explained separately for the following protocols:
- OPC-UA
- Siemens
- Modbus TCP/IP
- BACnet/IP
- SMTP
- Digital input
OPC-UA
On X4 Remote you can enter your variable’s address, consisting of an identifier type, a namespace index, and an identifier. Both identifier types (string and numeric) require a different address when used in Cloud Logging and Alarming. The example table below shows how to list the addresses in the CSV file.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Identifier type | Namespace index | Identifier | Address |
| String | 2 | 20001 | ns=2;s=20001 |
| Numeric | 2 | 20001 | ns=2;i=20001 |
Namespace index? Identifier? Unsure about what your variable's namespace index or identifier is?
Have a look at our OPC-UA data source article.
Siemens
On X4 Remote you can enter your variable’s region (DB, I, M, or Q) and address. If you have selected DB as region, you will see an additional field named “Data block“. The example table below shows how to list the addresses in the CSV file.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Region | Data block | Address | Address |
| DB | 3 | 2.1 | 3.2.1 |
| I | 2.1 | I2.1 | |
| M | 2.1 | M2.1 | |
| Q | 2.1 | Q2.1 | |
Address?
Unsure about what your variable's address is or unable to find it? Have a look at our Siemens S7 data source article.
Modbus TCP/IP
On X4 Remote you can enter your variable’s function code (coils, discrete input, holding registers, or input registers) and address. The example table below shows how to list the addresses in the CSV file.
| Online (X4 remote) | Offline (CSV file) | |
|---|---|---|
| Function code | Address | Address |
| 1 – Coils | 1 | 1.1 |
| 2 – Discrete input | 1 | 2.1 |
| 3 – Holding registers | 1 | 3.1 |
| 4 – Input registers | 1 | 4.1 |
BACnet/IP
On X4 Remote you can enter the variable’s object type, instance, and a property. The object type and property also have a numeric identifier. For example, object type “analog_value” corresponds with numeric identifier “2”. These are determined by the BACnet/IP protocol itself, but can also have custom identifiers that are configured by the user. The example table below shows how to list the addresses in the CSV file.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Object type | Object identifier | Object property | Address |
| analog_value | 4 | present_value | 2.4.85 |
SMTP
On X4 Remote you can enter the data type, action, and keywords to determine which data from the original e-mail you’d like to pass on. The table below shows examples of all possible actions.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Data type | Action | Keywords | Address |
| String | Return e-mail subject | High | SMTP::Keyw:High Ptrn:Subject: |
| String | Return e-mail body | Medium | SMTP::Keyw:Medium |
| String | Search for text pattern: “Description” | Low | SMTP::Keyw:Low Ptrn:Description |
Digital input
On X4 Remote you can enter the data type and communication protocol. The example below shows how to list the x500’s digital input in the CSV file.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Type | Protocol | Type | Address |
| Boolean | GPIO | bool | GPIO:: |
Data type (type, width & signed)
In the CSV file a variable’s data type is divided into 3 separate settings:
- Type: bool, int, float, or string.
- Width: is required when the type is an int or float. Available widths are 8, 16, 32, and 64 bits.
- Signed: “TRUE” for data types that can be positive and negative (signed). “FALSE” for data types that can only be positive (unsigned).
This table explains the available data types and their corresponding notation in the CSV file.
| Online (X4 Remote) | Offline (CSV file) | ||
|---|---|---|---|
| Data type | Type | Width | Signed |
| BOOL | bool | ||
| SINT | int | 8 | TRUE |
| INT | int | 16 | TRUE |
| DINT | int | 32 | TRUE |
| LINT | int | 64 | TRUE |
| USINT | int | 8 | FALSE |
| UINT | int | 16 | FALSE |
| UDINT | int | 32 | FALSE |
| ULINT | int | 64 | FALSE |
| REAL | float | 32 | |
| LREAL | float | 64 | |
| STRING | str | ||
Max string length
A string data type requires its maximum amount of characters to be specified in the “Max string length” column. Leave this column empty when the data type is not a string.
Factor
You can multiply the value. This can be useful when you would like to measure grams in kilograms, for example. In this example you would set the factor to 0.001.
Unit
The unit of measurement (i.e. kg, liter, °C, bar) will be visible in dashboards to the right of each value.