|
BMP581 Driver 0.1.0
API 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). | |
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.
| Port | Your class derived from I2cInterface<Port> or SpiInterface<Port>. |
|
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.
| port | The port; it must outlive the driver. |
| config | What EnsureInitialized() will apply. |
|
inlinenoexcept |
Bind the driver to an I2C port at a 7-bit address and store the configuration. No I/O.
| port | The port; it must outlive the driver. |
| address | i2c::kI2cAddress (SDO low) or i2c::kI2cAddressSdoHigh; checked by EnsureInitialized(). |
| config | What EnsureInitialized() will apply. |
|
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.
| config | Checked with Validate() before any I/O. |
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().
|
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.
Ok, NotInitialized, NoDevice, Bus, InvalidReply (a reserved bit, or an INT_STATUS.por that the registers contradict) or DeviceReset.
|
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.
Ok, InvalidArgument, NoDevice, Bus or WriteMismatch (INT_STATUS did not show the reset).
|
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:
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;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.
Ok, InvalidArgument, NoDevice, Bus, DeviceIdMismatch, Timeout, DeviceFault, InvalidReply, WriteMismatch, ConfigRejected or DeviceReset (the chip reset during the sequence).
|
inlinenoexcept |
mode follows SetPowerMode(). No I/O.
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
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.
|
inlinenoexcept |
|
inlinenoexcept |
GetConfig(), as last written and read back; false after a failed or mismatching write until ApplyConfig() or EnsureInitialized() succeeds. No I/O.
|
inlinenoexcept |
EnsureInitialized(), until Deinitialize() or a found reset. No I/O.
|
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().
| verify | Verify::ReadBack to read the data registers a second time, as ReadMeasurement() does. |
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.
|
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).
| out | Where the samples go; at least one. |
| verify | Verify::ReadBack to run the reset check also when frames were read. |
NotInitialized, Unsupported (the FIFO is off in Config), InvalidArgument (empty out), StateUnknown, NoDevice, Bus, InvalidReply or DeviceReset.
|
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).
NotInitialized, StateUnknown, NoDevice, Bus, InvalidReply (a reserved bit, or more frames than the FIFO holds) or DeviceReset.
|
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).
NotInitialized, NoDevice, Bus, InvalidReply or DeviceReset.
|
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.
| verify | Verify::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. |
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.
|
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).
| address | 0x01, 0x02, 0x11, 0x13 to 0x18, 0x1C to 0x28, 0x2B to 0x2D or 0x30 to 0x38. |
NotInitialized, InvalidArgument (nothing sent), NoDevice, Bus, InvalidReply or DeviceReset.
|
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).
| mode | Standby, Normal or Continuous; Forced is MeasureOnce(). |
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.
|
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).
Ok, NotInitialized, Unsupported (no data-ready source in Config, or standby, where no measurement comes; nothing sent), StateUnknown, NoDevice, Bus, InvalidReply, Timeout or DeviceReset.