# Bounded temperature calibration and drift recovery Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-25
Next Action: none

Canonical Truth: E:/dev/high_point/7520553_SMI_FW/docs/temperature-calibration-policy.md
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Current Context

The moving-window defect and inconsistent validation paths have been repaired in
source commit `809362d8` and frozen into artifact commit `c7a20522`. The
customer-facing calibration screen and service 514 now use the same inclusive
absolute interval `[-10.0, +10.0] C`, anchored to zero rather than to the
previous value.

Controller A review on 2026-07-24 refined the active UI scope. The primary
customer workflow is Temperature Setup -> Calibrate, where the displayed
temperature is adjusted to match a reference instrument. Its source path uses
a temporary configuration copy and clamps the total offset directly at the
shared endpoints. Service 514 is a separate direct-offset editor. Target
review found that its negative endpoint reaches `-10.0 C`, but its positive
endpoint stops at `+9.9 C`; this secondary defect is tracked in
`work/tickets/ticket-service-514-positive-endpoint-sticky-setpoint-state.md`.

The owner also requested press-and-hold repeat for the reference-calibration
increment/decrement buttons after the repeated-boundary test required one tap
per tenth of a degree. The implementation and target acceptance criteria are
tracked in
`work/tickets/ticket-reference-calibration-press-and-hold-auto-repeat.md`.

Both follow-up changes are frozen in source commit `23c6cc7f` and artifact
commit `2616e275`. All 17 PowerShell regression checks, both Python test suites,
and direct managed-make clean Debug and Release builds pass. Exact artifact
hashes are recorded in
`work/evidence/integrated-00-05-00-target-qualification-20260724/controller-a-calibration-matrix.md`.
The Debug S-record was hash-checked, programmed, and verified on Controller A.
Post-load read-only evidence confirms the intended `+0.3 C` correction,
configuration bytes, option bytes, healthy SD protocol state, and complete CID
were preserved. Operator UI verification passed for the bounded-calibration
interaction scope.

Controller A tap/hold/release review passed in both directions. The combined
sequence's requested final Cancel was visually confirmed, but post-test
VEEPROM changed in update count, low-order offset bits, and checksums. The
effective correction remained `+0.3 C`. A subsequent isolated one-step Cancel
case passed: VEEPROM was byte-identical, the stored offset was unchanged, the
temporary copy reflected the one-step edit, and no save request was pending.

The startup semantic validator and every direct save path now use the same
numeric policy. A fingerprinted legacy value outside the interval is retained
for diagnosis, produces a configuration/calibration finding, and leaves
effective heat inhibited until an explicit valid service replacement is saved.
Both LM73 and RTD temperature paths continue to add `MainTemp_Offset` to the
unadjusted measurement.

`MainTemp_UserEnteredOffset` exists in the persisted layout but is not consumed
by the present main-temperature calculation. It must not be repurposed casually:
doing so changes the effective-temperature contract and requires an explicit
schema/migration and compatibility decision.

The issue was raised from field experience: customers can calibrate repeatedly
until a healthy sensor appears failed or the controller behaves incorrectly.

Qualification-scope update (2026-07-24): Controller A uses the RTD main
temperature path, which is the only main-temperature sensor path in scope for
this product/release. The owner explicitly excluded LM73 hardware testing; it
is not deferred and will not be used as release evidence. Dormant LM73 source
support remains an observed implementation fact, not a qualification claim.
Any future LM73 use requires separately approved scope and qualification.
RTD-compatible raw/adjusted, alarm, display, logging, and non-power recovery
cases may continue. The owner has received the hardware needed to finish the
external G-PWR controller subsequently passed its canonical hostname-interface
witness matrix on 2026-07-25.

## Recommendation

Adopt one absolute calibration policy shared by every UI, service, startup,
restore, and runtime path. The immediate candidate policy is an inclusive
`-10.0 C` through `+10.0 C` total correction anchored to the unadjusted sensor
reading and zero offset, never to the previously stored offset. Define the
limits once in an owned configuration/calibration module and reuse them.

