API section

Sensors and meters

The Sensors and meters module: refrigeration controllers, UPS units, energy meters, Zigbee sensors and PLCs over OPC UA (Modbus RTU/TCP, SNMP, Mercury, Zigbee, OPC UA). Latest values and alarms, polling on request, the log for a period and CSV for inspectors, writing setpoints and relays, SNMP traps. Devices are set up on the agent page (Sensors tab); needs the sensors module in the key (except the emulator).

Modbus RTU/TCP, SNMP, Mercury, Zigbee, OPC UA: values, log, alarms

POST	`/api/v1/sensors/{id}/poll`	Poll now
POST	`/api/v1/sensors/{id}/points/{point}`	Write a point value
GET	`/api/v1/sensors`	Devices and latest values
GET	`/api/v1/sensors/{id}`	A device and its values
GET	`/api/v1/sensors/traps`	Latest SNMP traps
GET	`/api/v1/sensors/profiles`	Device profiles
GET	`/api/v1/sensors/journal.csv`	Log for Excel and inspectors (CSV)
GET	`/api/v1/sensors/history`	Value log

Poll now#

POST/api/v1/sensors/{id}/poll

Without waiting for the interval; the answer is fresh values

Parameters

Name	In	Type	Description
`id`required	path	string

Response 200 application/json

Fields · DeviceView

deviceSensorDevice
22 fields · SensorDevice
- idstring
- namestring
- protocolstring
- profilestring
- portstring
- baudRateinteger int32
- paritystring
- stopBitsinteger int32
- hoststring
- tcpPortinteger int32
- modestring
- unitinteger int32
- communitystring
- snmpVersionstring
- passwordstring
- intervalSecinteger int32
- timeoutMsinteger int32
- alarmDelaySecinteger int32
- enabledboolean
- pointsarray of Point
  16 fields · Point
  - idstring
  - namestring
  - tablestring
  - addressinteger int32
  - typestring
  - wordOrderstring
  - bitinteger int32
  - scalenumber double
  - offsetnumber double
  - unitstring
  - writableboolean
  - minnumber double
  - maxnumber double
  - oidstring
  - paramstring
  - logboolean
- usernamestring
- numberinteger int32
profileNamestring
statusstring
errorstring
lastOkstring
lastPollstring
readingsarray of Reading
10 fields · Reading
- pointstring
- namestring
- valuenumber double
- textstring
- unitstring
- atstring
- alarmstring
- minnumber double
- maxnumber double
- writableboolean
alarmsinteger int32
zigbeeZigbeeView
4 fields · ZigbeeView
- statestring
- coordinatorstring
- permitJoinLeftinteger int32
- nodesarray of Node
  6 fields · Node
  - ieeestring
  - nwkinteger int32
  - manufacturerstring
  - modelstring
  - endpointsmap → array of integer int32
  - joinedAtstring
detailstring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/poll'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/poll' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Write a point value#

POST/api/v1/sensors/{id}/points/{point}

Only points with writable: true (a setpoint, a Zigbee relay on/off — 1/0). Without the module — 402 LICENSE_REQUIRED

Parameters

Name	In	Type	Description
`id`required	path	string
`point`required	path	string

Request body application/json required

Fields · WriteRequest

valuenumber double

JSON

{
  "value": 1.5
}

Response 200 application/json

Fields · Reading

pointstring
namestring
valuenumber double
textstring
unitstring
atstring
alarmstring
minnumber double
maxnumber double
writableboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/points/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11/points/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

Devices and latest values#

GET/api/v1/sensors

Each device: polling status, points with the latest value, alarms (alarm: high/low)

Response 200 application/json

Fields · SensorList

licensedboolean
devicesarray of DeviceView
10 fields · DeviceView
- deviceSensorDevice
  22 fields · SensorDevice
  - idstring
  - namestring
  - protocolstring
  - profilestring
  - portstring
  - baudRateinteger int32
  - paritystring
  - stopBitsinteger int32
  - hoststring
  - tcpPortinteger int32
  - modestring
  - unitinteger int32
  - communitystring
  - snmpVersionstring
  - passwordstring
  - intervalSecinteger int32
  - timeoutMsinteger int32
  - alarmDelaySecinteger int32
  - enabledboolean
  - pointsarray of Point
    16 fields · Point
    idstring
    namestring
    tablestring
    addressinteger int32
    typestring
    wordOrderstring
    bitinteger int32
    scalenumber double
    offsetnumber double
    unitstring
    writableboolean
    minnumber double
    maxnumber double
    oidstring
    paramstring
    logboolean
  - usernamestring
  - numberinteger int32
