API guide¶
The driver's calls by task: start, measure, read the identity and handle errors.
Datasheet sections this page relies on
From PyroScience Datasheet_FDO2-G2 v5:
- Volume fraction from partial pressure: 2 Specifications, note on % O2 before Environment, p. 6
-
VERS: device, channels, firmware, sensors: 4.3 Commands, #VERS, p. 11¶
-
IDNR: the unique id: 4.3 Commands, #IDNR, p. 11¶
-
MOXY: oxygen, temperature, status: 4.3 Commands, #MOXY, p. 11¶
-
MRAW: phase, signals, pressure, humidity: 4.3 Commands, #MRAW, p. 12¶
-
LOGO: the status LED: 4.3 Commands, #LOGO, p. 13¶
-
RDUM and #WRUM: 64 user words: 4.3 Commands, #RDUM, #WRUM, p. 14¶
All of them, with the driver API for each: Datasheet map.
Start¶
FDO2<YourPort> sensor(port) stores the port and the Config and does no I/O. EnsureInitialized() is the
only start-up call: it powers the module if your port has the supply hook, waits for the power-up, reads #VERS and
#IDNR, checks the device and learns what the firmware offers. Every other I/O call returns NotInitialized
before it has succeeded. Deinitialize() goes back. Resync() recovers a line in an unknown state and
PowerCycle() restarts the module.
Measure oxygen¶
MeasureOxygen() returns an Oxygen: o2_mhpa (oxygen partial pressure in 0.001 hPa), temperature_mc (0.001
degC), the Status, its Quality and warming_up. The call fails with SensorFault when the status word is not
acceptable under the status policy, and with OutOfRange when oxygen or
temperature is outside the windows in Config.
#include "fdo2.hpp"
// Returns 0 and the oxygen partial pressure in 0.001 hPa and the temperature in 0.001 degC.
int read_oxygen(MyPort& port, int32_t& o2_mhpa, int32_t& temperature_mc) {
fdo2::FDO2<MyPort> sensor(port); // no I/O yet
// 1. Waits for the module's power-up, reads #VERS and #IDNR and checks the device.
if (auto r = sensor.EnsureInitialized(); !r) {
return static_cast<int>(
r.error); // Timeout or DeviceIdMismatch: check wiring and the 3 V levels
}
// 2. One #MOXY: oxygen, temperature and the status word.
const auto o = sensor.MeasureOxygen();
if (!o) {
return static_cast<int>(o.error); // SensorFault: see the status word; OutOfRange; Timeout
}
o2_mhpa = o.value.o2_mhpa; // 10^-3 hPa
temperature_mc = o.value.temperature_mc; // 10^-3 degC
return 0;
}
Oxygen as a fraction¶
// The oxygen fraction in 0.001 percent, from the module's own pressure reading.
fdo2::Result<int32_t> OxygenFraction(Sensor& sensor) {
return sensor.MeasureVolumePercentMilli(); // needs a good status and a plausible pressure
}
MeasureVolumePercentMilli() returns the oxygen fraction in 0.001 percent: the partial pressure divided by the
total pressure, from #MRAW. It needs a good status and a pressure inside
Config::pressure_min_ubar..pressure_max_ubar. Set pressure_reference_ubar to use your own pressure instead of
the module's. It is a dry-gas fraction.
Venting capillary
The module's pressure sensor measures through the venting capillary at the back of the housing. The fraction is
right only when the pressure at the capillary equals the pressure at the sensing membrane (datasheet section 2).
In a sealed or pressurised vessel with the capillary outside, they differ: set pressure_reference_ubar to the
pressure at the membrane, or use the oxygen partial pressure itself.
Raw values¶
// A full reading: oxygen, temperature, phase shift, signals, pressure and humidity.
bool ReadAll(Sensor& sensor, fdo2::Raw& out) {
const auto raw = sensor.MeasureRaw();
if (!raw) {
return false; // raw.error says why
}
out = raw.value;
return out.oxygen.quality == fdo2::Quality::Good;
}
MeasureRaw() adds the phase shift (dphi_mdeg), the signal and ambient light (microvolts), the pressure
(microbar) and the humidity (0.001 %RH). The pressure is not a gate of this call; it is checked when you ask for a
fraction or a calibration.
Identity¶
// The module's identity is read once at start-up and kept.
bool IsG2(Sensor& sensor) {
const fdo2::Identity& id = sensor.GetIdentity();
return id.caps.set_mode && (id.version.firmware >= 355);
}
GetIdentity() returns what start-up read: Version (device id, channels, firmware, sensors), the unique id and
Capabilities. ReadVersion(), ReadUniqueId() and Identify() ask the module again.
Handle errors¶
const char* Explain(fdo2::Error error) {
switch (error) {
case fdo2::Error::Timeout:
return "no reply: wiring, 3 V levels, power";
case fdo2::Error::Crc:
return "a corrupted reply: noise on the line";
case fdo2::Error::SensorFault:
return "the status word says the reading is not valid";
case fdo2::Error::NotPermitted:
return "a flash write needs Config::allow_persistent_writes";
case fdo2::Error::StateUnknown:
return "call Resync()";
default:
break;
}
return fdo2::ToString(error);
}
Every call returns a Result<T> (value and error); check ok() before you use the value. The full list is on
Status and errors. Reads are repeated up to Config::retries times when the failure may be
transient; writes to flash never are.
Next¶
- Calibration, Settings, Non-blocking use.
- API reference: every class and member.