Contract¶
What the BMP581 driver promises, what it needs, and the rules a caller follows.
Datasheet sections this page relies on
From Bosch Sensortec BST-BMP581-DS004-13 1.13:
- Supplies, timing and conversion times: 2 Specification; Table 4 Electrical characteristics, p. 10
- Power modes, deep standby and mode transitions: 4.3 Power modes; 4.3.1 STANDBY mode; 4.3.2 DEEP STANDBY; 4.3.7 Mode transitions, p. 16
- Register writes only in standby: 4.3.8 Mode-depending register write restrictions, p. 18
- Soft reset: 4.3.10 Soft reset; 7.36 Register (0x7E) Command Register, p. 18
- Pressure enable and oversampling: 4.4.1 Pressure and temperature measurement enable; 4.4.2 Oversampling ratio; Table 9, p. 18
- FIFO flush on configuration changes: 4.6.4 FIFO configuration changes; Table 4 t_reconf, p. 25
- Interrupt sources, out of range and power-on reset: 4.7 Interrupts; 4.7.2.3 Out-of-range interrupt; 4.7.2.4 Power-on reset interrupt, p. 25
- NVM data registers (the reset marker): 4.8.1 NVM User Range; 7.25 Register (0x2C) NVM data (LSB); 7.26 Register (0x2D) NVM data (MSB), p. 29
- Interrupt status (clear-on-read): 7.21 Register (0x27) Interrupt status register (clear-on-read), p. 58
- OSR and ODR configuration: 7.33 Register (0x36) OSR configuration; 7.34 Register (0x37) ODR configuration; 7.35 OSR_EFF, p. 64
All of them, with the driver API for each: Datasheet map.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Promises¶
- The constructor is
noexcept, stores the configuration, does no I/O and cannot fail. EnsureInitialized()is the only way to start the driver. Its first call checks the stored configuration and the I2C address (InvalidArgument, nothing sent), brings the bus up, waits t_powup, soft-resets the chip, checks CHIP_ID, NVM readiness and the reset flag, and only then writes the configuration, in standby, and reads it back. On any failure the driver stays uninitialised and the next call starts again from the beginning. Once started, a later call runs the reset check and returnsOk, or starts again when the chip reset.- Every call that touches the chip returns
NotInitializedbeforeEnsureInitialized()succeeds, exceptDeinitialize(). No call starts the chip as a side effect.ApplyConfig()before the start only stores the configuration. InvalidArgumentmeans nothing was sent.- Every port failure propagates (
Bus, orNoDevicefor an I2C address NACK the port reports); a failed value isT{}. - Every wait is bounded by a datasheet maximum or a validated
Configtimeout:kTimeoutMaxMsat most. Config{}equals the datasheet reset values, except that pressure is always measured (OSR_CONFIG.press_en).
Values¶
- A measurement comes from one 12-byte read of TEMP_DATA to STATUS, so temperature and pressure come from one conversion (section 4.5.1).
- No reply a broken line can produce is ever a value: a frame whose reserved registers (0x23 to 0x26) are not 0x00
or whose reserved bits are set (all 0xFF), or a frame of all 0x00, is
InvalidReply. - The reset value 0x7F7F7F is
NoData, never a reading; a value outside 30 kPa to 125 kPa or -40 °C to 85 °C isOutOfRange, never clamped. - A FIFO read reports validity per frame (
FifoSample::error); a FIFO burst of all 0x00 or all 0xFF isInvalidReplyfor the whole call. - The conversions are exact: pressure_raw / 64 Pa and temperature_raw / 65536 °C (section 4.5).
Resets¶
A power-on reset (a supply dip, a brown-out) or a soft reset loads every register with its reset value and sets INT_STATUS.por (sections 4.7.2.4, 7.21). The chip then sits in deep standby (section 4.3): it measures nothing, and a driver that did not notice would keep reading the old data or write its cached settings over the reset chip.
- The sentinel. The driver always writes OSR_CONFIG with press_en = 1, and only a reset clears it, so OSR_CONFIG.press_en = 0 is the reset. No write of the driver erases it.
- The marker. 0x3C and 0xC3 in NVM_DATA_LSB and NVM_DATA_MSB (reset value 0x00, inert without an NVM command in CMD, sections 4.8.1, 7.25, 7.26). NVM_DATA is the NVM read port, and the NVM is downloaded at the start of every measurement from deep standby (sections 4.8.1.1, 7.22); the datasheet does not say whether that reaches NVM_DATA, so a download may leave any value there, 0x00 0x00 (an unprogrammed word) included. The driver therefore counts the marker only while it is fresh: written or verified in standby, with no measurement from deep standby since.
- Every configuration sequence, after the call's reset check and with the chip in standby with deep standby
off (no download can follow until the sequence ends), reads NVM_DATA. A fresh marker that reads 0x00 0x00
twice is a reset (
DeviceReset, nothing written). Otherwise anything but the marker is overwritten at once, and the sentinel is read again: the sequence has not written OSR_CONFIG yet, so a reset between the call's check and the new marker still shows. - The sequence itself does not write NVM_DATA, so 0x00 0x00 at its read-back is a reset during it, even when the sequence's own OSR_CONFIG write covered the sentinel.
- The decision on a por the sentinel contradicts uses the marker only while it is fresh; otherwise the configuration alone decides.
- Any value other than the marker or 0x00 0x00 is the marker lost, never a reset.
- The evidence. Every INT_STATUS read (data reads, polls,
ReadInterruptStatus(), a raw read) is checked for por; the data registers at their reset value are evidence too. Each runs the reset check: OSR_CONFIG, ODR_CONFIG and OSR_EFF in one read. - Confirmed before acting. Reset evidence is read a second time: press_en = 0, a reserved bit set in
OSR_CONFIG or OSR_EFF (a reply that cannot come from the chip; no constant byte passes these checks, so neither
a stuck line nor the SPI frame that only selects SPI again does), or, with the configuration known,
OSR_CONFIG or ODR_CONFIG differing from what the driver wrote and read back. A second read that shows it again
is the reset: the driver is then uninitialised and returns
DeviceReset; callEnsureInitialized(). One corrupt read costs one more read. - Never written over.
ApplyConfig(),SetPowerMode()to a measuring mode andMeasureOnce()read INT_STATUS and then OSR_CONFIG and ODR_CONFIG before their first write, and a reset found sends nothing. - A por the sentinel contradicts. When INT_STATUS shows por but OSR_CONFIG does not, either the por read was
corrupt or a reset was followed by an OSR_CONFIG write (a sequence whose reads were disturbed). With the
configuration known, the whole configuration and the marker decide: a chip that no longer holds them reset; one
that holds them gives
InvalidReply, and the next call checks again. When those reads fail, the decision moves to the next call, which writes nothing before it. - Doubt is never dropped. A check that is due but cannot be read stays pending, and no call returns
Okuntil it has passed: a call that would succeed fails with the check's error, a call that failed keeps its own (a confirmed reset outranks it). - In a configuration sequence the sequence itself rewrites OSR_CONFIG, so a por read at its end cannot be
confirmed: it is taken as the reset, the safe direction for a sensor. A sequence that fails after its first
configuration write leaves the driver uninitialised, whatever the error: a reset during it could hide behind its
own writes and a lost INT_STATUS read, so the next
EnsureInitialized()starts again from the soft reset. - An empty FIFO (with the FIFO on), an empty FIFO frame and a FIFO frame out of range run the reset check too: a reset empties and disables the FIFO.
- On SPI the first frame after a reset only selects SPI again, and its bytes are whatever MISO shows (section
5.1): an INT_STATUS, FIFO_COUNT, FIFO_DATA or raw read cannot tell such a frame from data. On SPI,
ReadInterruptStatus(),WaitDataReady()(when it sees drdy),ReadFifoCount(),ReadFifo()andReadRegister()therefore run the reset check before they return what they read: one more 3-byte read. The data read needs none: its reserved registers refuse every constant frame. A pull-up on MISO (see Hardware) makes the frame read 0xFF.
A line stuck low reads OSR_CONFIG = 0x00 twice and is reported as a reset; EnsureInitialized() then fails with
DeviceIdMismatch. On I2C, calls that only read status (ReadInterruptStatus(), ReadFifoCount(),
ReadRegister()) report what they read and run the reset check only on evidence; where a supply dip is possible
and the application only reads status, call CheckForReset().
A bit flipped inside a data byte. The bus carries no CRC: a single bit flipped by noise inside a data byte (a
temperature LSB, a FIFO sample) gives a plausible value that no reserved bit or range check can refuse, and it is
not detectable without a second read. ReadMeasurement(Verify::ReadBack) and MeasureOnce(Verify::ReadBack) read
TEMP_DATA and PRESS_DATA again (6 bytes): equal is Ok; otherwise a third read decides, equal to either earlier
read (a new measurement in normal or continuous mode, or one disturbed read), and three different values, or two
reads of a stuck line, are InvalidReply. A FIFO read cannot be repeated: the frames leave the FIFO.
Writes¶
- Every write is one register in one transfer, stored whole or not at all; the driver never writes a burst.
- The configuration is written in standby with deep standby off, the only state that takes every write (sections 4.3.1, 4.3.8): ODR_CONFIG = standby with deep_dis = 1 and t_standby first, whenever the chip may be measuring or in deep standby, and ODR_CONFIG with the configured deep_dis last. It is read back in full; a power mode change goes through standby (section 4.3.7) and is read back. A forced measurement is polled until pwr_mode shows forced, at most t_startup (3 ms), before the driver waits for it, so a dropped write never returns the old data as new.
- A write that failed may have landed. A failed standby or mode write leaves the configuration in doubt
(
IsConfigKnown()false), and the calls that depend on it (MeasureOnce(),WaitDataReady(), the FIFO calls,SetPowerMode()to a measuring mode) returnStateUnknownwith nothing sent untilApplyConfig()orEnsureInitialized()succeeds; a runningEnsureInitialized()with the configuration in doubt starts again from the soft reset. A failed or mismatching configuration sequence leaves the driver uninitialised (see Resets). - A mode change is read back until it shows, at most t_startup_deep (4 ms), and in normal mode until
OSR_EFF.odr_is_valid = 1 too: the datasheet gives no time for either.
ConfigRejectedonly at the deadline. - With the FIFO on,
ApplyConfig()andSetPowerMode()return after t_reconf (3 ms): the change flushed the FIFO, and FIFO_COUNT is not to be read before the flush completes (section 4.6.4). SetPowerMode(PowerMode::Standby)andDeinitialize()are never refused once the driver has started: not after a reset was found, not with the configuration in doubt, not with a check pending.Deinitialize()writes ODR_CONFIG = standby with deep_dis = 1 and CMD = 0xB6, and isOkonly when INT_STATUS shows the reset.- Every soft reset, at start-up and in
Deinitialize(), is preceded by ODR_CONFIG = standby with deep_dis = 1 and t_standby: the datasheet does not say that deep standby takes CMD (section 4.3.1 says standby takes every write).
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates bmp581_version.h |
| Your port | The bus within its requirements, CSB idle high on SPI; the delay; optional hooks (Porting) |
Nothing else: no RTOS, no SDK, no other repository of the org.
Threading¶
The driver is not thread-safe and takes no lock. Use each driver object from one task at a time, or guard every call on it with one mutex; the layer that owns the driver owns that lock, and the bus lock when several chips share a bus. Nothing may run in an ISR: every call can block for a bus transfer or a delay. Separate objects share no state.
Errors¶
bmp581::Error inside bmp581::Result<T>. Values 0 to 9 are the shared base set; this driver returns every one
of them except Crc (the bus carries no CRC), plus eight chip-specific values.
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() has not succeeded, or Deinitialize() ran or a reset was found since |
InvalidArgument |
2 | A Config field, the address or an argument is out of range; nothing was sent |
Bus |
3 | A port hook returned false |
Timeout |
4 | NVM never ready, a forced measurement not ended, standby not reached, or no data ready in time |
DeviceIdMismatch |
5 | CHIP_ID is not 0x50, or INT_STATUS did not show the soft reset (0x10, then 0x00) |
Crc |
6 | Not returned |
Busy |
7 | MeasureOnce() while the chip measures; nothing was sent |
DeviceFault |
8 | STATUS reports an NVM error at start-up |
Unsupported |
9 | WaitDataReady() without the data-ready source or in standby; a FIFO call with the FIFO off |
DeviceReset |
16 | The chip reset, confirmed by a second read; the driver is uninitialised |
InvalidReply |
17 | A reply the chip cannot send: a stuck, floating or disturbed line |
NoDevice |
18 | An I2C address NACK, with GetLastFailure() |
NoData |
19 | The data registers hold their reset value: no measurement since the reset |
OutOfRange |
20 | A value outside the measurement range |
WriteMismatch |
21 | A register read back differently from what was just written |
StateUnknown |
22 | The configuration is in doubt after a failed write; nothing was sent |
ConfigRejected |
23 | Normal mode: OSR_EFF.odr_is_valid still 0 at the deadline; the chip was put back in standby |
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf and no static mutable state. A
driver object holds a reference to the port, a Config, a 96-byte read buffer and a few flags; an SPI driver also
holds two 97-byte frame buffers in its framing. The largest stack buffer is 12 bytes (a copy of the data frame).
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port
in examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
None.