|
FDO2 Driver 0.1.0
API reference
|
Driver for one FDO2-G2 or FDO2 on a platform port. More...
#include <fdo2.hpp>
Public Member Functions | |
| FDO2 (Port &port, const Config &config={}) noexcept | |
| Bind the driver to a port and store the configuration. No I/O, cannot fail. | |
| FDO2 (const FDO2 &)=delete | |
| One driver object per module. | |
| FDO2 & | operator= (const FDO2 &)=delete |
| One driver object per module. | |
Lifecycle | |
| Result< void > | BeginInitialize () noexcept |
Start the module without waiting: validate the Config, bring the UART up, power the module through GpioSet(CtrlPin::Power) when the port has it, and enter PoweringUp. | |
| Result< void > | EnsureInitialized () noexcept |
BeginInitialize() and Poll() until it ends; needs DelayUs(). Bounded by the sum of the allowances. | |
| bool | IsInitialized () const noexcept |
| State | GetState () const noexcept |
| Result< void > | Deinitialize () noexcept |
Drop the operation in flight, leave the broadcast alone, set the power pin INACTIVE (when the port has it) and mark the driver uninitialised. A failed pin write is reported as Bus. | |
| Result< void > | Resync () noexcept |
Find the module again after StateUnknown: #VERS at the candidate baud rates (the rate being set, the declared rate, 19200), each with the expected CRC mode and, with CrcMode::Auto, the other one (a lost #CRCE echo leaves the two sides in different modes), then the broadcast check. A stream seen in StateUnknown does not make the call Busy. Needs DelayUs(). | |
| Result< void > | PowerCycle () noexcept |
Switch the module off through CtrlPin::Power, wait power_off_ms, switch it on and start again at 19200 baud. Needs the GpioSet() hook and DelayUs(). When a flash write may still be in progress the call first waits out its allowance (at most calibration_ms plus the margin): the supply is not cut during a flash cycle (datasheet 4.3, WARNING). | |
Non-blocking core | |
| Result< bool > | Poll () noexcept |
Advance the state machine and read what arrived, with the port's clock. One Read() of at most 64 bytes with a zero timeout per call (bytes left over from the last read are processed first). | |
| Result< bool > | Poll (uint32_t elapsed_us) noexcept |
Poll() for a port without a clock: the caller says how much time passed since the previous call. | |
| Result< void > | AbortOperation () noexcept |
Drop the operation in flight. A read is dropped into Draining; a flash write or #BAUD becomes StateUnknown (the bytes were sent). Never talks to the port. | |
| OperationKind | Pending () const noexcept |
| Result< void > | StartMeasureOxygen () noexcept |
Send #MOXY; Poll() ends it; GetOxygen() returns it. | |
| Result< void > | StartMeasureRaw () noexcept |
Send #MRAW; GetRaw() returns it. | |
| Result< void > | StartReadVersion () noexcept |
Send #VERS; GetVersion() returns it. | |
| Result< void > | StartReadUniqueId () noexcept |
Send #IDNR; GetUniqueId() returns it. | |
| Result< void > | StartIdentify () noexcept |
Send #LOGO: the status LED flashes four times. | |
| Result< void > | StartReadUserMemory (uint8_t first, uint8_t count) noexcept |
Send #RDUM first count. | |
| Result< void > | StartWriteUserMemory (uint8_t first, std::span< const int32_t > words) noexcept |
Send #WRUM first count Y... (a flash write, guarded). | |
| Result< void > | StartCalibrateZero (uint32_t steady_s) noexcept |
Send #CALO (a flash write; loses the factory calibration). | |
| Result< void > | StartCalibrateHigh (int32_t po2_mhpa, uint32_t steady_s) noexcept |
Send #CAHI P (a flash write; loses the factory calibration). | |
| Result< void > | StartSetCrcEnabled (bool enabled) noexcept |
Send #CRCE K (a flash write), then #VERS to verify the mode. | |
| Result< void > | StartSetMeasurementMode (uint8_t mode) noexcept |
Send #SETM M (a flash write; the FDO2-G2 only). | |
| Result< void > | StartSetBroadcast (uint32_t interval_ms) noexcept |
Send #BCST T (a flash write). | |
| Result< void > | StartSetBaudRate (uint32_t baud) noexcept |
Send #BAUD R, switch the port, then #VERS at the new rate. Needs the port's SetBaudRate(). | |
| Result< Oxygen > | GetOxygen () const noexcept |
| Result< Raw > | GetRaw () noexcept |
| Result< Version > | GetVersion () const noexcept |
| Result< uint64_t > | GetUniqueId () const noexcept |
| Result< std::span< const int32_t > > | GetUserMemory () const noexcept |
| Result< Raw > | GetLastFrame () const noexcept |
| The last decoded measurement frame even when the status policy rejected it, for diagnostics. Never present it as a measurement. | |
Blocking calls (need <tt>DelayUs()</tt>) | |
| Result< Oxygen > | MeasureOxygen () noexcept |
#MOXY, with the status and plausibility checks. | |
| Result< Raw > | MeasureRaw () noexcept |
#MRAW, with the same checks. | |
| Result< Raw > | ReadRawFrame () noexcept |
#MRAW once: the same checks as MeasureRaw() but a failed read is reported, never repeated. | |
| Result< int32_t > | MeasureVolumePercentMilli () noexcept |
Oxygen in 10^-3 volume percent: #MRAW, then VolumePercentMilli() with the module's back-side pressure or Config::pressure_reference_ubar. | |
| Result< Version > | ReadVersion () noexcept |
#VERS. | |
| Result< uint64_t > | ReadUniqueId () noexcept |
#IDNR. | |
| Result< void > | Identify () noexcept |
#LOGO: waits for the echo (about 1 s). | |
| Result< void > | ReadUserMemory (uint8_t first, std::span< int32_t > out) noexcept |
#RDUM first out.size(); fills out. | |
| Result< void > | WriteUserMemory (uint8_t first, std::span< const int32_t > in) noexcept |
#WRUM; see StartWriteUserMemory(). | |
| Result< void > | CalibrateZero (uint32_t steady_s) noexcept |
#CALO; up to 10 s. | |
| Result< void > | CalibrateHigh (int32_t po2_mhpa, uint32_t steady_s) noexcept |
#CAHI P; up to 10 s. | |
| Result< void > | CalibrateAir (uint32_t steady_s, uint32_t fraction_ppm=kDryAirO2Ppm) noexcept |
One-point calibration in dry ambient air: #MRAW for the pressure, then #CAHI with AirO2Mhpa(P, fraction_ppm). Only correct when the membrane sees dry air at the measured back-side pressure; humid air has a lower pO2 (A-10). | |
| Result< void > | SetCrcEnabled (bool enabled) noexcept |
#CRCE, then #VERS; see StartSetCrcEnabled(). | |
| Result< void > | SetMeasurementMode (uint8_t mode) noexcept |
#SETM; see StartSetMeasurementMode(). | |
| Result< void > | SetBroadcast (uint32_t interval_ms) noexcept |
#BCST T: with T above 0 the module streams and the driver enters Streaming. | |
| Result< void > | DisableBroadcast () noexcept |
#BCST 0: the vendor's workaround, sent right after a frame, among frames. | |
| Result< void > | SetBaudRate (uint32_t baud) noexcept |
#BAUD; see StartSetBaudRate(). | |
| Result< bool > | ProbeBroadcast (uint32_t window_ms) noexcept |
Listen without sending for a window and say whether #MRAW lines arrived. | |
Observers (no I/O) | |
| const Identity & | GetIdentity () const &noexcept |
| void | GetIdentity () const &&=delete |
| Not on a temporary driver: the reference would dangle (KB-CPP20-044). | |
| const Counters & | GetCounters () const &noexcept |
| void | GetCounters () const &&=delete |
| Not on a temporary driver. | |
| int32_t | DeviceErrorCode () const noexcept |
| const Config & | GetConfig () const &noexcept |
| void | GetConfig () const &&=delete |
| Not on a temporary driver. | |
| bool | CrcActive () const noexcept |
| uint8_t | FlashWritesUsed () const noexcept |
| bool | FlashWritePending () const noexcept |
| uint32_t | StreamSilentMs () const noexcept |
Driver for one FDO2-G2 or FDO2 on a platform port.
Lifecycle: construct with the configuration (no I/O), then BeginInitialize() and Poll() or EnsureInitialized(), use, optionally Deinitialize(). Every call that touches the module returns Error::NotInitialized until start-up has succeeded.
Optional port hooks, found at compile time:
void DelayUs(uint32_t us) noexcept: the blocking calls and PowerCycle(); without it the first blocking call is a compile error.uint32_t NowUs() noexcept: Poll() measures its own time; without it only Poll(elapsed_us) exists.bool SetBaudRate(uint32_t) noexcept: #BAUD and Resync(); without it SetBaudRate() returns Unsupported.bool GpioSet(CtrlPin, GpioSignal) noexcept: CtrlPin::Power at start-up, in Deinitialize() and in PowerCycle(); without it the application powers the module and PowerCycle() returns Unsupported.void Log(LogLevel, const char*) noexcept: one line per lifecycle event or failure; without it nothing is logged.A hook declared with the wrong signature is a compile error.
| Port | Your class derived from UartInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | Checked by BeginInitialize(), before any I/O. |
|
noexcept |
Drop the operation in flight. A read is dropped into Draining; a flash write or #BAUD becomes StateUnknown (the bytes were sent). Never talks to the port.
Ok.
|
noexcept |
Start the module without waiting: validate the Config, bring the UART up, power the module through GpioSet(CtrlPin::Power) when the port has it, and enter PoweringUp.
Poll() then waits power_up_ms, optionally listens for a stream, reads #VERS (device id 8, one channel, firmware 3.28 or later, an oxygen sensor), then #IDNR. On an initialised driver it returns Ok with no traffic.
Ok, InvalidArgument (Validate(), no I/O), Bus, Busy (an operation is in flight).
|
noexcept |
One-point calibration in dry ambient air: #MRAW for the pressure, then #CAHI with AirO2Mhpa(P, fraction_ppm). Only correct when the membrane sees dry air at the measured back-side pressure; humid air has a lower pO2 (A-10).
| steady_s | Seconds of steady measuring, at least Config::min_steady_s. |
| fraction_ppm | Oxygen fraction in ppm (kDryAirO2Ppm). |
CalibrateHigh(), and SensorFault unless the status is good.
|
noexcept |
#CAHI P; up to 10 s.
| po2_mhpa | The pO2 of the standard, 10^-3 hPa. |
| steady_s | Seconds of steady measuring. |
StartCalibrateHigh(), or the error of the wait.
|
noexcept |
#CALO; up to 10 s.
| steady_s | Seconds of steady measuring at 0 % oxygen. |
StartCalibrateZero(), or the error of the wait.
|
inlinenoexcept |
#VERS, verified after #CRCE).
|
noexcept |
Drop the operation in flight, leave the broadcast alone, set the power pin INACTIVE (when the port has it) and mark the driver uninitialised. A failed pin write is reported as Bus.
The supply is never cut while a flash write may be in progress (datasheet 4.3, WARNING: a power loss during a flash cycle can corrupt the memory): the call returns Busy, changes nothing, and succeeds once the echo has arrived or the write's allowance has elapsed (FlashWritePending() says which; the time passes with Poll()). On a port without NowUs() the time moves only through Poll(elapsed_us): a caller that never polls stays Busy.
Ok, Busy (a flash write is pending) or Bus.
|
inlinenoexcept |
#ERRO, 0 when none.
|
noexcept |
#BCST 0: the vendor's workaround, sent right after a frame, among frames.
Ok, NotPermitted, Timeout, or the error of the call.
|
noexcept |
BeginInitialize() and Poll() until it ends; needs DelayUs(). Bounded by the sum of the allowances.
Ok, or the error of the failed step: InvalidArgument, Bus, Timeout, DeviceIdMismatch, Unsupported (firmware below 3.28), BroadcastActive, NotPermitted, InvalidReply, Crc, DeviceError.
|
inlinenoexcept |
Deinitialize() and PowerCycle() do not cut the supply meanwhile. No I/O.
|
inlinenoexcept |
|
inlinenoexcept |
baud follows a confirmed #BAUD.
|
inlinenoexcept |
|
inlinenoexcept |
|
noexcept |
The last decoded measurement frame even when the status policy rejected it, for diagnostics. Never present it as a measurement.
InvalidArgument when there is none.
|
noexcept |
#MOXY; Busy while pending; InvalidArgument when there is none.
|
noexcept |
#MRAW (or the next broadcast frame while streaming, once per frame).
|
inlinenoexcept |
Streaming while the module streams). No I/O.
|
noexcept |
#IDNR reply.
|
noexcept |
#RDUM, valid until the next operation.
|
noexcept |
#VERS reply.
|
noexcept |
#LOGO: waits for the echo (about 1 s).
Ok or an error as ReadVersion().
|
inlinenoexcept |
Deinitialize(). No I/O.
|
noexcept |
#MOXY, with the status and plausibility checks.
SensorFault, OutOfRange, Timeout, Crc, InvalidReply, EchoMismatch, DeviceError, Bus, Busy, NotInitialized.
|
noexcept |
#MRAW, with the same checks.
MeasureOxygen().
|
noexcept |
Oxygen in 10^-3 volume percent: #MRAW, then VolumePercentMilli() with the module's back-side pressure or Config::pressure_reference_ubar.
SensorFault (bit 9 with the module's pressure), OutOfRange.
|
inlinenoexcept |
|
noexcept |
Advance the state machine and read what arrived, with the port's clock. One Read() of at most 64 bytes with a zero timeout per call (bytes left over from the last read are processed first).
|
noexcept |
|
noexcept |
Switch the module off through CtrlPin::Power, wait power_off_ms, switch it on and start again at 19200 baud. Needs the GpioSet() hook and DelayUs(). When a flash write may still be in progress the call first waits out its allowance (at most calibration_ms plus the margin): the supply is not cut during a flash cycle (datasheet 4.3, WARNING).
EnsureInitialized(), or Unsupported without the hook.
|
noexcept |
Listen without sending for a window and say whether #MRAW lines arrived.
| window_ms | The window, 1 to 12000 ms (10500 covers every interval). |
true when a broadcast frame was seen.
|
noexcept |
#MRAW once: the same checks as MeasureRaw() but a failed read is reported, never repeated.
MeasureRaw().
|
noexcept |
#IDNR.
ReadVersion().
|
noexcept |
#RDUM first out.size(); fills out.
| first | The first word, 0 to 63. |
| out | Receives 1 to 64 words, with first + out.size() <= 64. |
Ok, InvalidArgument, Unsupported, or an error as ReadVersion().
|
noexcept |
#VERS.
Timeout, Crc, InvalidReply, EchoMismatch, DeviceError, Bus, Busy.
|
noexcept |
Find the module again after StateUnknown: #VERS at the candidate baud rates (the rate being set, the declared rate, 19200), each with the expected CRC mode and, with CrcMode::Auto, the other one (a lost #CRCE echo leaves the two sides in different modes), then the broadcast check. A stream seen in StateUnknown does not make the call Busy. Needs DelayUs().
Ok, Busy, NotInitialized, Timeout (nothing answered), DeviceIdMismatch (another module answered), BroadcastActive.
|
noexcept |
#BAUD; see StartSetBaudRate().
| baud | A rate of kBaudRates. |
Ok, InvalidArgument, Unsupported, or the error of the call.
|
noexcept |
#BCST T: with T above 0 the module streams and the driver enters Streaming.
| interval_ms | 0 (off) or 100 to 10000 ms. |
Ok or the error of the call.
|
noexcept |
#CRCE, then #VERS; see StartSetCrcEnabled().
| enabled | Whether replies carry the CRC. |
Ok or the error of the call.
|
noexcept |
#SETM; see StartSetMeasurementMode().
| mode | The measurement mode, 0 to 4. |
Ok or the error of the call.
|
noexcept |
Send #CAHI P (a flash write; loses the factory calibration).
| po2_mhpa | The pO2 of the standard, 10^-3 hPa, above 0 and at most o2_max_mhpa. |
| steady_s | Seconds of steady measuring, at least Config::min_steady_s. |
StartCalibrateZero().
|
noexcept |
Send #CALO (a flash write; loses the factory calibration).
| steady_s | Seconds the module has measured steadily at 0 % oxygen; at least Config::min_steady_s. |
NotPermitted, InvalidArgument or the common start errors.
|
noexcept |
Send #LOGO: the status LED flashes four times.
Ok, or Busy, NotInitialized, StateUnknown, Bus (nothing was sent when it is not Ok).
|
noexcept |
Send #MOXY; Poll() ends it; GetOxygen() returns it.
Ok, or Busy, NotInitialized, StateUnknown, Bus (nothing was sent when it is not Ok).
|
noexcept |
Send #MRAW; GetRaw() returns it.
Ok, or Busy, NotInitialized, StateUnknown, Bus (nothing was sent when it is not Ok).
|
noexcept |
Send #IDNR; GetUniqueId() returns it.
Ok, or Busy, NotInitialized, StateUnknown, Bus (nothing was sent when it is not Ok).
|
noexcept |
Send #RDUM first count.
| first | The first word, 0 to 63. |
| count | The number of words, 1 to 64, with first + count <= 64. |
InvalidArgument for a range error (nothing sent), or the common start errors.
|
noexcept |
Send #VERS; GetVersion() returns it.
Ok, or Busy, NotInitialized, StateUnknown, Bus (nothing was sent when it is not Ok).
|
noexcept |
Send #BAUD R, switch the port, then #VERS at the new rate. Needs the port's SetBaudRate().
| baud | A rate of kBaudRates. |
InvalidArgument, Unsupported (no hook), or the common start errors.
|
noexcept |
Send #BCST T (a flash write).
| interval_ms | 0 (off) or 100 to 10000 ms. |
NotPermitted, InvalidArgument, Unsupported, or the common start errors.
|
noexcept |
Send #CRCE K (a flash write), then #VERS to verify the mode.
| enabled | Whether replies carry the CRC. |
NotPermitted, InvalidArgument (against Config::crc), or the common start errors.
|
noexcept |
Send #SETM M (a flash write; the FDO2-G2 only).
| mode | The measurement mode, 0 to 4. |
NotPermitted, InvalidArgument, Unsupported, or the common start errors.
|
noexcept |
Send #WRUM first count Y... (a flash write, guarded).
| first | The first word. |
| words | The values; 1 to 64 with first + size <= 64. |
NotPermitted without consent or over the budget, InvalidArgument, Unsupported.
|
noexcept |
|
noexcept |
#WRUM; see StartWriteUserMemory().
| first | The first word. |
| in | The values to store. |
NotPermitted, InvalidArgument, Unsupported, StateUnknown after a lost echo, or a bus error.