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.
Documentation
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.
Hayson
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:
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.
ATES
We have incorporated the work from WG 734 on aquifer thermal energy storage systems. See the new ATES chapter in docHaystack for an overview.
Protos
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.
VAVs
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.
Loops
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.
Weather
Note that the weatherRef tag is now weatherStationRef for consistency. We also added an enthalpy quantity and its associated weather point.
ChangeLog
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
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:
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.
Documentation
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.
Hayson
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:
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 withconcentrationwhen 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.ATES
We have incorporated the work from WG 734 on aquifer thermal energy storage systems. See the new ATES chapter in docHaystack for an overview.
Protos
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
statetag 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 thestatetag. 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
drivetag 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 nowvfdis just a marker tag you put on a motor equip. Then you also use thevfdmarker in conjunction withspeedorfreqto model the command/status points. See the Motors chapter for how it all turned out.VAVs
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
vavModeto 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.
Loops
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.
Weather
Note that the
weatherReftag is now weatherStationRef for consistency. We also added an enthalpy quantity and its associated weather point.ChangeLog
Version 3.9.10 (23 Apr 2021)