For temperature-entry calibration, derive the admissible reference-temperature
window from `raw temperature + absolute minimum/maximum offset`. For direct
offset entry, always show the fixed absolute interval. Repeating either workflow
must not expand the reachable set.

Do not silently clamp an already-out-of-range persisted value on startup. Retain
the stored value for diagnosis, mark a calibration finding, inhibit effective
heat, and present a recoverable service action. The approved recovery must
record the old value and either recalibrate against a traceable reference or
explicitly reset the offset to zero. This avoids an unexplained temperature jump
and follows the existing requested-versus-effective configuration safety model.

Keep the immediate repair independent of PID retuning and the deferred sensor
transport/recovery work. They share qualification evidence, but calibration
bounds must be testable and releasable on their own.

Qualification sequencing approved by the owner on 2026-07-20: finish this and
all other intended firmware mutations first, freeze one integrated candidate,
then perform the thorough interactive checklist from a new empty results file.
Current 00.04.13 target checks remain useful development evidence but cannot
provide release disposition for the later image.

## Current State

Completed:

- Confirmed the repeatable service-code 514 moving-window defect at
  `HMI_MainEventHandler.c:3076`.
- Confirmed the normal temperature-control calibration UI already clamps to an
  absolute +/-10 C at `HMI_MainEventHandler.c:4673-4693`.
- Identified direct write callbacks and both LM73/RTD consumers of
  `MainTemp_Offset`.
- Approved and documented one inclusive `[-10.0,+10.0] C` total-correction
  policy for customer and service paths.
- Added shared constants and `AppConfigIsMainTempOffsetValid()`; startup and all
  direct save paths reject non-finite or out-of-range values before mutation.
- Changed service 514 to the fixed absolute interval. An invalid stored value is
  displayed diagnostically and the editor begins at zero without silently
  mutating or saving the record.
- Preserved the existing requested-versus-effective recovery contract: invalid
  fingerprinted configuration remains available for service diagnosis while
  effective heat is inhibited.
- Verified `MainTemp_UserEnteredOffset` is not consumed by present temperature
  control and did not assign it a new meaning.
- Added 13 calibration source-policy checks and integrated configuration
  regression coverage.
- Clean Debug and Release rebuilds passed; exact 00.05.00 artifacts are frozen
  in commit `c7a20522`.
- Corrected the service-514 positive-endpoint state leak and added reference
  calibration button auto-repeat in source commit `23c6cc7f`; froze the exact
  replacement artifacts in `2616e275`.
- Programmed and verified the exact replacement Debug S-record on Controller A;
  VEEPROM, option memory, intended offset, and SD CID/status were preserved.
- Passed reference-calibration tap/hold/release, isolated Cancel, upper-boundary
  clamp, service-514 positive endpoint with the former stale state injected,
  bounded positive Save, and final restoration to displayed `+0.3 C`.
- Reproduced a starting-value-dependent service-514 lower-endpoint failure:
  decrementing from the positive endpoint stopped and saved at raw
  `-9.9000225 C`. Implemented endpoint clamping; the complete regression set,
  clean Debug/Release rebuilds, corrected endpoint target retest, bounded Save,
  timeout-without-Save, and safe restoration all pass.
- Passed the reference-calibration lower auto-repeat endpoint after continued
  hold plus three extra taps, saved exactly `-10.0 C`, verified redundant
  CRC-valid persistence, and restored/verified intended `+0.3 C`.
- Promoted the current contract to
  `docs/temperature-calibration-policy.md` and updated development/recovery docs.

Transferred to final integrated qualification:

- Controller-specific capture of offset, raw temperature, adjusted temperature,
  sensor source, alarm state, and configuration hashes.
