SWOP¶

The SWOP Writing Operation Protocol (SWOP) is defined by aedifion GmbH for writing setpoints to building automation equipment and receiving feedback. It is used for all write operations between the aedifion cloud platform and the Edge Device:

• The aedifion.io HTTP API sends setpoints written by users to the Edge Device.
• aedifion.controls Controls Apps register themselves on the Edge Device, send setpoints and exchange heartbeats with it.

SWOP is a stateful, message-based protocol: it defines messages of certain types and formats that are exchanged in a certain order, the so-called flows. The messages are transported via MQTT.

The protocol is described in two parts:

• Setpoints - writing single setpoints and acknowledging them.
• Controls apps - registering, resetting and deleting Controls Apps on the Edge Device and monitoring their connectivity.

General rules¶

• All messages must be JSON-formatted [RFC4627] using UTF-8 encoding [RFC3629].
• All datetimes must be formatted according to [RFC3339].
• Decimals are separated by points (not commas).
• Every message contains the fields type, which identifies the message, and swop_version, which specifies the SWOP version used by the sender.
• Messages with an unknown type are rejected.

Versioning¶

The current version of SWOP is 0.3. The field swop_version is a string of the form "<major>.<minor>". A receiver rejects messages whose major version is higher than its own, since later major versions of the protocol may not be backwards compatible.

Messages¶

SWOP defines the messages summarized in Table 1.

Table 1: SWOP messages.

Status values¶

Acknowledgement messages report the outcome of an operation in the field status. Table 2 lists the possible values.

Table 2: Status values.