Skip to content

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.

quickstart.cpp
#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

api_guide.cpp
// 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

api_guide.cpp
// 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

api_guide.cpp
// 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

api_guide.cpp
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