Energomonitor CoAP Protocol¶

Note

This documentation contains preliminary information about technology in development. This information is subject to change, and software implemented according to this documentation should be tested with the final version of developed technology.

This is the documentation of the Energomonitor CoAP Protocol, which is used to communicate between CoAP-based Energomonitor devices and servers. The primary purpose of the protocol is to enable devices to send data they measure to a server which processes it.

Overview ¶

The Energomonitor CoAP Protocol is based on Constrained Application Protocol (CoAP), a specialized web transfer protocol for use with constrained nodes and constrained networks. The protocol uses CoAP over IPv4 and UDP. In the future, it may be extended to use IPv6 and/or DTLS.

Communication parties ¶

There are three parties in the communication:

Device

The device that performs measurements.

Provisioning server

A CoAP server which provides the device with configuration. This configuration includes the IP address of the data server.

Data server

A CoAP server which receives measured data, is notified about events, and optionally provides the device with current time.

Both the provisioning server and the data server use the standard CoAP port (5683).

Payload format ¶

All payloads are in JSON. All CoAP messages which have a payload must include the Content-Format option set to 50, which is the identifier corresponding to the application/json media type.

Versioning ¶

The protocol is not versioned. We plan to evolve it in a backward-compatible way.

In general, changes that add functionality (e.g. adding a new resource, request parameter, or object property) are considered compatible. Changes that change, rename, or delete existing functionality are considered incompatible.

Communication ¶

The overall communication flow is as follows:

The device boots, contacts the provisioning server on a well-known IP address (which is built into the device) and requests a configuration. This configuration includes the IP address of the data server.
The device performs measurements, periodically sends measured data to the data server, and notifies the data server about any events. The device also periodically re-requests the configuration from the provisioning server (which can lead to a change of the IP address of the data server). These configuration requests serve double duty as heartbeats.
Optionally, the device may contact the data server and request current time, which it can use to set its internal clock. Typically, the device will do this before it starts to perform measurements and then periodically.

Requesting configuration ¶

Note

The protocol for requesting configuration is currently under development. The prototype CoAP-based devices may end up having the configuration hard-coded.

Sending data ¶

The device sends data using a POST /data/{sn} request to the data server, where {sn} is the device’s serial number.

A payload is a JSON object conforming to the Energomonitor data format version 4. The object must not contain the ch, uniq and s properties and it must contain the o property. In other words, the data must come directly from the device (not from a device connected to it), and it must be encoded using DLMS/COSEM OBIS codes (not a proprietary Energomonitor scheme).

The server responds with one of the following responses without a payload:

2.04 Changed when the data is correctly received and processed
4.00 Bad Request when the serial number is invalid, the Content-Format option is missing, or the payload is missing or invalid
4.02 Bad Option when an option value is invalid
4.04 Not Found when the serial number is unknown
4.05 Unauthorized when the device is not authorized to send data to the server

Example request¶

{
  "f": 4,
  "t": 1526036941,
  "d": 9,
  "o": {
    "1-0:21.8.0": 22.82,
    "1-0:41.8.0": 93.49,
    "1-0:61.8.0": 18.2,
    "1-0:1.8.0": 90.99,
    "1-1:1.8.0": 84.93,
    "1-2:1.8.0": 7.81,
    "1-3:1.8.0": 14.81,
    "1-0:32.3.0": 47.43,
    "1-0:52.3.0": 53.43,
    "1-0:77.3.0": 34.7
  }
}

Sending events ¶

The device sends events using a POST /events/{sn} request to the data server, where {sn} is the device’s serial number.

A payload is a JSON object with the following properties:

Name	Type	Description
`timestamp`	`integer`	Time of the event as a Unix timestamp.
`event`	`string`	Event type (see below).

Currently the only defined event type is "POWER_CHANGE". This event is sent by devices powered by an external power source when the power level of any of the phases changes. Events of this type have the following additional properties:

Name	Type	Description
`phases`	`array`	A 3-element array of `boolean` values describing current power level of each phase. It can be either low (`false`) or high (`true`).

The server responds with one of the following responses without a payload:

2.04 Changed when the event is correctly received and processed
4.00 Bad Request when the serial number is invalid, the Content-Format option is missing, or the payload is missing or invalid
4.02 Bad Option when an option value is invalid
4.04 Not Found when the serial number is unknown
4.05 Unauthorized when the device is not authorized to send data to the server

Example request¶

{
  "timestamp": 1526036941,
  "event": "POWER_CHANGE",
  "phases": [true, true, false]
}

Requesting current time ¶

The device requests current time using a GET /clock request to the data server.

The server responds with 2.05 Content. A payload is a JSON object with the following properties:

Name	Type	Description
`time`	`integer`	Current time as a Unix timestamp.

Example response¶

{
  "time": 1526036941
}