Air-handling unit symbol
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.
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,standbyorfault;on,trueand1also 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,heatingValveandcoolingValve, in percent. Above 0, the coil fills with its color. Without a value, the coil stays gray. - Outdoor temperature and Supply temperature —
Timeseries,outdoorTempandsupplyTemp. 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,standbyorfaultin 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.