point as a setpoint, soft point, or process control variable.
Points are typically a digital or analog sensor or actuator entity (sometimes called hard points). Points can also represent a configuration value such as a setpoint or schedule log (sometimes called soft points). Point entities are tagged with the
All points are further classified as sensors, commands, or setpoints using one of the following three tags:
sensor: input, AI/BI, sensor
cmd: output, AO/BO, actuator, command
sp: setpoint, internal control variable, schedule
All points must be associated with a site via the
siteRef tag and a specific piece of equipment via the
equipRef tag. If a point doesn't have physical equipment relationship, then use a virtual equip entity to model a logical grouping.
By convention multiple tags are used to model the role of a point:
Here is an example of an AHU discharge air temperature input point:
id: @whitehouse.ahu3.dat dis: "White House AHU-3 DischargeAirTemp" point siteRef: @whitehouse equipRef: @whitehouse.ahu3 discharge air temp sensor kind: "Number" unit: "°F"
Points are classified as Bool, Number, or Str using the
- Bool: model digital points as true/false. Bool points may also define an
enumtag for the text to use for the true/false states
- Number: model analog ponts such as temperature or pressure. These points should also include the
unitto indicate the point's unit of measurement.
- Str: models an enumerated point with a mode such as "Off, Slow, Fast". Enumeraed points should also define an
The following tags may be used to define a minimum and/or maximum for the point:
When these tags are applied to a
sensor point, they model the range of values the sensor can read and report. Values outside of these range might indicate a fault condition in the sensor.
The term cur indicates synchronization of a point's current real-time value. By real-time we typically mean freshness within the order of of a few seconds. If a point supports a current or live real-time value then it should be tagged with
The following tags are used to model the current value and status:
curVal: current value of the point as Number, Bool, or Str
curStatus: ok, down, fault, disabled, or unknown
curErr: error message if curStatus indicated error
Writable points are points which model an output or setpoint and may be commanded. Writable points are modeled on the BACnet 16-level priority array with a relinquish default which effectively acts as level 17. Writable points which may be commanded by the pointWrite operation should be tagged with the
The following levels have special behavior:
- Level 1: highest priority reserved for emergency overrides
- Level 8: manual override with ability to set timer to expire back to auto
- Default: implicitly acts as level 17 for relinquish default
The priority array provides for contention resolution when many different control applications may be vying for control of a given point. Low level applications like scheduling typically control levels 14, 15, or 16. Then users can override at level 8. But a higher levels like 2 to 7 can be used to trump a user override (for example a demand response energy routine that requires higher priority).
The actual value to write is resolved by starting at level 1 and working down to relinquish default to find the first non-null value. It is possible for all levels to be null, in which case the overall write output is null (which in turn may be auto/null to another system). Anytime a null value is written to a priority level, we say that level has been set to auto or released (this allows the next highest level to take command of the output).
The following tags are used to model the writable state of a point:
writeVal: this is the current "winning" value of the priority array, or if this tag is missing then the winning value is null
writeLevel: number from 1 to 17 indicate the winning priority array level
writeStatus: status of the server's ability to write the last value to the output device: ok, disabled, down, fault.
writeErr: indicates the error message if writeStatus is error condition
If a point is historized this means that we have a time-series sampling of the point's value over a time range. Historized points are sometimes called logged or trended points. Historized points should be tagged with the
If a point implements the
his tag, then it should also implement these tags:
tz: all historized points must define this tag with their timezone name (must match the point's site timezone)
hisInterpolate: optionally defined to indicate whether the point is logged by interval of change-of-value
hisTotalized: optionally defined to indicate a point is collected an ongoing accumulated value
The current status of historization is modeled with: