unit_bmi270.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_IMU_UNIT_UNIT_BMI270_HPP
#define M5_UNIT_IMU_UNIT_UNIT_BMI270_HPP
 
#include <M5UnitComponent.hpp>
#include <m5_utility/container/circular_buffer.hpp>
#include <memory>
#include "unit_bmi270_data.hpp"
#include "unit_bmm150_data.hpp"
#include "../imu/imu_data_source.hpp"
 
namespace m5 {
namespace unit {
 
class UnitBMI270 : public Component,
                   public PeriodicMeasurementAdapter<UnitBMI270, bmi270::Data>,
                   public m5::imu::IMUDataSource {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitBMI270, 0x69);
 
public:
    struct config_t {
        bool start_periodic{true};
        bmi270::AccelRange accel_range{bmi270::AccelRange::G8};
        bmi270::GyroRange gyro_range{bmi270::GyroRange::DPS2000};
        bmi270::AccelODR accel_odr{bmi270::AccelODR::Rate200Hz};
        bmi270::GyroODR gyro_odr{bmi270::GyroODR::Rate200Hz};
        bmi270::FilterPerf accel_filter_perf{bmi270::FilterPerf::Performance};
        bmi270::AccelBwp accel_bwp{bmi270::AccelBwp::NormAvg4};
        bmi270::FilterPerf gyro_filter_perf{bmi270::FilterPerf::Performance};
        bmi270::GyroBwp gyro_bwp{bmi270::GyroBwp::Norm};
    };
 
    explicit UnitBMI270(const uint8_t addr = DEFAULT_ADDRESS);
    virtual ~UnitBMI270()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
    config_t config() const
    {
        return _cfg;
    }
    void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    bool writeAccelRange(const bmi270::AccelRange range);
    bool writeGyroRange(const bmi270::GyroRange range);
    bool readAccelRange(bmi270::AccelRange& range);
    bool readGyroRange(bmi270::GyroRange& range);
 
    bool writeAccelODR(const bmi270::AccelODR odr);
    bool writeGyroODR(const bmi270::GyroODR odr);
    bool readAccelODR(bmi270::AccelODR& odr);
    bool readGyroODR(bmi270::GyroODR& odr);
 
    bool softReset();
 
 
    bool startPeriodicMeasurement(const bmi270::AccelRange accel_range, const bmi270::GyroRange gyro_range,
                                  const bmi270::AccelODR accel_odr, const bmi270::GyroODR gyro_odr,
                                  const bmi270::FilterPerf accel_filter_perf, const bmi270::AccelBwp accel_bwp,
                                  const bmi270::FilterPerf gyro_filter_perf, const bmi270::GyroBwp gyro_bwp);
    bool startPeriodicMeasurement();
    bool stopPeriodicMeasurement();
 
 
    bool sleep() override;
    bool wakeup() override;
 
    virtual m5::imu::Capability imuSpec() const override
    {
        using m5::imu::Capability;
        return Capability::Accel | Capability::Gyro | Capability::Temp;
    }
    virtual m5::imu::Capability readImuRaw(m5::imu::imu_raw_data_t& out) override;
    virtual void imuConvertParam(m5::imu::imu_convert_param_t& out) const override;
 
protected:
    virtual bool start_periodic_measurement(const bmi270::AccelRange accel_range, const bmi270::GyroRange gyro_range,
                                            const bmi270::AccelODR accel_odr, const bmi270::GyroODR gyro_odr,
                                            const bmi270::FilterPerf accel_filter_perf,
                                            const bmi270::AccelBwp accel_bwp, const bmi270::FilterPerf gyro_filter_perf,
                                            const bmi270::GyroBwp gyro_bwp);
    bool start_periodic_measurement();
    bool stop_periodic_measurement();
    bool read_measurement(bmi270::Data& d);
    // Read one sample's sensor registers into d. Split out of read_measurement() so a subclass
    // can widen the burst without repeating the temperature handling that follows it (see
    // UnitBMI270AuxBMM150).
    virtual bool read_sensor_burst(bmi270::Data& d);
    bool write_register8_verified(const uint8_t reg, const uint8_t val);
    // readRegister8() without its "Failed to write" log, for the reads whose failure is expected:
    // the dummy transaction that brings the I2C interface up after power-on, the two polls that wait
    // out the ~2ms reboot after a soft reset, and the verified-write readback that is retried
    bool read_register8_quiet(const uint8_t reg, uint8_t& out);
    // Last resort for a CHIP_ID that came back wrong: soft reset the device and read it again.
    // Call only once the address has acknowledged, and only with the value it answered: the reset
    // is skipped unless that value is one the real CHIP_ID could have decayed into on a contended
    // bus (see the .cpp), so a different chip living at this address is never written to. Reaches
    // only the form where the chip still answers: a bus being held low takes no writes at all
    bool recover_wedged_interface(const uint8_t id);
    // Uploads the 8192 byte configuration blob (unit_bmi270_config.inl) to REG_INIT_DATA,
    // split into chunks that fit within the I2C write buffer (see .cpp for chunk size
    // rationale). Returns false (and logs) on the first failed chunk, unlike M5Unified's
    // BMI270_Class::_upload_file() which always returns true regardless of write result.
    bool upload_config();
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitBMI270, bmi270::Data);
 
private:
    // Settings for begin(); never written to after that. What is currently on the device lives in
    // the live-state members below, so config() keeps meaning "what was configured"
    config_t _cfg{};
    // Mirrors of the registers this driver can change at runtime. imuConvertParam() needs the range
    // actually in effect (a stale factor would silently misreport every sample), and the no-argument
    // startPeriodicMeasurement() resumes from these rather than reverting to _cfg
    bmi270::AccelRange _accel_range{};
    bmi270::GyroRange _gyro_range{};
    bmi270::AccelODR _accel_odr{};
    bmi270::GyroODR _gyro_odr{};
    // Bandwidth and filter performance have no runtime setter of their own, but they share
    // REG_ACC_CONF/REG_GYR_CONF with the rate: writeAccelODR() has to recompose the whole register,
    // and taking these from _cfg there would silently apply a config() change the caller only meant
    // to take effect at the next start
    bmi270::FilterPerf _accel_filter_perf{};
    bmi270::AccelBwp _accel_bwp{};
    bmi270::FilterPerf _gyro_filter_perf{};
    bmi270::GyroBwp _gyro_bwp{};
    int16_t _last_temp{};             // Latest valid REG_TEMPERATURE_0 reading (register update is not per-sample)
    uint32_t _pushed{}, _consumed{};  // readImuRaw pop counters (do not disturb latest()/oldest())
    std::unique_ptr<m5::container::CircularBuffer<bmi270::Data>> _data{};
};
 
