unit_BME688.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2024 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_ENV_UNIT_BME688_HPP
#define M5_UNIT_ENV_UNIT_BME688_HPP
 
#include <M5UnitComponent.hpp>
#include <m5_utility/stl/extension.hpp>
 
#if defined(ARDUINO)
#include <bme68xLibrary.h>
#else
#include <bme68x/bme68x.h>
#endif
 
// Enable BSEC2 (IAQ) only where the prebuilt blob exists and the headers are actually available.
// Arduino users opt in by installing boschsensortec/bsec2. ESP-IDF native users opt in via
// CONFIG_M5UNIT_ENV_ENABLE_BSEC2, which makes the in-repo components/bsec2 recipe expose headers.
#if defined(ARDUINO)
#if __has_include(<bsec2.h>) && \
    (defined(CONFIG_IDF_TARGET_ESP32) || defined(CONFIG_IDF_TARGET_ESP32S3) || defined(CONFIG_IDF_TARGET_ESP32C3))
#define UNIT_BME688_USING_BSEC2
#endif
#elif __has_include(<inc/bsec_interface.h>)
#define UNIT_BME688_USING_BSEC2
#endif
 
#if defined(UNIT_BME688_USING_BSEC2)
#if defined(ARDUINO)
#include <bsec2.h>
#else
#include <inc/bsec_datatypes.h>
// ESP-IDF native uses the raw BSEC API directly (no Arduino Bsec2 wrapper). The BME688 code relies
// on two small helpers that the Arduino wrapper (bsec2.h) provides but the raw API headers do not;
// define them here identically. BSEC_NUMBER_OUTPUTS comes from <inc/bsec_datatypes.h>.
#ifndef BSEC_CHECK_INPUT
#define BSEC_CHECK_INPUT(x, shift) (x & (1 << (shift - 1)))
#endif
typedef bsec_output_t bsecData;
typedef struct {
    bsecData output[BSEC_NUMBER_OUTPUTS];
    uint8_t nOutputs;
} bsecOutputs;
#endif
#endif
 
#include <memory>
#include <limits>
#include <initializer_list>
 
namespace m5 {
namespace unit {
 
namespace bme688 {
 
enum class Mode : uint8_t {
    Sleep,       
    Forced,      
    Parallel,    
    Sequential,  
};
 
 
using bme68xData = struct bme68x_data;
using bme68xDev = struct bme68x_dev;
using bme68xConf = struct bme68x_conf;
struct bme68xHeatrConf : bme68x_heatr_conf {
    uint16_t temp_prof[10]{};
    uint16_t dur_prof[10]{};
    bme68xHeatrConf() : bme68x_heatr_conf()
    {
        heatr_temp_prof = temp_prof;
        heatr_dur_prof  = dur_prof;
    }
};
using bme68xCalibration = struct bme68x_calib_data;
 
enum class Oversampling : uint8_t {
    None,  
    x1,    
    x2,    
    x4,    
    x8,    
    x16,   
};
 
enum class Filter : uint8_t {
    None,       
    Coeff_1,    
    Coeff_3,    
    Coeff_7,    
    Coeff_15,   
    Coeff_31,   
    Coeff_63,   
    Coeff_127,  
};
 
enum class ODR : uint8_t {
    MS_0_59,  
    MS_62_5,  
    MS_125,   
    MS_250,   
    MS_500,   
    MS_1000,  
    MS_10,    
    MS_20,    
    None,     
};
 
struct GasWait {
    GasWait() : value{0}
    {
    }
    enum class Factor { x1, x4, x16, x64 };
    inline uint8_t step() const
    {
        return value & 0x3F;
    }
    inline Factor factor() const
    {
        return static_cast<Factor>((value >> 6) & 0x03);
    }
 
    inline void step(const uint8_t s)
    {
        value = (value & ~0x3F) | (s & 0x3F);
    }
    inline void factor(const Factor f)
    {
        value = (value & ~(0x03 << 6)) | (m5::stl::to_underlying(f) << 6);
    }
 
