Skip to content

API guide

Common tasks with bmp581::BMP581<Port>, task by task. Every call returns Result<T>; check it before using the value. The API reference lists every member.

Datasheet sections this page relies on

From Bosch Sensortec BST-BMP581-DS004-13 1.13:

  • Measurement range, resolution and accuracy: 2 Specification; Table 1 Pressure Performance; Table 2 Temperature Performance, p. 8
  • 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
  • Forced mode: 4.3.3 FORCED mode, p. 16
  • Data registers and data shadowing: 4.5 Data registers; 4.5.1 Data Shadowing, p. 22
  • FIFO: 4.6 FIFO; 4.6.1 FIFO Configuration; 4.6.3 FIFO data readout; Tables 11 to 14, p. 22
  • 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
  • Register map: 7 Register Map, p. 50

All of them, with the driver API for each: Datasheet map.

Start the chip

bmp581::Error BringUp(Sensor& sensor) {
  // The one entry point: starts the chip on the first call; later calls run the reset check and
  // start again when the chip reset. After a failure the next call starts from the beginning.
  const auto r = sensor.EnsureInitialized();
  if (!r) {
    std::printf("BMP581 init: %s\n", bmp581::ToString(r.error));
  }
  return r.error;
}

The first call soft-resets the chip and configures it (about 5 ms); a later call checks for a reset with one 3-byte read. Nothing touches the chip before it: every other call returns NotInitialized.

Measure on request (forced mode)

bmp581::Result<bmp581::Measurement> SampleOnDemand(Sensor& sensor) {
  // Standby between calls (deep standby with Config{}); one forced measurement per call.
  return sensor.MeasureOnce(); // reset check, forced, poll until standby, one 12-byte read
}

The configured mode stays standby (deep standby with Config{}), and each MeasureOnce() runs one measurement: the reset check, ODR_CONFIG = forced, a read that proves it started, a wait of the typical conversion time less 5 %, polls until the chip is back in standby (at most ForcedMeasurementMaxUs(), Timeout after), and the data read. In normal or continuous mode it returns Busy with nothing sent.

Measurement holds the chip's own units. Convert with PressurePa(m.pressure_raw) (1/64 Pa per count) and TemperatureC(m.temperature_raw) (1/65536 °C per count); both are exact.

Stream in normal mode

bmp581::Error StreamAt25Hz(Sensor& sensor, int samples) {
  // HighResolutionPreset(): normal mode, 25 Hz, x16 pressure, IIR, data-ready source on.
  if (auto r = sensor.ApplyConfig(bmp581::HighResolutionPreset()); !r) {
    return r.error;
  }
  for (int i = 0; i < samples; ++i) {
    if (auto r = sensor.WaitDataReady(); !r) {
      return r.error; // Timeout, or DeviceReset: call EnsureInitialized()
    }
    const auto m = sensor.ReadMeasurement();
    if (!m) {
      return m.error;
    }
    std::printf("%.3f Pa\n", static_cast<double>(bmp581::PressurePa(m.value.pressure_raw)));
  }
  return bmp581::Error::Ok;
}

WaitDataReady() polls INT_STATUS every kPollUs until drdy, at most Config::data_ready_timeout_ms; it needs Config::source_data_ready (the chip reports drdy only for an enabled source, section 4.7.1). ReadMeasurement() reads the data registers whatever the mode; in standby it returns the last measurement. Each INT_STATUS read clears the flags on the chip; the driver keeps them in a latch, GetLatchedInterrupts(), until ClearLatchedInterrupts().

SetPowerMode() changes the mode alone: standby, normal or continuous, always through standby and read back. In normal mode the chip checks the data rate against the oversampling; when it disagrees (OSR_EFF.odr_is_valid = 0) the call returns ConfigRejected and leaves the chip in standby. Validate() refuses those combinations first, from table 7.

Read the FIFO

