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

See previous version notes:

• 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

The review process is drawing to a close soon.  There are a few outstanding design issues to address and we still have a lot of documentation to port/rewrite.  But my goal is to update this site to the Haystack 4 version in the next few months.

Please review the changes and provide feedback. Remember the repo has been moved from BitBucket to GitHub if you want to review changesets in detail.

Changes 3 to 4

I've added a new chapter Changes3to4 which details all the key changes when upgrading from Haystack 3 to 4:

• tags which are renamed
• tags not ported yet
• tags we are not going to keep

Misc choices

We made several tag renames to be more specific so we can setup choices:

condensorLoop:  renamed openLoop, closedLoop to condenserOpenLoop, condenserClosedLoop.  This is a choice on chilled-water-plant.

plantLoop:  renamed primaryLoop, secondaryLoop to plantPrimaryLoop, plantSecondaryLoop.  This is a choice on pipe.  I believe there is also a need for plantTertiaryLoop - can I get feedback for a proper definition?

airVolumeAdjustability: renamed constantVolume, variableVolume to constantAirVolume, variableAirVolume.  This is choice on airHandlingEquip.

Filter vs FilterStr

We renamed filter to filterStr which was a subtype of string and represented a Haystack filter.  This frees up filter to be a marker with its original Haystack 3 definition.

Protos

Previously the children tag which specified prototypes was formatted as a string of Zinc lines.  This has been redesigned as a properly typed list of dicts.

Docs

We have ported the Zinc, Trio, Csv, and Json docs.  There is a few tweaks which have been discussed on the forum.

We also ported the Rest and Ops chapter.  We have renamed Rest chapter to HttpApi which is more accurate terminology.  I will make separate proposal regarding Ops.

ChangeLog

Version 3.9.8 (24 Mar 2020)

• New Changes3to4 chapter
• Port file type docs: Zinc, Json, Trio, Csv
• Port docs: Grid, HttpApi (was Rest), Ops, and Auth
• Zinc and JSON support for symbol literals
• Zinc support for optional commas in nested dict literals
• Trio support for nested lists
• Rename lib includes to depends
• Rework children to be lists of dicts instead of Zinc strings
• Rename filter to filterStr and add filter marker tag
• Add tags: co, diverting, volume
• Add choice airVolumeAdjustability - constantAirVolume, variableAirVolume
• Add choice plantLoop - plantPrimaryLoop, plantSecondaryLoop
• Rename openLoop/closedLoop to condenserOpenLoop/condenserClosedLoop as choice
• Add openEnum marker for geoState
• 609: Add humidifier equip and points
• 609: Add economizing ahu point
• 609: Add dessicantDehumidifier ahu point
• 705: Add active-energy, reactive-energy, apparent-energy
• 741: HttpApi incomplete data
• 749: Add pointGroup, zoneAirPoints as supertype for hvac-zone-space, thermostat
• 778: Add elec-demand

Curious on peoples thoughts:

If planning to rename elecHeat, does elecResistanceHeating make more sense? And/or adding heatPump as a heatingProcessType? Basically, would just like to be able to delineate that although the fuel used is the same (electricity), the process by which that is used to generate heat can be different. I know electric resistance heating is the colloquial term, so maybe trying to align with that.

For airVolumeAdjustability, can we also include the concept of stepped in some fashion? It would align with Flow Control Type. Also, what are thoughts on moving this to a property of a fan - and to that question, do we have the generic concept of a fan still in Haystack4? (I see fan-motor), but I think this is still describing a motor used for a fan, not the fan itself?

With respect to fans - I think these are generally the questions we would like to be able to answer:

• Fan Placement (blow through, draw through, parallel, series)
• Fan Application (supply, return, exhaust)
• Flow Control Type - as above

If planning to rename elecHeat, does elecResistanceHeating make more sense?

I think we should stick the "good" name for elecHeating since its not only a term of art, but something just about everyone readily understands (and matches the wikipedia article).

adding heatPump as a heatingProcessType?

I think this makes sense, but not sure heatPumpHeating is a very good name. We need a precise but less awkward term for the process itself used by a heat pump (which is really more like a refrigeration cycle). Should it be dxHeating to match up with dxCooling?

For airVolumeAdjustability, can we also include the concept of stepped in some fashion?

I'm assuming by this you mean something like a fan with slow and fast speeds? I think that makes sense. Can you offer a definition?

what are thoughts on moving this to a property of a fan

I personally think that makes sense to add this a choice on fan-motor.

generic concept of a fan still in Haystack4? (I see fan-motor)