    static uint8_t from(const uint16_t duration)
    {
        uint8_t f{};
        uint16_t d{duration};
        while (d > 0x3F) {
            d >>= 2;
            ++f;
        }
        return (f <= 0x03) ? ((uint8_t)d | (f << 6)) : 0xFF;
    }
    static uint16_t to(const uint8_t v)
    {
        constexpr uint16_t tbl[] = {1, 4, 16, 64};
        return (v & 0x3F) * tbl[(v >> 6) & 0x03];
    }
 
    uint8_t value{};  
};
 
#if defined(UNIT_BME688_USING_BSEC2)
namespace bsec2 {
 
constexpr uint8_t ACCURACY_UNAVAILABLE{0xFF};
 
enum class SampleRate : uint8_t {
    Disabled,                          
    LowPower,                          
    UltraLowPower,                     
    UltraLowPowerMeasurementOnDemand,  
    Scan,                              
    Continuous,                        
};
 
template <typename T>
void is_bsec_virtual_sensor_t()
{
    static_assert(std::is_same<T, bsec_virtual_sensor_t>::value, "Argument must be of type bsec_virtual_sensor_t");
}
 
inline uint32_t virtual_sensor_array_to_bits(const bsec_virtual_sensor_t* ss, const size_t len)
{
    uint32_t ret{};
    for (size_t i = 0; i < len; ++i) {
        ret |= ((uint32_t)1U) << ss[i];
    }
    return ret;
}
 
template <typename... Args>
uint32_t subscribe_to_bits(Args... args)
{
    // In a C++17 or later environment, it can be written like this...
    // static_assert(std::conjunction<std::is_same<Args, bsec_virtual_sensor_t>...>::value,
    //          "All arguments must be of type bsec_virtual_sensor_t");
    int discard[] = {(is_bsec_virtual_sensor_t<Args>(), 0)...};
    (void)discard;
 
    bsec_virtual_sensor_t tmp[] = {args...};
    constexpr size_t n          = sizeof...(args);
    return virtual_sensor_array_to_bits(tmp, n);
}
 
}  // namespace bsec2
#endif
 
struct Data {
    bme688::bme68xData raw{};
#if defined(UNIT_BME688_USING_BSEC2)
    bsecOutputs raw_outputs{};
 
