8. Code Generation

This section describes the development of a proof-of-concept translator from CDL to a building automation system. Translating the CDL library to a building automation system needs to be done only when the CDL library is updated, and hence only developers need to perform this step. However, translation of a CDL-conforming control sequence, as well as translation of verification tests, will need to be done for each building project.

8.1. Challenges and Implications for Translation of Control Sequences

This section discusses challenges and implications for translating CDL-conforming control sequences to executable code on a building automation system.

First, we note that the translation will for most, if not all, systems only be possible from CDL to a building automation system, but not vice versa. This is due to specific constructs that may exist in building automation systems but not in CDL. For example, if Sedona were the target platform, then translating from Sedona to CDL will not be possible because Sedona allows boolean variables to take on the values true, false and null, but CDL has no null value.

Second, we note that most building automation product lines are based on old computing technologies. One may argue that to meet future process requirements and user-friendliness, these may be updated in the near future. Relatively recent or new product lines include

While Sedona has been designed for 3rd party developers to add new functionality, the others seem rather closed. For example, detailed developer documentation that describes the following is difficult to find, or may not exist:

  • the language specification for implementation of block diagrams,
  • the model of computation, and
  • how to simulate open loop control responses and implement regression testing,

Sedona “is designed to make it easy to build smart, networked embedded devices” and Sedona attempts to create an “Open Source Ecosystem” (http://www.sedonadev.org/). Block diagrams can be developed with the free Sedona Application Editor (https://www.ccontrols.com/basautomation/sae.htm).

8.2. Use of Control Sequences or Verification Tests in Realtime Applications

Use of control sequences or verification tests in realtime applications, such as in a building automation system or in a verification test module, consists of the following steps:

  1. Implementation of the control sequence or verification test as a Modelica model.
  2. Export of the Modelica model as a Functional Mockup Unit for Model Exchange (FMU-ME) or as a JSON specification.
  3. Import of the FMU-ME in the runtime environment, or translation of the JSON specification to the language used by the building automation system.
_images/codeExport.svg

Fig. 8.1 Overview of the code export and import of control sequences and verification tests.

Fig. 8.1 shows the process of exporting and importing control sequences or verification tests.

We will now describe three different approaches that can be used by control vendors to translate CDL to their product line:

  1. Export of the whole CDL-compliant sequence to one FMU (Section 8.2.1),
  2. Translation of the CDL-compliant sequence to a JSON intermediate format, which can be translated to the format used by the control platform (Section 8.2.2), and
  3. Translation of the CDL-compliant sequence to an xml-based standard called System Structure and Parameterization (SSP), which is then used to parameterize, link and execute pre-compiled elementary CDL blocks (Section 8.2.3).

The best approach will depend on the control platform.

8.2.1. Export of a Control Sequence or a Verification Test using the FMI Standard

This section describes how to export a control sequence, or a verification test, using the FMI standard. In this workflow, the intermediate format that is used is FMI for model exchange, as it is an open standard, and because FMI can easily be integrated into tools for controls or verification using a variety of languages.

Note

Also possible, but outside of the scope of this project, is the translation of the control sequences to JavaScript, which could then be executed in a building automation system. For a Modelica to JavasScript converter, see https://github.com/tshort/openmodelica-javascript.

To implement control sequences, blocks from the CDL library (Section 7.4) can be used to compose sequences that conform to the CDL language specification described in Section 7. For verification tests, any Modelica block can be used. Next, to export the Modelica model, a Modelica tool such as JModelica, OpenModelica or Dymola can be used. For example, with JModelica a control sequence can be exported using the Python commands

from pymodelica import compile_fmu
compile_fmu("Buildings.Controls.OBC.ASHRAE.G36_PR1.AHUs.SingleZone.Economizers.Controller")

This will generate an FMU-ME. Finally, to import the FMU-ME in a runtime environment, various tools can be used, including:

See also http://fmi-standard.org/tools/ for other tools.

Note that directly compiling Modelica models to building automation systems also allows leveraging the ongoing EMPHYSIS project (2017-20, Euro 14M) that develops technologies for running dynamic models on electronic control units (ECU), micro controllers or other embedded systems. This may be attractive for FDD and some advanced control sequences.

8.2.2. Translation of a Control Sequence using a JSON Intermediate Format

Control companies that choose to not use C-code generation or the FMI standard to execute CDL-compliant control sequences can develop translators from CDL to their native language. To aid in this process, a CDL to JSON translator can be used. Such a translator is currently being developed at https://github.com/lbl-srg/modelica-json. This translator parses CDL-compliant control sequences to a JSON format. The parser generates the following output formats:

  1. A JSON representation of the control sequence,
  2. a simplified version of this JSON representation, and
  3. an html-formated documentation of the control sequence.

To translate CDL-compliant control sequences to the language that is used by the respective building automation system, the simplified JSON representation is most suited.

As an illustrative example, consider the composite control block shown in Fig. 8.2.

_images/CustomPWithLimiter1.svg

Fig. 8.2 Example of a composite control block that outputs \(y = \max( k \, e, \, y_{max})\) where \(k\) is a parameter.

In CDL, this would be specified as

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
block CustomPWithLimiter
  "Custom implementation of a P controller with variable output limiter"
  parameter Real k "Constant gain";
  CDL.Interfaces.RealInput yMax "Maximum value of output signal"
    annotation (Placement(transformation(extent={{-140,20},{-100,60}})));
  CDL.Interfaces.RealInput e "Control error"
    annotation (Placement(transformation(extent={{-140,-60},{-100,-20}})));
  CDL.Interfaces.RealOutput y "Control signal"
    annotation (Placement(transformation(extent={{100,-10},{120,10}})));
  CDL.Continuous.Gain gain(final k=k) "Constant gain"
    annotation (Placement(transformation(extent={{-60,-50},{-40,-30}})));
  CDL.Continuous.Min minValue "Outputs the minimum of its inputs"
    annotation (Placement(transformation(extent={{20,-10},{40,10}})));
equation
  connect(yMax, minValue.u1) annotation (
    Line(points={{-120,40},{-120,40},{-20,40},{-20, 6},{18,6}}, color={0,0,127}));
  connect(e, gain.u) annotation (
    Line(points={{-120,-40},{-92,-40},{-62,-40}}, color={0,0,127}));
  connect(gain.y, minValue.u2) annotation (
    Line(points={{-39,-40},{-20,-40},{-20,-6}, {18,-6}}, color={0,0,127}));
  connect(minValue.y, y) annotation (
     Line(points={{41,0},{110,0}}, color={0,0,127}));
  annotation (Documentation(info="<html>
<p>
Block that outputs <code>y = min(yMax, k*e)</code>,
where
<code>yMax</code> and <code>e</code> are real-valued input signals and
<code>k</code> is a parameter.
</p>
</html>"));
end CustomPWithLimiter;

This specification can be converted to JSON using the program modelica-json. Executing the command

node modelica-json/app.js -f CustomPWithLimiter.mo -o json-simplified

will produce a file called CustomPWithLimiter-simplified.json that looks as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
[
  {
    "modelicaFile": "CustomPWithLimiter.mo",
    "topClassName": "CustomPWithLimiter",
    "comment": "Custom implementation of a P controller with variable output limiter",
    "public": {
      "parameters": [
        {
          "className": "Real",
          "name": "k",
          "comment": "Constant gain",
          "annotation": {
            "dialog": {
              "tab": "General",
              "group": "Parameters"
            }
          }
        }
      ],
      "models": [
        {
          "className": "CDL.Interfaces.RealInput",
          "name": "yMax",
          "comment": "Maximum value of output signal"
        },
        {
          "className": "CDL.Interfaces.RealInput",
          "name": "e",
          "comment": "Control error"
        },
        {
          "className": "CDL.Interfaces.RealOutput",
          "name": "y",
          "comment": "Control signal"
        },
        {
          "className": "CDL.Continuous.Gain",
          "name": "gain",
          "comment": "Constant gain",
          "modifications": [
            {
              "name": "k",
              "value": "k",
              "isFinal": true
            }
          ]
        },
        {
          "className": "CDL.Continuous.Min",
          "name": "minValue",
          "comment": "Outputs the minimum of its inputs"
        }
      ]
    },
    "info": "<html>\n<p>\nBlock that outputs <code>y = min(yMax, k*e)</code>,\nwhere\n<code>yMax</code> and <code>e</code> are real-valued input signals and\n<code>k</code> is a parameter.\n</p>\n</html>",
    "connections": [
      [
        {
          "instance": "yMax"
        },
        {
          "instance": "minValue",
          "connector": "u1"
        }
      ],
      [
        {
          "instance": "e"
        },
        {
          "instance": "gain",
          "connector": "u"
        }
      ],
      [
        {
          "instance": "gain",
          "connector": "y"
        },
        {
          "instance": "minValue",
          "connector": "u2"
        }
      ],
      [
        {
          "instance": "minValue",
          "connector": "y"
        },
        {
          "instance": "y"
        }
      ]
    ]
  }
]

Note that the graphical annotations are not shown. The JSON representation can then be parsed and converted to another block-diagram language. Note that CDL.Continuous.Gain is an elementary CDL block (see Section 7.4). If it were a composite CDL block (see Section 7.9), it would be parsed recursively until only elementary CDL blocks are present in the JSON file. Various examples of CDL converted to JSON can be found at https://github.com/lbl-srg/modelica-json/tree/master/test/FromModelica.

Todo

Add a JSON-schema definition for the simplified JSON representation, see http://json-schema.org.

8.2.3. Modular Export of a Control Sequence using the FMI Standard for Control Blocks and using the SSP Standard for the Run-time Environment

In early 2018, a new standard called System Structure and Parameterization (SSP) will be released. The standard provides an xml scheme for the specification of FMU parameter values, their input and output connections, and their graphical layout. The SSP standard allows for transporting complex networks of FMUs between different platforms for simulation, hardware-in-the-loop and model-in-the-loop [KohlerHM+16]. Various tools that can simulate systems specified using the SSP standard are in development, with FMI composer (http://www.modelon.com/products/modelon-deployment-suite/fmi-composer/) from Modelon being commercially available.

CDL-compliant control sequences could be exported to the SSP standard as shown in Fig. 8.3.

skinparam componentStyle uml2

scale 450 width

  database "CDL library" as cdl_lib {
  }
  database "FMU repository" as fmu_lib {
  }

  cdl_lib -r-> fmu_lib: generate

  [CDL-compliant\nsequence]

  [JSON-simplified\nrepresentation]

  [CDL-compliant\nsequence] -r-> [JSON-simplified\nrepresentation] : translate

  [JSON-simplified\nrepresentation] -r-> [SSP-compliant\nspecification] : translate

  fmu_lib -> [FMI Composer] : uses

  [SSP-compliant\nspecification] -d-> [FMI Composer] : import

Fig. 8.3 Translation of CDL to SSP.

In such a workflow, a control vendor would translate the elementary CDL blocks (Section 7.4) to a repository of FMU-ME blocks. These blocks will then be used during operation. For each project, its CDL-compliant control sequence could be translated to the simplified JSON format, as described in Section 8.2.2. Using a template engine (similar as is used by modelica-json to translate the simplified JSON to html), the simplified JSON representation could then be converted to the xml syntax specified in the SSP standard. Finally, a tool such as the FMI Composer could import the SSP-compliant specification, and execute the control sequence using the elementary CDL block FMUs from the FMU repository.

Note

In this workflow, all key representations are based on standards: The CDL-specification uses a subset of the Modelica standard, the elementary CDL blocks are converted to the FMI standard, and finally the runtime environment uses the SSP standard.

8.3. Replacement of Elementary CDL Blocks during Translation

When translating CDL to a control product lines, a translator may want to conduct certain substitutions. Some of these substitutions can change the control response, which can cause the verification that checks whether the actual implementation conforms to the specification to fail.

This section therefore explains how certain substitutions can be performed in a way that allows formal verification to pass. (How verification tests will be conducted will be specified later in 2018, but essentially we will require that the control response from the actual control implementation is within a certain tolerance of the control response computed by the CDL specification, provided that both sequences receive the same input signals and use the same parameter values.)

8.3.1. Substitutions that Give Identical Control Response

Consider the gain CDL.Continuous.Gain used above. If a product line uses different names for the inputs, outputs and parameters, then they can be replaced.

Moreover, certain transformations that do not change the response of the block are permissible: For example, consider the PID controller in the CDL library. The implementation has a parameter for the time constant of the integrator block. If a control vendor requires the specification of an integrator gain rather than the integrator time constant, then such a parameter transformation can be done during the translation, as both implementations yield an identical response.

8.3.2. Substitutions that Change the Control Response

If a control vendor likes to use for example a different implementation of the anti-windup in a PID controller, then such a substitution will cause the verification to fail if the control responses differ between the CDL-compliant specification and the vendor’s implementation.

Therefore, if a customer requires the implemented control sequence to comply with the specification, then the workflow shall be such that the control provider provides an executable implementation of its controller, and the control provider shall ask the customer to replace in the control specification the PID controller from the CDL library with the PID controller provided by the control provider. Afterwards, verification can be conducted as usual.

Note

Such an executable implementation of a vendor’s PID controller can be made available by publishing the controller or by contributing the controller to the Modelica Buildings Library. The implementation of the control logic can be done either using other CDL blocks, which is the preferred approach, using the C language, or by providing a compiled library. See the Modelica Specification [Mod12] for implementation details if C code or compiled libraries are provided. If a compiled library is provided, then binaries shall be provided for Windows 32/64 bit, Linux 32/64 bit, and OS X 64 bit.

8.3.3. Adding Blocks that are not in the CDL Library

If a control vendor likes to use a block that is not in the CDL library, such as a block that uses machine learning to schedule optimal warm-up, then such an addition must be approved by the customer. If the customer requires the part of the control sequence that contains this block to be verified, then the block shall be made available as described in Section 8.3.2.