- profileNamestring
- statusstring
- errorstring
- lastOkstring
- lastPollstring
- readingsarray of Reading
  10 fields · Reading
  - pointstring
  - namestring
  - valuenumber double
  - textstring
  - unitstring
  - atstring
  - alarmstring
  - minnumber double
  - maxnumber double
  - writableboolean
- alarmsinteger int32
- zigbeeZigbeeView
  4 fields · ZigbeeView
  - statestring
  - coordinatorstring
  - permitJoinLeftinteger int32
  - nodesarray of Node
    6 fields · Node
    ieeestring
    nwkinteger int32
    manufacturerstring
    modelstring
    endpointsmap → array of integer int32
    joinedAtstring
- detailstring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

A device and its values#

GET/api/v1/sensors/{id}

Parameters

Name	In	Type	Description
`id`required	path	string

Response 200 application/json

Fields · DeviceView

deviceSensorDevice
22 fields · SensorDevice
- idstring
- namestring
- protocolstring
- profilestring
- portstring
- baudRateinteger int32
- paritystring
- stopBitsinteger int32
- hoststring
- tcpPortinteger int32
- modestring
- unitinteger int32
- communitystring
- snmpVersionstring
- passwordstring
- intervalSecinteger int32
- timeoutMsinteger int32
- alarmDelaySecinteger int32
- enabledboolean
- pointsarray of Point
  16 fields · Point
  - idstring
  - namestring
  - tablestring
  - addressinteger int32
  - typestring
  - wordOrderstring
  - bitinteger int32
  - scalenumber double
  - offsetnumber double
  - unitstring
  - writableboolean
  - minnumber double
  - maxnumber double
  - oidstring
  - paramstring
  - logboolean
- usernamestring
- numberinteger int32
profileNamestring
statusstring
errorstring
lastOkstring
lastPollstring
readingsarray of Reading
10 fields · Reading
- pointstring
- namestring
- valuenumber double
- textstring
- unitstring
- atstring
- alarmstring
- minnumber double
- maxnumber double
- writableboolean
alarmsinteger int32
zigbeeZigbeeView
4 fields · ZigbeeView
- statestring
- coordinatorstring
- permitJoinLeftinteger int32
- nodesarray of Node
  6 fields · Node
  - ieeestring
  - nwkinteger int32
  - manufacturerstring
  - modelstring
  - endpointsmap → array of integer int32
  - joinedAtstring
detailstring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Latest SNMP traps#

GET/api/v1/sensors/traps

Up to 50, newest first; reception is turned on by the trapPort setting

Response 200 application/json

Type: array of map → any value

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors/traps'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/traps' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Device profiles#

GET/api/v1/sensors/profiles

Built-in register and OID maps and own ones from data/sensors/profiles

Response 200 application/json

Array · SensorProfile

idstring
namestring
vendorstring
kindstring
protocolstring
baudRateinteger int32
paritystring
stopBitsinteger int32
unitinteger int32
notestring
pointsarray of Point
16 fields · Point
- idstring
- namestring
- tablestring
- addressinteger int32
- typestring
- wordOrderstring
- bitinteger int32
- scalenumber double
- offsetnumber double
- unitstring
- writableboolean
- minnumber double
- maxnumber double
- oidstring
- paramstring
- logboolean
customboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors/profiles'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/profiles' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Log for Excel and inspectors (CSV)#

GET/api/v1/sensors/journal.csv

Separator “;”, decimal comma; the current month by default

Parameters

Name	In	Type
`device`	query	string
`from`	query	string date
`to`	query	string date

Response 200

File.

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors/journal.csv'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/journal.csv' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Value log#

GET/api/v1/sensors/history

Point values every historySec and every alarm raised and cleared. Dates — yyyy-MM-dd, today by default

Parameters

Name	In	Type
`device`	query	string
`point`	query	string
`from`	query	string date
`to`	query	string date
`limit`	query	integer int32

Response 200 application/json

Array · HistoryRow

atstring
devicestring
pointstring
valuenumber double
unitstring
alarmstring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/sensors/history'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/sensors/history' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'