Overview about Control Description Language and ASHRAE Standard 231P

This page contains an overview of, and links to further details about, the Control Description Langauge (CDL), its exchange format Control Exchange Format (CXF) and the proposed ASHRAE Standard 231P.

What is CDL?

ASHRAE Standard 231P defines a human-readable modeling language for control logic called Control Description Langauge (CDL) and a json-ld exchange format called Control Exchange Format (CXF) that is generated from CDL.

CDL was first conceived in 2018 (Wetter et al., 2018). It was subsequently expanded based on its use in the Modelica Buildings Library and based on discussions within ASHRAE Standard 231P Committee. CDL is now defined in the draft of ASHRAE Standard 231P. It is also explained at obc.lbl.gov/specification/cdl, which is the documentation that served as input to the ASHRAE Standard 231P development and is kept up to date as the draft 231P standard evolves.

Digitalized workflow for control delivery

To understand the proposed workflow of a digitized control delivery process, we recommend the overview paper “OpenBuildingControl: Digitizing the control delivery from building energy modeling to specification, implementation and formal verification”. This paper covers the process from sequence implementation to testing its correct operation and performance in whole building energy simulation, translation to a commercial control product line and testing of as-installed sequences relative to the original control specification.

How is CDL implemented?

CDL was designed as a small subset of Modelica to make it easy to use and to support by control providers.

Note that Buildings Automation Systems do not require a Modelica runtime environment to execute control logic that was translated from CDL.

However, for development and testing of new control logic, using a subset of Modelica has the advantage that it allows to use an ecosystem of open-source and commercial tools for authoring control sequences, and for testing the correctness and the performance of these sequences, such as their implications on energy use, peak power, load shifting and indoor air quality. This testing of the control logic is typically done with an HVAC and/or a whole building energy model in the loop. Using Modelica tools also allows generation of code, such as through the FMI Standard, the eFMI Standard, or through generation of C code for applications that prefer to use directly compiled code instead of a conventional Building Automation System. See the publications page for various illustrative applications.

A reference implementation of CDL is distributed with the Modelica Buildings Library. See the online documentation of the CDL implementation in the Modelica Buildings Library.

Control sequence repository

CDL has also been used to implement a variety of control sequences, both from ASHRAE Guideline 36 and from other sources. These are distributed with the Modelica Buildings Library and documented online at Buildings.Controls.OBC.

Interactive browsing, editing, simulating and inspecting control sequences

Control sequences, as well as HVAC systems and building or district energy models that are implemented in CDL and Modelica can be browsed, edited, simulated and inspected through a graphical Modelica modeling environment, such as OpenModelica’s OMEdit, Modelon’s IMPACT, or Dassault Systemes Dymola.

The Modelica Buildings Library with its CDL and control sequence repository can be installed through the corresponding package mangers of OpenModelica (OMEdit package manager) and IMPACT (IMPACT package manager). For Dymola, users can download the Modelica Building Library from simulationresearch.lbl.gov/modelica/download and load it into Dymola’s graphical environment.

A tutorial for how to implement a control sequence using CDL for a simple heating system can be access at Buildings.Examples.Tutorial.CDL.

Control selection and configuration

For mechanical designers that may not be familiar with modeling, a control selection and configuration tool called ctrl-flow is being developed. ctrl-flow can be accessed at ctrl-flow.lbl.gov. The content of ctrl-flow is served by the HVAC system templates of the Modelica Buildings Library, which can be viewed at Buildings.Templates and which implement the sequences of Buildings.Controls.OBC. ctrl-flow is exporting an English language specification of the configured control sequences, and work is ongoing to expand the range of sequences supported by ctrl-flow, and to add additional outputs, including point lists, a semantic model, engineering drawings and a Modelica model of the control sequence and the HVAC system. The Modelica model can then be used in performance analysis and in model-based verification of control sequences (as described in obc.lbl.gov/specification/verification.html). In addition, from the Modelica model, the aformentioned additional output such as the the CXF representation, the point lists, and the semantic model are generated.

Translation of CDL to other environments

Translation from CDL to controllers can be done in a variety of ways, and is explained in obc.lbl.gov/specification/codeGeneration. Most building control vendors are interested in translation via the CXF exchange format, but generation of C code, FMUs, which are self-contained computing units that conform to the FMI Standard or use of the eFMI Standard is also possible as these are supported by many Modelica tools, and CDL is a subset of Modelica, an open standard for modeling of engineered systems.

Translation from CDL to CXF can be done with the modelica-json translator, which is available at https://github.com/lbl-srg/modelica-json.

Further documentation

For further documentation, see the OpenBuildingControl specification at obc.lbl.gov/specification and the various papers at obc.lbl.gov/publications.