FDO2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Concepts | Enumerations | Functions | Variables
fdo2 Namespace Reference

The FDO2 driver: everything it declares lives here; internals in detail. More...

Classes

struct  Capabilities
 What the firmware revision offers (derived from datasheet 5; CapabilitiesFor). More...
 
class  CheckedConfig
 A configuration proven valid at build time. More...
 
struct  Config
 Everything the driver needs from the application, with the datasheet defaults. More...
 
struct  Counters
 Counters of what happened on the line; they only grow (docs/non-blocking.md). More...
 
class  FDO2
 Driver for one FDO2-G2 or FDO2 on a platform port. More...
 
struct  Identity
 Who the module is: #VERS, #IDNR, the family and what follows from the firmware. More...
 
class  LineAssembler
 Collects the bytes of a reply into lines, one byte at a time (datasheet 4.1: one CR ends a reply). More...
 
struct  Oxygen
 #MOXY result: oxygen partial pressure, temperature and status. More...
 
struct  ParsedLine
 A parsed reply line. More...
 
struct  ParseOptions
 How ParseLine() treats the CRC and the spacing (from the Config). More...
 
struct  Raw
 #MRAW result: the Oxygen fields plus the raw values. More...
 
struct  Result
 The value of a call, or why there is none. More...
 
struct  Result< void >
 The result of a call that returns no value. More...
 
struct  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...
 
class  UartInterface
 CRTP base of the platform UART port. More...
 
struct  Version
 #VERS result (datasheet 4.3, #VERS). More...
 

Concepts

concept  UartPort
 Satisfied by a class that derives from UartInterface<Port> and implements the required hooks with exactly the types above and noexcept.
 

Enumerations

enum class  Command : uint8_t {
  Command::Vers = 0 , Command::Idnr , Command::Moxy , Command::Mraw ,
  Command::Logo , Command::Crce , Command::Rdum , Command::Wrum ,
  Command::Baud , Command::Calo , Command::Cahi , Command::Bcst ,
  Command::Setm
}
 The thirteen commands of the module (datasheet 4.3). More...
 
enum class  PushResult : uint8_t { PushResult::Pending = 0 , PushResult::Line , PushResult::Bad }
 What LineAssembler::PushByte() did with a byte. More...
 
enum class  ParseStatus : uint8_t { ParseStatus::Ok = 0 , ParseStatus::BadCrc , ParseStatus::Malformed }
 The outcome class of ParseLine(). More...
 
enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch = 5 , Error::Crc = 6 , Error::Busy = 7 ,
  Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::DeviceError = 16 , Error::InvalidReply = 17 ,
  Error::EchoMismatch = 18 , Error::SensorFault = 19 , Error::OutOfRange = 20 , Error::CalibrationRejected = 21 ,
  Error::NotPermitted = 22 , Error::StateUnknown = 23 , Error::BroadcastActive = 24 , Error::NotReady = 25
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Family : uint8_t { Family::Fdo2G2 = 0 , Family::Fdo2 = 1 }
 The module generation the driver talks to (datasheet 1.1; ambiguity A-3). More...
 
enum class  CrcMode : uint8_t { CrcMode::Auto = 0 , CrcMode::Off = 1 , CrcMode::Required = 2 }
 Whether replies carry the CRC-16 suffix (datasheet 4.2). More...
 
enum class  StatusPolicy : uint8_t { StatusPolicy::Datasheet = 0 , StatusPolicy::Documented }
 What a status word other than 0 or 1 does (datasheet 4.3, ambiguity A-1). More...
 
enum class  BroadcastPolicy : uint8_t { BroadcastPolicy::Refuse = 0 , BroadcastPolicy::Stream = 1 , BroadcastPolicy::Disable = 2 }
 What start-up does when the module streams #MRAW lines (datasheet 4.3, #BCST). More...
 
enum class  Quality : uint8_t { Quality::Good = 0 , Quality::Warning = 1 , Quality::Degraded = 2 , Quality::Invalid = 3 }
 How far a reading can be trusted, from the status word. More...
 
enum class  OperationKind : uint8_t {
  OperationKind::None = 0 , OperationKind::Initialize , OperationKind::Version , OperationKind::UniqueId ,
  OperationKind::MeasureOxygen , OperationKind::MeasureRaw , OperationKind::Identify , OperationKind::ReadUserMemory ,
  OperationKind::WriteUserMemory , OperationKind::CalibrateZero , OperationKind::CalibrateHigh , OperationKind::SetCrc ,
  OperationKind::SetMeasurementMode , OperationKind::SetBroadcast , OperationKind::SetBaudRate
}
 The operation the driver has in flight. More...
 
enum class  State : uint8_t {
  State::Uninitialized = 0 , State::PoweringUp , State::Idle , State::Waiting ,
  State::Streaming , State::Draining , State::StateUnknown
}
 The driver's state machine (docs/non-blocking.md). More...
 
enum class  CtrlPin : uint8_t { Power = 0 }
 Control pins the port may drive through the optional GpioSet() hook. More...
 
