Skip to content


Technical documentation of the aedifion.controls framework.


In aedifion.controls, Controls Apps implement specific control algorithms. See section Algorithms for an introduction of available control algorithms. These apps are operated in the aedifion cloud platform and communicate with the Edge Device to transmit measurements and commands. Our Edge Devices are equipped with state-of-the-art algorithms that are able to detect problems such as communication failures and sensor failures immediately and return control of the building to the local automation system. As a safety measure, the Edge Device can immediately restore the state the local automation system had before the activation of the Controls App.


The signal flow is depicted in Figure 1. All commands coming from the aedifion cloud platform are MQTT or AMQP messages with a payload structured according to SWOP.
When a new Controls App is created in the framework, a configuration message is sent to the Edge Device. It contains the configurations such as fallback values that should be sent in cases of communication failure. During regular operation, Controls Apps send setpoint messages to the Edge Device, which contain the commands the Edge device writes to the field devices. In order to ensure a stable connection between Edge Device and Controls App, alive-messages are exchanged. If the time since the last alive-message exceeds a pre-configured threshold, the Edge Device automatically sends the fallback values that are stored in its database to the field devices.

Controller models
Figure 2: Signal flow

Safety features

As writing commands to an automation system must ensure the system's safe operation at all times, the following safety features are part of the .controls framework.

  • limit check: A Controls App always checks if the value of a command is within the pre-defined range and does not send any values outside this range.
  • priorities: In BACnet systems, the priority array allows overriding commands in cases of emergency. Each command sent using .controls is sent with a priority, per default the lowest available (16).
  • acknowledgments: To ensure that the automation system is always in a known state, the Edge Devices allow tracking if a command was successfully written to an automation device.
  • Alarms: Setting an alarm ensures that a user is notified immediately if a measurement exhibits unexpected behavior.

Communication protocol

Each MQTT or AMQP message that is published for sending a command to the automation system contains a value and a unique identifier of the datapoint to write. Moreover, it contains a priority that is used in BACnet systems. Refer to the detailed message description of the SWOP protocol.

Component models

aedifion.controls and make use of component models. The component models contain writable pins and read-only pins that are mapped to the data points belonging to a certain system or component in the automation system.

aedifion.controls library

The library contains many basic algorithms, forecasting modules and adaptors transforming the control commands. These ingredients can be combined and extended easily to create powerful applications for any HVAC optimization use case.

User-defined Controls Apps can initially be created as virtual data points. It is important to observe the convention of adding the suffix _controls-test-VDP to the name of the data point. Thus, the implementation of a control algorithm can be done under conditions as realistic as possible without influencing the real building. Instead, the values of this virtual datapoint can be validated before deploying the actual Controls App. The activation of a Controls App based on the implementation is done after request by aedifion staff. Likewise, more complex algorithms can be implemented upon request.

The following example shows the configuration for a Controls App that compares two measured values of a CO2 concentration with a limit value and generates a volume flow setpoint. In this example, the check would occur once per hour and a new value for the setpoint would be generated.

    "pins": {
        "P1": {
            "dataPointID": "co2_concentration_1",
            "data_range": { "time": "600s"},
            "aggregate": "mean",
            "trigger": "every_hour"
        "P2": {
            "dataPointID": "co2_concentration_2",
            "data_range": { "time": "600s"},
            "aggregate": "mean",
            "trigger": "every_hour"
    "parameters": {
        "formula": "mean=(P1+P2)/2;if(mean>800,1000,0);"

Communication with external applications

Applications deployed independent of the aedifion cloud platform can use the interfaces to send commands. Single commands to the building can be transmitted using the aedifion HTTP API, while continuously running applications should send commands via MQTT or Kafka messages according to InfluxDB Line Protocol. These are processed in the aedifion cloud platform and transmitted to the field, ensuring the security features described above.

Last update: 2023-04-23
Back to top