Sensor Calibration Workbench

Sensor Calibration Workbench

Use this skill when the sensor technically works, but the readings are not yet trustworthy enough for the project.

Resources

• references/calibration-flow.md - end-to-end calibration workflow and evidence checklist
• references/common-failure-patterns.md - warm-up, scaling, drift, saturation, and environment mistakes
• references/persistence-and-revalidation.md - storing coefficients and deciding when recalibration is needed

When to Use

Use this skill when the request involves:

• volatile or implausible sensor readings
• "how do I calibrate this sensor?"
• load-cell factor tuning
• CO2, magnetometer, or color-sensor calibration
• storing calibration coefficients in EEPROM or flash
• deciding whether the problem is calibration, hardware, or environment

Do not use this skill when the sensor is not detected at all. That should route through hardware or bus bring-up first.

Workflow

1. Confirm the measurement problem:

• unstable -> open references/common-failure-patterns.md
• offset or scaling error -> open references/calibration-flow.md
• values good once but bad later -> open

references/persistence-and-revalidation.md 2. Identify the calibration class:

• one-point or zero-offset
• two-point scale calibration
• multi-orientation or environmental calibration

3. Collect reference evidence before changing coefficients:

• known reference values
• warm-up state
• ambient conditions
• sample stability

4. Decide how calibration values will persist and how revalidation will be triggered after reboot, firmware update, or field drift.

Core Rules

• Calibration without a known reference is guesswork.
• Warm-up and stabilization time are part of calibration, not a side note.
• Do not mix hardware-fault symptoms with coefficient-tuning symptoms.
• Store both the calibration values and enough metadata to know when they became

stale.

Verification

• Confirm readings converge toward a known reference after calibration.
• Confirm the calibrated values stay stable across repeated samples.
• Confirm stored coefficients reload correctly after restart.
• If the project has operating thresholds, verify those thresholds against the

calibrated output rather than the raw sensor value.

Integration

• Pair with i2c-bringup-diagnostician or circuit-debugger when the sensor is

not yet electrically trustworthy.

• Pair with arduino-code-generator when the user needs persistence or

filtering code added to the sketch.

• Pair with field-power-and-connectivity-triager when sensor behavior changes

only off USB or under field power conditions.

Calibration Flow

Use this reference for the core calibration procedure.

Step 1: Define The Measurement Contract

Before calibrating, write down:

• what quantity is being measured
• the expected range
• the acceptable error
• the operating environment

If the project cannot state those four items, the calibration target is not yet clear enough.

Step 2: Prepare Known References

Examples:

• load cell -> known masses
• CO2 sensor -> fresh air baseline or controlled environment
• color sensor -> defined white and black references
• magnetometer -> known orientation or established calibration routine

Do not tune coefficients against unknown or drifting references.

Step 3: Stabilize First

Capture:

• warm-up time
• power source used during calibration
• whether readings are still drifting over time
• whether sampling noise is random or systematic

If the sensor is still drifting strongly, fix that before final coefficient changes.

Step 4: Apply The Right Calibration Class

• offset-only when the scale is correct but the zero point is wrong
• two-point when both offset and scale need correction
• multi-orientation or environmental calibration when geometry or physics

changes the response surface

Step 5: Validate After Applying Coefficients

Check:

• same reference again
• at least one different reference value
• threshold behavior in the actual project logic

If the second check fails, the calibration model is incomplete or the hardware is still unstable.

Common Calibration Failure Patterns

Use this reference when the user knows the sensor is present but the numbers are wrong.

Warm-Up And Stabilization

Symptoms:

• readings improve after a few minutes
• early readings are much noisier than later readings

Common with:

• load cells and HX711 setups
• gas sensors
• analog front ends

Wrong Reference Assumptions

Symptoms:

• coefficients seem to "work" only for one point
• readings are obviously clipped or nonsensical at another point

Typical cause:

• calibrating against an uncertain baseline
• assuming the environment is already stable

Saturation Or Scaling Errors

Symptoms:

• values pin at zero or max
• calibrated values exceed expected bounds dramatically

Typical cause:

• wrong mapping range
• wrong gain setting
• unit mismatch

Environment-Coupled Drift

Symptoms:

• values change with temperature, supply path, mounting, or nearby materials

Typical cause:

• the sensor is reacting to the real environment and the model ignores it

Hardware Fault Masquerading As Calibration

Symptoms:

• calibration values change wildly between runs
• impossible readings remain impossible after coefficient tuning

Typical cause:

• poor wiring
• noisy supply
• wrong sensor mode
• damaged module

Persistence And Revalidation

Use this reference when the user needs calibration values to survive reset or be rechecked over time.

What To Persist

• calibration coefficients
• sensor mode assumptions
• reference conditions if they matter
• timestamp or firmware version if useful

Where To Persist

• EEPROM for small, simple values
• flash-backed preferences or equivalent on platforms that support it

Revalidation Triggers

Recheck calibration when:

• firmware changes the measurement pipeline
• power path changes
• sensor mounting changes
• environment changes significantly
• readings cross sanity limits unexpectedly

Verification

• reboot and confirm coefficients reload
• compare one known reference before and after reboot
• log whether the stored values are being used or replaced