Calibration
The Calibration stage of a tag, the two-point assistant step by step, what Apply does and refuses, and what the Calibrate tags permission allows on its own.
Calibration is the second linear stage of a numeric tag's value pipeline: calibrated = scaled × Angular + Linear, applied after Scale and before Invalid reading, Limits and Decimals. It exists so an as-found/as-left correction made against a reference can be recorded without touching the range math in Scale, and it is the one stage a role with Calibrate tags may edit without Configure connector. Both the Scale and the Calibration stage carry a Two-point assistant that computes the pair from two reference points.
The stage
On the Conversion card of the Tags page the stage reads Calibration with its checkbox (off by default), Angular (×) (default 1), Linear (+) (default 0), the Two-point button in its head, and its running result on the right: = value while the stage applies, → value while it is bypassed. The device grid shows the same pair as Cal × and Cal + and the result as Calibrated, editable for Configure connector only.
An Angular of 0 is refused where it is typed: "A calibration factor of 0 would zero every reading. Enter the factor to multiply by (1 keeps the value)."
How a stage edit is saved
Scale and Calibration edits do not ride the device's debounced autosave. Each commit (the checkbox, either field) is written immediately and stage-scoped: only that stage of that tag is copied onto the stored device, so a Calibrate-only edit never carries a pending Configure draft with it, and a whole-device autosave running at the same time never overwrites the correction. A refused or failed commit reloads that stage from the database, so a rejected value never lingers on the page; the reason lands in the action feed ("Stage edit was not saved: …").
Who may edit which stage
| Stage | Manual fields and checkbox | Two-point Apply | Message when refused |
|---|---|---|---|
| Scale | Configure connector | Configure connector | "The “Configure connector” permission is required to edit the Scale stage." / "The “Configure connector” permission is required to apply a Scale adjustment." |
| Calibration | Calibrate tags or Configure connector | Calibrate tags or Configure connector | "The “Calibrate tags” or “Configure connector” permission is required to edit the Calibration stage." / "The “Calibrate tags” or “Configure connector” permission is required to apply a Calibration adjustment." |
On top of the permission, both stages refuse while a run holds the station ("Finish the active Process operation before editing this stage." / "Finish the active Process operation before applying this adjustment.") and while the runtime is stopped ("Runtime stopped"). The permission is read again when the edit is committed, not only when the field was drawn.
The two-point assistant
Press Two-point in a stage's head and the assistant unfolds under the stage as Two-point adjustment. It never edits the tag while it is open; nothing changes until you press Apply adjustment. The first line says what a capture reads: "Capture uses the current Scale output, before Calibration, Limits and Decimals." or "Capture uses the current Calibration output, before Limits and Decimals." The button is not drawn for a role that may never apply the stage.
Step 1: two reference points
Two fieldsets, Point 1 and Point 2, each with Expected (the value the stage should output at this reference) and Read (what the stage outputs there today). Type both as finite numbers; anything else is marked "Enter a finite number." Blank is allowed while you work. Order does not matter, but the two expected values must differ and the two read values must be distinguishable.
Step 2: capture or type the reading
Capture fills the point's Read with the stage's live output right now and stamps it ("Captured 14:02:33"); it reads Recapture afterwards. A capture is refused when the latest reading is not communications-good ("A communications-good live reading is required.") or when the stage has no finite value ("The selected stage does not have a finite live value."). Typing a Read by hand clears the point's capture stamp.
Both readings are pinned to the stage's coefficients at the moment they were taken. If those coefficients change under you (someone edits the field, another window applies an adjustment), the next capture or typed reading starts a fresh pair: the other point's Read and both stamps are cleared, and the draft says "The stage settings changed after the first reading. Capture or enter both read values again."
Step 3: read the verdict and the preview
With four values present the assistant evaluates the draft on a throwaway copy of the tag, so the preview runs the production math. A draft that cannot become a safe correction says why, next to the points:
| Message | Cause |
|---|---|
| Enter expected and read values for both points. | A field is blank. |
| Two-point correction requires a numeric tag. | The tag is not numeric. |
| All point values must be finite numbers. | A value is infinite or not a number. |
| The expected values must be different. | Equal expected values define no line. |
| The read values are equal or too close to distinguish safely. | The readings differ by no more than eight floating-point steps. |
| The difference between the points is too large to calculate safely. | Subtracting the points overflowed. |
| The selected stage has invalid current coefficients. | The stage's current Angular or Linear is not finite. |
| The point correction produces coefficients outside the supported range. | The correction itself is not finite. |
| Composing the correction with the current stage exceeds the supported range. | The composed pair is not finite. |
| The resulting stage cannot be inverted safely. | The composed Angular is 0 or too small to divide by, which would make writes impossible. |
| The candidate could not be evaluated through the tag pipeline. | The preview could not produce finite values. |
A valid draft shows the Adjustment preview table: one row per reference point and one for the Live reading, with the stage output Before the adjustment, After it, the Expected value and, for Scale only, Final, the value after every later stage. The Live row shows dashes while the tag has no reading.
What the assistant computes: a correction with slope (Expected2 − Expected1) ÷ (Read2 − Read1) and offset Expected1 − slope × Read1, applied on top of the stage's current output, then composed with the stage's current pair into the candidate Angular and Linear that replace it. A disabled stage counts as the identity pair (1, 0) for this purpose, and Apply turns the stage on.
Step 4: apply or cancel
Apply adjustment is enabled only when every field is valid, there is no capture error, the preview is valid, and the role and the station allow it; otherwise the reason is printed above the buttons. Pressing it writes the candidate pair to that stage alone, enables the stage, reports "Calibration two-point adjustment applied to 'Temperature'." (or "Scale …") and closes the assistant. It refuses, leaving the draft open for a retry, when the stage changed since the preview ("The stage settings changed after the preview. Review the points and try again; nothing was applied."), when the stored device changed outside this draft ("The persisted stage settings changed outside this draft. Reload and try again; nothing was applied."), when the tag or its device no longer exists, or when the station refuses mutations. "Applying…" shows while it runs; every refusal says "nothing was applied" and the previous coefficients stay.
Cancel closes the assistant and discards the draft. Selecting another tag closes it too; a draft lives only while its assistant is open.
What Calibrate tags allows on its own
A role with Calibrate tags and not Configure connector sees the whole Connector read-only, with one hole cut for calibration:
- On a tag's page, the Calibration stage's checkbox, its Angular and Linear, and its Two-point assistant with Apply are live. Every other field is inert, with the note "Changing the Connector requires the “Configure connector” permission." above the General card, and the Scale fields carry the Scale message as their tooltip.
- The device grid's Cal × and Cal + cells are not editable for this role; calibration goes through the tag page.
- No create, enable, disable, delete, write, discovery or replace verb is drawn.
Calibrate tags is a subset of Configure connector: a role that holds Configure holds everything here. The permission catalog is on Permissions.