SFM_FLOW_METER Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Classes | Concepts | Enumerations | Functions | Variables
sfm Namespace Reference

The SFM flow meter driver: everything it declares lives here; internals in detail. More...

Namespaces

namespace  feature
 Feature bits of a part (PartInfo::features); a clear bit makes the call Unsupported.
 
namespace  parts
 The part table: what the code, the docs generators and the tests read.
 
namespace  reg
 Command codes and field helpers.
 

Classes

struct  AddressSet
 The addresses a part may use; list[0] is the default. More...
 
struct  Capabilities
 Which calls a part offers, from its table row. More...
 
class  CheckedConfig
 A configuration proven valid at build time. More...
 
struct  Config
 Everything EnsureInitialized() applies. More...
 
struct  GasList
 The gases of a part. More...
 
struct  GasRow
 One calibrated gas of a part: its start code, its status index and its scaling. More...
 
class  I2cInterface
 CRTP base of the platform I2C port. More...
 
struct  PartInfo
 One row of the part table. More...
 
struct  ProductInfo
 The product identifier read at initialisation. More...
 
struct  RawReply
 The words of one reply, after their CRCs were checked and before anything was decoded. 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  Sample
 One measurement. Flow is in millilitres per minute at the part's reference conditions. More...
 
struct  Scaling
 Counts per slm as the rational num / den, the offset and the unit word of one gas. More...
 
struct  ScalingInfo
 What the sensor reports about the scaling of a gas, and whether it matches the table. More...
 
class  SfmFlowMeter
 The driver. More...
 
struct  Stats
 Counters the driver keeps; none of them is cleared by a successful call. More...
 
struct  TempRow
 The temperature scaling of a part. More...
 
struct  Timing
 Timings of a part in microseconds: the datasheet maxima. More...
 
struct  Wait
 A wait the caller owes the driver: delay us, then call Poll(). 0 means nothing to wait. More...
 

Concepts

concept  I2cPort
 Satisfied by a class that derives from I2cInterface<Port> and implements the required hooks with exactly the types above, noexcept and returning bool.
 

Enumerations

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::NoData = 16 , Error::NoDevice = 17 ,
  Error::OutOfRange = 18 , Error::StatusMismatch = 19 , Error::Stale = 20 , Error::DeviceReset = 21 ,
  Error::StateUnknown = 22 , Error::InvalidReply = 23
}
 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::Sf06 = 0 , Family::Sf06Gen2 , Family::Sf06Dual , Family::Sf05 ,
  Family::Sf04 , Family::Sfx6000
}
 The command-set family of a part. One protocol policy per family; every part is a row of data that names its family. More...
 
enum class  Variant : uint8_t {
  Variant::Auto = 0 , Variant::SFM4300_20_B , Variant::SFM4300_20_O , Variant::SFM4300_20_P ,
  Variant::SFM4300_50_B , Variant::SFM4300_50_O , Variant::SFM4300_50_P , Variant::SFM3003_300_CL ,
  Variant::SFM3003_300_CE , Variant::SFM3003_300_CET , Variant::SFM3013_300_CL , Variant::SFM3013_300_CLM ,
  Variant::SFM3019_200_CL , Variant::SFM3119_240_CL , Variant::SFM3304_250_D , Variant::SFM3505_300 ,
  Variant::SFM3505_300_X , Variant::SFM3000_200_C , Variant::SFM3200 , Variant::SFM3200_AW ,
  Variant::SFM3300_D , Variant::SFM3300_AW , Variant::SFM3400_D , Variant::SFM3400_AW ,
  Variant::SFM4200 , Variant::SFM4100_AIR , Variant::SFM4100_O2 , Variant::SFM4100_CO2 ,
  Variant::SFM4100_N2O , Variant::SFM4100_AR , Variant::SFM6000D_50 , Variant::SFM6000D_20 ,
  Variant::SFM6000D_5
}
 A part (one row of the table in sfm_flow_meter_parts.hpp). The names follow the vendor's ordering suffixes; _B, _O and _P are the SFM4300 fittings. More...
 
enum class  Gas : uint8_t {
  Gas::Air = 0 , Gas::O2 , Gas::N2 , Gas::N2O ,
  Gas::CO2 , Gas::Ar , Gas::HeOx , Gas::AirO2 ,
  Gas::N2OO2 , Gas::CO2O2 , Gas::HeOxO2
}
 A calibrated gas or gas mixture. Which gases a part offers is in its table row. More...
 
