Connecting to devices
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.