1. Intro
  2. TagModel
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
  10. Trio
  11. Csv
  12. Rest
  13. Ops
  14. Auth
  15. VFDs
  16. Networks
  17. Energy
    1. Overview
    2. Meters
    3. Meter Loads
    4. Elec Meter
      1. Active, Reactive, Apparent
      2. Import, Export, Net
      3. Elec Meter Points
      4. Elec Meter Diagram
    5. Flow Meters
    6. Thermal Meters
    7. Example Model
  18. Zones
  19. AHUs
  20. VAVs
  21. UnitaryEquips
  22. Chillers
  23. Boilers
  24. Tanks
  25. ElecPanels
  26. Lighting
  27. Builds
  28. Bacnet
  29. ChangeLog
  30. License
Networks Zones



The general problems addressed by the energy tags are:


Meters are modeled as equip entities with the meter tag. The following meter types are defined:

All meters must additionally define one of these two tags:

Meter Loads

Modeling the equip and point loads under specific meters can be used for analysis and visualization. Loads are modeled by applying a tag formatted as "{type}MeterLoad" on an equip or point. The meter load tag should be Ref to its associated meter. If modeling submeters, then the load should reference the closest submeter. Standardized load tags:

Meter loads have the same types of points as their associated meters.

Elec Meter

Electricity meters are probably the most common type of meters modeled. They are tagged as elec meter. Haystack supports a model designed to scale from very simple meters (just a power and energy point) up to a comprehensive point list for three-phase power quality meters.

Electricity meter points are described by combining tags from the lists given below. The tags in each set are mutually exclusive. (For example, a power point cannot be both active and reactive.)

The primary measured quantities in an electical system are:

AC power measurements are further qualified by:

Voltage and current measurements are further qualified by:

Three phase electicrical measurements are qualified by:

Energy exchange with the utility is qualified by:

In addition we define the following general purpose tags:

Active, Reactive, Apparent

As the name suggests, the voltage and current in alternating current (AC) electricity networks alternate polarity many times per second. Because instantaneous power is the product of voltage times current, it constantly fluctuates in an AC network. Three quantities describe the time-averaged nature of fluctuating AC power:

If a power point does not have an active, reactive, or apparent tag, active power is assumed as the default.

Import, Export, Net

Some electric meters track and report power and energy imported from the electric grid separately from power and energy exported to the electric grid. The tags import and export differentiate these quantities. More broadly, import indicates power or energy flowing toward the grid (in the direction of the siteMeter) and export indicates power or energy flowing toward the load.

These measurements register power or energy transfer only in their associated direction and always have positive values.

The net tag indicates the difference between import and export:

net = import - export

Haystack uses the load convention for net electric power and energy.

If a power or energy point does not have an import, export, or net tag, it is assumed by default to be a net quantity.

Elec Meter Points

Common tag combinations for the points of a electric meter:





Power Factor


Elec Meter Diagram

The follow diagram illustrates these basic relationships with a site level electric meter and its power and energy points. A submeter is associated with a load under the main meter.


Flow Meters

Water and gas meters measure flow rate and total volume consumed. Standardized points are:

Thermal Meters

Thermal meters measure energy as temperature differentials. Energy demand and consumption is modeled using the same tags as electric meters:

Example Model

Let's take a simple example. Let's assume we want to model this "tree" of meters and loads:

Main Elec Meter
 +- LightsGroup (equip load)
     +- Lights-ZoneX (point load)
     +- Lights-ZoneY (point load)
 +- HVAC Elec Submeter
     +- RTU-1 (equip load)
         +- Fan (point load)
         +- DischargeTemp (not a load)
     +- RTU-2 (equip load)
         +- Fan (point load)
         +- DischargeTemp (not a load)

The entities and their tags would look like this:

id:@A, dis: "Main Elec Meter", elec, meter, siteMeter, equip
       dis: "Main Elec Meter Demand", equipRef @A, power, unit:"kW", sensor, point, ...
       dis: "Main Elec Meter Consumption", equipRef:@A, energy, unit:"kWh", sensor, point, ...

id:@B, dis: "Lights", equip, elecMeterLoad:@A, lightsGroup
       dis: "Lights ZoneX", equipRef:@B, elecMeterLoad:@A, lights, cmd, point, ...
       dis: "Lights ZoneY", equipRef:@B, elecMeterLoad:@A, lights, cmd, point, ...

id:@C, dis: "HVAC Elec Submeter", elec, meter, submeterOf:@A, equip
       dis: "HVAC Elec Submeter Demand", equipRef:@C, power, unit:"kW", sensor, point, ...
       dis: "HVAC Elec Submeter Consumption", equipRef:@C, energy, unit:"kWh", sensor, point, ...

id:@D, dis: "RTU-1", equip, elecMeterLoad:@C, ahu
       dis: "RTU-1 Fan", equipRef:@D, elecMeterLoad:@C, fan, cmd, point, ...
       dis: "RTU-1 DA Temp", equipRef:@D, discharge, temp, sensor, point, ...
id:@E, dis: "RTU-2", equip, elecMeterLoad:@C, ahu
       dis: "RTU-2 Fan", equipRef:@E, elecMeterLoad:@C, fan, cmd, point, ...
       dis: "RTU-2 DA Temp", equipRef:@E, discharge, temp, sensor, point, ...

In the example above we have a top-level main electrical meter with the id @A. Note it is tagged as elec meter to model an electric meter. It is also tagged as siteMeter to indicate its the main site-level meter. It has two associated points for power (kW) and energy (kWh).

Then under the main meter, we have a HVAC submeter with the id @C. Note it is tagged as elec meter but not siteMeter, instead it is associated as a submeter of the main meter using the submeterOf tag. You can model submeter trees of arbitrary depth (submeters of submeters). It also has two points for kW and kWh.

Lastly we have three electrical equipment loads defined. The two RTUs are associated with HVAC submeter via elecMeterLoad which references the HVAC submeter via id. Since we don't have a lighting submeter, the lighting load references the main meter directly via its elecMeterLoad tag. We also tag one or more points under the equipment which are meaningful for the load. Actuators would often be tagged as loads since they draw energy, but sensors would typically not be considered loads.

Networks Zones