unit_INA226.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_METER_UNIT_INA226_HPP
#define M5_UNIT_METER_UNIT_INA226_HPP
 
#include <M5UnitComponent.hpp>
#include <limits>  // NaN
 
namespace m5 {
namespace unit {
 
namespace ina226 {
 
enum class Sampling : uint8_t {
    Rate1,     
    Rate4,     
    Rate16,    
    Rate64,    
    Rate128,   
    Rate256,   
    Rate512,   
    Rate1024,  
};
 
enum class ConversionTime : uint8_t {
    US_140,   
    US_204,   
    US_332,   
    US_588,   
    US_1100,  
    US_2116,  
    US_4156,  
    US_8244,  
};
 
enum class Mode : uint8_t {
    PowerDown,           
    ShuntVoltageSingle,  
    BusVoltageSingle,    
    ShuntAndBusSingle,   
    // 0x04 Same as PowerDown
    ShuntVoltage = 0x05,  
    BusVoltage,           
    ShuntAndBus,          
};
 
enum class Alert : int8_t {
    Unknown = -1,
    None,             
    ShuntOver,        
    ShuntUnder,       
    BusOver,          
    BusUnder,         
    PowerOver,        
    ConversionReady,  
};
 
struct Data {
    std::array<uint16_t, 4> raw{};  
    float currentLSB{};             
    uint8_t measureBits{};          
 
    inline float shuntVoltage() const
    {
        return (measureBits & 0x01) ? static_cast<int16_t>(raw[0]) * 0.0025f : std::numeric_limits<float>::quiet_NaN();
    }
    inline float voltage() const
    {
        return (measureBits & 0x02) ? raw[1] * 1.25f : std::numeric_limits<float>::quiet_NaN();
    }
    inline float power() const
    {
        return (measureBits & 0x04) ? raw[2] * currentLSB * 25.f * 1000.f : std::numeric_limits<float>::quiet_NaN();
    }
    inline float current() const
    {
        return (measureBits & 0x08) ? static_cast<int16_t>(raw[3]) * currentLSB * 1000.f
                                    : std::numeric_limits<float>::quiet_NaN();
    }
};
 
}  // namespace ina226
 
class UnitINA226 : public Component, public PeriodicMeasurementAdapter<UnitINA226, ina226::Data> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitINA226, 0x00);
 
public:
    struct config_t {
        bool start_periodic{true};
        bool current{true};
        bool voltage{true};
        bool power{true};
        ina226::Sampling sampling_rate{ina226::Sampling::Rate16};
        ina226::ConversionTime shunt_conversion_time{ina226::ConversionTime::US_1100};
        ina226::ConversionTime bus_conversion_time{ina226::ConversionTime::US_1100};
    };
 
protected:
    UnitINA226(const float shuntRes, const float maxCurA, const float curLSB, const uint8_t addr = DEFAULT_ADDRESS);
 
public:
    virtual ~UnitINA226()
    {
    }
 
    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 float shuntResistor() const
    {
        return _shuntRes;
    }
    inline float maximumCurrent() const
    {
        return _maxCurrentA;
    }
    inline float currentLSB() const
    {
        return _currentLSB;
    }
 