    float get(const bsec_virtual_sensor_t vs) const;
    uint8_t accuracy(const bsec_virtual_sensor_t vs) const;
    int64_t timestamp(const bsec_virtual_sensor_t vs) const;
    inline uint8_t iaq_accuracy() const
    {
        return accuracy(BSEC_OUTPUT_IAQ);
    }
    inline float iaq() const
    {
        return get(BSEC_OUTPUT_IAQ);
    }
    inline float static_iaq() const
    {
        return get(BSEC_OUTPUT_STATIC_IAQ);
    }
    inline float co2() const
    {
        return get(BSEC_OUTPUT_CO2_EQUIVALENT);
    }
    inline float voc() const
    {
        return get(BSEC_OUTPUT_BREATH_VOC_EQUIVALENT);
    }
    inline float temperature() const
    {
        return get(BSEC_OUTPUT_RAW_TEMPERATURE);
    }
    inline float pressure() const
    {
        return get(BSEC_OUTPUT_RAW_PRESSURE);
    }
    inline float humidity() const
    {
        return get(BSEC_OUTPUT_RAW_HUMIDITY);
    }
    inline float gas() const
    {
        return get(BSEC_OUTPUT_RAW_GAS);
    }
    inline bool gas_stabilization() const
    {
        return get(BSEC_OUTPUT_STABILIZATION_STATUS) == 1.0f;
    }
    inline bool gas_run_in_status() const
    {
        return get(BSEC_OUTPUT_RUN_IN_STATUS) == 1.0f;
    }
    inline float heat_compensated_temperature() const
    {
        return get(BSEC_OUTPUT_SENSOR_HEAT_COMPENSATED_TEMPERATURE);
    }
    inline float heat_compensated_humidity() const
    {
        return get(BSEC_OUTPUT_SENSOR_HEAT_COMPENSATED_HUMIDITY);
    }
    inline float compensated_gas() const
    {
        return get(BSEC_OUTPUT_COMPENSATED_GAS);
    }
    inline float gas_percentage() const
    {
        return get(BSEC_OUTPUT_GAS_PERCENTAGE);
    }
    inline float gas_estimate_1() const
    {
        return get(BSEC_OUTPUT_GAS_ESTIMATE_1);
    }
    inline float gas_estimate_2() const
    {
        return get(BSEC_OUTPUT_GAS_ESTIMATE_2);
    }
    inline float gas_estimate_3() const
    {
        return get(BSEC_OUTPUT_GAS_ESTIMATE_3);
    }
    inline float gas_estimate_4() const
    {
        return get(BSEC_OUTPUT_GAS_ESTIMATE_4);
    }
    inline uint32_t gas_index() const
    {
        return get(BSEC_OUTPUT_RAW_GAS_INDEX);
    }
    inline float regression_estimate_1() const
    {
        return get(BSEC_OUTPUT_REGRESSION_ESTIMATE_1);
    }
    inline float regression_estimate_2() const
    {
        return get(BSEC_OUTPUT_REGRESSION_ESTIMATE_2);
    }
    inline float regression_estimate_3() const
    {
        return get(BSEC_OUTPUT_REGRESSION_ESTIMATE_3);
    }
    inline float regression_estimate_4() const
    {
        return get(BSEC_OUTPUT_REGRESSION_ESTIMATE_4);
    }
#endif
    inline float raw_temperature() const
    {
        return raw.temperature;
    }
    inline float raw_pressure() const
    {
        return raw.pressure;
    }
    inline float raw_humidity() const
    {
        return raw.humidity;
    }
    inline float raw_gas() const
    {
        return raw.gas_resistance;
    }
};
 
}  // namespace bme688
 
class UnitBME688 : public Component, public PeriodicMeasurementAdapter<UnitBME688, bme688::Data> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitBME688, 0x77);
 
public:
    struct config_t {
        bool start_periodic{true};
        int8_t ambient_temperature{25};
#if defined(UNIT_BME688_USING_BSEC2) || defined(DOXYGEN_PROCESS)
 
        uint32_t subscribe_bits{1U << BSEC_OUTPUT_IAQ | 1U << BSEC_OUTPUT_RAW_TEMPERATURE |
                                1U << BSEC_OUTPUT_RAW_PRESSURE | 1U << BSEC_OUTPUT_RAW_HUMIDITY |
                                1U << BSEC_OUTPUT_RAW_GAS | 1U << BSEC_OUTPUT_STABILIZATION_STATUS |
                                1U << BSEC_OUTPUT_RUN_IN_STATUS};
        bme688::bsec2::SampleRate sample_rate{bme688::bsec2::SampleRate::LowPower};
#endif
#if !defined(UNIT_BME688_USING_BSEC2) || defined(DOXYGEN_PROCESS)
 
