10. Code Generation

10.1. Introduction

This section describes the translation of control sequences expressed in CDL to a building automation system.

Translating the CDL library to a building automation system to make it available as part of a product line 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 that has been developed for a specific building will need to be done for each building project.

While translation from CDL to C code or to a Functional Mockup Unit is support by Modelica simulation environments, translation to legacy building automation product lines is more difficult as they typically do not allow executing custom C code. Moreover, a building operator typically needs a graphical operator interface, which would not be supported if one were to simply upload compiled C code to a building automation system.

Use of CDL control sequences for building operation, or use of such sequences in a verification test module, consists of the following steps:

  1. Implementation of the control sequence using CDL.

  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.

Fig. 10.1 shows the process of exporting and importing control sequences.

_images/codeExport.svg

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

The next section describes three different approaches that can be used by control vendors to translate CDL to their product line:

  1. Translation of the CDL-compliant sequence to a JSON intermediate format, which can be translated to the format used by the control platform (Section 10.3).

  2. Export of the whole CDL-compliant sequence using the FMI standard (Section 10.4), a standard for exchanging simulation models that can be simulated using a variety of open-source tools.

  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 10.5).

The best approach will depend on the control platform. While in the short-term, option 1) is likely preferred as it allows reusing existing control product lines, the long term vision is that control product lines would directly compile CDL using option 2) or 3). Before explaining these three approaches, we first discuss challenges of translation of CDL sequences to building automation systems, as well as their implications.

10.2. Challenges and Implications for Translation of Control Sequences from and to Building Control Product Lines

This section discusses challenges and implications for translating CDL-conforming control sequences to the programming languages used by building automation system.

First, we note that simply generating C code is not viable for such applications because building automation systems generally do not allow users to upload C code. Moreover, they also need to provide an interface for the building operator that allows editing the control parameters and control sequences.

Second, 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 (https://www.sedona-alliance.org/) 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.

10.3. 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 target building automation system, the simplified JSON representation is most suited.

As an illustrative example, consider the composite control block shown in Fig. 7.3 and reproduced in Fig. 10.2.

_images/CustomPWithLimiter1.svg

Fig. 10.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

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

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.Reals.MultiplyByParameter is an elementary CDL block (see Section 7.6). If it were a composite CDL block (see Section 7.12), 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.

The simplified JSON representation of a CDL sequence must be compliant with the corresponding JSON Schema. A JSON Schema describes the data format and file structure, lists the required or optional properties, and sets limitations on values such as patterns for strings or extrema for numbers.

The CDL Schema can be found at https://github.com/lbl-srg/modelica-json/blob/master/schema-cdl.json .

The program modelica-json automatically tests the JSON representation parsed from a CDL file against the schema right after it is generated.

The validation of an existing JSON representation of a CDL file against the schema can be done executing the command

node modelica-json/validation.js -f filename.json

Control providers can use the JSON Schema as a specification to develop a translator to a control product line. If JSON files are the starting point, then they should first validate the JSON files against the JSON Schema, as this ensures that the input files to the translator are valid.

10.4. 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 JavaScript converter, see https://github.com/tshort/openmodelica-javascript.

To implement control sequences, blocks from the CDL library (Section 7.6) 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 OpenModelica, Impact, OPTIMICA or Dymola can be used. For example, with OPTIMICA a control sequence can be exported using the Python commands

from pymodelica import compile_fmu
compile_fmu("Buildings.Controls.OBC.ASHRAE.G36.AHUs.SingleZone.VAV.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 https://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.

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

In 2019, a new standard called System Structure and Parameterization (SSP) was released (https://ssp-standard.org/). 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 available, see https://ssp-standard.org/tools/.

CDL-compliant control sequences could be exported to the SSP standard as shown in Fig. 10.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. 10.3 Translation of CDL to SSP.

In such a workflow, a control vendor would translate the elementary CDL blocks (Section 7.6) 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 10.3. 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.

10.6. 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.)

10.6.1. Substitutions that Give Identical Control Response

Consider the gain CDL.Reals.MultiplyByParameter 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.

10.6.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 [Mod23] 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.

10.6.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 10.6.2.