Calibration¶
How to calibrate the module in air or with two points, and why every calibration call needs your consent first.
Datasheet sections this page relies on
From PyroScience Datasheet_FDO2-G2 v5:
-
CALO: zero calibration: 4.3 Commands, #CALO, p. 14¶
-
CAHI: high calibration: 4.3 Commands, #CAHI, p. 15¶
- Flash endurance and interrupted writes: 4.3 Commands, WARNING, p. 16
All of them, with the driver API for each: Datasheet map.
Consent and the write budget¶
#CALO and #CAHI write the module's flash, and so do #CRCE, #WRUM, #BCST and #SETM. The flash
survives only a limited number of writes (the module's own limit, about 20000 cycles in all). So the driver sends
these commands only when you ask for it in the Config:
fdo2::Config WritableConfig() {
fdo2::Config c{};
c.allow_persistent_writes = true; // every flash-writing call needs this
c.max_flash_writes = 4; // and is counted against this budget (about 20000 cycles in all)
return c;
}
allow_persistent_writesis false by default. A flash-writing call returnsNotPermittedand sends nothing.max_flash_writes(1 to 64, default 8) is the number of such calls the driver sends in its lifetime.FlashWritesUsed()shows the count. A write counts when it is sent, even if the port fails, because the module may have received it.- A flash write is never repeated. If the reply is lost, the call returns the original error (for example
Timeout) and the state becomesStateUnknown; callResync()and read the module back before you try again.
Vendor warnings¶
The datasheet (section 4.3, Commands, and the warning that follows it) says, and the driver follows:
- Flash endurance is about 20,000 flash cycles in all, triggered by
#CALO,#CAHI,#CRCE,#SETMand#BCST(and by#WRUM, which the datasheet describes as one cycle per call). Use them only when needed.max_flash_writesis a guard against a loop in your code, not the vendor figure: its limit of 64 per driver lifetime is far below 20,000. - A power loss during a flash cycle can corrupt the flash. Keep the supply stable while one runs. The driver
refuses
Deinitialize()withBusywhile a write is pending, andPowerCycle()waits for it to end (Settings). - Always evaluate the reply. A write without its echo may have corrupted the flash: the driver reports the
original error and the state
StateUnknown. #CALOand#CAHIreplace the factory calibration. The datasheet asks for at least 5 minutes of steady measuring in the reference medium before the command, and the command takes up to 10 seconds.
The guard before every flash write¶
A wrong calibration is stored in the module for good, so the driver checks before it sends #CALO or #CAHI:
- It reads
#VERSand compares it with the identity found at start-up. A different module on the line, or a module that has reset without the driver seeing it (a power glitch, for example), ends inStateUnknownorDeviceIdMismatchand nothing is written. - It reads
#MOXY. The status must be acceptable, and the sensor must have been powered for the warm-up time of 3 minutes (datasheet section 2): earlier the call returnsNotReady. The measured oxygen partial pressure must lie withinConfig::cal_window_pctpercent (default 20, at leastcal_window_min_mhpa, default 5000 milli-hPa) of the value you are about to store. A sensor still in air cannot be calibrated as nitrogen, and the reverse: the call returnsOutOfRangeand nothing is written. - Only then does it send the write, and it counts it.
The guard reads #MOXY but not #VERS before a calibration, and its warm-up test counts the time since the
driver powered the module, using the host's clock (the datasheet gives no uptime value to read). A module that was
swapped or reset after start-up is therefore seen only through the plausibility window and the status word.
The other flash commands (#CRCE, #WRUM, #BCST, #SETM) get the identity check (1). The one exception is
#BCST 0 while the module streams, which is sent as it is because no reply can be read in a stream.
CalibrateHigh() accepts 10 to 2000 hPa (10000 to 2000000 in 0.001 hPa): a standard outside the range of a
real calibration gas returns InvalidArgument.
Before you calibrate¶
- Keep the sensor in the reference medium until the readings are steady. The datasheet asks for five minutes.
steady_sis the time you have waited; a value belowConfig::min_steady_s(default 300) returnsInvalidArgumentand sends nothing. - The status must be good.
CalibrateAir()returnsSensorFaultotherwise. - The sensor must be warmed up (3 minutes after power-up), or the call returns
NotReady. - Calibration changes the module's stored calibration. Not verified on hardware: nobody has run these calls against a module yet.
One point in air¶
// One high point in ambient air; the sensor has been in it for at least five minutes.
fdo2::Error CalibrateInAir(Sensor& sensor) {
// Reads the module's pressure, takes 20.95 % oxygen (dry air) and sends #CAHI.
return sensor.CalibrateAir(300).error; // NotPermitted unless allowed in the Config
}
CalibrateAir() reads #MRAW for the pressure, computes the oxygen partial pressure of dry air at that
pressure (20.95 percent by default, kDryAirO2Ppm) and sends #CAHI. It is correct only when the sensor sees
dry air at the pressure of the module's own sensor, which sees the air through the venting capillary at the back of
the housing (datasheet section 2): keep the capillary open to the same air as the membrane. Humid air has a lower
oxygen partial pressure; the datasheet does not give a correction, so the driver applies none. You can see the
value before anything is written:
// The value #CAHI will receive, before anything is written.
int32_t AirValue(int32_t pressure_ubar) {
const auto v = fdo2::AirO2Mhpa(pressure_ubar); // 1013000 ubar -> 212224 (10^-3 hPa)
return v ? v.value : 0;
}
Two points¶
// Zero in nitrogen, then a known partial pressure; each step needs its own steady time.
fdo2::Error CalibrateTwoPoint(Sensor& sensor, int32_t high_po2_mhpa) {
if (const auto r = sensor.CalibrateZero(300); !r) {
return r.error; // CalibrationRejected: #ERRO -60, the value is outside the expected range
}
return sensor.CalibrateHigh(high_po2_mhpa, 300).error;
}
CalibrateZero() sends #CALO with the sensor in an oxygen-free medium. CalibrateHigh() sends #CAHI with
the oxygen partial pressure of your standard in 0.001 hPa. A call allows Config::calibration_ms (10 s by default)
for the reply.
Errors¶
| Error | Meaning |
|---|---|
NotPermitted |
No consent, or the write budget is used |
InvalidArgument |
steady_s too short, or the value is out of range (10 to 2000 hPa) |
NotReady |
The sensor is still warming up (3 minutes after power-up) |
OutOfRange |
The measured value is far from the calibration value (the guard) |
DeviceIdMismatch |
The module on the line is not the one found at start-up (the guard) |
CalibrationRejected |
#ERRO -60: the module judged the value outside its expected range (firmware 3.51 and later) |
SensorFault |
The status word was not good (CalibrateAir()) |
StateUnknown |
The reply was lost; Resync() |
Next: Settings.