unit_MAX30102.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_HEART_UNIT_MAX30102_HPP
#define M5_UNIT_HEART_UNIT_MAX30102_HPP
 
#include <M5UnitComponent.hpp>
#include <m5_utility/stl/extension.hpp>
#include <m5_utility/container/circular_buffer.hpp>
#include <limits>  // NaN
 
namespace m5 {
namespace unit {
namespace max30102 {
 
enum class Mode : uint8_t {
    None,             
    HROnly = 0x02,    
    SpO2,             
    MultiLED = 0x07,  
};
 
enum class ADC : uint8_t {
    Range2048nA,   
    Range4096nA,   
    Range8192nA,   
    Range16384nA,  
};
 
enum class Sampling : uint8_t {
    Rate50,    
    Rate100,   
    Rate200,   
    Rate400,   
    Rate800,   
    Rate1000,  
    Rate1600,  
    Rate3200,  
};
 
enum class LEDPulse : uint8_t {
    Width69,   
    Width118,  
    Width215,  
    Width411,  
};
 
enum class Slot : uint8_t {
    None,  
    Red,   
    IR,    
};
 
enum class FIFOSampling : uint8_t {
    Average1,   
    Average2,   
    Average4,   
    Average8,   
    Average16,  
    Average32,  
    //    Average32, duplicated
    //    Average32, duplicated
};
 
constexpr uint8_t MAX_FIFO_DEPTH{32};  
 
struct Data {
    std::array<uint8_t, 6> raw{};  
    uint32_t mask{0x3FFFF};        
    inline uint32_t ir() const
    {
        return mask & ((static_cast<uint32_t>(raw[3]) << 16) | (static_cast<uint32_t>(raw[4]) << 8) |
                       static_cast<uint32_t>(raw[5]));
    }
    inline uint32_t red() const
    {
        return mask & ((static_cast<uint32_t>(raw[0]) << 16) | (static_cast<uint32_t>(raw[1]) << 8) |
                       static_cast<uint32_t>(raw[2]));
    }
};
 
struct TemperatureData {
    std::array<uint8_t, 2> raw{0x80, 0x00};  // [0]:integer [1]:fraction  sentinel:0x80(-128) is outside operating range
    inline float temperature() const
    {
        return celsius();
    }
    inline float celsius() const
    {
        return (raw[0] != 0x80) ? static_cast<int8_t>(raw[0]) + raw[1] * 0.0625f
                                : std::numeric_limits<float>::quiet_NaN();
    }
    inline float fahrenheit() const
    {
        return celsius() * 9.0f / 5.0f + 32.f;
    }
};
 
namespace command {
// STATUS
constexpr uint8_t READ_INTERRUPT_STATUS_1{0x00};
constexpr uint8_t READ_INTERRUPT_STATUS_2{0x01};
constexpr uint8_t INTERRUPT_ENABLE_1{0x02};
constexpr uint8_t INTERRUPT_ENABLE_2{0x03};
// FIFO
constexpr uint8_t FIFO_WRITE_POINTER{0x04};
constexpr uint8_t FIFO_OVERFLOW_COUNTER{0x05};
constexpr uint8_t FIFO_READ_POINTER{0x06};
constexpr uint8_t FIFO_DATA_REGISTER{0x07};
// CONFIGURATION
constexpr uint8_t FIFO_CONFIGURATION{0x08};
constexpr uint8_t MODE_CONFIGURATION{0x09};
constexpr uint8_t SPO2_CONFIGURATION{0x0A};
constexpr uint8_t LED_CONFIGURATION_1{0x0C};
constexpr uint8_t LED_CONFIGURATION_2{0x0D};
// MultiLED
constexpr uint8_t MULTI_LED_MODE_CONTROL_12{0x11};
constexpr uint8_t MULTI_LED_MODE_CONTROL_34{0x12};
// TEMPERATURE
constexpr uint8_t TEMP_INTEGER{0x1F};
constexpr uint8_t TEMP_FRACTION{0x20};
constexpr uint8_t TEMP_CONFIGURATION{0x21};
// PART ID
constexpr uint8_t READ_REVISION_ID{0xFE};
constexpr uint8_t READ_PART_ID{0xFF};
 
}  // namespace command
 
struct SpO2Configuration;
 
}  // namespace max30102
 
class UnitMAX30102 : public Component, public PeriodicMeasurementAdapter<UnitMAX30102, max30102::Data> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitMAX30102, 0x57);
 
public:
    struct config_t {
        max30102::Mode mode{max30102::Mode::SpO2};
        bool start_periodic{true};
        max30102::ADC adc_range{max30102::ADC::Range4096nA};
        max30102::Sampling sampling_rate{max30102::Sampling::Rate400};
        max30102::LEDPulse pulse_width{max30102::LEDPulse::Width411};
        uint8_t ir_current{0x1F};
        uint8_t red_current{0x1F};
        max30102::FIFOSampling fifo_sampling_average{max30102::FIFOSampling::Average4};
    };
 
