#844 Haystack 4 Review - 3.9.9

Brian Frank Thu 23 Jul 2020

We have upgraded the project-haystack.dev with a new version.

See previous version notes:

  • 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

There are some significant enhancements/changes to note:

  • Brand new Examples section of website
  • Final design for flow relationships
  • Several new rewritten chapters from Haystack 3
  • Progress on lighting
  • New defs from AHU Standing WG


The new project-haystack.dev website has a new top-level Examples section.  This has been something I've wanted to add for a long time, and 3.9.9 implements the first pass of this new feature.

We have had three different users from the community donate anonymous datasets of a fully tagged real-world site.  The models include steam, hot water, and chilled water plants along with AHU, FCU, and VAV air systems (all 3 are mostly Energy/HVAC focused).  The sites are generically named using the phonetic alphabet.

You can browse these datasets on the website and link between all their ref relationships.  Plus you can download the entire site as a grid in any of the usual formats (Zinc, JSON, Trio, CSV, Turtle, etc).

I'm hoping that these public datasets will spur the following:

  1. Inspire others to donate their building models (just let us know!)
  2. Public review to determine if these are "good" reference models
  3. Analysis for where custom tags where used (which I have left in the datasets using a special custom tag) to see where Haystack is lacking. I did however strip obvious vendor specific tags which are not included in custom.
  4. Datasets you can download and use to test out code (Zinc parsers, ML naming algorithms, RDF tools, etc)
  5. The infrastructure here to display Haystack data in a browser with cross-referencing to defs/other entities is ideal for use when we are ready to add "equip/device templates"

Flow Relationships

This version contains all the changes proposed in topic 808 for flow relationships.  The fundamentals of the design are to model flow relationships using a tag named {what}Ref applied on the entity side which receives the flow and references where the flow originates from.  These tags replace all the existing flow relationships such as ahuRef, chilledWaterPlantRef, etc.

Here is a simple example using the new design:

id: @ahu, ahu, equip
id: @vav, vav, equip, airRef:@ahu

I struggled with writing the definitions of these tags and organizing them into the ontology using the terms "receives" and "supplies".  So I took the liberty of renaming these terms to inputs/outputs.  Entities which supply a substance are termed {what}-output such as air-output, chilled-water-output.  And entities which receive a substance are termed {what}-input such as air-input, chilled-water-input, etc.  

These new input/output conjuncts have been applied to the various equips and spaces. For example vav is now both an air-input and air-output; and hvac-zone-space is an air-input (to wire them together).  I did not get into the subtleties of the return air flow (so hvac-zone is not yet an air-output).

Also as part of this redesign, I removed the processUses tag and replaced it with the appropriate input conjunct.  For example hotWaterHeating by definition is now a hot-water-input.

The new terminology is just a strawman, and it should be discussed.  Input/output are more generic terms and seem to work better.  We've avoided those terms in the past due (potential) conflict with the terminology in I/O controllers:

New Chapters

Before we can switch the official website over to the Haystack 4 development version, we have to finish porting all the documentation.  For 3.9.9 I've rewritten several chapters to keep this moving along:

The Kinds chapter goes into a lot more detail about representation of the data types than was specified by Haystack 3.

Lighting WG #705

Based on work from the ANSI C137.6-20XX draft document, we have flushed out the Haystack 4 lighting model.  There is a new lightingZonePoints grouping as the "container" for common lighting points which is used by both luminaire and lighting-zone-space.  This is a design pattern we first used for HVAC points for both thermostat and hvac-zone-space to keep things DRY (it seems to be working well).  

The standard lighting points are now:

light level sensor point
light level sp point
light illuminance sensor point
light luminous flux sensor point

Included in the lighting changes is a new occupancy tag for sensor points which count the number of occupants.

There are still several items left to do in lighting:

  • color/chromaticity (I personally would like one string format that covers standard "CSS-like" color models such as RGB/HSL as well as those used by lighting technology)
  • scenes and presets (which may overlap with scheduling/HVAC modes)

AHU Standing WG #609

A few changes are in this build from meetings of WG 609:


Version 3.9.9 (23 Jul 2020)

  • Enhance enum value spec to allow list of dicts
  • Add plantTertiaryLoop tag
  • Add doas tag for Dedicated Outside Air System
  • Change mau to subtype from doas
  • Add economizer, ventilation ductSectionTypes
  • 808: Rename gasHeating, oilHeating to naturalGasHeating, fuelOilHeating
  • 808: New flow relationship tags: airRef, elecRef, chilledWaterRef, etc
  • Remove processUses in favor of xxx-input subtyping
  • Rename receives/supplies to inputs/outputs
  • Rename zoneAirPoints to hvacZonePoints
  • 705: Add lightingZonePoints
  • 705: Add occupancy sensor for number of occupants
  • New Intro chapter
  • New Kinds chapter
  • New Filetypes chapter
  • Add waterCooling as subtype of coolingProcessType

David Waterworth Sat 25 Jul 2020

The input/output taxonomy seems like you're moving towards a port based representation a bit like Simulink or Modelica? i.e. you have a relationship which is the connector between an output port on one block and an input on the next?

I find "Entity inputs air which flows from another entity" difficult to understand - if I "input" something I'm normally supplying not receiving it (i.e. I input my credit card number into a field or I provide input in a meeting). Maybe "Entity contains an air flow input from another entity"? (although personally I prefer supplies/recieves/discharges etc. - on the other hand an ahu can supply or discharge depending on whether it's single or multizone and whether you agree about the distinction between supply and discharge in the first place)

Cory Mosiman Thu 3 Sep 2020

Hey Brian - a few questions regarding how the usage is generated on the dev website. My understanding is that one should be able to resolve all tags necessary to convey a concept via a query of the following form:

SELECT ?m WHERE { <https://project-haystack.org/def/phIoT/3.9.9#heatPump> <http://www.w3.org/2000/01/rdf-schema#subClassOf>* ?m . ?m <https://project-haystack.org/def/ph/3.9.9#mandatory> <https://project-haystack.org/def/ph/3.9.9#marker> }

Based on the usage in the docs, this should always use the tags: {heatPump equip}, however, the above only resolves to returning an {equip}.

Am I missing something?

Brian Frank Thu 3 Sep 2020

Based on the usage in the docs, this should always use the tags: {heatPump equip}, however, the above only resolves to returning an {equip}.

You always have to the include the tags of the def itself (I don't think that subClassOf clause matches the def itself). But I do not have very deep experience in SparkQL

Cory Mosiman Thu 3 Sep 2020

So in the event the def is a conjunct (ac-elec-meter), the logic would be to:

  1. split the def on -
  2. add all those as tags (ac, elec, meter)
  3. run the above style query and add any tags which were not included in the def itself (equip)

to get to a final usage of: {ac elec meter equip}? That seems correct - thanks!

Login or Signup to reply.