enum class  GpioSignal : uint8_t { INACTIVE = 0 , ACTIVE = 1 }
 Logical level of a control pin; the port maps it to the physical polarity. More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the defaults of Config{}.
 
constexpr const char * HeaderOf (Command command) noexcept
 The four header letters of a command, without the #.
 
template<typename T >
requires (std::is_same_v<T, uint8_t> || std::is_same_v<T, char>)
constexpr uint16_t Crc16Modbus (std::span< const T > data) noexcept
 The CRC-16/MODBUS of a byte or character string (polynomial 0xA001 reflected, start 0xFFFF), as the module computes it over the reply before the colon (datasheet 4.2). "123456789" gives 0x4B37.
 
constexpr std::size_t EncodeCommand (Command command, std::span< const int32_t > args, std::span< char > out) noexcept
 Encode a command line: #HEAD, each argument as plain decimal with one space before it, and one carriage return (never a LF: datasheet 4.1 allows CR or CR LF, the driver sends CR).
 
constexpr ParsedLine ParseLine (std::span< const char > line, const ParseOptions &options) noexcept
 Parse one reply line (without its CR) under the grammar of datasheet 4.
 
constexpr std::size_t ExpectedCount (Command command, std::span< const int32_t > args) noexcept
 How many values the reply to a command holds (datasheet 4.3).
 
constexpr bool VerifyEcho (Command command, std::span< const int32_t > args, const ParsedLine &reply) noexcept
 The echo check of datasheet 4.2: the header and the echoed arguments equal what was sent.
 
constexpr uint32_t MaxReplyChars (Command command, uint32_t words) noexcept
 The longest reply of a command, in characters including the CR and a CRC suffix, for the deadline (derived from datasheet 4.1 and 4.3: #MRAW with eight 11-character values).
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Capabilities CapabilitiesFor (Family family, int32_t firmware) noexcept
 What a firmware revision offers.
 
constexpr bool HasNoiseErratum (int32_t firmware) noexcept
 Whether a firmware revision shows the noise erratum (datasheet G2 6.1, G1 6.4).
 
constexpr bool IsSupportedBaud (uint32_t baud) noexcept
 Whether baud is one of the eleven rates.
 
constexpr uint32_t AirtimeUs (uint32_t chars, uint32_t baud) noexcept
 Time to send chars characters, 10 bits each at 8N1.
 
constexpr Error Validate (const Config &config) noexcept
 Check a configuration without touching the module (zero port traffic).
 
void 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 > 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 > 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 > AirO2Mhpa (int32_t pressure_ubar) noexcept
 AirO2Mhpa() for standard dry air.
 
constexpr int32_t 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 * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

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

What the FDO2 needs from the UART and its supply (datasheet sections 2 and 4). A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123).

constexpr uint32_t kPortDefaultBaud = 19'200
 Rate after every power-up (datasheet 4).
 
constexpr uint32_t kLogicLevelMv = 3000
 Logic level of the module's UART, millivolts (datasheet 2, Interface).
 
constexpr uint32_t kMaxLogicLevelMv = 3300
 Absolute maximum on the module's UART pins, millivolts: a 5 V host needs a level shifter.
 
constexpr uint32_t kSupplyMinMv = 3300
 Lowest supply the datasheet allows, millivolts (below it the readings can be wrong).
 
constexpr uint32_t kSupplyMaxMv = 5000
 Highest supply, millivolts (absolute maximum 5.5 V).
 
constexpr uint32_t kPowerUpMs = 1000
 Time from power to the first answer, milliseconds ("ca. 1 sec", datasheet 4).
 
constexpr uint32_t kRxBufferBytes = 800
 Receive buffer a port needs to never lose a #RDUM reply, bytes (or it polls every 300 ms).
 
constexpr uint32_t kMaxBaudRate = 115'200
 Highest baud rate the module accepts (datasheet 4.3, #BAUD).
 
constexpr uint32_t kTurnaroundUs = 2000
 

Detailed Description

The FDO2 driver: everything it declares lives here; internals in detail.

Enumeration Type Documentation

◆ CtrlPin

enum class fdo2::CtrlPin : uint8_t
strong

Control pins the port may drive through the optional GpioSet() hook.

Enumerator
Power 

Supply switch of the module: ACTIVE powers it. It idles INACTIVE (off).

◆ GpioSignal

enum class fdo2::GpioSignal : uint8_t
strong

Logical level of a control pin; the port maps it to the physical polarity.

Enumerator
INACTIVE 

The pin function is deasserted (module unpowered).

ACTIVE 

The pin function is asserted (module powered).

Function Documentation

◆ KconfigDefaults()

constexpr Config fdo2::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the defaults of Config{}.

Returns
Config{} with the family, status policy, power-up wait, measurement allowance, retries, CRC mode, broadcast policy and the flash-write guard taken from Kconfig.

Variable Documentation

◆ kTurnaroundUs

constexpr uint32_t fdo2::kTurnaroundUs = 2000
inlineconstexpr

Design value: the longest wait from the last request byte to the first reply byte that the driver treats as normal, microseconds. The datasheet gives no turnaround; the allowances cover it.