DeviceHub Bulk Upload Tags
Estimated reading time: 9 minutes
Typically, in a large environment, data needs to be collected from hundreds of device registers. In this case, adding tags one by one is a daunting task. OT Link Platform DeviceHub makes that task easier with a bulk load option, which creates tags from an uploaded comma-separated-values (CSV) file. This attribute values in the CSV file can be derived from DeviceHub Devices and from register definitions supplied by PLC vendors.
Use the following information to complete the bulk-loading task:
For additional tag-management tasks, see DeviceHub Manage Tags.
Overview of DeviceHub Tag Bulk Loading
Prerequisite
A DeviceHub device must be configured for the specific device and driver, for example, Allen-Bradley Micrologix. See DeviceHub Add, Monitor, or Delete Device.
The goal of this bulk-loading operation is to add a large set of tags/registers to OT Link Platform, as illustrated in the following DeviceHub Tags list. To add just a single tag, see DeviceHub Add a Tag.
Download the Sample CSV File Template
OT Link Platform provides a template of the required fields.
- Go to DeviceHub > Tags.
- Click the at the right of the window.
- Select Upload CSV from the list.
-
Click Download Sample CSV.
Atag-template.csv
file downloads. - Populate the CSV File
Populate the CSV File
A row/record for each tag must be populated with attribute values, as described below. Refer to the PLC’s register definitions for details.
- Using the downloaded template, add a row for each tag to be added.
- Keep the header row as defined in the template:
deviceId | deviceName | driverName | registerName | tagName | description | valueType | address | dbNumber | pollinginterval | omaObjectId | omaInstanceId | omaResourceId | omaValueType |
Backward compatibility for previous CSV versions
If you are using a CSV file from a previous OT Link Platform version:
- Check the downloaded CSV template to verify that all columns are present in your CSV file. Additional columns may have been added or columns may have been renamed.
- The order of the attribute columns in the latest CSV template may be different from previous versions. The columns can be in any order.
Example of a Tag CSV File
deviceId | deviceName | driverName | registerName | tagName | description | valueType | address | dbNumber | pollinginterval | omaObjectId | omaInstanceId | omaResourceId | omaValueType |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0b55610e-d501-4b68-832c-ca392aa20faa | Siemens-S7-D1 | siemens_snap7 | C5:0.PRE | D1000 | bit | 10 | 1 | 1 | 3303 | 0 | 5700 | Boolean | |
Siemens-S7-D1 | siemens_snap7 | C5:0.PRE | D1001 | bit | 10 | 2 | 2 | 3303 | 1 | 5700 | Boolean |
Definition of Tag Attributes
- For OMA object and resource details, refer to the device vendor documentation, as well as this reference page: IPSO Object Reference Guide.
Tag Attribute Rules
- Either
deviceId
ordeviceName
can be omitted, but not both. One of these fields is required to find the corresponding device.- If a device identified by the
deviceId
is not found, the entire tag record is rejected. - If a device identified by the
deviceName
is not found, this is not an error and the tag record is added.
- If a device identified by the
- Attribute values are required unless noted as optional.
- If an optional value is null, it is ignored. This allows for the loading of register definitions for multiple device types from a single file.
- If the value is null and the device driver defines it as mandatory, the tag will not be imported.
- If an optional value is present in the CSV file, but it is not supported by the device driver, it is treated as an error and the tag will not be imported.
- Attribute columns in the CSV can be in any order.
Attribute Name | Data Type | Sample Value | Description | Notes |
---|---|---|---|---|
deviceId |
string |
"0b55610e-d501-4b68-832c-ca392aa20faa" |
ID of the device (optional) |
Click the pages icon next to the very long device ID in the DeviceHub device card to copy the device ID. If a device identified by the |
deviceName |
string |
"Siemens-S7-D01773" |
Name of the device (used if deviceId is not provided) |
Copy the user-defined name for the device from the DeviceHub device card. If a device identified by the |
driverName |
string |
"siemens_snap7" |
Driver name is for validating optional attributes against registration.json. This type should directly correspond to the name of the driver package. |
Click the pages icon next to the driver name in the Device card to copy the driver name. Using this mandatory driver name, along with the device name, enables a user to replicate the device with the same tags over multiple OT Link Platform systems. |
registerName |
string |
"C5:0.PRE" |
PLC register name or full PLC register address | This name is case sensitive. |
tagName |
string | "D1000" | Tag name that will be displayed in DeviceHub | Often this is a combination of the register and address |
description |
string |
Any text (optional) | An optional user-supplied description for each tag | |
omaObjectId |
integer |
3303 |
OMA Object ID (optional) |
The numeric ID for the OMA object. Example for a temperature sensor object: 3303 All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag. |
omaInstanceId |
integer |
0 |
OMA Instance ID (optional) |
All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag. |
omaResourceId |
integer |
5602 |
OMA Resource ID (optional) |
Example for the maximum measured value of a temperature sensor object: 5602 All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag. |
omaValueType |
string, one of:
|
"Boolean" |
OMA value type (optional) |
All four OMA values either must be present or all four must be empty. When OMA values are present, OMA binding is applied to the tag. |
valueType |
string |
"bit" |
Type of the register value | Examples: bit, word |
address |
integer |
10 |
Register address | Refer to the PLC vendor's guide for a list of valid addresses. |
dbNumber |
integer |
1 | Siemens dbNumber (optional) | This is a device-specific attribute. Refer to the PLC vendor's guide for a valid list. |
CSV Formatting and Escaping Rules
Because CSV format is not standardized, several different methods could be used for escaping special characters. And, depending on locality, a different value separator may be used. For example, in European countries, a semi-colon is widely used as a separator. The OT Link Platform CSV specification adheres to the rules used by Microsoft Excel, as listed below.
- Field separators can be comma ( , ), semicolon ( ; ), or tab ( \t ).
- Fields can have white spaces around them. This space is removed during processing.
- Fields can be escaped with double quotes ( “ ) or single quotes ( ‘ ). Leading or trailing white spaces inside the quotes are preserved.
- Any separator characters within a quoted field is treated as part of the field value.
- Any quotation character in a field value must be escaped with a backslash ( \ ) character.
- Fields are parsed based on their data type: string values are read “as is” and numeric values are parsed with a numeric parser.
- Empty fields are treated as null values.
Upload the CSV File into DeviceHub
- Go to DeviceHub > Tags.
- Click the at the upper right of the Tags window.
- Select Upload CSV.
- Select the file and click Upload.
Upon a successful upload, the tags will appear in the Tags window. If the details in the CSV file do not match the expected configuration, error messages will indicate the issues.