FDO2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, status, measurements, configuration and conversions. More...

Classes

struct  fdo2::Result< T >
 The value of a call, or why there is none. More...
 
struct  fdo2::Result< void >
 The result of a call that returns no value. More...
 
struct  fdo2::Status
 The status word S of #MOXY and #MRAW, decoded (datasheet 4.3, #MOXY). Pure functions of the word; the word is kept whole. More...
 
struct  fdo2::Oxygen
 #MOXY result: oxygen partial pressure, temperature and status. More...
 
struct  fdo2::Raw
 #MRAW result: the Oxygen fields plus the raw values. More...
 
struct  fdo2::Version
 #VERS result (datasheet 4.3, #VERS). More...
 
struct  fdo2::Capabilities
 What the firmware revision offers (derived from datasheet 5; CapabilitiesFor). More...
 
struct  fdo2::Identity
 Who the module is: #VERS, #IDNR, the family and what follows from the firmware. More...
 
struct  fdo2::Counters
 Counters of what happened on the line; they only grow (docs/non-blocking.md). More...
 
struct  fdo2::Config
 Everything the driver needs from the application, with the datasheet defaults. More...
 
class  fdo2::CheckedConfig
 A configuration proven valid at build time. More...
 

Enumerations

enum class  fdo2::Error : uint8_t {
  fdo2::Error::Ok = 0 , fdo2::Error::NotInitialized = 1 , fdo2::Error::InvalidArgument = 2 , fdo2::Error::Bus = 3 ,
  fdo2::Error::Timeout = 4 , fdo2::Error::DeviceIdMismatch = 5 , fdo2::Error::Crc = 6 , fdo2::Error::Busy = 7 ,
  fdo2::Error::DeviceFault = 8 , fdo2::Error::Unsupported = 9 , fdo2::Error::DeviceError = 16 , fdo2::Error::InvalidReply = 17 ,
  fdo2::Error::EchoMismatch = 18 , fdo2::Error::SensorFault = 19 , fdo2::Error::OutOfRange = 20 , fdo2::Error::CalibrationRejected = 21 ,
  fdo2::Error::NotPermitted = 22 , fdo2::Error::StateUnknown = 23 , fdo2::Error::BroadcastActive = 24 , fdo2::Error::NotReady = 25
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  fdo2::LogLevel : uint8_t { fdo2::LogLevel::Error = 0 , fdo2::LogLevel::Warning , fdo2::LogLevel::Info , fdo2::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  fdo2::Family : uint8_t { fdo2::Family::Fdo2G2 = 0 , fdo2::Family::Fdo2 = 1 }
 The module generation the driver talks to (datasheet 1.1; ambiguity A-3). More...
 
enum class  fdo2::CrcMode : uint8_t { fdo2::CrcMode::Auto = 0 , fdo2::CrcMode::Off = 1 , fdo2::CrcMode::Required = 2 }
 Whether replies carry the CRC-16 suffix (datasheet 4.2). More...
 
enum class  fdo2::StatusPolicy : uint8_t { fdo2::StatusPolicy::Datasheet = 0 , fdo2::StatusPolicy::Documented }
 What a status word other than 0 or 1 does (datasheet 4.3, ambiguity A-1). More...
 
enum class  fdo2::BroadcastPolicy : uint8_t { fdo2::BroadcastPolicy::Refuse = 0 , fdo2::BroadcastPolicy::Stream = 1 , fdo2::BroadcastPolicy::Disable = 2 }
 What start-up does when the module streams #MRAW lines (datasheet 4.3, #BCST). More...
 
enum class  fdo2::Quality : uint8_t { fdo2::Quality::Good = 0 , fdo2::Quality::Warning = 1 , fdo2::Quality::Degraded = 2 , fdo2::Quality::Invalid = 3 }
 How far a reading can be trusted, from the status word. More...
 
enum class  fdo2::OperationKind : uint8_t {
  fdo2::OperationKind::None = 0 , fdo2::OperationKind::Initialize , fdo2::OperationKind::Version , fdo2::OperationKind::UniqueId ,
  fdo2::OperationKind::MeasureOxygen , fdo2::OperationKind::MeasureRaw , fdo2::OperationKind::Identify , fdo2::OperationKind::ReadUserMemory ,
  fdo2::OperationKind::WriteUserMemory , fdo2::OperationKind::CalibrateZero , fdo2::OperationKind::CalibrateHigh , fdo2::OperationKind::SetCrc ,
  fdo2::OperationKind::SetMeasurementMode , fdo2::OperationKind::SetBroadcast , fdo2::OperationKind::SetBaudRate
}
 The operation the driver has in flight. More...
 
enum class  fdo2::State : uint8_t {
  fdo2::State::Uninitialized = 0 , fdo2::State::PoweringUp , fdo2::State::Idle , fdo2::State::Waiting ,
  fdo2::State::Streaming , fdo2::State::Draining , fdo2::State::StateUnknown
}
 The driver's state machine (docs/non-blocking.md). More...
 

Functions

constexpr const char * fdo2::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Capabilities fdo2::CapabilitiesFor (Family family, int32_t firmware) noexcept
 What a firmware revision offers.
 
constexpr bool fdo2::HasNoiseErratum (int32_t firmware) noexcept
 Whether a firmware revision shows the noise erratum (datasheet G2 6.1, G1 6.4).
 
constexpr bool fdo2::IsSupportedBaud (uint32_t baud) noexcept
 Whether baud is one of the eleven rates.
 
constexpr uint32_t fdo2::AirtimeUs (uint32_t chars, uint32_t baud) noexcept
 Time to send chars characters, 10 bits each at 8N1.
 
constexpr Error fdo2::Validate (const Config &config) noexcept
 Check a configuration without touching the module (zero port traffic).
 
void fdo2::ConfigIsInvalid () noexcept
 Reached only when a CheckedConfig is built from an invalid configuration: it is never defined, so the build fails and names it (KB-CPP20-013).
 
constexpr Result< int32_t > fdo2::VolumePercentMilli (int32_t o2_mhpa, int32_t pressure_ubar) noexcept
 The oxygen content in volume percent of the gas at the membrane (datasheet 2, p. 6): 100 x pO2 / p, in 10^-3 percent, rounded half up.
 
constexpr Result< int32_t > fdo2::AirO2Mhpa (int32_t pressure_ubar, uint32_t fraction_ppm) noexcept
 The pO2 of dry air at a pressure, for a one-point calibration (A-10).
 
constexpr Result< int32_t > fdo2::AirO2Mhpa (int32_t pressure_ubar) noexcept
 AirO2Mhpa() for standard dry air.
 
constexpr int32_t fdo2::AmbientLoadMv (const Raw &raw) noexcept
 Sum of ambient light and signal intensity in millivolts, for the 2000 mV advice (datasheet 4.3, #MRAW, ambient light).
 
constexpr const char * fdo2::GetDriverVersion () noexcept
 
constexpr uint32_t fdo2::GetDriverVersionMajor () noexcept
 
constexpr uint32_t fdo2::GetDriverVersionMinor () noexcept
 
constexpr uint32_t fdo2::GetDriverVersionPatch () noexcept
 

Variables

constexpr int32_t fdo2::kMinFirmware = 328
 Lowest firmware revision any document covers: 3.28 (datasheet G1, 5).
 
constexpr int32_t fdo2::kFirmwareBroadcast = 341
 First revision with the #BCST command, the persistent #CRCE and the broadcast bug fix 3.53.
 
constexpr int32_t fdo2::kFirmwareStatusBit0 = 329
 First revision with status bit 0.
 
constexpr int32_t fdo2::kFirmwareCalibrationError = 351
 First revision with #ERRO -60.
 
constexpr int32_t fdo2::kFirmwareTempFlag = 354
 First revision whose temperature-sensor failure sets status bit 5.
 
constexpr int32_t fdo2::kFirmwareG2 = 355
 First revision of the FDO2-G2 (the first with #SETM).
 
constexpr int32_t fdo2::kDeviceId = 8
 First revision of the FDO2 (the device id of both families).
 
constexpr int32_t fdo2::kChannels = 1
 Number of oxygen channels.
 
constexpr int32_t fdo2::kSensorOxygen = 1
 #VERS sensor mask bit: oxygen.
 
constexpr uint32_t fdo2::kUserMemoryWords = 64
 Words of user memory (#RDUM, #WRUM).
 
constexpr uint32_t fdo2::kBroadcastMinMs = 100
 Shortest and longest broadcast interval, milliseconds (#BCST).
 
constexpr uint32_t fdo2::kBroadcastMaxMs = 10'000
 Longest broadcast interval, milliseconds.
 
constexpr uint32_t fdo2::kMaxMeasurementMode = 4
 Highest #SETM mode.
 
constexpr uint32_t fdo2::kWarmUpSeconds = 180
 Warm-up after power-up, seconds (datasheet 2, Specifications).
 
constexpr std::array< uint32_t, 11 > fdo2::kBaudRates
 The baud rates #BAUD accepts, ascending (datasheet 4.3, #BAUD).
 
constexpr uint32_t fdo2::kDefaultBaud = 19'200
 The rate after every power-up.
 
constexpr uint32_t fdo2::kPowerUpMsMin = 1000
 Bounds of the Config fields, shared by Validate() and the docs.
 
constexpr uint32_t fdo2::kPowerUpMsMax = 30'000
 Largest Config::power_up_ms, ms.
 
constexpr uint32_t fdo2::kCommandMsMin = 10
 Smallest Config::command_ms, ms.
 
constexpr uint32_t fdo2::kCommandMsMax = 5000
 Largest Config::command_ms, ms.
 
constexpr uint32_t fdo2::kMeasurementMsMin = 50
 Smallest Config::measurement_ms, ms.
 
constexpr uint32_t fdo2::kMeasurementMsMax = 5000
 Largest Config::measurement_ms, ms.
 
constexpr uint32_t fdo2::kCalibrationMsMin = 10'000
 Smallest Config::calibration_ms, ms.
 
constexpr uint32_t fdo2::kCalibrationMsMax = 60'000
 Largest Config::calibration_ms, ms.
 
constexpr uint32_t fdo2::kFlashMsMin = 100
 Smallest Config::flash_ms, ms.
 
constexpr uint32_t fdo2::kFlashMsMax = 30'000
 Largest Config::flash_ms, ms.
 
constexpr uint32_t fdo2::kLogoMsMin = 100
 Smallest Config::logo_ms, ms.
 
constexpr uint32_t fdo2::kLogoMsMax = 10'000
 Largest Config::logo_ms, ms.
 
constexpr uint32_t fdo2::kMarginMsMax = 1000
 Largest Config::margin_ms, ms.
 
constexpr uint32_t fdo2::kPowerOffMsMin = 10
 Smallest Config::power_off_ms, ms.
 
constexpr uint32_t fdo2::kPowerOffMsMax = 10'000
 Largest Config::power_off_ms, ms.
 
constexpr uint8_t fdo2::kRetriesMax = 3
 Largest Config::retries.
 
constexpr uint32_t fdo2::kBroadcastListenMsMax
 Largest Config::broadcast_listen_ms, ms (covers the longest interval).
 
constexpr uint8_t fdo2::kFlashBudgetMax = 64
 Largest Config::max_flash_writes.
 
constexpr uint16_t fdo2::kMinSteadyMax = 3600
 Largest Config::min_steady_s, s.
 
constexpr uint8_t fdo2::kCalWindowPctMax = 100
 Largest Config::cal_window_pct.
 
constexpr int32_t fdo2::kCalWindowMinMhpaMin = 1000
 Smallest Config::cal_window_min_mhpa.
 
constexpr int32_t fdo2::kCalWindowMinMhpaMax = 50'000
 
constexpr int32_t fdo2::kCalHighMinMhpa = 10'000
 
constexpr int32_t fdo2::kCalHighMaxMhpa = 2'000'000
 Highest standard #CAHI accepts: the maximum measuring range, 2000 hPa (2, not specified).
 
constexpr uint32_t fdo2::kDryAirO2Ppm = 209'500
 Fraction of oxygen in dry air, parts per million (standard dry air, assumption A-10).
 

Detailed Description

Errors, results, status, measurements, configuration and conversions.

Enumeration Type Documentation

◆ BroadcastPolicy

enum class fdo2::BroadcastPolicy : uint8_t
strong

What start-up does when the module streams #MRAW lines (datasheet 4.3, #BCST).

Enumerator
Refuse 

Fail with BroadcastActive; the driver stays uninitialised.

Stream 

Go to the Streaming state and decode the frames.

Disable 

Send #BCST 0 (a flash write: needs allow_persistent_writes).

◆ CrcMode

enum class fdo2::CrcMode : uint8_t
strong

Whether replies carry the CRC-16 suffix (datasheet 4.2).

Enumerator
Auto 

Learn from the first #VERS reply: a suffix means CRC is on.

Off 

Never expect a suffix: a reply with one is InvalidReply.

Required 

Every reply must carry a valid suffix (except #ERRO with erro_without_crc).

◆ Error

enum class fdo2::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. [[nodiscard]] on the type: a function that returns a bare Error cannot have it ignored either (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

A port hook returned false.

Timeout 

No complete reply within the deadline (datasheet 4.1, 4.3).

DeviceIdMismatch 

#VERS is not an FDO2 with an oxygen sensor: wrong device or wiring.

Crc 

The CRC-16 of a reply did not match (datasheet 4.2).

Busy 

An operation is pending, draining or the module streams.

DeviceFault 

#ERRO with a code the datasheet calls potentially fatal (4.4).

Unsupported 

The hook, firmware revision or family does not offer this call.

DeviceError 

#ERRO -1, -21, -22 or -23: the module could not do it.

InvalidReply 

A line the protocol grammar refuses (bytes, header, tokens, number).

EchoMismatch 

The header or an echoed value differs from what was sent (4.2).

SensorFault 

The status word was rejected by the StatusPolicy (4.3, #MOXY).

OutOfRange 

A decoded value is outside the plausibility window of the Config.

CalibrationRejected 

#ERRO -60: the calibration is outside the expected range.

NotPermitted 

A flash-writing call without consent, or over the write budget.

StateUnknown 

A flash write or baud change ended without a confirmed echo.

BroadcastActive 

The module streams #MRAW lines and the call needs it silent.

NotReady 

Warming up: a calibration needs a settled sensor (datasheet 2).

◆ Family

enum class fdo2::Family : uint8_t
strong

The module generation the driver talks to (datasheet 1.1; ambiguity A-3).

Enumerator
Fdo2G2 

FDO2-G2, the current module (firmware 3.55 and later); #SETM is documented.

Fdo2 

FDO2, the legacy module (firmware 3.28 to 3.55); no #SETM in its data sheet.

◆ LogLevel

enum class fdo2::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised, reset.

Debug 

Detail for bring-up.

◆ OperationKind

enum class fdo2::OperationKind : uint8_t
strong

The operation the driver has in flight.

Enumerator
None 

Nothing pending.

Initialize 

BeginInitialize() and its #VERS and #IDNR steps.

Version 

#VERS.

UniqueId 

#IDNR.

MeasureOxygen 

#MOXY.

MeasureRaw 

#MRAW.

Identify 

#LOGO.

ReadUserMemory 

#RDUM.

WriteUserMemory 

#WRUM.

CalibrateZero 

#CALO.

CalibrateHigh 

#CAHI.

SetCrc 

#CRCE.

SetMeasurementMode 

#SETM.

SetBroadcast 

#BCST.

SetBaudRate 

#BAUD.

◆ Quality

enum class fdo2::Quality : uint8_t
strong

How far a reading can be trusted, from the status word.

Enumerator
Good 

S = 0.

Warning 

S = 1: detector amplification reduced, the reading is valid.

Degraded 

No fatal or undefined bit; bit 7, 9 or 10 set.

Invalid 

A fatal bit (1 to 5) or an undefined bit.

◆ State

enum class fdo2::State : uint8_t
strong

The driver's state machine (docs/non-blocking.md).

Enumerator
Uninitialized 

Nothing started, or Deinitialize() ran.

PoweringUp 

Waiting power_up_ms before the first command.

Idle 

Ready for a call.

Waiting 

An operation is waiting for its reply.

Streaming 

The module sends #MRAW lines by itself.

Draining 

Discarding input after a failed read, so a late reply is never taken.

StateUnknown 

A flash write or baud change ended without a confirmed echo.

◆ StatusPolicy

enum class fdo2::StatusPolicy : uint8_t
strong

What a status word other than 0 or 1 does (datasheet 4.3, ambiguity A-1).

Enumerator
Datasheet 

"S should always be 0 or 1": any other word is SensorFault.

Documented 

Only fatal and undefined bits are SensorFault; bits 7, 9, 10 are Degraded.

Function Documentation

◆ AirO2Mhpa() [1/2]

constexpr Result< int32_t > fdo2::AirO2Mhpa ( int32_t  pressure_ubar)
constexprnoexcept

AirO2Mhpa() for standard dry air.

Parameters
pressure_ubarThe pressure, microbar.
Returns
See above.

◆ AirO2Mhpa() [2/2]

constexpr Result< int32_t > fdo2::AirO2Mhpa ( int32_t  pressure_ubar,
uint32_t  fraction_ppm 
)
constexprnoexcept

The pO2 of dry air at a pressure, for a one-point calibration (A-10).

Parameters
pressure_ubarThe pressure, microbar.
fraction_ppmThe oxygen fraction, parts per million (kDryAirO2Ppm for dry air).
Returns
10^-3 hPa, rounded; InvalidArgument for a pressure of 0 or below, or a fraction of 0 or above 1000000. Humid air has a lower pO2 than this and is not corrected.

◆ AirtimeUs()

constexpr uint32_t fdo2::AirtimeUs ( uint32_t  chars,
uint32_t  baud 
)
constexprnoexcept

Time to send chars characters, 10 bits each at 8N1.

Parameters
charsThe number of characters.
baudThe rate; 0 gives 0.
Returns
Microseconds, rounded up.

◆ AmbientLoadMv()

constexpr int32_t fdo2::AmbientLoadMv ( const Raw &  raw)
constexprnoexcept

Sum of ambient light and signal intensity in millivolts, for the 2000 mV advice (datasheet 4.3, #MRAW, ambient light).

Parameters
rawA #MRAW result.
Returns
(A + I) / 1000 using 64-bit arithmetic.

◆ CapabilitiesFor()

constexpr Capabilities fdo2::CapabilitiesFor ( Family  family,
int32_t  firmware 
)
constexprnoexcept

What a firmware revision offers.

Parameters
familyThe module generation.
firmwareR of #VERS, 100 x major + minor.
Returns
The capabilities; all false below kMinFirmware.

◆ GetDriverVersion()

constexpr const char * fdo2::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated fdo2_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t fdo2::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t fdo2::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t fdo2::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ HasNoiseErratum()

constexpr bool fdo2::HasNoiseErratum ( int32_t  firmware)
constexprnoexcept

Whether a firmware revision shows the noise erratum (datasheet G2 6.1, G1 6.4).

Parameters
firmwareR of #VERS.
Returns
true for 3.54 and 3.55 (before the 3.57 hardware change); informational only.

◆ IsSupportedBaud()

constexpr bool fdo2::IsSupportedBaud ( uint32_t  baud)
constexprnoexcept

Whether baud is one of the eleven rates.

Parameters
baudThe rate.
Returns
true when #BAUD accepts it.

◆ ToString()

constexpr const char * fdo2::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Timeout"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error fdo2::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the module (zero port traffic).

Fails when a baud rate is not one of the eleven, a timeout is out of its bound, retries is above 3, an enumeration holds a value that is not an enumerator, the plausibility windows are not ordered, pressure_reference_ubar is neither 0 nor inside the pressure window, or max_flash_writes is outside 1 to 64, cal_window_pct is outside 1 to 100 or cal_window_min_mhpa is outside 1000 to 50000.

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument.

◆ VolumePercentMilli()

constexpr Result< int32_t > fdo2::VolumePercentMilli ( int32_t  o2_mhpa,
int32_t  pressure_ubar 
)
constexprnoexcept

The oxygen content in volume percent of the gas at the membrane (datasheet 2, p. 6): 100 x pO2 / p, in 10^-3 percent, rounded half up.

The factor 1000 of the two units cancels (o2_mhpa and pressure_ubar are both thousandths).

Parameters
o2_mhpaThe partial pressure, 10^-3 hPa.
pressure_ubarThe total pressure at the membrane, microbar (equal to 10^-3 hPa).
Returns
10^-3 percent (20351 is 20.351 percent); InvalidArgument for a pressure of 0 or below, OutOfRange when the result does not fit 32 bits. Never a silent 0.

Variable Documentation

◆ kBaudRates

constexpr std::array<uint32_t, 11> fdo2::kBaudRates
inlineconstexpr
Initial value:
= {1200, 2400, 4800, 9600, 14400, 19200,
28800, 38400, 56000, 57600, 115200}

The baud rates #BAUD accepts, ascending (datasheet 4.3, #BAUD).

◆ kBroadcastListenMsMax

constexpr uint32_t fdo2::kBroadcastListenMsMax
inlineconstexpr
Initial value:
=
12'000

Largest Config::broadcast_listen_ms, ms (covers the longest interval).

◆ kCalHighMinMhpa

constexpr int32_t fdo2::kCalHighMinMhpa = 10'000
inlineconstexpr

Lowest standard #CAHI accepts: the datasheet gives accuracy from 10 hPa up (2); below that the zero point #CALO is the right call.

◆ kCalWindowMinMhpaMax

constexpr int32_t fdo2::kCalWindowMinMhpaMax = 50'000
inlineconstexpr

◆ kPowerUpMsMin

constexpr uint32_t fdo2::kPowerUpMsMin = 1000
inlineconstexpr

Bounds of the Config fields, shared by Validate() and the docs.

Smallest Config::power_up_ms, ms.