Setpoint Restructure

[connorjcantrell]

Problem

The current Setpoint class has a combination of "Targets" (e.g., Zone Air Temp Setpoint), "Thresholds" (e.g., Cooling Setpoint), and "Parameters" (e.g., Deadband Setpoint).

Issues:

• "Offset" Ambiguity #668
• Clarification Needed on Effective/ Actual Setpoints #669

Solution

Restructure classes to clearly represent the semantic differences between these fundamental concepts:

1. Redefine Setpoint to represent only "Target" setpoints:

   The desired or target value for an essential variable, or process value (PV) of a control system which may differ from the actual measured value of the variable.

2. Introduce a new Threshold class for concepts initiating actions when a process value crosses a limit:

   • Examples: Cooling, Heating, Humidification, Lockout, Enable, etc.

3. Create two Threshold subclasses:

   • Upper Threshold: A specified value that, when exceeded by the process value, initiates an action. (e.g. Cooling, Dehumidification)
   • Lower Threshold: A specified value that, when the process value falls below it, initiates an action. (e.g. Heating, Humidification)

4. Move (and rename) several Setpoints to Parameter:

   • Deadband Setpoint: Represents the distance between two thresholds, typically between heating and cooling "thresholds".
   • Time setpoint: Specifies durations or intervals for various control actions.

This separation clarifies the distinct concepts and improves class organization.

Proposed Class Reorganization (Draft)

Reclassified as Parameters

• Deadband Setpoint → Deadband
• Time Setpoint → Time Parameter

Reclassified as Thresholds

• Cooling Setpoint → Cooling Threshold
• Heating Setpoint → Heating Threshold
• Reset Setpoint → Reset Threshold
• Lockout Setpoint → Lockout Threshold

Deprecated Classes

• Max_Air_Temperature_Setpoint
• Max_Water_Temperature_Setpoint
• Min_Air_Temperature_Setpoint
• Min_Water_Temperature_Setpoint
• Load_Setpoint
• Outside_Air_Temperature_Setpoint

New Additions

Setpoint:

• Position_Setpoint
• Valve_Position_Setpoint

Threshold:

• Dehumidification_Threshold
• Humidification_Threshold
• Lockout_Threshold

Under Consideration

Potential reclassification as Parameters:

• Demand Setpoint
• Voltage Ratio Setpoint
• Current Ratio Setpoint

Open Discussion Topics

• Discuss the naming convention for threshold. We want to encourage "an action" for threshold.

[epaulson]

When this goes in it needs to be accompanied with a new chapter in docs.brickschema.org

[wroantree]

@connorjcantrell, excellent suggestion. A few considerations I might add:

Deadband can be ambiguous so it needs to be very clearly defined. As an example, if you have a 2 degree deadband, some people interpret that as 2 degrees either side of the setpoint while others interpret it as 1 degree either side of the setpoint. Also, not all deadbands are centered around the setpoint. As an example, you might have a total deadband of 2 degrees, with 1.5 degrees above the setpoint and 0.5 degrees below the setpoint. I would personally define that as a 2 degree deadband with +0.5 degree offset.

Airflow thresholds, particularly for terminal boxes with reheat, can be tricky. The box will have a minimum airflow threshold below which the active airflow setpoint can not be reset. Cooling only boxes will have a single maximum airflow threshold above which the active airflow setpoint can not be reset. But terminal boxes with reheat can have, but don't always have, a cooling maximum airflow threshold and a heating maximum airflow threshold, like what's shown in this diagram:

My apologies for forgetting, but how were you planning on differentiating "active" setpoints from "target" setpoints. To clarify, if a terminal box has a zone air temperature setpoint of 72 degrees F, I would call that the target setpoint, and if that box also has a 4 degree deadband and is in heating, it would be effectively controlling to 70 degrees F, which I would call the active setpoint.

[epaulson]

Annoyingly, at least with Ecobee, the term they use is '{heat|cool} differential temperature'. https://support.ecobee.com/s/articles/Threshold-settings-for-ecobee-thermostats

[connorjcantrell]

Deadband

Deadband can be ambiguous so it needs to be very clearly defined

Thanks @wroantree, you're right about the potential ambiguity of deadband terminology. To avoid confusion, I agree we should adopt the interpretation that a 2-degree deadband means 2 degrees total, or 1 degree on either side of the setpoint.

