Lawrence Berkeley National Laboratory

Developing an open-source HVAC controls design tool 

The Department of Energy’s Lawrence Berkeley National Laboratory (Berkeley Lab) aims to tackle the most pressing global challenges in energy, environment, and health.

DEPT® worked with their team to design and develop ctrl-flow, a high-performance controls design tool that helps deploy energy-efficient control sequences for building HVAC systems.

Introducing ctrl-flow

Designing efficient controls for a complex HVAC system is a challenging task that requires expertise and specific knowledge. Highly specialized controls system designers are few and far between, which forces mechanical engineers to muddle their way through the process. 

ctrl-flow highly automates this process, making control system design more accessible and efficient to mechanical engineers. This free, open-source tool allows them to robustly design, specify, and deliver high-performance control sequences at a lower cost.

The overarching objective of ctrl-flow is to help improve energy efficiency. Even a few percentages of energy efficiency can improve large commercial buildings’ carbon footprints while saving money on operational costs. 

ctrl-flow generates a specification for the sequence of operations in a text document based on the mechanical engineer’s decisions. This document is based on the ASHRAE Guideline 36, a 300-page document. Using the mechanical engineer’s designs, ctrl-flow narrows it down to a fraction of that, saving the engineer time by avoiding manually editing the document. 

Designing for clarity 

Designing controls is inherently complex, so we needed to design the user interface simply. After conducting user research, we found that the lack of industry consensus for terminology confused users. To create clarity, we spelled out the full name of system types across the entire tool. 

During prototyping and research, we found that users would benefit from a short introduction to the usage and output of the tool.  Therefore, an onboarding tutorial was created to set users up for success. This ended up being a five-screen tutorial that familiarized users with the tool. 

Parsing the Modelica language 

ctrl-flow automated the design of HVAC systems by providing templates. These templates are defined in Modelica, a language for modeling cyber-physical systems that is particularly good for modeling complex systems. 

After they are defined in Modelica, they are converted to a serializable format developed by Berkeley Lab, Modelica-JSON. Modelica-JSON uses an abstract syntax tree representation (AST) of the full Modelica grammar.

To improve the responsiveness of the tool, we simplified Modelica JSON representation as much as possible, removing items that are important for simulation but not needed for ctrl-flow. The setup required supporting the dynamic behavior of the Modelica-JSON representation (e.g., if a ‘fan’ is selected, show ‘fan’ options). Anything we could ‘pre-solve’ before sending data to the interpreter was a win. 

The parser filtered out JSON items that were not needed for ctrl-flow, and it resolved features of Modelica like external references, dependency injection, and inheritance, taking many implicit behaviors and making them explicit.

Employing this strategy allowed us to represent all the various files, classes, functions, and their relations as a tree in a single file with a much simpler data type. The interpreter’s simplified format weighed around 4MB instead of the original 40MB.

Front end interpreting  

The front end then had to take the simplified JSON and determine what configuration options needed to be displayed based on system choices and configuration options.

Each object within the simplified JSON was considered a potential configuration option to be displayed to the user. The option had a set of child options that were either definitions (a fan, CO2 sensor, etc.) or nested options within the tree that could be displayed to the user. An option also had an object of modifications which were special rules that helped us determine if we needed to display, change a value, or replace an option to be displayed.

Because we had simplified the JSON to a tree structure, we had to keep track of where we started within the tree and what paths we were taking within the tree (user-selected options). This became the instance path we could use to access our modifications on each option.

By following the modification rules and understanding where we came from (system choice and configuration choices), we could display configuration options dynamically from the simplified JSON.

Anticipated future releases of the tool will include the following:

  • Support for a broad range of systems, including all systems in ASHRAE Guideline 36 
  • The ability to provide additional project information and then download more detailed documentation, including:
  • Points lists
  • Systems diagrams
  • The control logic for the specified sequence in the Control Description Language (CDL) as well as in the Control Exchange Format (CXF), which are both
  • undergoing a standardization process within ASHRAE Standard 231P
  • A Modelica model of the HVAC system selected that can be used with tools such as the Spawn of EnergyPlus.


This work was supported by the Assistant Secretary for Energy Efficiency and Renewable Energy, Office of Building Technologies of the U.S. Department of Energy, under Contract No. DE-AC02-05CH11231.


Discover more

Next Case

Yuga Labs