enum class  ScalingCheck : uint8_t { ScalingCheck::Strict = 0 , ScalingCheck::Lenient , ScalingCheck::Off }
 What ReadScaling() does when the sensor's scale or offset differs from the datasheet. More...
 
enum class  RangePolicy : uint8_t { RangePolicy::Reject = 0 , RangePolicy::Flag }
 What ReadSample() does with a flow or temperature outside the part's span. More...
 
enum class  TimingPolicy : uint8_t { TimingPolicy::Conservative = 0 , TimingPolicy::Datasheet }
 Which waits the driver uses after a reset or a wake. More...
 
enum class  State : uint8_t {
  State::Uninitialized = 0 , State::Idle , State::Measuring , State::Asleep ,
  State::StateUnknown
}
 The driver's shadow of the chip's mode. More...
 

Functions

constexpr Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the datasheet defaults.
 
constexpr const PartInfo * FindPart (Variant variant) noexcept
 The table row of a variant.
 
constexpr const PartInfo * FindById (Family family, uint32_t id, uint8_t address) noexcept
 The table row that a product identifier and address select inside one family.
 
constexpr const PartInfo * FamilyRow (Family family) noexcept
 The first row of a family: what Variant::Auto uses for waits before the part is known.
 
constexpr const GasRow * FindGas (const PartInfo &part, Gas gas) noexcept
 The gas row of a part.
 
constexpr bool Has (const PartInfo &part, uint32_t bits) noexcept
 
constexpr Capabilities CapabilitiesOf (const PartInfo &part) noexcept
 
constexpr int64_t DivideRounded (int64_t value, int64_t divisor) noexcept
 Divide value by divisor rounding to nearest, ties away from zero.
 
constexpr int32_t FlowMlPerMin (int32_t raw, const Scaling &scaling) noexcept
 A raw flow in millilitres per minute: (raw - offset) * 1000 * den / num, rounded.
 
constexpr int32_t TemperatureMdegC (int32_t raw, const TempRow &row) noexcept
 A raw temperature in milli-degrees Celsius: (raw - offset) * 1000 / scale, rounded.
 
constexpr Error Validate (const Config &config) noexcept
 Check a configuration against the part it names, without touching the chip.
 
constexpr Config PresetFor (Variant variant) noexcept
 A part's datasheet defaults as a configuration.
 
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 const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint32_t FamilyBit (Family f) noexcept
 A bit in a family mask: SfmFlowMeter<Port, kFamilySf06 | kFamilySf05>.
 
constexpr const char * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

constexpr uint32_t kFamilySf06 = 1U << 0
 Family mask bits.
 
constexpr uint32_t kFamilySf06Gen2 = 1U << 1
 Family::Sf06Gen2.
 
constexpr uint32_t kFamilySf06Dual = 1U << 2
 Family::Sf06Dual.
 
constexpr uint32_t kFamilySf05 = 1U << 3
 Family::Sf05.
 
constexpr uint32_t kFamilySf04 = 1U << 4
 Family::Sf04.
 
constexpr uint32_t kFamilySfx6000 = 1U << 5
 
constexpr uint32_t kAllFamilies = 0x3FU
 Every family: the default mask.
 
constexpr uint16_t kAveragingDefault = 0xFFFFU
 Marks Config::averaging as "the family's reset value".
 
constexpr uint16_t kFilterDefault = 50961U
 The filter argument of the default 3 ms response (SFM3304, SFM3505).
 
Bus requirements

What the SFM family needs from the I2C bus. A port and a board configuration check their settings against these with static_assert (handbook KB-CPP-123). Per-part clock limits are in PartInfo::max_clock_hz.

constexpr uint8_t kI2cAddress = 0x2A
 
constexpr uint32_t kMaxClockHz = 1'000'000
 
constexpr uint32_t kTypClockHz = 400'000
 Typical SCL frequency of the SF06 family.
 
constexpr uint32_t kSafeClockHz = 100'000
 
constexpr bool kRepeatedStart = false
 
constexpr std::size_t kMaxRead = 18
 
constexpr std::size_t kMaxWrite = 5
 

Detailed Description

The SFM flow meter driver: everything it declares lives here; internals in detail.

Function Documentation

◆ CapabilitiesOf()

constexpr Capabilities sfm::CapabilitiesOf ( const PartInfo &  part)
constexprnoexcept
Parameters
partThe part.
Returns
The part's capabilities, from its feature bits.

◆ DivideRounded()

constexpr int64_t sfm::DivideRounded ( int64_t  value,
int64_t  divisor 
)
constexprnoexcept

Divide value by divisor rounding to nearest, ties away from zero.

Parameters
valueThe dividend.
divisorThe divisor; positive.
Returns
The rounded quotient.