std::size_t DrainFifo(Sensor& sensor, std::span<bmp581::FifoSample> out) {
  // FifoPreset(): pressure-and-temperature frames at 10 Hz, threshold at 8 frames.
  const auto n = sensor.ReadFifo(out);
  if (!n) {
    return 0; // InvalidReply (a stuck line) or DeviceReset
  }
  std::size_t good = 0;
  for (std::size_t i = 0; i < n.value; ++i) {
    good += (out[i].error == bmp581::Error::Ok) ? 1U : 0U; // each frame has its own validity
  }
  return good;
}

ReadFifo() reads FIFO_COUNT, then whole frames in one burst from FIFO_DATA, as many as out holds; the rest stay. Each FifoSample has its own error: NoData for the empty frame (0x7F7F7F), OutOfRange. A temperature-and-pressure frame fills both values; a single-value frame says which one it has. A configuration change flushes the FIFO (section 4.6.4). An empty FIFO runs the reset check, because a reset empties it.

Handle a reset

bmp581::Error Supervise(Sensor& sensor) {
  // A brown-out resets the chip to standby with every register at its reset value. Every data
  // read checks for it; CheckForReset() does it alone (one 2-byte read).
  const auto r = sensor.CheckForReset();
  if (r.error == bmp581::Error::DeviceReset) {
    return sensor.EnsureInitialized().error; // soft reset and the configuration, again
  }
  return r.error;
}

Data reads, polls and setters find a reset by themselves and return DeviceReset; the driver is then uninitialised, so the next call is EnsureInitialized(). How the driver tells a reset from a broken line: Contract.

Handle errors

const char* Describe(bmp581::Error e) {
  switch (e) {
  case bmp581::Error::NoDevice:
  case bmp581::Error::Bus:
  case bmp581::Error::DeviceIdMismatch:
    return "check the wiring, CSB and SDO, and the address";
  case bmp581::Error::InvalidReply:
    return "a line is stuck or floating: check pull-ups and SDO";
  case bmp581::Error::DeviceReset:
    return "the chip reset: call EnsureInitialized()";
  case bmp581::Error::OutOfRange:
    return "outside 30 to 125 kPa or -40 to 85 degrees C";
  default:
    return bmp581::ToString(e);
  }
}
Error What to do
NoDevice, Bus Check power, wiring and the address (I2C) or CSB (SPI); retry EnsureInitialized()
DeviceIdMismatch Another part answers, or the soft reset did not happen: see Troubleshooting
InvalidReply A line is stuck, floating or disturbed: check pull-ups, SDO, CSB; the next call reads again
DeviceReset Call EnsureInitialized()
NoData No measurement since the reset: start one (MeasureOnce(), normal mode)
OutOfRange The environment is outside the sensor's range, or the reading is wrong
WriteMismatch, StateUnknown Call ApplyConfig() again; check the bus
Timeout See Troubleshooting
Busy Switch to standby before MeasureOnce()
Unsupported Enable the data-ready source or the FIFO in Config
ConfigRejected Lower the data rate or the oversampling (table 7)

Crc is never returned: neither bus carries a CRC.

Diagnostics and raw access

  • ReadRegister(address) reads one register once, with no retry (KB-CPP-129); FIFO_DATA and CMD are refused. A raw INT_STATUS read clears the flags and feeds the latch.
  • GetLastIntStatus(), GetLastStatus(), GetLastOsrEff(), GetRevision() return what the last read saw, with no I/O.
  • ReadInterruptStatus() reads INT_STATUS once and decodes it.
  • ReadMeasurement(Verify::ReadBack) and ReadFifo(out, Verify::ReadBack) add the reset check, one 3-byte read. ReadMeasurement(Verify::ReadBack) and MeasureOnce(Verify::ReadBack) also read the data registers a second time (6 bytes, a third when they differ): a bit flipped inside a data byte is not detectable without it.

Shut down

void PowerDown(Sensor& sensor) {
  // One byte, CMD = 0xB6: deep standby with the reset values, proved by INT_STATUS.por.
  if (auto r = sensor.Deinitialize(); !r) {
    std::printf("BMP581 soft reset not proved: %s\n", bmp581::ToString(r.error));
  }
}

Deinitialize() always does its work, also before a start or after a reset; the driver is uninitialised afterwards either way.