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 and device type management

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 categories grid

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.

equipment types grid

Device Type

Navigate to Device model properties and protocols and see predefined device types.

device types grid

To create a new device type click Add Device Type. Specify a unique name, optional description and assign equipment type.

add device 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.

protocol editor overview

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

protocol command
protocol command request parameters

Request Parameters

Command request parameters consist of a name, type and value. Name and type are predefined and expected to have next values:

Table 1. REST Protocol
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)

Table 2. SNMP Protocol
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

protocol command 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.

protocol macro command order

Events

The Events section describes the supported events to be received from a device.

protocol events
  • Event Name - unique event name

  • Event Type - predefined event type

  • Pattern - an event template that is used to filter a specific event

  • Event Data - event data e.g. sensor identifier, sensor value, description