powermon.h

/* Copyright (C) 2020 - 2024, Thornwave Labs Inc
 * Written by Razvan Turiac <razvan.turiac@thornwave.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated 
 * documentation files (the “Software”), to deal in the Software without restriction, including without limitation 
 * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, 
 * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 * Attribution shall be given to Thornwave Labs Inc. and shall be made visible to the final user. 
 * 
 * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 
 * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
 
#ifndef _POWERMON_H
#define _POWERMON_H
 
 
#include <stdint.h>
#include <string.h>
 
#include <string>
#include <vector>
#include <functional>
 
 
#include <powermon_config.h>
#include <powermon_schedule.h>
#include <powermon_log.h>
 
 
#define MAX_WIFI_SSID_SIZE          32
#define MAX_WIFI_PASSWORD_SIZE      64
 
#define CHANNEL_ID_SIZE             16
#define ENCRYPTION_KEY_SIZE         32
 
#define MAX_BLE_NAME_LENGTH         8
#define MAX_NAME_LENGTH             32
 
#define MAX_TIMER_NAME_LENGTH       16
#define MAX_TIMER_COUNT             16
 
#define FG_SOC_DISABLED             0xFF
#define FG_SOC_UNKNOWN              0xFE
 
#define FG_RUNTIME_DISABLED         0xFFFF
#define FG_RUNTIME_UNKNOWN          0xFFFE
#define FG_RUNTIME_MAX              0xFFF0
 

class Powermon
{
public:
    enum HardwareRevision: uint8_t
    {
        FAMILY_MASK = 0xF0,          
    
        POWERMON_E = 0x10,            
        POWERMON = 0x20,            
        POWERMON_5S = 0x30,          
        POWERMON_W = 0x40         
    };
 

    enum State: uint8_t
    {
        Disconnected = 0,           
        Connecting,                   
        Connected                  
    };
 
    
    enum DisconnectReason: uint8_t
    {
        CLOSED = 0,
        NO_ROUTE,
        FAILED,
        UNEXPECTED_ERROR,
        UNEXPECTED_RESPONSE,
        WRITE_ERROR,
        READ_ERROR,
    };
 

    enum ResponseCode: uint16_t
    {
        RSP_SUCCESS         = 0x0000,
        RSP_SUCCESS_MORE    = 0x0100,
        
        RSP_INVALID_REQ     = 0x0001,
        RSP_INVALID_PARAM   = 0x0002,
        RSP_ERROR           = 0x0003,
        RSP_LOCKED_USER     = 0x0004,
        RSP_LOCKED_MASTER   = 0x0005,
        RSP_CANNOT_UNLOCK   = 0x0006,
        RSP_NOT_FOUND       = 0x0007,
        
        RSP_TIMEOUT         = 0x0008,
        RSP_INVALID         = 0x0009,
        RSP_CANCELLED       = 0x000A,
    };
    
    
    enum PowerStatus: uint8_t
    {
        PS_OFF = 0,               
        PS_ON = 1,             
        PS_LVD = 2,               
        PS_OCD = 3,               
        PS_HVD = 4,               
        PS_FGD = 5,               
        PS_NCH = 6,               
        PS_LTD = 7,               
        PS_HTD = 8,               
    };
 

    struct AuthKey
    {
        uint8_t data[32];
    };
 

    struct WifiAccessKey
    {
        uint8_t channel_id[CHANNEL_ID_SIZE];
        uint8_t encryption_key[ENCRYPTION_KEY_SIZE];
    };
 

    struct WifiNetwork
    {
        enum SecurityMode: uint16_t
        {
            OPEN                         = 0x0,    
            WEP                          = 0x1,    
            WPA2_WPA1_PSK                = 0x2,    
            WPA2_PSK                     = 0x4,    
            WPA3_SAE                     = 0x6     
        };
 
        uint8_t ssid_length;
        uint8_t ssid[MAX_WIFI_SSID_SIZE];
 
        uint8_t pass_length;
        uint8_t pass[MAX_WIFI_PASSWORD_SIZE];
 
        uint16_t flags;
 
        bool isPasswordProtected(void) const;
        bool isMetered(void) const;
        bool isFailed(void) const;
 
        void setMetered(bool enabled);
    };
 
    
    struct WifiScanResult
    {
        uint8_t ssid_length;
        uint8_t ssid[MAX_WIFI_SSID_SIZE];
        uint8_t mac[6];
        uint8_t channel;
 
        struct
        {
            uint8_t wep : 1;                                        
            uint8_t wpa : 1;                                        
            uint8_t wpa2 : 1;                                       
            uint8_t wpa3 : 1;                                       
            uint8_t pmf : 1;                                        
            uint8_t unused : 1;                                     
            uint8_t psk : 1;                                        
            uint8_t eap : 1;                                        
        }security;
 
        int8_t rssi;
 
        bool operator==(const WifiScanResult &rhs) const;
    };
 

    struct DeviceInfo
    {
        std::string name;
 
        uint16_t firmware_version_bcd;
        uint8_t hardware_revision_bcd;
 
        uint64_t address;
        uint64_t serial;
 
        uint8_t ssid_length;
        uint8_t ssid[MAX_WIFI_SSID_SIZE];
        uint8_t flags;
        int8_t timezone;
        
        bool isUserPasswordSet(void) const;
        bool isMasterPasswordSet(void) const;
        bool isUserLocked(void) const;
        bool isMasterLocked(void) const;
        
        bool isWifiConnecting(void) const;
        bool isWifiConnected(void) const;
        bool isWifiFailed(void) const;
    };
 

    struct DeviceIdentifier
    {
        std::string name;                   
        uint64_t serial;                  
        uint8_t hardware_revision_bcd;     
        uint64_t address;                    
 
        WifiAccessKey access_key;            
 
        DeviceIdentifier();
 
        bool operator==(const DeviceIdentifier &rhs);

        bool fromURL(const char* url);
        
        std::string toURL(void);
    };
 

    struct MonitorData
    {
        uint16_t firmware_version_bcd;          
        uint8_t hardware_revision_bcd;         
 
        uint32_t time;                          
        uint32_t flags;                            
 
        float voltage1;                         
        float voltage2;                         
        float current;                           
        float power;                           
        float temperature;                       
 
        int64_t coulomb_meter;                 
        int64_t energy_meter;                   
 
        PowerStatus power_status;                
 
        uint8_t fg_soc;                           
        uint16_t fg_runtime;                  
 
        int16_t rssi = INT16_MIN;                           

        bool isTemperatureExternal(void) const;
    };
 

    struct MonitorStatistics
    {
        uint32_t seconds_since_on;              
 
        float voltage1_min;
        float voltage1_max;
 
        float voltage2_min;
        float voltage2_max;
 
        float peak_charge_current;
        float peak_discharge_current;
 
        float temperature_min;                   
        float temperature_max;                   
    };
 

    struct FuelgaugeStatistics
    {
        uint32_t time_since_last_full_charge;   //in seconds
        float full_charge_capacity;             //current total capacity in Ah
 
        uint64_t total_discharge;               //in mAh
        uint64_t total_discharge_energy;        //in mWh
 
        uint64_t total_charge;                  //in mAh
        uint64_t total_charge_energy;           //in mWh
 
        float min_voltage;
        float max_voltage;
        float max_discharge_current;
        float max_charge_current;
 
        float deepest_discharge;                //in Ah
        float last_discharge;                   //in Ah
 
        float soc;                              //in percentage
        uint32_t RESERVED;
    };
 

    struct LogFileDescriptor
    {
        uint32_t id;              
        uint32_t size;              
    };
 

    static Powermon* createInstance(void);
    virtual ~Powermon();

    static uint16_t getVersion(void);
 

    virtual bool initBle(void) = 0;
 
    
    virtual void connectWifi(const WifiAccessKey &key) = 0;
 
    
    virtual void connectWifi(uint32_t ipaddr) = 0;
    
    
    virtual void connectBle(uint64_t ble_address) = 0;
    
    
    virtual void disconnect(void) = 0;
 
    
    virtual bool isLocalConnection(void) const = 0;
    
    
    virtual void setOnConnectCallback(const std::function<void(void)> &cb) = 0;
 

    virtual void setOnDisconnectCallback(const std::function<void(DisconnectReason)> &cb) = 0;
 
    
    virtual void setOnMonitorDataCallback(const std::function<void(const MonitorData&)> &cb) = 0;
 

    virtual void setOnWifiScanReportCallback(const std::function<void(const WifiScanResult*)> &cb) = 0;
 

    virtual const DeviceInfo& getLastDeviceInfo(void) const = 0;
 

    virtual void requestGetInfo(const std::function<void(ResponseCode, const DeviceInfo&)> &cb) = 0;
 

    virtual void requestGetMonitorData(const std::function<void(ResponseCode, const MonitorData&)> &cb) = 0;
 

    virtual void requestGetStatistics(const std::function<void(ResponseCode, const MonitorStatistics&)> &cb) = 0;
 

    virtual void requestGetFgStatistics(const std::function<void(ResponseCode, const FuelgaugeStatistics&)> &cb) = 0;
    

    virtual void requestUnlock(const AuthKey &key, std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestSetUserPasswordLock(const AuthKey &key, std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestSetMasterPasswordLock(const AuthKey &key, std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestClearUserPasswordLock(std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestClearMasterPasswordLock(std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestGetAuthKey(std::function<void(ResponseCode, const AuthKey&)> cb) = 0;
    

    virtual void requestResetAuthKey(std::function<void(ResponseCode)> cb) = 0;
 

    virtual void requestResetEnergyMeter(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestResetCoulombMeter(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestResetStatistics(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestSetPowerState(bool state, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestGetConfig(const std::function<void(ResponseCode, const PowermonConfig&)> &cb) = 0;
 

    virtual void requestSetConfig(const PowermonConfig &config, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestResetConfig(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestRename(const char* name, const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestSetTime(uint32_t time, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestFgSynchronize(const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestStartWifiScan(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestWifiConfigure(const WifiNetwork &network, const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestGetWifiNetworks(const std::function<void(ResponseCode, const std::vector<WifiNetwork>&)> &cb) = 0;

    virtual void requestAddWifiNetwork(const WifiNetwork& network, const std::function<void(ResponseCode)> &cb) = 0;

    virtual void requestRemoveWifiNetwork(uint8_t index, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestGetAccessKeys(const std::function<void(ResponseCode, const WifiAccessKey&)> &cb) = 0;
 

    virtual void requestResetAccessKeys(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestZeroCurrentOffset(const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestCalibrateCurrent(float value, const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestGetSchedules(const std::function<void(ResponseCode, const std::vector<PowermonSchedule>&)> &cb) = 0;
 

    virtual void requestAddSchedules(const std::vector<PowermonSchedule> &schedules, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestUpdateSchedule(uint64_t old_schedule_descriptor, const PowermonSchedule &new_schedule, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestDeleteSchedule(uint64_t schedule_descriptor, const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestClearSchedules(const std::function<void(ResponseCode)> &cb) = 0;
    

    virtual void requestCommitSchedules(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestGetLogFileList(const std::function<void(ResponseCode, const std::vector<LogFileDescriptor>&)> &cb) = 0;
 

    virtual void requestReadLogFile(uint32_t file_id, uint32_t offset, uint32_t read_size, const std::function<void(ResponseCode, const uint8_t*, size_t)> &cb) = 0;
 

    virtual void requestClearLog(const std::function<void(ResponseCode)> &cb) = 0;
 

    virtual void requestUpdateFirmware(const uint8_t* firmware_image, uint32_t size, const std::function<bool(uint32_t, uint32_t)> &progress_cb, 
                                                                            const std::function<void(ResponseCode)> &done_cb) = 0;
 
 
 
    virtual void requestReadDebug(uint32_t offset, uint32_t read_size, const std::function<void(ResponseCode, const uint8_t*, size_t)> &cb) = 0;
    virtual void requestEraseDebug(const std::function<void(ResponseCode)> &cb) = 0;
 
 
    virtual void requestReboot(const std::function<void(ResponseCode)> &cb) = 0;
 
 

    static std::string getIpAddressString(uint32_t ip);
 
    
    static std::string getMacAddressString(uint64_t mac);
 
    
    static uint64_t parseMacAddress(const char* address);
 

    static std::string getHardwareString(uint8_t bcd);
 
    
    static std::string getPowerStatusString(PowerStatus ps);
 

    static bool hasDataLog(uint8_t bcd);
 
    
    static bool hasVoltage2(uint8_t bcd);
 
    
    static bool hasConfigurableShunt(uint8_t bcd);
 

    static bool hasIntegratedShunt(uint8_t bcd);
 
    
    static bool hasWifi(uint8_t bcd);
 

    static bool hasEthernet(uint8_t bcd);
 

    static bool hasNetwork(uint8_t bcd);
 

    static bool hasBluetooth(uint8_t bcd);
 

    static inline bool checkBCD(uint16_t bcd)
    {
        for(uint32_t i = 0; i < 4; i++)
        {
            if ((bcd & 0xF) > 0x9)
                return false;
            bcd >>= 4;
        }
 
        return true;
    }

    static AuthKey getAuthKeyFromPassword(const char* password);

    static std::string getUpdateFirmwareImageUrl(uint8_t hardware_revision_bcd, uint16_t firmware_revision_bcd);
    
    static uint16_t checkFirmwareImage(const uint8_t* image, size_t size, uint8_t hardware_revision_bcd);
};
 
 
#include <powermon_scanner.h>
 
 
#endif