    explicit UnitMAX30102(const uint8_t addr = DEFAULT_ADDRESS)
        : Component(addr), _data{new m5::container::CircularBuffer<max30102::Data>(max30102::MAX_FIFO_DEPTH)}
    {
        auto ccfg        = component_config();
        ccfg.clock       = 400 * 1000U;
        ccfg.stored_size = max30102::MAX_FIFO_DEPTH;
        component_config(ccfg);
    }
    virtual ~UnitMAX30102()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
 
    inline config_t config()
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    inline uint32_t ir() const
    {
        return !empty() ? oldest().ir() : 0;
    }
    inline uint32_t red() const
    {
        return !empty() ? oldest().red() : 0;
    }
    inline uint8_t retrieved() const
    {
        return _retrieved;
    }
    [[deprecated("Please use retrieved()")]] inline uint8_t retrived() const
    {
        return retrieved();
    }
    inline uint8_t overflow() const
    {
        return _overflow;
    }
 
    uint32_t calculateSamplingRate();
    [[deprecated("Please use calculateSamplingRate()")]] inline uint32_t caluculateSamplingRate()
    {
        return calculateSamplingRate();
    }
 
 
    inline bool startPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitMAX30102, max30102::Data>::startPeriodicMeasurement();
    }
    inline bool startPeriodicMeasurement(const max30102::Mode mode, const max30102::ADC range,
                                         const max30102::Sampling rate, const max30102::LEDPulse width,
                                         const max30102::FIFOSampling avg, const uint8_t ir_current,
                                         const uint8_t red_current)
    {
        return PeriodicMeasurementAdapter<UnitMAX30102, max30102::Data>::startPeriodicMeasurement(
            mode, range, rate, width, avg, ir_current, red_current);
    }
    inline bool stopPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitMAX30102, max30102::Data>::stopPeriodicMeasurement();
    }
 
 
    bool readMode(max30102::Mode& mode);
    bool writeMode(const max30102::Mode mode);
    bool readShutdownControl(bool& shdn);
    bool writeShutdownControl(const bool shdn);
 
 
    bool readSpO2Configuration(max30102::ADC& range, max30102::Sampling& rate, max30102::LEDPulse& width);
    inline bool readSpO2ADCRange(max30102::ADC& range)
    {
        max30102::Sampling rate{};
        max30102::LEDPulse width{};
        return readSpO2Configuration(range, rate, width);
    }
    inline bool readSpO2SamplingRate(max30102::Sampling& rate)
    {
        max30102::ADC range{};
        max30102::LEDPulse width{};
        return readSpO2Configuration(range, rate, width);
    }
    inline bool readSpO2LEDPulseWidth(max30102::LEDPulse& width)
    {
        max30102::ADC range{};
        max30102::Sampling rate{};
        return readSpO2Configuration(range, rate, width);
    }
    bool writeSpO2Configuration(const max30102::ADC range, const max30102::Sampling rate,
                                const max30102::LEDPulse width);
    bool writeSpO2ADCRange(const max30102::ADC range);
    bool writeSpO2SamplingRate(const max30102::Sampling rate);
    bool writeSpO2LEDPulseWidth(const max30102::LEDPulse width);
 
 
    inline bool readLEDCurrent(uint8_t& raw, const uint8_t slot)
    {
        return read_led_current(slot, raw);
    }
    inline bool readLEDCurrent(float& mA, const uint8_t slot)
    {
        return read_led_current(slot, mA);
    }
    inline bool writeLEDCurrent(const uint8_t slot, const uint8_t raw)
    {
        return write_led_current(slot, raw);
    }
    template <typename T, typename std::enable_if<std::is_floating_point<T>::value, std::nullptr_t>::type = nullptr>
    inline bool writeLEDCurrent(const uint8_t slot, const T mA)
    {
        return write_led_current(slot, static_cast<float>(mA));
    }
 
 
    bool readMultiLEDModeControl(max30102::Slot& slot1, max30102::Slot& slot2);
    bool writeMultiLEDModeControl(const max30102::Slot slot1, const max30102::Slot slot2);
 
 
    bool measureTemperatureSingleshot(max30102::TemperatureData& td);
 
 
    bool readFIFOConfiguration(max30102::FIFOSampling& avg, bool& rollover, uint8_t& almostFull);
    bool writeFIFOConfiguration(const max30102::FIFOSampling avg, const bool rollover, const uint8_t almostFull);
 
    inline bool readFIFOReadPointer(uint8_t& rptr)
    {
        rptr = 0xFF;
        return read_register8(max30102::command::FIFO_READ_POINTER, rptr);
    }
    inline bool writeFIFOReadPointer(const uint8_t rptr)
    {
        return writeRegister8(max30102::command::FIFO_READ_POINTER, rptr);
    }
    inline bool readFIFOWritePointer(uint8_t& wptr)
    {
        wptr = 0xFF;
        return read_register8(max30102::command::FIFO_WRITE_POINTER, wptr);
    }
    inline bool writeFIFOWritePointer(const uint8_t wptr)
    {
        return writeRegister8(max30102::command::FIFO_WRITE_POINTER, wptr);
    }
    inline bool readFIFOOverflowCounter(uint8_t& cnt)
    {
        cnt = 0xFF;
        return read_register8(max30102::command::FIFO_OVERFLOW_COUNTER, cnt);
    }
    inline bool writeFIFOOverflowCounter(const uint8_t cnt)
    {
        return writeRegister8(max30102::command::FIFO_OVERFLOW_COUNTER, cnt);
    }
    inline bool resetFIFO()
    {
        return reset_FIFO();
    }
 
    bool reset();
 
    bool readRevisionID(uint8_t& rev);
 
