portapack-mayhem/firmware/common/max17055.hpp

/*
 * Copyright (C) 2024 jLynx.
 *
 * This file is part of PortaPack.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street,
 * Boston, MA 02110-1301, USA.
 */

#ifndef __MAX17055_H__
#define __MAX17055_H__

#include <cstdint>
#include <array>
#include <string>

#include "battery.hpp"
#include "i2c_pp.hpp"

#define MAX17055_POR 0
#define MAX17055_IMin 1
#define MAX17055_IMax 2
#define MAX17055_VMin 3
#define MAX17055_VMax 4
#define MAX17055_TMin 5
#define MAX17055_TMax 6
#define MAX17055_SOC_Min 7
#define MAX17055_SOC_Max 8
#define MAX17055_SOC_Change 9
#define MAX17055_Bat_Status 10
#define MAX17055_Bat_Insert 11
#define MAX17055_Bat_Remove 12

// Design Parameters
//----------------------------------------------

// Define Battery Capacity
#ifndef __MAX17055_Design_Capacity__
#define __MAX17055_Design_Capacity__ BATTERY_DESIGN_CAP  // Battery Capacity
#endif

// Define Gauge Resistor
#ifndef __MAX17055_Resistor__
#define __MAX17055_Resistor__ 0.01  // Shunt Resistor
#endif

// Define Minimum Voltage
#ifndef __MAX17055_Min_Voltage__
#define __MAX17055_Min_Voltage__ BATTERY_MIN_VOLTAGE / 1000.0  // Minimum Voltage
#endif

// Define Maximum Voltage
#ifndef __MAX17055_Max_Voltage__
#define __MAX17055_Max_Voltage__ BATTERY_MAX_VOLTAGE / 1000.0  // Maximum Voltage
#endif

// Define Empty Voltage
#ifndef __MAX17055_Empty_Voltage__
#define __MAX17055_Empty_Voltage__ BATTERY_MIN_VOLTAGE / 1000.0  // Empty Voltage
#endif

// Define Recovery Voltage
#ifndef __MAX17055_Recovery_Voltage__
#define __MAX17055_Recovery_Voltage__ 3.1  // Recovery Voltage
#endif

// Define Maximum Current
#ifndef __MAX17055_Max_Current__
#define __MAX17055_Max_Current__ 3.0  // Maximum Current
#endif

// Define Termination Current
#ifndef __MAX17055_Termination_Current__
#define __MAX17055_Termination_Current__ 200  // Termination Current
#endif

// Define Minimum Temperature
#ifndef __MAX17055_Min_Temperature__
#define __MAX17055_Min_Temperature__ -20  // Minimum Temperature
#endif

// Define Maximum Temperature
#ifndef __MAX17055_Max_Temperature__
#define __MAX17055_Max_Temperature__ 60  // Maximum Temperature
#endif

// Define Battery Model
#ifndef __MAX17055_Battery_Model__
#define __MAX17055_Battery_Model__ 0  // Battery Model
#endif

// Define Limits
//----------------------------------------------

// Define Minimum SOC
#ifndef __MAX17055_Min_SOC__
#define __MAX17055_Min_SOC__ 0  // Minimum SOC
#endif

// Define Maximum SOC
#ifndef __MAX17055_Max_SOC__
#define __MAX17055_Max_SOC__ 100  // Maximum SOC
#endif

// Config1 (0x1D) Configuration
//----------------------------------------------

// Enable alert on battery removal when the IC is mounted host side.
// When Ber = 1, a battery-removal condition, as detected by the AIN pin voltage, triggers an alert.
#ifndef MAX17055_Ber
#define MAX17055_Ber 0
#endif

// Enable alert on battery insertion when the IC is mounted host side.
// When Bei = 1, a battery-insertion condition, as detected by the AIN pin voltage, triggers an alert.
#ifndef MAX17055_Bei
#define MAX17055_Bei 0
#endif

// When Aen = 1, violation of any of the alert threshold register values
// by temperature, voltage, or SOC triggers an alert. This bit
// affects the ALRT pin operation only. The Smx, Smn, Tmx,
// Tmn, Vmx, Vmn, Imx, and Imn bits of the Status register
// (00h) are not disabled.
#ifndef MAX17055_Aen
#define MAX17055_Aen 1
#endif

// This allows the host to control the bias of the thermistor switch or
// enable fast detection of battery removal. Set FTHRM = 1
// to always enable the thermistor bias switch. With a standard 10kΩ thermistor,
// this adds an  additional ~200μA to the current drain of the circuit.
#ifndef MAX17055_FTHRM
#define MAX17055_FTHRM 0
#endif

// Set to logic 1 to enable the automatic THRM output bias and AIN measurement.
#ifndef MAX17055_ETHRM
#define MAX17055_ETHRM 0
#endif

// Set to logic 1 to force the device to enter shutdown mode if both
// SDA and SCL are held low for more than timeout of the
// ShdnTimer register.
#ifndef MAX17055_COMMSH
#define MAX17055_COMMSH 0
#endif

// Write this bit to logic 1 to force a shutdown of the device after timeout of the ShdnTimer register (default 45s delay).
#ifndef MAX17055_SHDN
#define MAX17055_SHDN 0
#endif

// When set to 1, the fuel gauge requires external temperature measurements to be
// written from the host. When set to 0, the IC's own measurements as used as selected by Config.TSEL.
#ifndef MAX17055_Tex
#define MAX17055_Tex 0
#endif

// Set to 1 and set ETHRM or FTHRM to 1 to enable temperature measurements selected by Config.TSel.
#ifndef MAX17055_Ten
#define MAX17055_Ten 1
#endif

