Porting¶
Write the port class for your MCU's SDK. The driver calls hooks on a class you derive from
sfm::I2cInterface<YourPort>; it never calls an SDK. A port is about 20 lines on most platforms.
Datasheet sections this page relies on
- Sf04 trigger bytes and the hold-master read: Sensirion AG SFM4100 1.4, Digital interface (trigger, clock stretching, address per gas), p. 4
- Timing (reset, first sample, wake-up, stop): Sensirion AG SFM4300 D1 1.0, 2.4 Timing specification, p. 5
- I2C address and bus: Sensirion AG SFM4300 D1 1.0, 4 Digital interface description; 4.1 I2C address, p. 9
- Command framing and read framing: Sensirion AG SFM4300 D1 1.0, 4.2 I2C sequences, p. 9
- Soft reset (general call): Sensirion AG SFM4300 D1 1.0, 4.3.7 Soft reset, p. 13
All of them, with the driver API for each: Datasheet map.
The contract¶
The sensors have no register map on the bus. A transaction is a raw command write (a command code, optionally an argument word with its CRC) or a raw read of 16-bit words, each followed by a CRC-8 byte. The port moves bytes; it never retries, never interprets and never aborts a read early.
| Hook | Contract | Required |
|---|---|---|
bool EnsureInitialized() noexcept |
Bring the bus up on the first call; true at once afterwards |
yes |
bool Write(uint8_t addr, const uint8_t* data, std::size_t len) noexcept |
START, addr + W, len bytes, STOP; false on a NACK or a bus error. len is at least 1: the driver never sends an empty transfer. A NACK is expected while a sensor sleeps or resets (see below) |
yes |
bool Read(uint8_t addr, uint8_t* data, std::size_t len) noexcept |
START, addr + R, len bytes, ACK every byte but the last, STOP; false when the address is NACKed (the "no data yet" signal) or on a bus error |
yes |
bool ReadStretch(uint8_t addr, uint8_t* data, std::size_t len) noexcept and static constexpr bool kClockStretch = true |
A read that tolerates the slave holding SCL low | SFM4100 only |
bool WriteGeneralCall(uint8_t byte) noexcept |
START, address 0x00 + W, byte, STOP |
the general-call soft reset of the SF06, SFM3505 and SFM6000D families |
bool PowerCycle() noexcept |
Remove and restore the sensor supply, holding SDA and SCL low while it is off (see Hard reset wiring) | optional: HardReset() of the SF05 parts and SFM3505, which the caller runs when the SF05 error limit leaves StateUnknown |
bool SetResetPin(bool asserted) noexcept |
Drive the /RES pin of the SFM4200 (active low), holding SDA and SCL low while it is asserted | optional |
void DelayUs(uint32_t us) noexcept |
Wait at least us microseconds |
optional: the blocking calls need it |
uint32_t NowUs() noexcept |
A free-running microsecond counter | optional: settled and staleness checks need it |
void Log(LogLevel, const char*) noexcept |
One log line per event; plain text | optional |
addr is the 7-bit address. The hooks are found at compile time: a hook you leave out is not called, and the calls
that need it return Unsupported or are refused at build time. A hook you declare with the wrong signature is a
compile error that names it.
The smallest port:
class MyPort : public sfm::I2cInterface<MyPort> {
public:
bool EnsureInitialized() noexcept {
return board::I2cBegin(); // bring the bus up on the first call; true at once afterwards
}
bool Write(uint8_t addr, const uint8_t* data, std::size_t len) noexcept {
return board::I2cWrite(addr, data, len); // START, addr+W, len bytes (never 0), STOP
}
bool Read(uint8_t addr, uint8_t* data, std::size_t len) noexcept {
return board::I2cRead(addr, data, len); // START, addr+R, len bytes, NACK on the last, STOP
}
void DelayUs(uint32_t us) noexcept {
board::SleepUs(us); // optional; without it only the non-blocking calls work
}
uint32_t NowUs() noexcept {
return board::MicrosNow(); // optional; a free-running microsecond counter
}
};
A port with every optional hook, for an SFM4100 (the only part that needs a stretching read):
class FullPort : public sfm::I2cInterface<FullPort> {
public:
static constexpr bool kClockStretch = true; // marks ReadStretch() for the SFM4100
bool EnsureInitialized() noexcept {
return board::I2cBegin();
}
bool Write(uint8_t a, const uint8_t* d, std::size_t n) noexcept {
return board::I2cWrite(a, d, n);
}
bool Read(uint8_t a, uint8_t* d, std::size_t n) noexcept {
return board::I2cRead(a, d, n);
}
bool ReadStretch(uint8_t a, uint8_t* d, std::size_t n) noexcept {
return board::I2cReadStretching(a, d, n);
}
bool WriteGeneralCall(uint8_t byte) noexcept {
return board::I2cGeneralCall(byte);
}
void DelayUs(uint32_t us) noexcept {
board::SleepUs(us);
}
uint32_t NowUs() noexcept {
return board::MicrosNow();
}
void Log(sfm::LogLevel /*level*/, const char* text) noexcept {
board::Print(text);
}
};
A port for the legacy parts, which uses the supply and reset hooks:
class ResettablePort : public sfm::I2cInterface<ResettablePort> {
public:
bool EnsureInitialized() noexcept {
return board::I2cBegin();
}
bool Write(uint8_t a, const uint8_t* d, std::size_t n) noexcept {
return board::I2cWrite(a, d, n);
}
bool Read(uint8_t a, uint8_t* d, std::size_t n) noexcept {
return board::I2cRead(a, d, n);
}
void DelayUs(uint32_t us) noexcept {
board::SleepUs(us);
}
// Both hooks hold SDA and SCL low while the sensor is without supply or in reset, so it is not
// powered through the bus pins and really resets (SFM4200 2.3, SFM3505 3.3.5).
bool PowerCycle() noexcept { // the legacy parts' last resort: remove and restore the supply
board::BusLow();
board::SupplyOff();
board::SleepUs(100'000U);
board::SupplyOn();
board::BusRelease();
return true;
}
bool SetResetPin(bool asserted) noexcept { // the /RES pin of the SFM4200, active low
if (asserted) {
board::BusLow(); // at the same time as /RES, not after it
}
board::ResetLine(asserted);
if (!asserted) {
board::BusRelease();
}
return true;
}
};
What the bus must do¶
| Requirement | Why |
|---|---|
| A write ends with a STOP and a read starts with its own START | The documents show a STOP between a command and its read and do not allow or forbid a repeated START (ambiguity K-RS). The driver has no WriteRead hook |
| Never abort a read after the first byte | An SF05 sensor locks up when the master NACKs the first data byte; recovery needs a power cycle |
| No empty write, ever | A write has at least one data byte. Wake from sleep and every reset poll send the next real command (the stop command, the SF05 serial pointer, the SF04 register read); a sensor that sleeps or resets does not acknowledge its address and the transfer ends there, as an empty probe would have; an awake one accepts the whole command |
SCL at most kMaxClockHz (1 MHz), 100 kHz when unsure |
The limits per part are in PartInfo::max_clock_hz and on the Hardware page. Check your setting with static_assert |
| External pull-ups on SDA and SCL | The sensors do not have them, and the datasheets give no value. The weak internal pull-ups of a microcontroller do not suit 400 kHz or 1 MHz or the 5 V SF05 parts (the ESP-IDF port leaves them off unless internal_pullup is set, a bench aid only) |
| Clock stretching enabled for the SFM4100 | The sensor holds SCL low while it measures |
sfm::kRepeatedStart is false, sfm::kMaxRead is 18 bytes and sfm::kMaxWrite is 5 bytes: size your buffers and
DMA descriptors from them.
The clock and the delay¶
| Port has | What works |
|---|---|
DelayUs() |
EnsureInitialized(), AwaitPending() and every blocking call; the driver loops over DelayUs() |
NowUs() |
Poll() measures elapsed time itself; Sample::settled and Config::max_age_us work; Sample::timestamp_us is set |
| neither | Only the non-blocking calls: sleep for the wait you were given and call Poll(elapsed_us) |
Without NowUs() the driver cannot know that a wait ended, so Poll() counts the whole wait as elapsed and
settled stays false.
Checked at build time¶
The mistakes a port can make are compile errors, not run-time surprises:
| Mistake | Result |
|---|---|
The class does not derive from I2cInterface<Self>, or a required hook is missing |
SfmFlowMeter is not instantiated: the I2cPort concept fails |
A hook is not noexcept or has another signature |
The same, naming the hook |
DelayUs, NowUs, Log, ReadStretch, WriteGeneralCall, PowerCycle or SetResetPin declared with the wrong signature |
A static_assert names the hook |
| A family mask of 0 or with bits outside the families | A static_assert |
SfmFlowMeter<Port, kFamilySf04> over a port without ReadStretch() |
A static_assert |
CheckedConfig built from an invalid Config |
The build fails, naming ConfigIsInvalid |
These are tested: tests/compile_fail/ has one case for each, and CTest runs them.
Transfers the sensor NACKs by design¶
These are not bus faults. The driver counts them in Stats::no_data or not at all, never in Stats::bus_errors.
| Transfer | What the datasheet says | What the driver does |
|---|---|---|
| Any write to a sleeping SF06 sensor | The address is not acknowledged until the sensor is awake (SFM4300 4.3.8); the address phase wakes it | WakeUp() and the identification poll send the stop command every 1 ms up to the part's wake bound; a NACK in between is expected; at the bound the result is Timeout (wake) or NoDevice (initialisation) |
| A write to a sleeping SFM3304 | The address is acknowledged, the data bytes are NACKed until it is awake (SFM3304 4.3.8, Table 11) | The same poll; the two-byte stop command supplies the data bytes |
| Any transfer after a reset or power-up | The sensor does not acknowledge for the reset time (SFM4300 4.3.7) | The driver waits the datasheet time, then polls with the next real command |
| A read before a new sample | The read header is NACKed (SFM4300 3.3, SFM3003 4.3.1, SFM3505 3.3.1); a result comes every N x 0.5 ms | NoData, state unchanged. After the silence bound (first-result time plus one averaged period plus 10 % and 1 ms) the driver asks with the stop command: no answer is NoDevice, an answer is DeviceReset |
| SF05: a read before the first result | The read is NACKed (AN-05 4.1) | NoData; the first data byte of a read that is ACKed is never NACKed (lock-up) |
| SFM4200 during /RES | Nothing is acknowledged | The driver waits the reset time, then polls the serial pointer |
Control pins: idle levels¶
A port drives each control output to its inactive level before it enables the output and before the first frame, so
configuring it never pulses it. The ESP-IDF port does this in EnsureInitialized().
| Pin | Inactive level | Polarity |
|---|---|---|
| /RES of the SFM4200 | High (released) | Active low |
Supply switch (PowerCycle()) |
High (supply on) | Active high; the supply is off only inside PowerCycle() |
| SDA, SCL | Released (pulled up) | Held low only inside PowerCycle() and while /RES is asserted |
Hard reset wiring¶
The SFM4200 datasheet (2.3) says that to interrupt the power to the SF05 chip during the reset, SDA and SCL must be
pulled low at the same time as /RES, and the SFM3505 (3.3.5) says all pins, the communication lines included, must be
at 0 V for a power reset. A sensor that stays powered through the bus pull-ups or the protection diodes does not reset,
so a locked-up SF05 stays locked up. The port's PowerCycle() and SetResetPin(true) therefore hold SDA and SCL low
for as long as the supply is off or /RES is asserted, and release them afterwards. On the board, switch the supply
of the sensor and its pull-ups together, or make sure the pull-ups cannot back-feed the sensor.
The SF05 error limit does not cycle the supply from inside ReadSample() (which never waits): at the limit the state
is StateUnknown, and the caller runs HardReset(), then EnsureInitialized().
A port on ESP-IDF¶
examples/esp32/main/esp32_sfm_flow_meter_port.hpp is a port
for ESP-IDF's i2c_master with every optional hook: a stretching read, the general call, a supply switch for
PowerCycle() and a /RES pin, both holding SDA and SCL low, and a bus clear after a timed-out transfer. It is
compiled by CI and has not been run against a sensor.