For example, with a setpoint of 70°F and a 4-degree deadband:

• Cooling Threshold: 72°F
• Heating Threshold: 68°F

Offset

The term "offset" seems to have its own ambiguity issues. We should reconsider how we use it for setpoint-threshold differences. Many sources indicate "offset" typically describes the error between a process and target value, which differs from our current usage.

If we reserve "offset" for process-target value errors, what term should we use for the setpoint-threshold difference?

Offset: A sustained deviation between the control point and the setpoint of a proportional control system under stable operating conditions - source

source

All together now...

I have put together several scenarios that we might come across in practice. I am open to suggestions on how to model each scenario.

For these examples, I'm using the following terms (open to alternative suggestions):

Setpoint Offset: The deviation between a threshold and the setpoint.

Deadband Shift (replacing "Offset"): The displacement of the deadband's center from the setpoint. It indicates how much the deadband is shifted above or below the setpoint, rather than being equally distributed around it.

Deadband: The total range between two thresholds where no control action occurs. Calculated as the difference between the upper and lower thresholds. For example, with an upper threshold of 72 and a lower threshold of 68, the deadband would be 4 units.

Scenario A:

• Explicit Setpoint (72)
• Explicit Deadband (4)
• Implicit Setpoint Offsets (-2 and +2)
• Implicit Lower Threshold (70)
• Implicit Upper Threshold (74)
  

Scenario B:

• Explicit Setpoint (71)
• Explicit Setpoint Offsets (-1 and +3)
• Implicit Deadband (4)
• Implicit Lower Threshold (70)
• Implicit Upper Threshold (74)

  

Scenario C:

• Explicit Setpoint (71)
• Explicit Deadband Shift (+1)
• Implicit Setpoint Offsets (-1 and +3)
• Implicit Deadband (4)
• Implicit Lower Threshold (70)
• Implicit Upper Threshold (74)

  

Scenario D:

• Explicit Lower Threshold (70)
• Explicit Upper Threshold (74)
• Implicit Deadband (4)
• No Setpoint and therefore no Offsets
  

[SBlechmann]

Hey @connorjcantrell ,

I stumbled over some modelling issues regarding setpoints in the past as well, so thanks for your important suggestions!

I have one question and a remark:
Question: In scenario C, why are the "setpoint offsets" -1 and +3 if the deadband shift is -1? Should it not be -1 and +1 as setpoint offsets? Or am I missing something?
Remark: I have some troubles with the word "setpoint offset". As you mention, the term offset is used as a deviation from a setpoint - to me a deadband is not a deviation from a setpoint per se but more like a tolerance around a certain setpoint. What do you think the term "setpoint tolerance" instead?

Edit: One could also argue that there is no need to model the setpoint/tolerance at all. If the deadband is not equally distributed, one has to model using lower and upper thresholds.

[connorjcantrell]

In Scenario C, the "setpoint offsets" of -1 and +3 describe the position of the the lower and upper thresholds relative to the setpoint. The "deadband shift" of +1 (corrected from -1) indicates the deadband's center is 1 unit above the setpoint.

Definitions:

• Setpoint Offset (alternatively Setpoint Tolerance): Distance from setpoint to a threshold
• Deadband Shift: Position of deadband center relative to setpoint

One could also argue that there is no need to model the setpoint/tolerance at all. If the deadband is not equally distributed, one has to model using lower and upper thresholds.

I agree with this. Perhaps we can hold off on introducing this concept and wait to see if it is needed in the future.

We have two options:

1. Come to a conclusion on the class names to represent the concepts of:
   • Distance from setpoint to a threshold
   • Position of deadband center relative to setpoint
2. Avoid defining them altogether. This approach focuses on essential concepts (Setpoints, Thresholds, and Deadbands) without introducing additional complexity, and avoiding potentially confusing terminology.

I'm in favor of option 2.

Do you have any strong opinions on this @wroantree / @SBlechmann?

[wroantree]

We have two options:

1. Come to a conclusion on the class names to represent the concepts of:

   • Distance from setpoint to a threshold
   • Position of deadband center relative to setpoint