◆ FamilyRow()

constexpr const PartInfo * sfm::FamilyRow ( Family  family)
constexprnoexcept

The first row of a family: what Variant::Auto uses for waits before the part is known.

Parameters
familyThe family.
Returns
The row, or nullptr when the family has none.

◆ FindById()

constexpr const PartInfo * sfm::FindById ( Family  family,
uint32_t  id,
uint8_t  address 
)
constexprnoexcept

The table row that a product identifier and address select inside one family.

Parameters
familyThe configured family; a row of another family never matches.
idThe 32-bit product identifier read from the sensor.
addressThe 7-bit address the sensor answered at.
Returns
The row, or nullptr when no row of family matches (for example a controller product).

◆ FindGas()

constexpr const GasRow * sfm::FindGas ( const PartInfo &  part,
Gas  gas 
)
constexprnoexcept

The gas row of a part.

Parameters
partThe part.
gasThe gas.
Returns
The row, or nullptr when the part does not calibrate that gas.

◆ FindPart()

constexpr const PartInfo * sfm::FindPart ( Variant  variant)
constexprnoexcept

The table row of a variant.

Parameters
variantA variant other than Auto.
Returns
The row, or nullptr for Auto or a value that is not an enumerator.

◆ FlowMlPerMin()

constexpr int32_t sfm::FlowMlPerMin ( int32_t  raw,
const Scaling &  scaling 
)
constexprnoexcept

A raw flow in millilitres per minute: (raw - offset) * 1000 * den / num, rounded.

Parameters
rawThe received flow word (16-bit signed or unsigned, or 24-bit unsigned).
scalingThe gas's scaling.
Returns
The flow in ml/min; the intermediate is 64-bit, so no input overflows.

◆ Has()

constexpr bool sfm::Has ( const PartInfo &  part,
uint32_t  bits 
)
constexprnoexcept
Parameters
partThe part.
bitsfeature:: bits.
Returns
Whether the part has every bit of bits set in its features.

◆ KconfigDefaults()

constexpr Config sfm::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the datasheet defaults.

Returns
Config{} with the averaging, scaling check, range policy, timing, general-call permission, restart rule and error limit taken from Kconfig.

◆ PresetFor()

constexpr Config sfm::PresetFor ( Variant  variant)
constexprnoexcept

A part's datasheet defaults as a configuration.

Parameters
variantThe part.
Returns
Config{} with the variant, family and default address of the row; Config{} for Auto.

◆ TemperatureMdegC()

constexpr int32_t sfm::TemperatureMdegC ( int32_t  raw,
const TempRow &  row 
)
constexprnoexcept

A raw temperature in milli-degrees Celsius: (raw - offset) * 1000 / scale, rounded.

Parameters
rawThe received temperature word.
rowThe part's temperature scaling; scale must not be 0.
Returns
The temperature in 1/1000 degC; 0 when the part has no temperature scaling.

◆ Validate()

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

Check a configuration against the part it names, without touching the chip.

Fails when an enumeration holds a value that is not an enumerator, the family is not the part's, the address is not in the part's set, Auto is combined with TimingPolicy::Datasheet, averaging or the filter is used on a part without that feature, averaging is out of range for the part, or the error limit is 0.

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

Variable Documentation

◆ kI2cAddress

constexpr uint8_t sfm::kI2cAddress = 0x2A
inlineconstexpr

The default 7-bit address of the family Config{} selects (SF06; the SFM4300 with ADDR open or at GND). Every part's addresses are in PartInfo::addresses; PresetFor() fills the right one.

◆ kMaxClockHz

constexpr uint32_t sfm::kMaxClockHz = 1'000'000
inlineconstexpr

Highest SCL frequency of the SF06 family and the SFx6000 (datasheet: 1 MHz maximum, 400 kHz typical).

◆ kMaxRead

constexpr std::size_t sfm::kMaxRead = 18
inlineconstexpr

Longest read the driver issues, in bytes (the product identifier: six words with CRC).

◆ kMaxWrite

constexpr std::size_t sfm::kMaxWrite = 5
inlineconstexpr

Longest write the driver issues, in bytes (a command, one argument word and its CRC).

◆ kRepeatedStart

constexpr bool sfm::kRepeatedStart = false
inlineconstexpr

false: a command write and the following read are separate transfers with a STOP between them.

◆ kSafeClockHz

constexpr uint32_t sfm::kSafeClockHz = 100'000
inlineconstexpr

Conservative default clock for any part: the lowest "maximum" of the supported parts is 100 kHz.