// Set to 1 to enable device shutdown when the IC is mounted host side and the battery is removed.
#ifndef MAX17055_AINSH
#define MAX17055_AINSH 0
#endif

// When IS = 1, current alerts can only be cleared through software. When IS = 0,
// current alerts are cleared automatically when the thresholdis no longer exceeded.
#ifndef MAX17055_IS
#define MAX17055_IS 0
#endif

// When VS = 1, voltage alerts can only be cleared through software. When VS = 0,
// voltage alerts are cleared automatically when the threshold is no longer exceeded.
#ifndef MAX17055_VS
#define MAX17055_VS 0
#endif

// When TS = 1, temperature alerts can only be cleared through software. WhenTS = 0,
// temperature alerts are cleared automatically whenthe threshold is no longer exceeded.
#ifndef MAX17055_TS
#define MAX17055_TS 0
#endif

// When SS = 1, SOC alerts can only be cleared through software. When SS = 0,
// SOC alerts are cleared automatically when the threshold is no longer exceeded.
#ifndef MAX17055_SS
#define MAX17055_SS 0
#endif

// 0 to use internal die temperature. 1 to use temperature information from thermistor.
// ETHRM bit should be set to 1 when TSel is 1.
#ifndef MAX17055_TSel
#define MAX17055_TSel 0
#endif

// Config1 (0xBB) Configuration
//----------------------------------------------

// Set to 1 to enable constant-power mode. If it is set to 0,
// AtRate/AvgCurrent is used for (At)TTE/(At) QResidual/(At)AvSOC/(At)AvCap.
#ifndef MAX17055_CPMode
#define MAX17055_CPMode 0
#endif

// Host sets this bit to 1 in order to initiate firmware to finish processing a newly loaded model.
// Firmware clears this bit to zero to indicate that model loading is finished.
#ifndef MAX17055_LDMDL
#define MAX17055_LDMDL 0
#endif

// Set this bit to 1 to enable temperature based alerts.
// Write this bit to 0 to disable temperature alerts. This bit is set to 1 at power-up.
#ifndef MAX17055_TAIrtEN
#define MAX17055_TAIrtEN 1
#endif

// Set this bit to 1 to enable alert output with the Status.dSOCi bit function.
// Write this bit to 0 to disable alert output with the Status. dSOCi bit. This bit is set to 0 at power-up.
#ifndef MAX17055_dSOCen
#define MAX17055_dSOCen 0
#endif

// When this bit is set to 0, Dynamic Power calculations are disabled and registers
// MaxPeakPower/SusPeakPower/MPPCurrent/ SPPCurrent can be used as general purpose memory.
#ifndef MAX17055_DPEn
#define MAX17055_DPEn 0
#endif

// When this bit is set to 0, AtRate calculations are disabled and registers
// AtQResidual/AtTTE/AtAvSOC/AtAvCap can be used as general purpose memory.
#ifndef MAX17055_AtRateEn
#define MAX17055_AtRateEn 0
#endif

namespace battery {
namespace max17055 {

using address_t = uint8_t;

struct RegisterEntry {
    const char* name;
    uint8_t address;
    const char* type;
    float scalar;
    bool is_signed;
    const char* unit;
    bool abbr_units;
    int resolution;
    bool is_user;
    bool is_save_restore;
    bool is_nv;
    uint16_t por_data;
    bool is_read_only;
};

class MAX17055 {
   public:
    constexpr MAX17055(I2C& bus, const I2C::address_t bus_address)
        : bus(bus), bus_address(bus_address), detected_(false) {}

    static const RegisterEntry entries[];
    static constexpr size_t entries_count = 144;

    uint16_t read_register(const uint8_t reg);
    bool write_register(const uint8_t reg, const uint16_t value);

    void init();
    bool detect();
    bool isDetected() const { return detected_; }

    void getBatteryInfo(uint8_t& valid_mask, uint8_t& batteryPercentage, uint16_t& voltage, int32_t& current);
    bool reset_learned();

    float getValue(const char* entityName);
    uint16_t averageMVoltage(void);
    int32_t instantCurrent(void);
    uint16_t stateOfCharge(void);

   private:
    I2C& bus;
    const I2C::address_t bus_address;
    bool detected_ = false;

    const RegisterEntry* findEntry(const char* name) const;

    bool needsInitialization();
    void partialInit();

    bool statusControl(const uint8_t _Status);
    bool statusClear();

    bool full_reset_and_init();
    bool soft_reset();
    bool clear_por();
    bool initialize_custom_parameters();
    bool load_custom_parameters();

    bool setEmptyVoltage(uint16_t _Empty_Voltage);
    bool setRecoveryVoltage(uint16_t _Recovery_Voltage);
    bool setMinVoltage(uint16_t _Minimum_Voltage);
    bool setMaxVoltage(uint16_t _Maximum_Voltage);
    bool setMaxCurrent(uint16_t _Maximum_Current);
    bool setChargeTerminationCurrent(uint16_t _Charge_Termination_Current);
    bool setDesignCapacity(const uint16_t _Capacity);
    bool setFullCapRep(const uint16_t _Capacity);
    bool setFullCapNom(const uint16_t _Capacity);
    bool setRepCap(const uint16_t _Capacity);
    bool setMinSOC(uint8_t _Minimum_SOC);
    bool setMaxSOC(uint8_t _Maximum_SOC);
    bool setMinTemperature(uint8_t _Minimum_Temperature);
    bool setMaxTemperature(uint8_t _Maximum_Temperature);
    bool setModelCfg(const uint8_t _Model_ID);
    bool setHibCFG(const uint16_t _Config);
    void config(void);
};

} /* namespace max17055 */
}  // namespace battery
#endif /* __MAX17055_H__ */