# Delta CO source mapping and implementation limits

This implementation uses the three user-supplied enteliWEB 4.33 references below.
Page numbers are PDF page numbers, starting at one. The PDFs remain user files;
the application has no dependency on them at runtime. They describe a controller,
not a validated FCU thermal model. This is not a firmware emulator.

| Source | Relevant content |
| --- | --- |
| Loop (CO) Object Configuration Reference.pdf, pp. 5–6 | Types/action, whole-output deadband, effective PB, Bias, integral rate, reset band, derivative gain and sample time |
| Loop (CO) Object Concepts.pdf, pp. 2–5, 10–14 | Direct/reverse action, P correction and Bias, deadband hold, time-based integral, limit hold, reset-band taper |
| Loop (CO) Object Tasks.pdf, pp. 1–2 | Tuning workflow beginning with P and Bias 50%, then PI |

## Implemented source behavior

- Direct-acting cooling and reverse-acting heating.
- P, I, PI and PID with zero D. P correction is −50..+50 percentage points,
  added to Bias; final output is bounded to 0..100% (Concepts p. 5).
- Effective proportional band equals configured PB plus configured deadband
  (Configuration Reference p. 5). The source example PB 38 plus DB 2 gives 40.
- Deadband is the full width around setpoint. All types hold their previous
  output inside it (Concepts pp. 10–11). DB 0.2 means SP ±0.1.
- Integral changes Bias by a configured percentage-point rate per minute, rather
  than multiplying by error magnitude (Concepts pp. 11–12).
- Integral stops at CO 0% or 100% (Concepts p. 12).
- Reset band is distinct from deadband. It tapers reset linearly near setpoint;
  zero disables it (Concepts p. 14; Configuration Reference p. 6). For full reset
  band 20, error 5, and rate 2%/min, the effective rate is 1%/min.
- The UI labels accumulated integral state as Bias: it includes initial Bias,
  rather than presenting that baseline as an integral increment from zero.

## Explicit simulator choices where the source is incomplete

- The fixed numerical step remains one simulated second. An increment crossing an
  output limit is truncated to reach that limit exactly, then Bias holds.
- Applied P/Bias diagnostics freeze together with held CO. The source promises
  output hold but does not specify its internal diagnostic-register behavior.
- Boundaries are inclusive. New in-band loops initialize P to zero and output to
  configured Bias; no previous output exists to hold.
- Active retuning preserves accumulated Bias, except a changed configured Bias
  replaces it. Initialization/reactivation restore the configured baseline.
  The first retuning observation does not integrate. This is not a BACnet write
  implementation or a claim of exact firmware startup/retuning behavior.
- At an output limit, no further integral adjustment occurs. With pure I this
  conservative interpretation requires a Bias change or reinitialization to leave
  the limit; the source does not specify its error-reversal recovery algorithm.
- FCU enable/inhibit, retained output ownership, mutual exclusion and fan gating
  are application sequence decisions, not properties intrinsic to the CO object.
  Inactive objects command zero to their valves. Initial room-mode deadband does
  not enable both objects just because their configured Bias is 50%.
- Default PI / PB 2°C / Bias 50% / rate 1% per minute / DB 0.2°C / reset 0 are
  teaching choices. Rate 1 is within the room-temperature guidance on Concepts
  p. 13; it is not a universal tuning recommendation or equipment requirement.

## Unsupported behavior

The references describe Derivative Gain and derivative Sample Time, but provide
no equation, scaling convention, or complete sampling/filtering algorithm.
The prior Td formula is removed. Nonzero Derivative Gain fails validation and
the pure loop also rejects it. PID with Gain 0 behaves as PI. Sample Time is
validated and stored, but has no effect while derivative action is disabled.
An authoritative derivative algorithm is needed before nonzero D can be enabled.

BACnet properties/services, priority arrays, manual/timed overrides, alarms,
GCL programs and actual equipment interlocks are outside this FCU implementation.
LEGACY_P preserves the old simulator proportional sequence for comparison; it
is explicitly different from the document-based P object.

## Verification

`tests/pid-tests.js` checks source numerical examples, each type's output hold,
inclusive boundaries, Bias initialization/retuning, integral rate and reset taper,
limit handling, derivative rejection, FCU exclusion, history and atomic editing.
Existing legacy controller, thermal, engine, playback and UI regressions remain.
Run `node tests/run-node.cjs` or open `tests/index.html` directly.
Node DOM checks are not browser visual/console checks or physical validation.