- Invalid-persisted recovery, reboot/update preservation, and RTD alarm/logging
  behavior on the final integrated HPT candidate. LM73 hardware qualification
  is explicitly out of scope.
- Final release disposition and controller restoration.

These are release-candidate regression gates, not remaining bounded-calibration
implementation. Per the owner's 2026-07-25 sequencing decision, they will run
once after the filesystem/HPT/triple-mirror code changes are complete and one
integrated candidate is frozen.

## Goal

No sequence of customer, service, reboot, update, or persistence operations can
move the effective main-temperature correction outside an approved absolute
range. Invalid legacy values are detected before heat is permitted and are
recoverable without losing diagnostic evidence.

## Why It Matters

Calibration directly changes the temperature used by control, display, alarm,
and logging behavior. An accumulative window lets an authorized-looking action
create a hazardous or nonfunctional control state even when the sensor hardware
is healthy. A fixed, auditable policy also makes calibration evidence meaningful
because a later calibration cannot redefine the earlier acceptance boundary.

## Major Outcomes

- One named absolute limit and unit contract used by all main-temperature paths.
- No moving-window or cumulative calibration behavior.
- Safe startup and visible recovery for non-finite or out-of-range persisted
  corrections.
- Clear separation of raw measurement, stored correction, adjusted temperature,
  and any future factory-versus-customer trim.
- Traceable evidence covering repeated RTD calibration, persistence, firmware
  update, alarms, logging, and heat inhibition.

## Delivery Stages

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1. Policy | Absolute bound, inclusivity, precision, roles, and recovery behavior are approved | Field defect and current code paths documented | Signed behavior table for valid, boundary, invalid, cancel, and legacy states |
| 2. Baseline | Both physical controllers have read-only configuration and live-temperature captures | Current A/B routing reconfirmed | Controller ID, firmware hash, VEEPROM hash, raw/adjusted values, offset, sensor source, and alarm state recorded |
| 3. Central implementation | All entry/save/startup paths use one policy | Approved contract and fixtures | Source checks and executable boundary/repetition tests pass |
| 4. Safety integration | Invalid persisted correction cannot influence active heat | Existing configuration recovery behavior understood | Recovery indication, effective heat inhibition, diagnostic retention, and repair action pass fault fixtures |
| 5. Freeze final integrated candidate | This change and all other intended firmware mutations are complete | Clean automated, Debug, and Release gates | Source commit and exact ELF/SREC/update hashes frozen; identical image loaded on both controllers |
| 6. Fresh interactive qualification | One new results file covers the frozen image on both controllers | Candidate freeze and restored safe bench state | UI/service repetition, reboot/update preservation, RTD alarm/audio, logging, graph/export, and J-Link readback pass with comments and sign-off; no LM73 claim |
| 7. Release closeout | Field/service behavior is documented and auditable | Qualification evidence reviewed | Canonical policy, release note, service instruction, and final controller restoration are complete |

## Detailed Verification Matrix

| Case | Expected result |
| --- | --- |
| Offset `0.0`, enter `+10.0` or `-10.0` | accepted exactly |
| Customer calibration at one endpoint, then another step outward | displayed value remains clamped at the endpoint; no out-of-range mutation is possible |
| Start at `+10.0`, repeat service 514 | available interval remains `[-10.0,+10.0]`; `+20.0` is unreachable |
| Start at `-10.0`, repeat service 514 | available interval remains `[-10.0,+10.0]`; `-20.0` is unreachable |
| Temperature-reference entry | permitted reference equals raw temperature plus the fixed absolute offset interval |
| Cancel, timeout, malformed, NaN, or infinity | no configuration mutation and no persistence request |
| Fingerprinted VEEPROM contains `+10.1`, `-10.1`, NaN, or infinity | calibration finding, requested value retained for diagnosis, effective heat inhibited, visible recovery |
| Corrected value saved, rebooted, and firmware updated | exact valid correction preserved; bounds do not drift |
| RTD selected | offset policy and raw/adjusted calculation are consistent |
| LM73 selected | N/A by owner-approved product/release scope; no qualification claim |
| Alarm and logging active | adjusted temperature basis is documented and values remain consistent with displayed/control behavior |

