Controls apps¶

aedifion.controls Controls Apps run in the aedifion cloud platform and write their commands to the building automation system via the Edge Device. To keep the building in a safe state at all times, each Controls App registers itself on the Edge Device together with a set of reset values. Controls App and Edge Device exchange heartbeats, and the Edge Device writes the reset values as soon as the connection to the Controls App is lost.

The commands themselves are sent as regular setpoints. This page describes the additional messages for managing Controls Apps on the Edge Device.

UpsertControls¶

The UpsertControls message UPSRTCTRL creates a Controls App on the Edge Device or updates an existing one.

Fields¶

Table 1: Fields of the UpsertControls UPSRTCTRL message.

Reset values¶

Each entry of reset_values defines the value that is written to one datapoint when the Controls App is reset.

Table 2: Fields of a reset value.

Example¶

{
  "type": "UPSRTCTRL",
  "swop_version": "0.3",
  "controls_app_id": "cef8160a-0023-4c8a-b839-a1ec8e7ac0b0",
  "service_id": "flot_123",
  "reset_values": [
    {
      "fqdn": "bacnet93-4120-External-Room-Set-Temperature-RTs",
      "value": "null",
      "priority": 13,
      "out_of_service": false
    }
  ],
  "alive_timeout": 300,
  "reference": "2e770718-ccef-4539-ae1a-975a47cfd0a7"
}

Example 1: An UPSRTCTRL message that clears the Controls App's setpoint on reset.

ResetControls¶

The ResetControls message RESETCTRL instructs the Edge Device to write the reset values of a Controls App to the building automation system.

Table 3: Fields of the ResetControls RESETCTRL message.

{
  "type": "RESETCTRL",
  "swop_version": "0.3",
  "controls_app_id": "cef8160a-0023-4c8a-b839-a1ec8e7ac0b0",
  "reference": "1645775b-00ad-4dbd-ba5d-145fb8f60f15"
}

Example 2: A RESETCTRL message.

DeleteControls¶

The DeleteControls message DELCTRL deletes a Controls App from the Edge Device.

Table 4: Fields of the DeleteControls DELCTRL message.

{
  "type": "DELCTRL",
  "swop_version": "0.3",
  "controls_app_id": "cef8160a-0023-4c8a-b839-a1ec8e7ac0b0",
  "reference": "8d0c3f5e-3a43-4a5c-9a4e-2b1f0e6c7d21"
}

Example 3: A DELCTRL message.

Acknowledgements¶

The Edge Device acknowledges every UPSRTCTRL, RESETCTRL and DELCTRL message with an AcknowledgeUpsertControls (ACKUPSRTCTRL), AcknowledgeResetControls (ACKRESETCTRL) or AcknowledgeDeleteControls (ACKDELCTRL) message, respectively. All three share the same fields.

Table 5: Fields of the ACKUPSRTCTRL, ACKRESETCTRL and ACKDELCTRL messages.

Table 6: Status values of the acknowledgement messages.

{
  "type": "ACKUPSRTCTRL",
  "swop_version": "0.3",
  "controls_app_id": "cef8160a-0023-4c8a-b839-a1ec8e7ac0b0",
  "service_id": "edge_device_123",
  "status": "added",
  "time": "2026-07-22T07:15:45.121503+00:00",
  "message": "Successfully added the controls app context for controls app cef8160a-0023-4c8a-b839-a1ec8e7ac0b0.",
  "reference": "2e770718-ccef-4539-ae1a-975a47cfd0a7"
}

Example 4: An ACKUPSRTCTRL message acknowledging the creation of a Controls App.

{
  "type": "ACKDELCTRL",
  "swop_version": "0.3",
  "controls_app_id": "cef8160a-0023-4c8a-b839-a1ec8e7ac0b0",
  "service_id": "edge_device_123",
  "status": "failed",
  "time": "2026-07-22T07:24:29.692596+00:00",
  "message": "Error: Could not delete controls app cef8160a-0023-4c8a-b839-a1ec8e7ac0b0 because it is running. Please stop the controls app first and try again.",
  "reference": "8d0c3f5e-3a43-4a5c-9a4e-2b1f0e6c7d21"
}

Example 5: An ACKDELCTRL message rejecting the deletion of a running Controls App.

Alive¶

The Alive message ALIVE is a heartbeat that Controls App and Edge Device send to each other periodically to monitor their connectivity.

Table 7: Fields of the Alive ALIVE message.

{
  "type": "ALIVE",
  "swop_version": "0.3",
  "sender_id": "flot_123",
  "timestamp": 1658474210133333828
}

Example 6: An ALIVE message.

Flows¶

Upsert controls flow¶

1. When a Controls App is started, it sends an UPSRTCTRL message with its reset values to the Edge Device.
2. The Edge Device validates the message and stores the Controls App and its reset values. If the Controls App already exists, it is updated.
3. The Edge Device starts monitoring the ALIVE messages of the Controls App, see Alive flow.
4. The Edge Device replies with an ACKUPSRTCTRL message with status added, updated or failed.
5. The running Controls App sends its commands as NEWSPT messages according to the write setpoint flow.

Alive flow¶

Controls App and Edge Device both send ALIVE messages periodically, more often than the alive_timeout of the Controls App.

• Edge Device side: Each ALIVE message from a service restarts the timeout of all Controls Apps registered with that service_id. If no ALIVE message is received within alive_timeout, the Edge Device resets the Controls App as described in the reset controls flow, i.e., writes its reset values and sends an ACKRESETCTRL message.
• Controls App side: If no ALIVE message is received from the Edge Device within alive_timeout, the Controls App stops. Controls Apps with auto recovery enabled start again as soon as the Edge Device sends ALIVE messages again.

ALIVE messages that are too old when they arrive are ignored. Sender and receiver therefore need synchronized clocks.

Reset controls flow¶

1. When a Controls App is stopped, it sends a RESETCTRL message to the Edge Device.
2. The Edge Device writes all reset values of the Controls App to the building automation system as unacknowledged setpoints, using the given priority and out_of_service settings.
3. The Edge Device stops monitoring the ALIVE messages of the Controls App.
4. The Edge Device replies with an ACKRESETCTRL message with status reset. If the Controls App is not known on the Edge Device, the status is failed.

If the Controls App does not receive the ACKRESETCTRL message, it sends the RESETCTRL message again after a restart.

Delete controls flow¶

1. When a Controls App is deleted, it sends a DELCTRL message to the Edge Device.
2. The Edge Device deletes the Controls App and its reset values.
3. The Edge Device replies with an ACKDELCTRL message with status deleted.

A running Controls App cannot be deleted. It must be reset first, see reset controls flow. Otherwise, and if the Controls App is not known on the Edge Device, the status is failed.