Skip to content

Cookie preferences

We use cookies for our own analytics, to see how our campaigns perform and, if you allow it, to load content from other services such as the Google site search. We never sell your data. Necessary cookies keep the site working and cannot be switched off. See our Cookie Policy for details and our Privacy Policy for how we handle personal data.

Security, load balancing and remembering your cookie choice.

Show us which pages people read, how they find the site and where they get stuck, so we can improve it (Google Analytics, Microsoft Clarity).

Show us which of our ad campaigns bring visitors to the site and remember the campaign or partner link you arrived from (Google Ads, LinkedIn, Meta, partner program). We do not use these cookies to build advertising profiles.

Load the site search from Google when you use it. Google sets its own cookies and shows ads in the search results.

© 2026 The ThingsBoard Authors

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

Rather run it yourself? Install on your own servers

Air-handling unit symbol

  • Widget
  • 42 installs
  • v1.0.0
  • Nov 17, 2026
  • MIT license
  • v4.2+

Show an air-handling unit on a SCADA dashboard: outdoor damper, filter, heating and cooling coils, and a supply fan that spins while it runs. Coils color with their valves, a dirty filter turns amber, a fault turns the casing red, and an offline unit stops spinning. Outdoor and supply temperatures sit at the edges. Switch off the filter or a coil and the drawing closes the gap, so one AHU symbol fits most HVAC units.

Widget Type
  • Control
Category
  • Controls

Who it’s for

The Air-handling unit symbol is for facility operators and building engineers who watch HVAC plant rooms on a ThingsBoard SCADA dashboard. They need to see at a glance whether an AHU is running, how fast its supply fan turns, whether it is heating or cooling the air, and when its filter needs changing. The question they would type is “is AHU-2 running and is its filter dirty?”

What it does

Take an AHU on a November morning that reports unitStatus = running, fanSpeed = 60, damperPosition = 38, heatingValve = 82, coolingValve = 0, filterDp = 266, outdoorTemp = 6.1 and supplyTemp = 18.3. The symbol shows AHU-2 with a green Running badge. Outdoor air enters at 6.1 °C through a damper with its blades tilted to 38%. The filter is amber with Filter 266 Pa, because 266 is above the default limit of 250. The heating coil is filled orange at Heating 82%, the cooling coil stays gray, the green fan spins at Fan 60%, and the air leaves at 18.3 °C.

  • Draws the AHU as one air line, left to right: outdoor damper, filter, heating coil, cooling coil and supply fan, with the outdoor and supply air temperatures at the edges.
  • Spins the fan while its speed is above 0, and colors it running, standby or fault with the same green, gray and red as the HP Pump station symbol.
  • Fills each coil with its own color as its valve opens, and tilts the damper blades with the damper position: flat when open, upright when closed.
  • Turns the filter amber when its pressure drop reaches the limit you set, so a dirty filter is visible before anyone opens a chart.
  • Tells apart three states that often look the same: a fault turns the casing red, an offline device dims the whole unit and stops the fan, and a unit that has never reported is drawn with a dashed casing and a No data badge.
  • Fits smaller units: switch off the filter, the heating coil or the cooling coil, and the remaining sections spread out with no gap.
  • Is a status picture, not a control. It does not start the unit, change a setpoint or move a damper, and it draws no return fan, exhaust damper or mixing section.

Requirements

A SCADA symbol reads one entity, so all the values have to arrive on the same device or asset, picked as the widget’s Target device. When the fan, the coils and the sensors report as separate devices, copy their values to one AHU device or asset with a calculated field or a rule chain first.

How to set up

Behavior

The Air-handling unit symbol has no data keys and no datasource. Like every SCADA symbol, it reads its values through the Behavior section of the widget settings. Pick the Target device once, and each behavior row says where its value comes from. Every row is prefilled with the key name below, so a device that sends these keys works without changes.

  • Status — Timeseries, unitStatus. Text: running, standby or fault; on, true and 1 also read as running. Optional: without it, the fan speed decides between Running and Standby, and a unit with neither value shows No data.
  • Online — Attribute, server scope, active. ThingsBoard sets this attribute itself when the device connects or goes silent. When it is false, the unit dims and the fan stops, so a unit whose data stopped coming does not look alive. Without a value the unit counts as online.
  • Fan speed — Timeseries, fanSpeed, in percent. The fan spins while it is above 0. Without a value the fan is drawn dashed and the label reads Fan –.
  • Damper — Timeseries, damperPosition, the outdoor air damper opening in percent. Without a value the blades sit halfway and the label reads Damper –.
  • Filter pressure drop — Timeseries, filterDp. Without a value the filter stays gray.
  • Heating valve and Cooling valve — Timeseries, heatingValve and coolingValve, in percent. Above 0, the coil fills with its color. Without a value, the coil stays gray.
  • Outdoor temperature and Supply temperature — Timeseries, outdoorTemp and supplyTemp. A missing one shows – at its edge.
  • On click — a widget action that does nothing by default. Set it to open a dashboard state or a popup with the unit details.

Properties

Three switches in the Properties section decide which sections the unit has, and one number decides when the filter counts as dirty.

  • Filter — on by default. Turn it off for a unit without a filter, and the Filter pressure drop row can stay unbound.
  • Limit under Filter — 250 by default, in the pressure units. At or above this pressure drop the filter turns amber. Set it to 0 to never mark the filter.
  • Heating coil — on by default. Turn it off for a unit that only cools.
  • Cooling coil — on by default. Turn it off for a unit that only heats or ventilates.

How to customize

  • To name the unit — edit Label, AHU-2 by default.
  • To show other units — set Temperature and Pressure under Units, °C and Pa by default.
  • To match your state colors — set Running, Standby and Fault under Colors: green, gray and red by default.
  • To change the coil colors — set Heating and Cooling under Colors, orange and blue by default.
  • To change the dirty filter color — set Dirty filter under Colors, amber by default.
  • To use a dark background — set the widget background to dark, then set Text and Lines under Colors to light ones.

Tips

  • Turn the controller’s own status codes into running, standby or fault in a rule chain or a calculated field before they reach the symbol, so the logic lives in one place.
  • Point On click at a dashboard state with the unit’s charts, so the operator goes from the picture to the history in one click.
  • Raise or lower Limit to the pressure drop your filter maker gives for a filter that needs changing. That value differs between filter classes.
  • For a plant with several units, place one symbol per AHU and give each its own Label and Target device.

Share Your Widget with the Community

Built a custom widget? Export it as a JSON from ThingsBoard and publish it to the IoT Hub through a simple 4-step wizard (Upload, Listing, Readme, Review & Submit). Share it with thousands of ThingsBoard developers worldwide and get featured in the catalog.