protected:
    bool read_register(const uint8_t reg, uint8_t* buf, const size_t len);
    bool read_register8(const uint8_t reg, uint8_t& v);
 
    bool start_periodic_measurement();
    bool start_periodic_measurement(const max30102::Mode mode, const max30102::ADC range, const max30102::Sampling rate,
                                    const max30102::LEDPulse width, const max30102::FIFOSampling avg,
                                    const uint8_t ir_current, const uint8_t red_current);
    bool stop_periodic_measurement();
 
    bool write_spo2_configuration(const max30102::SpO2Configuration& sc);
 
    bool read_led_current(const uint8_t idx, uint8_t& raw);
    bool read_led_current(const uint8_t idx, float& mA);
    bool write_led_current(const uint8_t idx, const uint8_t raw);
    bool write_led_current(const uint8_t idx, const float mA);
 
    bool write_fifo_sampling_average(const max30102::FIFOSampling avg);
 
    bool read_FIFO();
    bool reset_FIFO(const bool circling_read_ptr = true);
 
    bool read_measurement_temperature(max30102::TemperatureData& td);
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitMAX30102, max30102::Data);
 
protected:
    std::unique_ptr<m5::container::CircularBuffer<max30102::Data>> _data{};
    max30102::Mode _mode{};
    uint8_t _retrieved{}, _overflow{};
    uint32_t _mask{};  // Valid bits based on ADC range
    max30102::Slot _slot[2]{};
    config_t _cfg{};
};
 
}  // namespace unit
}  // namespace m5
#endif