## Related Artifacts

- Completed configuration recovery: `work/wp/completed/wp-semantic-configuration-validation-and-recovery.md`
- Deferred control regulation: `work/wp/deferred/wp-temperature-control-profile-recovery-and-steady-state-regulation.md`
- Deferred sensor validity: `work/wp/deferred/wp-temperature-sensor-validity-interlock-and-rtd-transport-recovery.md`
- Current inventories: `work/inventories/smi-current-setup-a.md`, `work/inventories/smi-current-setup-b.md`
- Planned canonical policy: `E:/dev/high_point/7520553_SMI_FW/docs/temperature-calibration-policy.md`

## Rough Sequence

1. Reconfirm the A/B physical-controller mapping and capture read-only current
   configuration plus live raw/adjusted temperature evidence before mutation.
2. Program the precisely identified frozen candidate and run the RTD target
   matrix on both controller variants.
3. Restore intended alarm/configuration state, publish final service guidance,
   attach evidence, and close the workpackage.

## Milestones

### Milestone 1: Safety contract approved

Completion criteria:

- [x] The total absolute correction limit and endpoints are approved.
- [x] Customer versus service permissions are explicit.
- [x] The action for an existing out-of-range controller is explicit.
- [x] Raw, adjusted, displayed, controlled, alarmed, and logged temperature bases are defined.

### Milestone 2: All mutation and consumption paths controlled

Completion criteria:

- [x] No HMI range is centered on the prior stored offset.
- [x] Every write path rejects out-of-range and non-finite input before mutation.
- [x] Startup validation uses the same numeric policy.
- [x] Effective heat is inhibited for invalid persisted calibration without erasing evidence.
- [x] `MainTemp_UserEnteredOffset` remains unused; no new schema meaning or migration was introduced.

### Milestone 3: Implementation and focused target evidence complete

Completion criteria:

- [x] Automated boundary and repeated-calibration tests pass.
- [x] Clean Debug/Release builds and exact hashes are recorded.
- [x] Focused Controller A interaction, endpoint, Save, Cancel, timeout, persistence, and safe-restoration evidence passes.
- [x] Cross-controller reboot/update, alarm, logging, and final restoration checks are transferred without loss to the post-freeze integrated release qualification.

## Open Questions

- Is +/-10.0 C the approved total correction, or should customer access be
  tighter while qualified service uses a separately controlled range?
- Should a valid factory/service calibration and a customer trim be represented
  separately in a future schema, with independent limits and a bounded sum?
- For an existing out-of-range value, should recovery require traceable
  recalibration, allow an explicit reset to zero, or support both?
- Which independent reference thermometer, accuracy, stabilization interval,
  and acceptance tolerance are required for target qualification?
- Is the alarm/control/logging basis intentionally the adjusted temperature in
  every mode, including high heat?

## Completion Standard

This implementation workpackage is complete when an approved absolute
calibration contract is implemented across every entry, save, validation,
restore, and runtime path; repetition cannot expand the allowed range; invalid
legacy corrections cannot enable heat; focused target evidence covers the
changed interactions; and settled behavior is promoted to canonical
engineering/service documentation. Cross-controller reboot/update,
alarm/logging, and final-restoration regression remains mandatory, but is owned
by the single post-freeze integrated release qualification.

## Closeout Routing

- Current truth promoted to: `E:/dev/high_point/7520553_SMI_FW/docs/temperature-calibration-policy.md`
- Historical context remains in: this workpackage and setup-specific evidence
- Runtime/status evidence: `work/evidence/setup-a/` and `work/evidence/setup-b/`
- Cleanup deferred to: the separately approved temperature-profile and sensor-validity workpackages
