BMP581 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
bmp581::BMP581< Port > Class Template Reference

Driver for one BMP581 on a platform port. More...

#include <bmp581.hpp>

Public Member Functions

 BMP581 (Port &port, const Config &config={}) noexcept
 Bind the driver to a port (on I2C at i2c::kI2cAddress) and store the configuration. No I/O, cannot fail: EnsureInitialized() checks the configuration.
 
 BMP581 (Port &port, uint8_t address, const Config &config={}) noexcept
 Bind the driver to an I2C port at a 7-bit address and store the configuration. No I/O.
 
 BMP581 (const BMP581 &)=delete
 One driver object per chip.
 
BMP581 & operator= (const BMP581 &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Start the chip. Once started, a later call runs the reset check (one 3-byte read) and returns Ok, or starts again when the chip reset or the configuration is in doubt.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Put the chip in its lowest-power state with the soft reset, CMD = 0xB6: it leaves the chip in deep standby with every register at its reset value (section 4.3). Marks the driver uninitialised.
 
Result< void > ApplyConfig (const Config &config) noexcept
 Replace the configuration.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
bool IsConfigKnown () const noexcept
 
Result< void > SetPowerMode (PowerMode mode) noexcept
 Change the power mode (section 4.3.7).
 
Result< void > CheckForReset () noexcept
 Find out whether the chip reset since the start: one 3-byte read of OSR_CONFIG to OSR_EFF, a second one only to confirm reset evidence. Also settles a pending check.
 
Measurement
Result< Measurement > ReadMeasurement (Verify verify=Verify::None) noexcept
 Read the latest measurement from the data registers: one 12-byte read of TEMP_DATA to STATUS (sections 4.5, 4.5.1), whatever the power mode (in standby, the last one measured).
 
Result< Measurement > MeasureOnce (Verify verify=Verify::None) noexcept
 One forced measurement (section 4.3.3): the reset check, ODR_CONFIG with pwr_mode = forced, polled until it shows forced, at most t_startup (WriteMismatch: the write was lost), a wait of the typical conversion time less 5 %, then polls of OSR_CONFIG to OSR_EFF every kPollUs until the chip is back in standby, at most ForcedMeasurementMaxUs() (Timeout), then the read of ReadMeasurement().
 
Result< void > WaitDataReady () noexcept
 Wait for new data in normal or continuous mode: INT_STATUS polled every kPollUs until drdy_data_reg, at most Config::data_ready_timeout_ms. Each read clears the flags on the chip and feeds the latch. On SPI the reset check runs before Ok (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).
 
Result< InterruptStatus > ReadInterruptStatus () noexcept
 Read INT_STATUS once (section 7.21): clears its flags on the chip; the driver latches them. On SPI the reset check runs before it returns (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).
 
FIFO
Result< uint8_t > ReadFifoCount () noexcept
 Read FIFO_COUNT (section 4.6.2). With the FIFO on, a count of 0 runs the reset check: a reset empties and disables the FIFO. On SPI the reset check runs before it returns (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).
 
Result< std::size_t > ReadFifo (std::span< FifoSample > out, Verify verify=Verify::None) noexcept
 Read up to out.size() frames from the FIFO: FIFO_COUNT, then one burst of whole frames from FIFO_DATA (section 4.6.3). Each sample carries its own validity (NoData for the empty frame, OutOfRange). A burst of all 0x00 or all 0xFF is InvalidReply (a stuck line; the frames read are lost). An empty FIFO, an empty frame or a frame out of range runs the reset check, since a reset empties the FIFO. On SPI the reset check always runs before the samples return (one 3-byte read): a reset between FIFO_COUNT and FIFO_DATA turns the burst into the frame that only selects SPI (section 5.1).
 
Diagnostics
InterruptStatus GetLatchedInterrupts () const noexcept
 The INT_STATUS flags seen by any read since ClearLatchedInterrupts(), the driver's own reads included (handbook KB-CPP-119). No I/O. The start-up empties it: the por of the driver's own soft reset is not news.
 
void ClearLatchedInterrupts () noexcept
 Empty the latch of GetLatchedInterrupts(). No I/O.
 
uint8_t GetLastIntStatus () const noexcept
 
uint8_t GetLastStatus () const noexcept
 
uint8_t GetLastOsrEff () const noexcept
 
uint8_t GetRevision () const noexcept
 
Result< uint8_t > ReadRegister (uint8_t address) noexcept
 Read one register once: one transfer, no retry, no decoding (handbook KB-CPP-129).
 

Detailed Description

template<BusPort Port>
class bmp581::BMP581< Port >

Driver for one BMP581 on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (soft reset, identity, NVM ready, configuration), use, optionally Deinitialize() (soft reset: deep standby). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip as a side effect.

Values. A measurement is one 12-byte read of TEMP_DATA to STATUS (sections 4.5.1, 5.4), so temperature and pressure come from the same conversion, the reserved registers in the middle prove the line, and INT_STATUS comes for free. No all-0x00 or all-0xFF frame, no reset value (0x7F7F7F) and nothing outside the measurement range is ever returned as a value.

Resets. A power-on reset (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 driver always writes OSR_CONFIG with press_en = 1, so OSR_CONFIG.press_en = 0 is the reset sentinel, and no write of the driver erases it; a marker in NVM_DATA, written at start-up, shows a reset that a configuration sequence's own OSR_CONFIG write covered. Every setter reads INT_STATUS, OSR_CONFIG and ODR_CONFIG first and writes nothing over a reset chip; every INT_STATUS read (data reads, polls, raw reads) is checked for por. Evidence is confirmed by a second read before the driver acts: it is then uninitialised and returns DeviceReset. A check that is due but cannot be read stays pending, and no call returns Ok until it has passed.

Writes. Every write is one register in one transfer, stored whole or not at all. The configuration is written in standby with deep standby off (sections 4.3.1, 4.3.8), ODR_CONFIG last, and read back in full; a power mode change goes through standby (section 4.3.7) and is read back. A failed or mismatching standby or mode write leaves the configuration in doubt (IsConfigKnown()): calls that depend on it return StateUnknown until ApplyConfig() or EnsureInitialized() succeeds. A configuration sequence that fails after its first write leaves the driver uninitialised. SetPowerMode(PowerMode::Standby) and Deinitialize() are never refused once the driver has started.

Port hooks besides the bus hooks, found at compile time:

Hook Used for Without it
void DelayUs(uint32_t us) noexcept t_powup, t_soft_res, t_standby and the polls Compile error: the waits are required
bool GetLastFailure(I2cFailure& failure) noexcept (I2C) Telling an address NACK (NoDevice) from other failures Every failed transfer is Bus
void Log(LogLevel, const char* message) noexcept One line per lifecycle event or failure Nothing is logged

A hook declared with the wrong signature (for example void DelayUs(uint16_t)) is a compile error.

Template Parameters
PortYour class derived from I2cInterface<Port> or SpiInterface<Port>.

Constructor & Destructor Documentation

◆ BMP581() [1/2]

template<BusPort Port>
bmp581::BMP581< Port >::BMP581 ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port (on I2C at i2c::kI2cAddress) and store the configuration. No I/O, cannot fail: EnsureInitialized() checks the configuration.

Parameters
portThe port; it must outlive the driver.
configWhat EnsureInitialized() will apply.

◆ BMP581() [2/2]

template<BusPort Port>
bmp581::BMP581< Port >::BMP581 ( Port &  port,
uint8_t  address,
const Config &  config = {} 
)
inlinenoexcept

Bind the driver to an I2C port at a 7-bit address and store the configuration. No I/O.

Parameters
portThe port; it must outlive the driver.
addressi2c::kI2cAddress (SDO low) or i2c::kI2cAddressSdoHigh; checked by EnsureInitialized().
configWhat EnsureInitialized() will apply.

Member Function Documentation

◆ ApplyConfig()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::ApplyConfig ( const Config &  config)
noexcept

Replace the configuration.

Uninitialised: config is only stored, for EnsureInitialized(), with no I/O. Initialised: the reset check, standby (when the chip measures: ODR_CONFIG, t_standby, a read that confirms it), INT_SOURCE = 0 and an INT_STATUS read, the twelve configuration writes, a full read-back, a last INT_STATUS read, then the configured mode. About 20 transfers.

Parameters
configChecked with Validate() before any I/O.
Returns
Ok, InvalidArgument (nothing stored or sent), NoDevice, Bus, InvalidReply, Timeout, WriteMismatch, ConfigRejected or DeviceReset. After a failure that wrote, IsConfigKnown() is false; after a failure among the configuration writes the driver is uninitialised (a reset could hide behind them): call EnsureInitialized().

◆ CheckForReset()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::CheckForReset ( )
noexcept

Find out whether the chip reset since the start: one 3-byte read of OSR_CONFIG to OSR_EFF, a second one only to confirm reset evidence. Also settles a pending check.

Call it where a supply dip is possible and the application only reads the FIFO: data reads check INT_STATUS by themselves.

Returns
Ok, NotInitialized, NoDevice, Bus, InvalidReply (a reserved bit, or an INT_STATUS.por that the registers contradict) or DeviceReset.

◆ Deinitialize()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::Deinitialize ( )
noexcept

Put the chip in its lowest-power state with the soft reset, CMD = 0xB6: it leaves the chip in deep standby with every register at its reset value (section 4.3). Marks the driver uninitialised.

Always does its work, whatever the driver believes (never started, started, a reset found, the configuration in doubt): brings the bus up, selects SPI on SPI, writes ODR_CONFIG = standby with deep_dis = 1 and waits t_standby (the datasheet does not say that deep standby takes CMD; the result of this write is not needed), writes CMD, waits t_soft_res, and reads INT_STATUS, which must show por: Ok only when the reset is proved. An address that EnsureInitialized() refuses is InvalidArgument with no I/O.

Returns
Ok, InvalidArgument, NoDevice, Bus or WriteMismatch (INT_STATUS did not show the reset).

◆ EnsureInitialized()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::EnsureInitialized ( )
noexcept

Start the chip. Once started, a later call runs the reset check (one 3-byte read) and returns Ok, or starts again when the chip reset or the configuration is in doubt.

Checks the configuration and the address (no I/O when either is bad), brings the bus up, then:

  1. waits t_powup (2 ms, table 4); on SPI sends the dummy read that selects SPI (section 5.1);
  2. soft reset: CMD = 0xB6 (over I2C the chip NACKs it by design, section 7.36), waits t_soft_res (2 ms), and on SPI selects SPI again;
  3. the post-power-up checks of section 4.3.9: CHIP_ID = 0x50 (DeviceIdMismatch), STATUS polled every kPollUs until status_nvm_rdy = 1, at most Config::startup_timeout_ms (Timeout), with status_nvm_err and status_nvm_cmd_err clear (DeviceFault), and INT_STATUS = 0x10 (the reset happened) then 0x00 (the read cleared it): a stuck, floating or looped line cannot pass both;
  4. leaves the deep standby the reset left the chip in (standby with deep_dis = 1, t_standby: only standby takes every write, section 4.3.1), writes the reset marker to NVM_DATA, writes the configuration with ODR_CONFIG last, reads all of it and the marker back (WriteMismatch, DeviceReset) and enters the configured mode, read back too (ConfigRejected when normal mode's data rate is still invalid at the deadline). With the FIFO on, it waits t_reconf for the FIFO flush (section 4.6.4).

About 7 ms and 26 transfers. After a failure the driver stays uninitialised and the next call starts again at step 1.

Returns
Ok, InvalidArgument, NoDevice, Bus, DeviceIdMismatch, Timeout, DeviceFault, InvalidReply, WriteMismatch, ConfigRejected or DeviceReset (the chip reset during the sequence).

◆ GetConfig()

template<BusPort Port>
const Config & bmp581::BMP581< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration stored or last applied; mode follows SetPowerMode(). No I/O.

◆ GetLastIntStatus()

template<BusPort Port>
uint8_t bmp581::BMP581< Port >::GetLastIntStatus ( ) const
inlinenoexcept
Returns
INT_STATUS as last read, by any call; 0 before the first. No I/O (KB-CPP-129).

◆ GetLastOsrEff()

template<BusPort Port>
uint8_t bmp581::BMP581< Port >::GetLastOsrEff ( ) const
inlinenoexcept
Returns
OSR_EFF as last read (by a change to normal or continuous mode); 0 before. No I/O.

◆ GetLastStatus()

template<BusPort Port>
uint8_t bmp581::BMP581< Port >::GetLastStatus ( ) const
inlinenoexcept
Returns
STATUS as last read, by any call; 0 before the first. No I/O.

◆ GetLatchedInterrupts()

template<BusPort Port>
InterruptStatus bmp581::BMP581< Port >::GetLatchedInterrupts ( ) const
inlinenoexcept

The INT_STATUS flags seen by any read since ClearLatchedInterrupts(), the driver's own reads included (handbook KB-CPP-119). No I/O. The start-up empties it: the por of the driver's own soft reset is not news.

Returns
The latched flags.

◆ GetRevision()

template<BusPort Port>
uint8_t bmp581::BMP581< Port >::GetRevision ( ) const
inlinenoexcept
Returns
REV_ID read by the last start; 0 before. No I/O.

◆ IsConfigKnown()

template<BusPort Port>
bool bmp581::BMP581< Port >::IsConfigKnown ( ) const
inlinenoexcept
Returns
true when the chip holds GetConfig(), as last written and read back; false after a failed or mismatching write until ApplyConfig() or EnsureInitialized() succeeds. No I/O.

◆ IsInitialized()

template<BusPort Port>
bool bmp581::BMP581< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized(), until Deinitialize() or a found reset. No I/O.

◆ MeasureOnce()

template<BusPort Port>
Result< Measurement > bmp581::BMP581< Port >::MeasureOnce ( Verify  verify = Verify::None)
noexcept

One forced measurement (section 4.3.3): the reset check, ODR_CONFIG with pwr_mode = forced, polled until it shows forced, at most t_startup (WriteMismatch: the write was lost), a wait of the typical conversion time less 5 %, then polls of OSR_CONFIG to OSR_EFF every kPollUs until the chip is back in standby, at most ForcedMeasurementMaxUs() (Timeout), then the read of ReadMeasurement().

Parameters
verifyVerify::ReadBack to read the data registers a second time, as ReadMeasurement() does.
Returns
The measurement, or NotInitialized, InvalidArgument (verify not an enumerator; nothing sent), StateUnknown, Busy (the configured mode is not standby, or the chip still measures; nothing sent), NoDevice, Bus, InvalidReply, Timeout, DeviceReset, NoData or OutOfRange.

◆ ReadFifo()

template<BusPort Port>
Result< std::size_t > bmp581::BMP581< Port >::ReadFifo ( std::span< FifoSample >  out,
Verify  verify = Verify::None 
)
noexcept

Read up to out.size() frames from the FIFO: FIFO_COUNT, then one burst of whole frames from FIFO_DATA (section 4.6.3). Each sample carries its own validity (NoData for the empty frame, OutOfRange). A burst of all 0x00 or all 0xFF is InvalidReply (a stuck line; the frames read are lost). An empty FIFO, an empty frame or a frame out of range runs the reset check, since a reset empties the FIFO. On SPI the reset check always runs before the samples return (one 3-byte read): a reset between FIFO_COUNT and FIFO_DATA turns the burst into the frame that only selects SPI (section 5.1).

Parameters
outWhere the samples go; at least one.
verifyVerify::ReadBack to run the reset check also when frames were read.
Returns
The number of samples written, or NotInitialized, Unsupported (the FIFO is off in Config), InvalidArgument (empty out), StateUnknown, NoDevice, Bus, InvalidReply or DeviceReset.

◆ ReadFifoCount()

template<BusPort Port>
Result< uint8_t > bmp581::BMP581< Port >::ReadFifoCount ( )
noexcept

Read FIFO_COUNT (section 4.6.2). With the FIFO on, a count of 0 runs the reset check: a reset empties and disables the FIFO. On SPI the reset check runs before it returns (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).

Returns
The frames waiting, or NotInitialized, StateUnknown, NoDevice, Bus, InvalidReply (a reserved bit, or more frames than the FIFO holds) or DeviceReset.

◆ ReadInterruptStatus()

template<BusPort Port>
Result< InterruptStatus > bmp581::BMP581< Port >::ReadInterruptStatus ( )
noexcept

Read INT_STATUS once (section 7.21): clears its flags on the chip; the driver latches them. On SPI the reset check runs before it returns (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).

Returns
The flags, or NotInitialized, NoDevice, Bus, InvalidReply or DeviceReset.

◆ ReadMeasurement()

template<BusPort Port>
Result< Measurement > bmp581::BMP581< Port >::ReadMeasurement ( Verify  verify = Verify::None)
noexcept

Read the latest measurement from the data registers: one 12-byte read of TEMP_DATA to STATUS (sections 4.5, 4.5.1), whatever the power mode (in standby, the last one measured).

INT_STATUS in the same read goes to the latch (GetLatchedInterrupts()); a por in it runs the reset check first.

Parameters
verifyVerify::ReadBack to run the reset check too (one more 3-byte read) and read the data registers a second time (6 bytes; a third read when they differ): the bus has no CRC, and a bit flipped inside a data byte is not detectable without a second read. In continuous mode on a slow bus, or with a pre-empted caller, two new measurements inside the three reads give a false InvalidReply, never a wrong value.
Returns
The measurement, or NotInitialized, InvalidArgument (verify not an enumerator; nothing sent), NoDevice, Bus, InvalidReply (the frame cannot come from the chip, or three reads of the data differ), DeviceReset, NoData (no measurement since the reset) or OutOfRange.

◆ ReadRegister()

template<BusPort Port>
Result< uint8_t > bmp581::BMP581< Port >::ReadRegister ( uint8_t  address)
noexcept

Read one register once: one transfer, no retry, no decoding (handbook KB-CPP-129).

For bring-up and diagnostics. Reading INT_STATUS clears it on the chip (the driver latches it, and a por in it runs the reset check before the value is returned); reading CHIP_STATUS clears its I3C error flags. FIFO_DATA (it would consume part of a frame) and CMD are refused. On SPI the reset check runs before it returns (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).

Parameters
address0x01, 0x02, 0x11, 0x13 to 0x18, 0x1C to 0x28, 0x2B to 0x2D or 0x30 to 0x38.
Returns
The register value, or NotInitialized, InvalidArgument (nothing sent), NoDevice, Bus, InvalidReply or DeviceReset.

◆ SetPowerMode()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::SetPowerMode ( PowerMode  mode)
noexcept

Change the power mode (section 4.3.7).

Standby: never refused once the driver has started, also when it is uninitialised after a reset or the configuration is in doubt, and after a failed first start that reached the chip: ODR_CONFIG with pwr_mode = 0, t_standby (2.5 ms), then a read that confirms pwr_mode = 0. Normal and Continuous: the reset check, standby first when the chip measures, ODR_CONFIG, then reads of OSR_CONFIG to OSR_EFF every kPollUs until the mode and, in normal mode, OSR_EFF.odr_is_valid show, at most t_startup_deep (ConfigRejected only then). With the FIFO on, every mode waits t_reconf for the FIFO flush before Ok (section 4.6.4).

Parameters
modeStandby, Normal or Continuous; Forced is MeasureOnce().
Returns
Ok, NotInitialized, InvalidArgument (Forced, not an enumerator, or a data rate normal mode cannot reach with the oversampling; nothing sent), StateUnknown, NoDevice, Bus, InvalidReply, Timeout (standby not reached), WriteMismatch, ConfigRejected or DeviceReset.

◆ WaitDataReady()

template<BusPort Port>
Result< void > bmp581::BMP581< Port >::WaitDataReady ( )
noexcept

Wait for new data in normal or continuous mode: INT_STATUS polled every kPollUs until drdy_data_reg, at most Config::data_ready_timeout_ms. Each read clears the flags on the chip and feeds the latch. On SPI the reset check runs before Ok (one 3-byte read): the frame after a reset only selects SPI and may read like data (section 5.1).

Returns
Ok, NotInitialized, Unsupported (no data-ready source in Config, or standby, where no measurement comes; nothing sent), StateUnknown, NoDevice, Bus, InvalidReply, Timeout or DeviceReset.

The documentation for this class was generated from the following file: