Setpoints¶

Setpoints are immediate, one-shot, best-effort write operations to a single datapoint. They are requested with a NewSetpoint message and can optionally be acknowledged by the Edge Device with an AcknowledgeSetpoint message.

Setpoints are sent by the aedifion.io HTTP API, when a user writes a setpoint, and by Controls Apps.

An acknowledged setpoint has three states:

• requested - the issuer has sent the setpoint to the Edge Device. An unacknowledged setpoint remains in this state.
• written - the Edge Device has acknowledged the successful write of this setpoint.
• failed - the Edge Device has acknowledged an error during the write of this setpoint, or the write operation has already failed on the issuer side.

NewSetpoint¶

The NewSetpoint message NEWSPT contains all information required to write a setpoint.

Fields¶

Table 1: Fields of the NewSetpoint NEWSPT message.

Explanation¶

• The field datapoint references the datapoint on the building automation network to write to.
• The field value contains the value that should be written to the given datapoint. The type of the value must be consistent with the type of the target datapoint or allow a loss-free conversion. E.g., converting the integer 10 to the float 10.0 is loss-free, while rounding the float 10.3 to the integer 10 is not. If the value cannot be converted without information loss, the write operation is aborted and an error is returned.
  • The special string value "null" instructs the Edge Device to clear this setpoint so that the local control takes over again. In BACnet, this writes null to the datapoint's priority array at the position specified by priority.
• The field priority contains the priority at which the value should be written. For automation protocols that support priorities, such as BACnet (priorities 1 to 16), this field is optional but highly recommended. The priority has no effect if the building automation network is not BACnet or the datapoint has no priority array.
• The field acknowledge specifies whether the issuer expects an AcknowledgeSetpoint message for this write operation.
• With the field dry_run, the issuer can request that the write operation is only tested and nothing is written to the target datapoint. The extent of the test depends on the capabilities of the underlying automation network.
• The field reference identifies this operation. It must be provided if acknowledge is true, and the corresponding ACKSPT message repeats it.
• The field keep_out_of_service only applies to BACnet datapoints that are not commandable and must be set out of service to be written. By default, the Edge Device sets outOfService back to false after writing. If keep_out_of_service is true, the datapoint is left out of service.

Source¶

The optional object source describes the sender of a setpoint.

Table 2: Fields of the source object.

Examples¶

{
  "type": "NEWSPT",
  "swop_version": "0.3",
  "datapoint": "bacnet93-4120-External-Room-Set-Temperature-RTs",
  "value": 20.3,
  "priority": 13
}

Example 1: A minimal NEWSPT message without acknowledgement.

{
  "type": "NEWSPT",
  "swop_version": "0.3",
  "datapoint": "bacnet93-4120-External-Room-Set-Temperature-RTs",
  "value": 22.3,
  "priority": 9,
  "acknowledge": true,
  "dry_run": true,
  "reference": "80b8127d-757c-417d-a8bf-fa9980dc20de",
  "keep_out_of_service": false,
  "source": {
    "type": "api",
    "id": "42"
  }
}

Example 2: A NEWSPT message from the HTTP API requesting an acknowledged dry run.

{
  "type": "NEWSPT",
  "swop_version": "0.3",
  "datapoint": "bacnet93-4120-External-Room-Set-Temperature-RTs",
  "value": "null",
  "priority": 13
}

Example 3: A NEWSPT message clearing the setpoint at priority 13.

AcknowledgeSetpoint¶

The AcknowledgeSetpoint message ACKSPT reports the success or failure of a setpoint write operation from the Edge Device to the issuer. It is only sent if the NEWSPT message requested it via acknowledge.

Fields¶

Table 3: Fields of the AcknowledgeSetpoint ACKSPT message.

Explanation¶

• The field reference repeats the reference of the NEWSPT message that is acknowledged.
• The field status indicates whether the setpoint has been written (written) or not (failed). A successful dry run is acknowledged as written.
• The field message contains a human readable message, e.g., the reason for a failure. It can be appended to the log of the setpoint operation.
• The field detail is a JSON object with additional details. For BACnet datapoints, it contains the state of the datapoint before the setpoint was written in state_before.

Examples¶

{
  "type": "ACKSPT",
  "swop_version": "0.3",
  "reference": "f2d70718-fe44-46bd-a3e0-8c4008749851",
  "status": "failed",
  "message": "Value neither one of ['null'] nor parse-able as float: 15,3"
}

Example 4: An ACKSPT message reporting an invalid value.

{
  "type": "ACKSPT",
  "swop_version": "0.3",
  "reference": "f2d70718-fe44-46bd-a3e0-8c4008749851",
  "status": "written",
  "message": "Setpoint is active",
  "detail": {
    "state_before": {
      "presentValue": 16.4,
      "outOfService": false,
      "priorityArray": [
        "null", "null", "null", "null", "null", "null", "null", "null",
        "null", "null", "null", "null", "null", 16.4, "null", "null"
      ]
    }
  },
  "source": {
    "type": "multilogger",
    "id": "edge_device_123"
  }
}

Example 5: An ACKSPT message reporting a successful write to a BACnet datapoint, including its state before writing.

Write setpoint flow¶

The flow for writing a single setpoint proceeds as follows (square brackets mark optional steps):

1. A user writes a setpoint via the HTTP API, or a Controls App computes a new setpoint. This is the issuer.
2. The issuer validates the request, e.g., against the allowed value range and priority, and creates internal state for this operation with status requested.
3. The issuer sends a NEWSPT message to the Edge Device.
4. The Edge Device validates the NEWSPT message and writes the setpoint, or only tests the write if dry_run is true.
5. [If acknowledge is true, the Edge Device reports success or failure in an ACKSPT message.]
6. [The issuer receives the ACKSPT message and updates the state of the operation to written or failed.]

If the Edge Device does not know the requested datapoint, it replies with an ACKSPT message with status failed, as long as the NEWSPT message requested an acknowledgement.

Lost messages¶

NEWSPT and ACKSPT messages can be lost in transit, e.g., when the Edge Device is temporarily offline. SWOP does not retry messages automatically, and the Edge Device does not detect duplicates. If an acknowledged setpoint receives no ACKSPT, it remains in the state requested on the issuer side. It is up to the issuer to decide whether to send the setpoint again or to abort the operation.