2. Avoid defining them altogether. This approach focuses on essential concepts (Setpoints, Thresholds, and Deadbands) without introducing additional complexity, and avoiding potentially confusing terminology.

I'm in favor of option 2.

Do you have any strong opinions on this @wroantree / @SBlechmann?

@connorjcantrell I am also in favor of option 2. I think the concepts will need to be defined eventually, but not necessarily right now. One quick point about which approach to take when they do get defined, I would suggest defining both as well as the translations between the two. The reality is that there's no standardized approach and I've seen both approaches in practice, so we should define both so that regardless of what points are discovered (setpoint, threshold, threshold or setpoint, deadband, and shift), the points can be accurately modeled and potentially translated to a "standard" approach, using virtual calculated points, if one is selected. Thoughts?

[KatieJMcGee]

I have been spending time on this at Switch as well, my findings align well with yours, here is a summary:

• 'Target Setpoint' and 'Threshold Setpoint' are reserved exclusively for points where the system actively maintains a value. These terms are reserved for controlled variables, indicating that the system adjusts to keep the value near (target) or above/below (threshold) setpoint. Other control variables (e.g., Outside Air Temperature Lockout) may be referred to as "setpoints" in traditional BMS terminology but will be categorized differently in this context.

  • This differs from your proposal only in that we still assign threshold as a 'setpoint' in some cases. The reason for this is they are still relevant for 'sensor deviating from setpoint' type analytics.

• The threshold class may add confusion unless the triggered action is clearly defined — I agree with your discussion point.

  • I even think upper and lower thresholds can be confusing. For example, compare:
    • EMW Mode Outside Air Temperature Upper Threshold (assumes the action is known)
    • EMW Mode Disable Outside Air Temperature Upper Threshold (unclear whether we disable once crossing the threshold or it is disabled within the threshold)
    • EMW Mode Disable Above Outside Air Temperature Threshold (clearly indicates expected operation)
  • Or similarly: Acceptable Below Zone Air CO2 Threshold Setpoint

• Offset/Deadband: I haven't gotten far with this concept, but I feel deadband is just a specific version (heating/cooling off) of a threshold band. It may be too specific to use generally across all classes. Although I understand it is a concept deeply embedded in the industry, there might be a more generalized concept using setpoint rise, fall, and total offset/delta or similar.

  • For example, if you have a stage 1 heating starting 2°F below setpoint and stopping 1°F above setpoint, 'deadband' is incorrect, but you could have:
    • Total Offset = 3°F
    • Rise Offset = 1°F
    • Fall Offset = 2°F

[SBlechmann]

@connorjcantrell I agree with option 2 as well. Thanks for clarifying.
So you'd like to go with Threshold, Deadband and Setpoint?

[connorjcantrell]

Hi @KatieJMcGee,

Regarding your comparison of "EMW Mode Disable Outside Air Temperature Upper Threshold" vs "EMW Mode Disable Above Outside Air Temperature Threshold":

Upper Threshold implies the action is initiated when the temperature is above the specified value. I have updated the definition of Upper and Lower Threshold for added clarity. Here's the improved definition:

Upper Threshold: A specified value that, when exceeded by the process value, initiates an action. (e.g. Cooling, Dehumidification)

Am I understanding your concern of upper/lower thresholds correctly?

there might be a more generalized concept using setpoint rise, fall, and total offset/delta or similar

I agree, the term offset is used in several contexts. There are several offsets that appear to require their own distinct name:

• Offset between PV and Setpoint (most common)
• Offset between Setpoint and Threshold (e.g., distance from "zone air temp setpoint" and "cooling threshold"
• Perhaps there are more? Feel free to add them here "Offset" Ambiguity #668

[connorjcantrell]

@wroantree @SBlechmann @KatieJMcGee

I've created a separate issue to address Offset Ambiguity: #668

Given the potential depth of this discussion, I believe it warrants its own dedicated thread. This will allow us to thoroughly explore the various contexts and definitions of "Offset" in our industry. More in particular, the offset between setpoint and threshold is related to the topic of deadband mentioned in this PR.

The resolution of this new issue has been added as a prerequisite for this PR. This ensures that we'll have clarity on offset-related terminology before proceeding with the changes proposed here.

Please continue any offset-related discussions in the new issue. This will help keep our conversations organized and focused.