    inline float shuntVoltage() const
    {
        return !empty() ? oldest().shuntVoltage() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float voltage() const
    {
        return !empty() ? oldest().voltage() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float power() const
    {
        return !empty() ? oldest().power() : std::numeric_limits<float>::quiet_NaN();
    }
    inline float current() const
    {
        return !empty() ? oldest().current() : std::numeric_limits<float>::quiet_NaN();
    }
 
 
    inline bool startPeriodicMeasurement(const bool current = true, const bool voltage = true, const bool power = true)
    {
        return PeriodicMeasurementAdapter<UnitINA226, ina226::Data>::startPeriodicMeasurement(current, voltage, power);
    }
    inline bool startPeriodicMeasurement(const ina226::Sampling rate, const ina226::ConversionTime sct,
                                         const ina226::ConversionTime bct, const bool current = true,
                                         const bool voltage = true, const bool power = true)
    {
        return PeriodicMeasurementAdapter<UnitINA226, ina226::Data>::startPeriodicMeasurement(rate, sct, bct, current,
                                                                                              voltage, power);
    }
    inline bool stopPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitINA226, ina226::Data>::stopPeriodicMeasurement();
    }
 
 
    bool measureSingleshot(ina226::Data& data, const bool current = true, const bool voltage = true,
                           const bool power = true);
    bool measureSingleshot(ina226::Data& data, const ina226::Sampling rate, const ina226::ConversionTime sct,
                           const ina226::ConversionTime bct, const bool current = true, const bool voltage = true,
                           const bool power = true);
 
 
 
    bool readMode(ina226::Mode& mode);
    bool readSamplingRate(ina226::Sampling& rate);
    bool writeSamplingRate(const ina226::Sampling rate);
    bool readBusVoltageConversionTime(ina226::ConversionTime& ct);
    bool writeBusVoltageConversionTime(const ina226::ConversionTime ct);
    bool readShuntVoltageConversionTime(ina226::ConversionTime& ct);
    bool writeShuntVoltageConversionTime(const ina226::ConversionTime ct);
    bool readCalibration(uint16_t& cal);
    bool writeCalibration(const uint16_t cal);
    bool readAlert(ina226::Alert& type);
    bool writeAlert(const ina226::Alert type, const uint16_t limit, const bool latch = true);
    bool readAlertLimit(uint16_t& limit);
    bool writeAlertLimit(const uint16_t limit);
 
    // ============================================================
    // M5Unified M5.Power.Ina226 compatible API
#if defined(__M5UNIFIED_HPP__)
 
 
    inline float getBusVoltage()
    {
        return voltage() / 1000.0f;
    }
    inline float getShuntVoltage()
    {
        return shuntVoltage() / 1000.0f;
    }
    inline float getShuntCurrent()
    {
        return current() / 1000.0f;
    }
    inline float getPower()
    {
        return power() / 1000.0f;
    }
 
#endif
 
    bool readAlertOccurred(bool& alert);
    bool powerDown();
    bool softReset(const bool all = false);
 
protected:
    bool start_periodic_measurement(const bool current, const bool voltage, const bool power);
    bool start_periodic_measurement(const ina226::Sampling rate, const ina226::ConversionTime sct,
                                    const ina226::ConversionTime bct, const bool current, const bool voltage,
                                    const bool power);
    bool stop_periodic_measurement();
 
    bool write_mode(const ina226::Mode mode);
    bool read_configuration(uint16_t& v);
    bool write_configuration(const uint16_t v);
    bool read_mask(uint16_t& m);
    bool write_mask(const uint16_t m);
 
    bool is_data_ready();
    bool read_measurement(ina226::Data& d);
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitINA226, ina226::Data);
 
private:
    std::unique_ptr<m5::container::CircularBuffer<ina226::Data>> _data{};
    config_t _cfg{};
    float _shuntRes{}, _maxCurrentA{}, _currentLSB{};
    uint8_t _measureBits{};  // LSB 0:Shunt 1:Bus 2:Power 3:Current MSB
};
 
class UnitINA226_10A : public UnitINA226 {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitINA226_10A, 0x41);
 
public:
    explicit UnitINA226_10A(const float curLSB = 0.0f)
        : UnitINA226(0.005f /* 5mR */, 10.0f /* 10A */, curLSB, DEFAULT_ADDRESS)
    {
    }
    virtual ~UnitINA226_10A()
    {
    }
};
 
class UnitINA226_1A : public UnitINA226 {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitINA226_1A, 0x41);
 
public:
    explicit UnitINA226_1A(const float curLSB = 0.0f)
        : UnitINA226(0.080f /* 80mR */, 1.0f /* 1A */, curLSB, DEFAULT_ADDRESS)
    {
    }
    virtual ~UnitINA226_1A()
    {
    }
};
 
namespace ina226 {
namespace command {
constexpr uint8_t CONFIGURATION_REG{0x00};
 
constexpr uint8_t SHUNT_VOLTAGE_REG{0x01};
constexpr uint8_t BUS_VOLTAGE_REG{0x02};
constexpr uint8_t POWER_REG{0x03};
constexpr uint8_t CURRENT_REG{0x04};
 
constexpr uint8_t CALIBRATION_REG{0x05};
constexpr uint8_t MASK_REG{0x06};
constexpr uint8_t ALERT_LIMIT_REG{0x07};
 
constexpr uint8_t MANUFACTURER_ID_REG{0xFE};
constexpr uint8_t DIE_ID_REG{0xff};
}  // namespace command
}  // namespace ina226
 
}  // namespace unit
}  // namespace m5
#endif