From a controls perspective we decided to use fan-motor/pump-motor and damper-actuator/valve-actuator to describe the "equipment" itself. This is to distinguish from when those points are used at the point level.

Fan Placement (blow through, draw through, parallel, series)

This seems pretty easy to add and we don't have it today. But BEDES never has any actual definitions. Can you open a new post and propose the actual tag names and their definitions?

Fan Application (supply, return, exhaust)

This is already covered by the ductSection choice

I think we should stick the "good" name for elecHeating

I agree

Should it be dxHeating to match up with dxCooling?

I think this is an excellent idea and vote for dxHeating.

Thanks Cory for raising these ideas. These will be great improvements, and I look forward to the tag proposals. Feel free to reach out to me if you'd like any assistance formulating them in the Haystack 4 def format.

I think we should stick the "good" name for elecHeating

This works well when bringing in dxHeating, so am good with that.

I'm assuming by this you mean something like a fan with slow and fast speeds? I think that makes sense. Can you offer a definition?

Yeah - will look for a good definition and get back.

Should it be dxHeating to match up with dxCooling?

Great.

From a controls perspective we decided to use fan-motor/pump-motor and damper-actuator/valve-actuator to describe the "equipment" itself.

I see - ok thanks for the clarification. I know we are not at this point yet, but I think an interesting modeling exercise to consider is how do we look at a VFD -> driving a motor -> driving a fan. Is it something like a {vfd, equip} controls {motor, equip} drives {variableSpeed, fan, equip}. All of these things will have efficiencies that maybe we want to capture (I'm coming from the energy auditing world where we like to know these things). I guess maybe in Haystack we generally take the approach of modeling the thing where the control points land? The physical gets intertwined with the controllable?

Can you open a new post and propose the actual tag names and their definitions?

Can do.

This is already covered by the ductSection choice

Missed - thanks.

Hi Brian - wondering if there was ever consensus on using the state marker. For VFD docs previously there was a {run, cmd, point} and {run, sensor, point}. Right now when I look at the 4.0 pointProtos, I see {discharge, fan, run, state, point}. Is the expectation that you would use a {discharge, fan, run, state, point, cmd} and {discharge, fan, run, state, point, sensor}?

A few questions:

• Why add the discharge and fan markers at the point level?
• What does state provide differently?

If these are the expectations, could this make it into the Changes3to4 documentation? Thanks.

This works well when bringing in dxHeating, so am good with that.

Ok, I will add dxHeating for next version. Can someone help with a concise definition?

I guess maybe in Haystack we generally take the approach of modeling the thing where the control points land?

I would say the core philosophy for Haystack has about around tagging the point data and putting that into the context for sites, spaces, and equip since that is the most readily available data to extract from the BAS. But as the standard grows in scope and usage, certainly its good to examine how it can be successfully applied to models where the points may not be modeled at all. I think the whole area of VFDs and motors could use a deep dive for review and suggestions.

Hi Brian - wondering if there was ever consensus on using the state marker.

The genesis of the state tag was to try and unify the concepts of pointSubject and pointQuantity. For example we say air is the subject. Then temp or humidity are the quantities of that subject. Its not an exact parallel for control points, but the idea was that state is the subject and enable or run were the quantities.

I would say that is just a proposal and has not been fully vetted.

Is the expectation that you would use a {discharge, fan, run, state, point, cmd} and {discharge, fan, run, state, point, sensor}?

Yes. What I've been doing in the prototypes is just leaving off sensor or cmd unless only one is completely obvious. What happens in our own tools is that you default to sensor then can change it (versus picking one or the other from the prototypes list). So from a tooling and verbosity perspective I think not enumerating every possible combination is preferred. But you could make the case to explode the combinations more fully in the children prototypes.

Why add the discharge and fan markers at the point level?

Because this follows the conventions everybody does today and its very useful. For example if you have both a discharge and return fan in an AHU and decided to not model the ducts or fans as first class equip, then you can still easily distinguish between the two command points.

Years ago we decided that it doesn't make sense to force people to model a pump or fan as a first class equip, sometimes you just want to model it as a point. In Haystack 4 that gives you potentially four levels of detail:

1. AHU equip level {ahu equip}
2. Duct equip level {discharge duct equip}
3. Fan equip level {discharge fan motor equip}
4. Fan command point level {discharge fan cmd point}

But we allow you the flexibility to omit both or either of the levels 2 and 3. Hence you always have the fan and discharge tag on the point and we have the childrenFlatten mechanism in the prototype.

I will add dxHeating for next version. Can someone help with a concise definition?

I'll work on this, coordinate with Cory, and provide a definition. I've done a bit of thinking about this recently, and its connection to the heatPump equip.