From 05fcd389109bb01dd0ca25ffa0aada7defd1d57b Mon Sep 17 00:00:00 2001 From: Adam Garnhart Date: Wed, 25 Mar 2026 08:47:01 -0600 Subject: [PATCH 1/2] Add Valve and Damper abstract base specs Introduce Valve and Damper as abstract Equip bases for non-actuated equipment. ValveActuator and DamperActuator become intersection types (Actuator & Valve, Actuator & Damper). Adds *thermostatic global marker for feature layering on valves. --- src/xeto/ph/entity.xeto | 5 +++++ src/xeto/ph/equip.xeto | 23 +++++++++++++++++++---- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/src/xeto/ph/entity.xeto b/src/xeto/ph/entity.xeto index 923ae09..755e918 100644 --- a/src/xeto/ph/entity.xeto +++ b/src/xeto/ph/entity.xeto @@ -1448,6 +1448,11 @@ PhEntity: Entity { // may provide an interface for setpoint control. *thermostat: Marker + // Self-actuated temperature regulation. Used as a feature marker on + // valves (e.g. thermostatic mixing valve) and other equipment where + // temperature drives the control action without an external actuator. + *thermostatic: Marker + // Three-phase AC electricity. Power is provided by three AC voltage // sources, each separated from the others by a 120-degree phase angle. // May have a 4-wire connection with a neutral (Wye) or a 3-wire connection diff --git a/src/xeto/ph/equip.xeto b/src/xeto/ph/equip.xeto index bcf531c..cb13d17 100644 --- a/src/xeto/ph/equip.xeto +++ b/src/xeto/ph/equip.xeto @@ -174,12 +174,19 @@ Crac: Fcu { crac } -// Actuator to regulate the flow of air. -DamperActuator: Actuator { +// Equipment to regulate the flow of air in ductwork. Dampers may be +// manually operated or automated via an actuator. Non-actuated dampers +// such as manual balancing dampers, backdraft dampers, and fire dampers +// use this spec directly. BAS-controlled dampers use DamperActuator. +Damper: Equip { damper ductSection: DuctSection? } +// Actuator to regulate the flow of air. +DamperActuator: Actuator & Damper { +} + // DC Electricity meter. // See [ph.doc::Meters] chapter. DcElecMeter: ElecMeter { @@ -481,13 +488,21 @@ Ups: Equip { ups } -// Actuator to regulate the flow of fluid. -ValveActuator: Actuator { +// Equipment to regulate the flow of fluid in piping. Valves may be +// manually operated, self-actuated, or automated via an actuator. +// Non-actuated valves such as manual isolation valves, check valves, +// pressure-reducing valves, and thermostatic mixing valves use this +// spec directly. BAS-controlled valves use ValveActuator. +Valve: Equip { valve pipeFluid: Fluid? pipeSection: PipeSection? } +// Actuator to regulate the flow of fluid. +ValveActuator: Actuator & Valve { +} + // Variable air volume terminal unit. VAV systems use a constant air // temperature with a variable air flow rate. See [ph.doc::VAVs] chapter. Vav: AirTerminalUnit { From c6b83f7c1ac9b2712a889dccfc880fcc61d1987f Mon Sep 17 00:00:00 2001 From: Adam Garnhart Date: Wed, 25 Mar 2026 08:48:13 -0600 Subject: [PATCH 2/2] Add valve and actuator enum types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 7 new Enum types for valve/actuator classification: ValveFunction (11 values), ValveBodyType, ValvePorts, ActuatorFailPosition, ActuatorDirection, ActuatorControlAction, ActuatorMechanism. Adds actuatorDirection slot on Actuator. ValveFunction scoped to piping role — pressureIndependent and thermostatic are feature markers, not function values. --- src/xeto/ph/enums.xeto | 69 ++++++++++++++++++++++++++++++++++++++++++ src/xeto/ph/equip.xeto | 1 + 2 files changed, 70 insertions(+) diff --git a/src/xeto/ph/enums.xeto b/src/xeto/ph/enums.xeto index 6a8069f..37c8652 100644 --- a/src/xeto/ph/enums.xeto +++ b/src/xeto/ph/enums.xeto @@ -4,6 +4,41 @@ // Auto-generated 17-Jan-2025 // +// Control behavior of an actuator. Determines whether the actuator +// positions continuously (modulating), snaps between discrete states +// (twoPosition), or is driven by raise/lower signals without position +// feedback (floating). +ActuatorControlAction: Enum { + modulating // continuous proportional positioning (0-100%) + twoPosition // discrete open/closed (binary) + floating // motor driven by raise/lower signals, no position feedback +} + +// Relationship between command signal direction and physical position. +// The Haystack convention is 0% = closed and 100% = open. The +// actuatorDirection tells tools when the raw BAS signal is inverted. +ActuatorDirection: Enum { + directActing // 0% signal = closed, 100% signal = open + reverseActing // 0% signal = open, 100% signal = closed +} + +// Position an actuator assumes on loss of control signal or power. +// Applies to both valve and damper actuators. +ActuatorFailPosition: Enum { + failOpen // actuator drives/springs to fully open + failClosed // actuator drives/springs to fully closed + failInPlace // actuator holds last position (no spring return) + failToPosition // actuator drives to a configurable intermediate position +} + +// Physical mechanism used by the actuator to produce motion. +ActuatorMechanism: Enum { + electricMotor // gear motor actuator (rotary or linear) + pneumatic // compressed air diaphragm or piston + hydraulic // hydraulic fluid piston + solenoid // electromagnetic coil (linear, typically on/off) +} + // Status of point's current value reading. The [ph::PhEntity.curVal] is only available // when curStatus is "ok" or "stale". However a "stale" value should // be used with caution since the local system does not have a fresh value. @@ -521,6 +556,40 @@ PrimaryFunction: Enum { zoo } +// Valve body construction type +ValveBodyType: Enum { + ball // quarter-turn spherical closure element + butterfly // quarter-turn rotating disc + gate // linear multi-turn wedge or knife + globe // linear rising-stem plug + needle // fine-adjustment variant of globe + plug // quarter-turn tapered or cylindrical plug +} + +// Functional role of a valve in a piping system. +// Features like pressureIndependent and thermostatic are layered +// as separate markers rather than enum values. +ValveFunction: Enum { + balancing // proportional flow balancing + bypass // diverts flow around equipment + check // prevents reverse flow (non-return) + control // modulating or two-position BAS control + diverting // splits one inlet to two outlets + expansion // thermal expansion relief + isolation // on/off service isolation + mixing // blends two inlets to one outlet + pressureReducing // downstream pressure regulation + relief // overpressure safety relief + safety // code-required overpressure protection (ASME rated) +} + +// Number of ports on a valve body +ValvePorts: Enum { + twoWay // single inlet, single outlet + threeWay // two inlets/one outlet or one inlet/two outlets + fourWay // two inlets, two outlets (rare) +} + // Enumeration of weather conditions WeatherCondEnum: Enum { unknown diff --git a/src/xeto/ph/equip.xeto b/src/xeto/ph/equip.xeto index cb13d17..48a88ad 100644 --- a/src/xeto/ph/equip.xeto +++ b/src/xeto/ph/equip.xeto @@ -47,6 +47,7 @@ AcEvsePort: EvsePort { // hydraulics, or pneumatics. Actuator: Equip { actuator + actuatorDirection: ActuatorDirection? } // Air Handling Unit: An enclosure with a fan that delivers air to a space