Calibration Service

Factory calibration is managed as a single device-wide session. The session owns the measurement path, expires after 30 seconds of inactivity, and holds a RAM draft until commit. Successful status, range, capture, and commit operations extend the lease.

Authorization

• GET /api/service/calibration/report/ requires Bearer powerUser; a service dongle is not required.
• status and all modifying endpoints require Bearer powerUser and a stored flag indicating that the service dongle is present.
• If the dongle is absent, the endpoint returns 403 ERROR_NO_ACCESS.

Data Model

There are six independent slots: x24_p1 (50 Ω), x24_p2 (100 Ω), x24_p3 (200 Ω), x2_p1 (500 Ω), x2_p2 (1000 Ω), and x2_p3 (2000 Ω).

Each saved snapshot contains the applied absolute tolerance and the raw ADC values for four channels. The live resistance and verification values for the current slot are calculated only from its reference and captured ADC value: R = referenceOhm * ADC / capturedAdc. previewOhm, deltaOhm, and deltaPercent are calculated dynamically when the response is generated. Other slots do not participate in the calculation.

The Manufacturer Tool calculates the tolerance. At commit, the firmware receives the two final values, stores them as historical data, and does not determine whether the measurement complies with the specification.

Immediately after capture, the corresponding captures element already contains all snapshot fields. Until ten fresh verification windows have been processed, the verifyAdc, previewOhm, deltaOhm, and deltaPercent fields have zero values. Before commit, the tolerance field is null. Result readiness must be determined from the state: a completed snapshot is available after the transition from verify_capture to active.

The source data of a completed snapshot does not change until the same slot is captured again. Capturing another point does not invalidate completed snapshots.

---

GET /api/service/calibration/report/

Generates the latest complete quality report from the saved calibration slots. No separate report entity is stored in Flash.

Response 200, report unavailable

{
  "available": false
}

A response of available: false means that the saved report is unavailable. The API does not specify why it is unavailable.

Response 200, report available

{
  "available": true,
  "committedAt": "2026-07-23T12:00:00Z",
  "snapshots": {
    "x2_p1": {
      "capturedAt": "2026-07-23T11:58:00Z",
      "tolerance": { "ohm": 1.875 },
      "channels": [
        {
          "channel": 0,
          "referenceOhm": 500.0,
          "capturedAdc": 123456,
          "verifyAdc": 123460,
          "previewOhm": 500.0162,
          "deltaOhm": 0.0162,
          "deltaPercent": 0.00324
        }
      ]
    }
  }
}

The complete response contains all six snapshot keys and four channels within each snapshot. There is no top-level tolerance map. There are no scale or offset fields.

---

GET /api/service/calibration/status/

Returns the active session and extends its 30-second lease.

Response 200, idle

{
  "state": "idle"
}

Response 200, active

{
  "state": "active",
  "sessionId": "7A19C2E4",
  "activeGain": "x24",
  "activePoint": "p1",
  "committedAt": null,
  "captures": {},
  "live": [
    { "channel": 0, "filteredAdc": 123456, "resistanceOhm": 100.01 }
  ]
}

Observable active states are switching, active, and verify_capture. The internal model also includes committing and stopping, but commit and finish are processed synchronously, so status does not return these transitional states.

The Manufacturer Tool applies the tolerance for the current procedure from its configuration. For uncommitted captures elements, the tolerance field is null; after commit, each slot contains the historical tolerance supplied by the Tool.

live[].resistanceOhm has the type number|null: for an empty or incomplete draft, a resistance that cannot be calculated is serialized as null.

---

POST /api/service/calibration/begin/

Starts the single calibration session from the saved point set. If the Flash record is missing or invalid, the session starts with an empty draft. The request body is not used.

The initial active slot is x24_p1.

Response 200

{
  "sessionId": "7A19C2E4"
}

Returns 400 ERROR_INVALID_VALUE if another session is already active. 503 ERROR_NOT_READY means that the measurement task did not accept the command.

---

POST /api/service/calibration/range/

Selects the gain and point. When the gain changes, the session transitions to switching until a fresh measurement window is published, confirming that the hardware path has been applied.

{
  "sessionId": "7A19C2E4",
  "gain": "x24",
  "point": "p1"
}

Response 200

{
  "state": "switching",
  "activeGain": "x24",
  "activePoint": "p1"
}

---

POST /api/service/calibration/capture/

Captures the current raw ADC window for all four channels and starts verification over ten fresh windows.

{
  "sessionId": "7A19C2E4",
  "gain": "x24",
  "point": "p1",
  "referenceOhm": 1000.01
}

Response 200

{
  "gain": "x24",
  "point": "p1",
  "capturedAt": "2026-07-23T11:58:00Z",
  "state": "verify_capture",
  "channels": [
    { "channel": 0, "referenceOhm": 1000.01, "capturedAdc": 123456 }
  ]
}

referenceOhm must be a finite positive number. The supplied gain and point must match the active slot.

---

POST /api/service/calibration/commit/

Saves the point set and all six completed, structurally valid snapshots. Reference resistances and ADC values must increase from p1 to p3; the ADC difference between each adjacent pair must be at least 5%. Before calling the endpoint, the Manufacturer Tool verifies that measurements are within tolerance.

{
  "sessionId": "7A19C2E4",
  "toleranceOhm": {
    "x24": 0.1875,
    "x2": 1.875
  }
}

Response 200

{
  "committedAt": "2026-07-23T12:00:00Z"
}

toleranceOhm.x24 is written to the three slots in the x24 range, and toleranceOhm.x2 is written to the three slots in the x2 range. Both values must be finite positive numbers.

Repeating commit for the same saved revision within a session is idempotent. Missing, incomplete, or structurally invalid snapshots return 400 ERROR_INVALID_ARGUMENT. Exceeding the specified tolerance is not itself a firmware error.

---

POST /api/service/calibration/finish/

Ends the session, discards the uncommitted draft, and releases the measurement path.

{
  "sessionId": "7A19C2E4"
}

Response 200

{
  "state": "idle",
  "finished": true
}

---

Storage Limitations

A single record in internal Flash Sector 1 contains the service magic, format version, and CRC, while the nested Calibration_t contains the shared committedAt value and six calibration slots. Each slot stores capturedAt, referenceOhm, the historical toleranceOhm supplied at commit, and, for each channel, capturedAdc and verifyAdc. Derived measurement results are not stored in Flash. The current format version is 0x0600; records with other versions are not loaded and require recalibration. The report endpoint calculates the derived fields and serializes them on request; no separate report entity is stored.

During normal measurement, resistance is calculated using piecewise-linear interpolation. When ADC <= ADC(p2), coefficients derived from p1+p2 are used; for a higher ADC value, coefficients derived from p2+p3 are used. Beyond the outermost points, the nearest pair is used for extrapolation.

A storage error leaves the RAM session active for another commit attempt or an explicit finish. The previous Flash revision is not guaranteed to survive a power failure or programming error during erase/write. True old-or-new atomicity requires a second erase bank or a change to the Flash layout.

---

Session Errors

• Empty or syntactically invalid JSON body → 400 ERROR_API_PARSING.
• Missing fields or fields of an incorrect type → 400 ERROR_INVALID_ARGUMENT.
• Invalid/expired sessionId or an operation in an invalid state → 400 ERROR_INVALID_VALUE.
• Measurement path not ready during status or capture → 503 ERROR_NOT_READY.
• Save failure during commit → 500 ERROR_IO.