#908 Haystack 4 Review - 3.9.10

Brian Frank Fri 23 Apr 2021

We have upgraded project-haystack.dev with a new version. There is a huge amount of new content to review in this latest version 3.9.10.

See previous version notes:

  • 3.9.9 topic 844
  • 3.9.8 topic 797
  • 3.9.7 topic 743
  • 3.9.6 topic 737
  • 3.9.5 topic 714
  • 3.9.4 topic 699
  • 3.9.3 topic 694
  • 3.9.2 topic 687

This is the final preview release we will run on project-haystack.dev!   Next week we will be updating this website to the latest Haystack 4 documentation.

If you have comments or feedback on this release, please open a new forum post for each topic to organize the conversation.


There are 16 new chapters added to the documentation to cover how the ontology is used to model entities. There are new chapters on horizontal entities like sites, spaces, and equip. And we've ported/rewritten many of the old chapters for vertical systems including Meters, AHUs, VAVs, and Plants.


The work from WG 792 to define a new JSON dialect code named Hayson has been integrated.  The JSON chapter reflects the new specification.  All the JSON downloads are now made available in the updated format.

Greenhouse Gases

This release incorporates the work from WG 776 to define several new gases related to global warming.  We also define new emission quantities for these greenhouse gases.

Air Quality

In addition to the greenhouse gases, we have flushed out many new air quality substances including:

  • ch2o: formaldehyde
  • nh3: ammonia
  • no2: nitrogen dioxide
  • o3: ozone
  • pm01: particulate matter 0.1

As part of the WG 776 proposal, we have tweaked how these terms are represented in the ontology.  They now subtype from gas (or in case of pmXXX tags from substance).  Then we pair these tags with concentration when modeling them as quantities.  This models the terminology more correctly and enables us to pair co2 with emission to distinguish between air quality measurements versus greenhouse emission measurements.


We have incorporated the work from WG 734 on aquifer thermal energy storage systems. See the new ATES chapter in docHaystack for an overview.


As part of the effort to double down on usage of children protos for point enumeration, we are now including the exploded protos in machine readable formats.   See the new Protos section in the Downloads page to download protos in any of the standard formats (Zinc, JSON, CSV, Turtle, etc).

Also as part of this effort, we have reviewed and expanded the children protos of many different equip types.  In cases where we didn't make a distinction between sensor/cmd or sensor/sp we have now made this explicit.  

State Tag

Previously we attempted to model all the points with a "subject" and a "quantity". This led to a situation with a new state tag to pair with tags like run or enable. However it was awkward and isn't really a viable design to use for all the different point types we need to model.  So have nuked the state tag.  See the Motors chapter for how to properly model run/enable command and status points.

VFD Modeling

As part of the review process we followed a similar philosophy with the drive tag which was previously paired with speed and freq to model VFD points.  In the last version vfd was defined a subtype of motor, which technically wasn't correct since a VFD is a peer component to the actual motor.  So now vfd is just a marker tag you put on a motor equip.  Then you also use the vfd marker in conjunction with speed or freq to model the command/status points.  See the Motors chapter for how it all turned out.


Previously we had started creating some subtypes of VAVs including a coolOnly-vav and fanPowered-vav.  But after some discussions, it seems better to handle VAVs more akin to AHUs where we flatten all the options out.  Those options still exist, but not as first class subtypes.  See the new VAVs chapter for details.  

We did introduce a new breaking change to rename vavMode to hvacMode so that it can be used in other situations such as on an AHU, thermostat, etc.

Dual Effective Setpoints

One the issues that came up is how to model thermostats which don't provide a true effective setpoint across all modes, but rather provide separate effective heating/cooling setpoints.  I have written some language up how this should work in the new Zones chapter by requiring an hvacMode point in that case.  It warrants a deeper review and maybe discussion.

Flow/Thermal Meters

After some discussions, there seems be interest in using the tags flow and thermal on meter equip based upon what points you expect.  Review the Flow Meter and Thermal Meter section in the new Meters chapter to see if you like the current design.

Meter Loads

I have written up meter load modeling using the new elecRef, steamRef, etc flow references.  I think many of us had an implicit idea that this is how it should work and we no longer should have tags such as elecMeterLoad.  In my mind these tags model the flow of electricity/fluid almost like a wiring diagram.  You insert meters, valves, loads, etc all together consistently this way.  But this might be contentious not separately modeling supply flow from meter flow.  So it probably warrants further discussion.


Based on the requirements of the ATES work, it made sense to revert plantPrimaryLoop and plantSecondaryLoop back to the original names from Haystack 3.  We made the definitions  a little more generic so they can be used in other situations beside just central plants.


Note that the weatherRef tag is now weatherStationRef for consistency.  We also added an enthalpy quantity and its associated weather point.


Version 3.9.10 (23 Apr 2021)

  • Rename weatherRef to weatherStationRef for consistency
  • Annotate equip which typically uses electricity as elec-input
  • Rename docSection to docAssociations
  • Change protocol to subtype from marker, not entity
  • Add nodoc, nosrc, deprecated
  • Generate children prototypes as RDF blank nodes
  • Update filters chapter for ref list handling
  • Exploded point types (attempt only)
  • Remove state and stateQuantity in favor of keeping run/enable on their own
  • Tweaks to how vfd is used, remove drive tag
  • Expand some of the sp/sensor cmd/sensor proto pairs
  • Add enthalpy tag, associated weather, duct, and zone points
  • Add protos grid files to the distribution
  • Add greenhouse gases into ontology from WG 776
  • Expand children: ducts, zones
  • Port min/max marker tags from Haystack 3
  • New alarm point; alarm sensor on motor, chiller, boiler
  • New air-velocity quantity
  • Rename vavMode to hvacMode, clarify use with dual effective setpoints
  • Other new tags: deadband, deviceRef, nh3, no2, o2, o3
  • Add heatingOnly as peer to coolingOnly, clarify usage in AHU
  • FumeHood children protos
  • Add enable cmd as plant level point
  • Add cool/heat enable cmd as ahu points
  • Revert plantPrimaryLoop/plantSecondaryLoop to primaryLoop/secondaryLoop
  • Rework VAVs to not use subtypes (more like AHUs)
  • Add ups equipment type
  • New Sites chapter
  • New Spaces chapter
  • New Equips chapter
  • New Points chapter
  • New Weather chapter
  • New Devices chapter
  • New Meters chapter
  • New AHUs chapter
  • New VAVs chapter
  • New Plants chapter
  • New Zones chapter
  • New Motors chapter
  • New ElecPanels chapter
  • New ATES chapter and tags from WG 734
  • New DataCenters chapter

Login or Signup to reply.