        bme688::Mode mode{bme688::Mode::Forced};
        bme688::Oversampling oversampling_temperature{bme688::Oversampling::x2};
        bme688::Oversampling oversampling_pressure{bme688::Oversampling::x1};
        bme688::Oversampling oversampling_humidity{bme688::Oversampling::x16};
        bme688::Filter filter{bme688::Filter::None};
        bme688::ODR odr{bme688::ODR::None};
        bool heater_enable{true};
        uint16_t heater_temperature{300};
        uint16_t heater_duration{100};
#endif
    };
 
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    explicit UnitBME688(const uint8_t addr = DEFAULT_ADDRESS);
    virtual ~UnitBME688()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
    inline bme688::Mode mode() const
    {
        return _mode;
    }
    inline const bme688::bme68xCalibration& calibration() const
    {
        return _dev.calib;
    }
    inline const bme688::bme68xConf& tphSetting() const
    {
        return _tphConf;
    }
    inline const bme688::bme68xHeatrConf& heaterSetting() const
    {
        return _heaterConf;
    }
    inline int8_t ambientTemperature() const
    {
        return _dev.amb_temp;
    }
 
#if defined(UNIT_BME688_USING_BSEC2)
    inline float iaq() const
    {
        return !empty() ? oldest().iaq() : std::numeric_limits<float>::quiet_NaN();
    }
    inline uint8_t iaqAccuracy() const
    {
        return !empty() ? oldest().iaq_accuracy() : bme688::bsec2::ACCURACY_UNAVAILABLE;
    }
    inline float temperature() const
    {
        return !empty() ? oldest().temperature() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float pressure() const
    {
        return !empty() ? oldest().pressure() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float humidity() const
    {
        return !empty() ? oldest().humidity() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float gas() const
    {
        return !empty() ? oldest().gas() : std::numeric_limits<float>::quiet_NaN();
    }
#else
    inline float temperature() const
    {
        return !empty() ? oldest().raw_temperature() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float pressure() const
    {
        return !empty() ? oldest().raw_pressure() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float humidity() const
    {
        return !empty() ? oldest().raw_humidity() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float gas() const
    {
        return !empty() ? oldest().raw_gas() : std::numeric_limits<float>::quiet_NaN();
    }
#endif
    float altitude(const float sea_level_pa = 101325.0f) const;
    float relativeAltitude() const;
    void setAltitudeReference();
 
#if 0
    inline uint8_t numberOfRawData() const
    {
        return _num_of_data;
    }
    inline const bme688::bme68xData* data(const uint8_t idx)
    {
        return (idx < _num_of_data) ? &_raw_data[idx] : nullptr;
    }
#endif
 
    inline void setAmbientTemperature(const int8_t temp)
    {
        _dev.amb_temp = temp;
    }
    [[deprecated("Use setAmbientTemperature")]] inline void setAambientTemperature(const int8_t temp)
    {
        setAmbientTemperature(temp);
    }
    bool readCalibration(bme688::bme68xCalibration& c);
    bool writeCalibration(const bme688::bme68xCalibration& c);
    uint32_t calculateMeasurementInterval(const bme688::Mode mode, const bme688::bme68xConf& s);
    bool readUniqueID(uint32_t& id);
    bool softReset();
    bool selfTest();
    bool writeMode(const bme688::Mode m);
    bool readMode(bme688::Mode& m);
 
 
    bool readTPHSetting(bme688::bme68xConf& s);
    bool readOversamplingTemperature(bme688::Oversampling& os);
    bool readOversamplingPressure(bme688::Oversampling& os);
    bool readIIRFilter(bme688::Filter& f);
    bool readOversamplingHumidity(bme688::Oversampling& os);
    bool writeTPHSetting(const bme688::bme68xConf& s);
    bool writeOversampling(const bme688::Oversampling t, const bme688::Oversampling p, const bme688::Oversampling h);
    bool writeOversamplingTemperature(const bme688::Oversampling os);
    bool writeOversamplingPressure(const bme688::Oversampling os);
    bool writeOversamplingHumidity(const bme688::Oversampling os);
    bool writeIIRFilter(const bme688::Filter f);
 
 
    bool readHeaterSetting(bme688::bme68xHeatrConf& hs);
    bool writeHeaterSetting(const bme688::Mode mode, const bme688::bme68xHeatrConf& hs);
 
 
    inline bool startPeriodicMeasurement(const bme688::Mode m)
    {
        return PeriodicMeasurementAdapter<UnitBME688, bme688::Data>::startPeriodicMeasurement(m);
    }
#if defined(UNIT_BME688_USING_BSEC2) || defined(DOXYGEN_PROCESS)
    inline bool startPeriodicMeasurement(const uint32_t subscribe_bits,
                                         const bme688::bsec2::SampleRate sr = bme688::bsec2::SampleRate::LowPower)
    {
        return PeriodicMeasurementAdapter<UnitBME688, bme688::Data>::startPeriodicMeasurement(subscribe_bits, sr);
    }
    inline bool startPeriodicMeasurement(const bsec_virtual_sensor_t* ss, const size_t len,
                                         const bme688::bsec2::SampleRate sr = bme688::bsec2::SampleRate::LowPower)
    {
        return ss ? startPeriodicMeasurement(bme688::bsec2::virtual_sensor_array_to_bits(ss, len), sr) : false;
    }
 
#endif
    inline bool stopPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitBME688, bme688::Data>::stopPeriodicMeasurement();
    }
 
 
    bool measureSingleshot(bme688::bme68xData& data);
    [[deprecated("Use measureSingleshot")]] inline bool measureSingleShot(bme688::bme68xData& data)
    {
        return measureSingleshot(data);
    }
 
#if defined(UNIT_BME688_USING_BSEC2) || defined(DOXYGEN_PROCESS)
 
    float bsec2GetTemperatureOffset() const
    {
        return _temperatureOffset;
    }
    void bsec2SetTemperatureOffset(const float offset)
    {
        _temperatureOffset = offset;
    }
    const bsec_version_t& bsec2Version() const
    {
        return _bsec2_version;
    }
    bool bsec2SetConfig(const uint8_t* cfg, const size_t sz = BSEC_MAX_PROPERTY_BLOB_SIZE);
    bool bsec2GetConfig(uint8_t* cfg, uint32_t& actualSize);
    bool bsec2SetState(const uint8_t* state);
    bool bsec2GetState(uint8_t* state, uint32_t& actualSize);
    bool bsec2UpdateSubscription(const uint32_t sensorBits, const bme688::bsec2::SampleRate sr);
    inline bool bsec2UpdateSubscription(const bsec_virtual_sensor_t* ss, const size_t len,
                                        const bme688::bsec2::SampleRate sr)
    {
        return bsec2UpdateSubscription(bme688::bsec2::virtual_sensor_array_to_bits(ss, len), sr);
    }
    inline bool bsec2IsSubscribed(const bsec_virtual_sensor_t id)
    {
        return _bsec2_subscription & (1U << id);
    }
    uint32_t bsec2Subscription() const
    {
        return _bsec2_subscription;
    }
    bool bsec2Subscribe(const bsec_virtual_sensor_t id);
    bool bsec2Unsubscribe(const bsec_virtual_sensor_t id);
    bool bsec2UnsubscribeAll();
#endif
 
protected:
    static int8_t read_function(uint8_t reg_addr, uint8_t* reg_data, uint32_t length, void* intf_ptr);
    static int8_t write_function(uint8_t reg_addr, const uint8_t* reg_data, uint32_t length, void* intf_ptr);
 
    bool start_periodic_measurement(const bme688::Mode m);
    bool stop_periodic_measurement();
#if defined(UNIT_BME688_USING_BSEC2)
    bool start_periodic_measurement(const uint32_t subscribe_bits, const bme688::bsec2::SampleRate sr);
#endif
 
    bool write_mode_forced();
    bool write_mode_parallel();
    bool fetch_data();
 
    void update_bme688(const bool force);
    bool read_measurement();
#if defined(UNIT_BME688_USING_BSEC2)
    bool process_data(bsecOutputs& outputs, const int64_t ns, const bme688::bme68xData& data);
    void update_bsec2(const bool force);
#endif
 
    inline virtual bool in_periodic() const override
    {
        return _periodic || (_bsec2_subscription != 0);
    }
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitBME688, bme688::Data);
 
protected:
    bme688::Mode _mode{bme688::Mode::Sleep};
 
    // bme68x
    bme688::bme68xData _raw_data[3]{};  // latest data
    uint8_t _num_of_data{};
    bme688::bme68xDev _dev{};
    bme688::bme68xConf _tphConf{};
    bme688::bme68xHeatrConf _heaterConf{};
 
    // BSEC2
    uint32_t _bsec2_subscription{};  // Enabled virtual sensor bit
 
#if defined(UNIT_BME688_USING_BSEC2)
    bsec_version_t _bsec2_version{};
    std::unique_ptr<uint8_t> _bsec2_work{};
    bsec_bme_settings_t _bsec2_settings{};
 
    bme688::Mode _bsec2_mode{};
    bme688::bsec2::SampleRate _bsec2_sr{};
 
    bsecOutputs _outputs{};
    float _temperatureOffset{};
#endif
 
    std::unique_ptr<m5::container::CircularBuffer<bme688::Data>> _data{};
 
    bool _waiting{};
    types::elapsed_time_t _can_measure_time{};
 
    config_t _cfg{};
    float _altitude_reference_pa{101325.0f};
};
 
namespace bme688 {
namespace command {
constexpr uint8_t CHIP_ID{0xD0};
constexpr uint8_t RESET{0xE0};
constexpr uint8_t VARIANT_ID{0xF0};
 
constexpr uint8_t IDAC_HEATER_0{0x50};  // ...9
constexpr uint8_t RES_HEAT_0{0x5A};     // ...9
constexpr uint8_t GAS_WAIT_0{0x64};     // ...9
constexpr uint8_t GAS_WAIT_SHARED{0x6E};
 
constexpr uint8_t CTRL_GAS_0{0x70};
constexpr uint8_t CTRL_GAS_1{0x71};
constexpr uint8_t CTRL_HUMIDITY{0x72};
constexpr uint8_t CTRL_MEASUREMENT{0x74};
constexpr uint8_t CONFIG{0x75};
 
constexpr uint8_t MEASUREMENT_STATUS_0{0x1D};
constexpr uint8_t MEASUREMENT_STATUS_1{0x2E};
constexpr uint8_t MEASUREMENT_STATUS_2{0x3F};
 
constexpr uint8_t MEASUREMENT_GROUP_INDEX_0{0x1F};
constexpr uint8_t MEASUREMENT_GROUP_INDEX_1{0x30};
constexpr uint8_t MEASUREMENT_GROUP_INDEX_2{0x41};
 
constexpr uint8_t UNIQUE_ID{0x83};
 
// calibration
constexpr uint8_t CALIBRATION_GROUP_0{0x8A};
constexpr uint8_t CALIBRATION_GROUP_1{0xE1};
constexpr uint8_t CALIBRATION_GROUP_2{0x00};
constexpr uint8_t CALIBRATION_TEMPERATURE_1_LOW{0xE9};
constexpr uint8_t CALIBRATION_TEMPERATURE_2_LOW{0x8A};
constexpr uint8_t CALIBRATION_TEMPERATURE_3{0x8C};
constexpr uint8_t CALIBRATION_PRESSURE_1_LOW{0x8E};
constexpr uint8_t CALIBRATION_PRESSURE_2_LOW{0x90};
constexpr uint8_t CALIBRATION_PRESSURE_3{0x92};
constexpr uint8_t CALIBRATION_PRESSURE_4_LOW{0x94};
constexpr uint8_t CALIBRATION_PRESSURE_5_LOW{0x96};
constexpr uint8_t CALIBRATION_PRESSURE_6{0x99};
constexpr uint8_t CALIBRATION_PRESSURE_7{0x98};
constexpr uint8_t CALIBRATION_PRESSURE_8_LOW{0x9C};
constexpr uint8_t CALIBRATION_PRESSURE_9_LOW{0x9E};
constexpr uint8_t CALIBRATION_PRESSURE_10{0xA0};
constexpr uint8_t CALIBRATION_HUMIDITY_12{0xE2};
constexpr uint8_t CALIBRATION_HUMIDITY_1_HIGH{0xE3};
constexpr uint8_t CALIBRATION_HUMIDITY_2_HIGH{0xE1};
constexpr uint8_t CALIBRATION_HUMIDITY_3{0xE4};
constexpr uint8_t CALIBRATION_HUMIDITY_4{0xE5};
constexpr uint8_t CALIBRATION_HUMIDITY_5{0xE6};
constexpr uint8_t CALIBRATION_HUMIDITY_6{0xE7};
constexpr uint8_t CALIBRATION_HUMIDITY_7{0xE8};
constexpr uint8_t CALIBRATION_GAS_1{0xED};
constexpr uint8_t CALIBRATION_GAS_2_LOW{0xEB};
constexpr uint8_t CALIBRATION_GAS_3{0xEE};
constexpr uint8_t CALIBRATION_RES_HEAT_RANGE{0x02};  // [5:4]
constexpr uint8_t CALIBRATION_RES_HEAT_VAL{0x00};
 
}  // namespace command
}  // namespace bme688
 
}  // namespace unit
}  // namespace m5
#endif