Connecting to devices
This section describes how to crete an equipment type, device type and design a protocol. Everything you need can be found in the Equipment and Device Type Management section of the main Dashboard.
Equipment Category
Navigate to Equipment category properties and see predefined categories. You can reuse one of them or create a new one by clicking Add Equipment Category and provide a unique name and optional description.
Equipment Type
Navigate to Equipment types properties and see predefined types. You can reuse one of them or create a new one by clicking Add Equipment Type. The same as with categories just provide a unique name, optional description and assign category for it.
Device Type
Navigate to Device model properties and protocols and see predefined device types.
To create a new device type click Add Device Type. Specify a unique name, optional description and assign equipment type.
Next step is to add a protocol.
Protocol Editor
The protocol defines the way to communicate with the device. It consists of the several sections.
General
Describes basic information like name, description, version, transport type. Transport type corresponds to the communication protocol type.
Commands
In this section you can define one or more commands that will be executed one by one on the target device. Command has request and response parts. In request, you define a list of request parameters that will be used during command execution. In response, you define a list of output parameters that should be returned as a result of command execution.
Command type depends on the protocol type. Here are the supported values:
-
REST
-
get
-
post
-
put
-
multipart_upload
-
x-tar_upload
-
-
SNMP
-
read
-
read_table
-
Request Parameters
Command request parameters consist of a name, type and value. Name and type are predefined and expected to have next values:
| name (predefined) | type (predefined) | value (example) | value (predefined) |
|---|---|---|---|
url |
string |
/api/v1/discover |
N/A |
body |
json |
{"key": "value"} |
#{configuration.content} |
file |
string |
N/A |
#{firmware-update.file} |
The following placeholders will be resolved at runtime:
-
#{configuration.content} - placeholder for configuration file content (used in configuration update command)
-
#{firmware-update.file} - contains reference to firmware file (used in firmware update command)
| name (example) | type (predefined) | value (example) |
|---|---|---|
agentVersion |
OID |
.1.3.6.1.4.1.850.1.2.1.1.2.0 |
TODO: provide more details for snmp command types
Response Parameters
Using response parameters you can map a result of command execution.
Structure:
-
Expression - javascript expression that is used to transform raw data into an array of arrays i.e. "[[]]"
-
Output Key - TBD
-
Name - unique name
-
Alias - unique alias
-
Value - optional default value, will be populated from response
-
Formula - javascript expression applied to transform raw value
-
Data Type - string | integer | decimal | oid | boolean
-
UOM - unit of measure
-
Format - TBD
-
Length - TBD
Response parameters share a common execution context, so you can use a value from one response parameter in another by using placeholder with paramter alias e.g. #{sensorName}
Macros
A macro is a set of logically grouped commands designed to perform a specific operation. The application has a number of predefined macros that are expected in the protocol. Below is a list of the available macros:
-
DISCOVERY - discovery process
-
POLLING - polling process
-
GET_CONFIGURATION - configuration import
-
SET_CONFIGURATION - configuration update
-
GET_FIRMWARE_VERSION - firmware update
-
FIRMWARE_UPDATE - firmware update
Each macro can contain any number of commands. Commands will be executed according to the order in the list. You can change the order by using Promote or Denote buttons.