namespace bmi270 {
constexpr uint32_t DEFAULT_STORED_SIZE{8};
 
namespace command {
// Register addresses (I2C addr 0x68 (SDO=GND) / 0x69 (SDO=VDDIO, M5 board default))
constexpr uint8_t REG_DATA_0{0x04};         // AUX (mag) burst start: 20 bytes = mag(8)+accel(6)+gyro(6), see REG_DATA_8
constexpr uint8_t REG_STATUS{0x03};         // bit2 = aux_man_op busy (named REG_STATUS, not STATUS: ESP-IDF's
                                            // ets_sys.h has a global `typedef enum STATUS STATUS`)
constexpr uint8_t REG_DATA_8{0x0C};         // 12 bytes: accel X/Y/Z, gyro X/Y/Z (little-endian)
constexpr uint8_t REG_INT_STATUS_1{0x1D};   // bit7 acc_drdy, bit6 gyr_drdy, bit5 aux_drdy
constexpr uint8_t REG_TEMPERATURE_0{0x22};  // 2 bytes, little-endian, 0x8000 = invalid
constexpr uint8_t REG_INTERNAL_STATUS{0x21};
constexpr uint8_t REG_ACC_CONF{0x40};
constexpr uint8_t REG_ACC_RANGE{0x41};
constexpr uint8_t REG_GYR_CONF{0x42};
constexpr uint8_t REG_GYR_RANGE{0x43};
constexpr uint8_t REG_AUX_DEV_ID{0x4B};
// Poll rate and trigger-readout offset for the AUX target (see UnitBMI270AuxBMM150)
constexpr uint8_t REG_AUX_CONF{0x44};
constexpr uint8_t REG_AUX_IF_CONF{
    0x4C};  // bit7 manual_en, bit6 fcu_write_en, bits[3:2] man_rd_burst, bits[1:0] aux_rd_burst
constexpr uint8_t REG_AUX_RD_ADDR{0x4D};  // write triggers an AUX read transaction
constexpr uint8_t REG_AUX_WR_ADDR{0x4E};  // write triggers an AUX write transaction (of REG_AUX_WR_DATA)
constexpr uint8_t REG_AUX_WR_DATA{0x4F};
constexpr uint8_t REG_INIT_CTRL{0x59};
constexpr uint8_t REG_INIT_ADDR_0{0x5B};  // followed by INIT_ADDR_1 (0x5C)
constexpr uint8_t REG_INIT_DATA{0x5E};
constexpr uint8_t REG_IF_CONF{0x6B};   // bit5 aux_en
constexpr uint8_t REG_PWR_CONF{0x7C};  // bit0 adv_power_save
constexpr uint8_t REG_PWR_CTRL{0x7D};  // bit0 aux_en, bit1 gyr_en, bit2 acc_en, bit3 temp_en
constexpr uint8_t REG_CMD{0x7E};
constexpr uint8_t REG_CHIP_ID{0x00};
 
// BMM150 registers, reachable only indirectly through the AUX bridge above (distinct address
// space from this chip's own registers). Only UnitBMI270AuxBMM150 talks to them; they live here
// because they are addressed through this chip's AUX registers
constexpr uint8_t REG_BMM150_CHIP_ID{0x40};
constexpr uint8_t REG_BMM150_DATA_X_LSB{0x42};
constexpr uint8_t REG_BMM150_POWER_CONTROL{0x4B};
constexpr uint8_t REG_BMM150_OP_MODE{0x4C};
constexpr uint8_t REG_BMM150_REP_XY{0x51};
constexpr uint8_t REG_BMM150_REP_Z{0x52};
}  // namespace command
 
constexpr uint8_t CHIP_ID{0x24};
 
template <class ReadReg>
bool detectAddress(ReadReg read, uint8_t& addr)
{
    for (const uint8_t candidate : {static_cast<uint8_t>(0x68), static_cast<uint8_t>(0x69)}) {
        uint8_t id{};
        if (read(candidate, command::REG_CHIP_ID, id) && id == CHIP_ID) {
            addr = candidate;
            return true;
        }
    }
    return false;
}
}  // namespace bmi270
 
}  // namespace unit
}  // namespace m5
#endif