Skip to content

Non-blocking use

How to run the driver from a super-loop or a task without waiting inside a call.

Datasheet sections this page relies on

From PyroScience Datasheet_FDO2-G2 v5:

  • Power-up time: 4 Communication Interface, p. 10
  • BCST: broadcast mode: 4.3 Commands, #BCST, p. 15

  • Measurement duration: 4.3 Commands, #SETM, modes, p. 16

All of them, with the driver API for each: Datasheet map.

Two ways to call

Every operation has a blocking form and a start form:

Blocking Start Result
EnsureInitialized() BeginInitialize() Identity
MeasureOxygen() StartMeasureOxygen() GetOxygen()
MeasureRaw() StartMeasureRaw() GetRaw()
CalibrateZero(), CalibrateHigh() StartCalibrateZero(), StartCalibrateHigh() none
SetCrcEnabled(), SetBroadcast(), SetBaudRate(), SetMeasurementMode() Start...() none
ReadUserMemory(), WriteUserMemory() StartReadUserMemory(), StartWriteUserMemory() GetUserMemory()

The blocking forms need the port's DelayUs hook: calling one from a port without it is a compile error. They wait for the module's reply, which takes up to 300 ms for a measurement and up to 10 s for a calibration.

Poll

A start call sends the request and returns. Poll() then reads what has arrived and moves the state forward. It returns Ok(false) while the operation is pending, Ok(true) when it ended, and an error when it failed.

  • With a clock in the port (NowUs), call Poll() with no argument; it measures its own time.
  • Without one, call Poll(elapsed_us) with the time since the last call.
non_blocking.cpp
// Start-up and one measurement per second, without blocking the loop.
class OxygenTask {
public:
  explicit OxygenTask(TickPort& port) : sensor_(port) {}

  // Call from the super-loop every few milliseconds.
  void Step() {
    const uint32_t elapsed_us = platform_ticks_us();
    if (state_ == Phase::Start) {
      if (sensor_.BeginInitialize()) {
        state_ = Phase::Starting;
      }
      return;
    }
    const auto p = sensor_.Poll(elapsed_us);
    if (!p) {
      state_ = Phase::Start; // the operation failed: p.error; start again
      return;
    }
    if (!p.value) {
      return; // still waiting for the module
    }
    if (state_ == Phase::Starting) {
      state_ = Phase::Idle;
    } else if (state_ == Phase::Measuring) {
      last_o2_mhpa_ = sensor_.GetOxygen().value.o2_mhpa;
      state_ = Phase::Idle;
    } else if (sensor_.StartMeasureOxygen()) {
      state_ = Phase::Measuring;
    } else {
      // the start was refused (busy): try again at the next poll
    }
  }

  [[nodiscard]] int32_t last_o2_mhpa() const {
    return last_o2_mhpa_;
  }

private:
  enum class Phase : uint8_t { Start, Starting, Idle, Measuring };
  fdo2::FDO2<TickPort> sensor_;
  Phase state_ = Phase::Start;
  int32_t last_o2_mhpa_ = 0;
};
non_blocking.cpp
// With a clock in the port (NowUs), Poll() takes no argument.
bool Tick(fdo2::FDO2<MyPort>& sensor) {
  if (sensor.IsInitialized() && (sensor.Pending() == fdo2::OperationKind::None)) {
    return sensor.StartMeasureRaw().ok();
  }
  return false;
}

Only one operation runs at a time. A start call while one is pending returns Busy. Pending() names it and AbortOperation() drops it.

States

GetState() returns one of seven states.

State diagram of fdo2::FDO2: Uninitialized, PoweringUp, Idle, Waiting, Streaming, Draining and StateUnknown, with the calls and events that move between them.State diagram of fdo2::FDO2: Uninitialized, PoweringUp, Idle, Waiting, Streaming, Draining and StateUnknown, with the calls and events that move between them.
The driver's states
Figure description and sources

Each box is a State of fdo2::FDO2, read from the enumeration in inc/fdo2_types.hpp; each arrow is a call or an event that moves it. Start-up goes through PoweringUp to Idle. An operation (Start* or a blocking call) puts the driver in Waiting; a good reply returns it to Idle. A timeout, a CRC error or a refused line sends it through Draining, where input is discarded until the line is quiet, so a late reply is never read as the next answer. A flash-writing command or a baud change that ended without a confirmed echo leaves StateUnknown, which only Resync() or a power cycle ends. While the module streams, Idle is reported as Streaming. The transitions are fixed in this figure and checked against the names used in src/fdo2.ipp.

Drawn from: inc/fdo2_types.hpp State; src/fdo2.ipp State transitions; figure module docs/diagrams/figures/state-machine.py.

State Meaning
Uninitialized Nothing started, or Deinitialize() ran
PoweringUp Waiting for the module's power-up (Config::power_up_ms)
Idle Ready for a call
Waiting A request is out; waiting for its reply (a flash write first runs a guard read)
Streaming The module sends #MRAW lines by itself
Draining Waiting for bytes of a late reply to stop before the next request
StateUnknown A flash write or baud change ended with no echo; Resync()

Deinitialize() returns Busy while a flash write may still be running, that is until its echo has arrived or its allowance has run down. On a port without NowUs() the time moves only through Poll(elapsed_us), so a caller that does not poll stays Busy; FlashWritePending() shows whether the wait is over.

Timing of one request

Five steps of a transaction: flush the receive buffer, write the command, wait for the module, read the echo and values, end at the carriage return; the allowance of each kind of command is listed under the wait.Five steps of a transaction: flush the receive buffer, write the command, wait for the module, read the echo and values, end at the carriage return; the allowance of each kind of command is listed under the wait.
One command and its reply
Figure description and sources

A transaction is five steps, left to right. The driver drops what is in the receive buffer, writes the command and its carriage return, then waits for the module: the module echoes the command, with its values, and ends the reply with one carriage return. The wait is the characters' airtime at the current baud rate, plus the module's processing allowance for the command (command_ms, measurement_ms, calibration_ms, flash_ms or logo_ms of the Config), plus margin_ms. The numbers shown are the Config defaults, read from inc/fdo2_types.hpp. A reply that does not end in time is a Timeout: the driver drains the line, and sends an idempotent read again when retries allow.

Drawn from: inc/fdo2_types.hpp Config; figure module docs/diagrams/figures/transaction-timing.py.

The deadline of a request is the allowance for its command (measurement_ms, calibration_ms, flash_ms, ...) plus the time the line needs for the bytes plus Config::margin_ms.

Next: Status and errors.