Skip to content

Quickstart

Run the driver on your PC first, with no hardware; then read the oxygen partial pressure from your MCU: wire the module, write a small port class, call two driver functions.

Datasheet sections this page relies on
  • Power-up time: PyroScience Datasheet_FDO2-G2 v5, 4 Communication Interface, p. 10
  • Connector, pins and signal levels: PyroScience Datasheet_FDO2-G2 v5, 7 Mechanical Dimensions and Electrical Interface, drawing and pin table, p. 20
  • Start-up flashes of the status LED: PyroScience Quick_Start_FDO2-G2 v1.00, Quick start, connecting the module, p. 2

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

Try it on your PC

examples/host/ runs the real driver against a simulated module, through a host port. From the repository root, with CMake and a C++20 compiler:

cmake -S examples/host -B build-example
cmake --build build-example
./build-example/fdo2_host_example
FDO2 driver on the host
fdo2: initialised
module: device 8, firmware 3.57, sensors 0xF
oxygen 211.717 hPa
temperature 21.000 degC
oxygen fraction 20.900 %

The full output is in expected_output.txt; CI runs the example and compares it. The numbers come from the simulated module, not from a measurement.

1. Wire it

MCU FDO2 Notes
UART TX RXD (pin 3) 19200 baud, 8N1; 3.3 V at most
UART RX TXD (pin 2) The module's output is 3.0 V
3.3 V to 5 V VCC (pin 4) Below 3.3 V the readings can be wrong
GND GND (pin 1)

The Hardware page has the pin figure and the 5 V circuit.

2. Add the driver

Add the repository as a submodule and link the fdo2::fdo2 CMake target. Installation covers CMake on any MCU, the installed package and ESP-IDF.

git submodule add https://github.com/kokeb-labs-drivers/driver-fdo2.git external/driver-fdo2

3. Write the port

The port is the only platform code: it brings the UART up and moves bytes. Replace the platform_* calls with your SDK's.

my_port.hpp
class MyPort : public fdo2::UartInterface<MyPort> {
public:
  // Bring the UART up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_uart_init();
    }
    return ready_;
  }

  bool Write(const uint8_t* data, std::size_t len) noexcept {
    return platform_uart_write(data, len);
  }

  // The number of bytes read (0 to `max`), waiting up to `timeout_ms` for the first one.
  // The reply length is not known in advance, so this is not an exact-length read.
  std::size_t Read(uint8_t* data, std::size_t max, uint32_t timeout_ms) noexcept {
    return platform_uart_read(data, max, timeout_ms);
  }

  // Drop stale bytes before each request.
  bool FlushInput() noexcept {
    return platform_uart_flush_input();
  }

  // Wait at least `us` microseconds: the module's processing times depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Porting explains each method and the optional hooks.

4. Read the oxygen

main.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;
}

What each step does:

  1. EnsureInitialized() calls your port's EnsureInitialized(), waits for the module's power-up, reads #VERS and #IDNR and checks that the device is an FDO2 with an oxygen sensor.
  2. MeasureOxygen() sends #MOXY and checks the status word and the plausibility windows.
  3. The values are integers: oxygen in 0.001 hPa, temperature in 0.001 degC.

This example is built by the host CI, so it compiles against the current headers.

If it does not work

Symptom First thing to check
EnsureInitialized() returns Bus Your port's EnsureInitialized(): the UART did not come up
EnsureInitialized() returns Timeout Supply, wiring, the TX and RX swap, the baud rate
EnsureInitialized() returns DeviceIdMismatch The device is not an FDO2 (Troubleshooting)
MeasureOxygen() returns SensorFault The status word: Status and errors

Next