EVSE add Session and Event support, test event trigger support

.github/.wordlist.txt

@@ -519,8 +519,10 @@ EthyleneOxideConcentrationMeasurement
 EvalCode
 EvalCodeWithName
 EvalFrameDefault
+EV
 EVB
 evk
+EVSE
 exceptfds
 ExchangeContext
 exe

examples/energy-management-app/energy-management-common/include/EVSECallbacks.h

@@ -30,26 +30,42 @@ using namespace chip::app::Clusters::EnergyEvse;
  * This is not specific to the EnergyEVSE cluster, but includes DeviceEnergyManagement
  * and potential future clusters.
  */
-enum EVSECallbackType
+
+enum class EVSECallbackType : uint8_t
 {
     /*
      * The State has changed (e.g. from Disabled to Charging, or vice-versa)
      */
     StateChanged,
     /*
-     * ChargeCurrent has changed
+     * ChargeCurrent has changed (e.g. maxChargingCurrent so requires an
+       update to advertise a different charging current to the EV)
      */
     ChargeCurrentChanged,
     /*
      * Charging Preferences have changed
+     * The daily charging target time, SoC / Added Energy schedules have changed
+     * and may require the local optimiser to re-run.
      */
     ChargingPreferencesChanged,
     /*
-     * DeviceEnergyManagement has changed
+     * Energy Meter Reading requested from the hardware, e.g. so that the session
+     * information can be updated.
+     */
+    EnergyMeterReadingRequested,
+    /*
+     * The associated DeviceEnergyManagement cluster has changed. This may mean
+     * that the start time, or power profile or power levels have been adjusted
      */
     DeviceEnergyManagementChanged,
 };
 
+enum class ChargingDischargingType : uint8_t
+{
+    kCharging,
+    kDischarging
+};
+
 struct EVSECbInfo
 {
     EVSECallbackType type;
@@ -68,6 +84,13 @@ struct EVSECbInfo
         {
             int64_t maximumChargeCurrent;
         } ChargingCurrent;
+
+        /* for type = EnergyMeterReadingRequested */
+        struct
+        {
+            ChargingDischargingType meterType;
+            int64_t * energyMeterValuePtr;
+        } EnergyMeterReadingRequest;
     };
 };
 

examples/energy-management-app/energy-management-common/include/EVSEManufacturerImpl.h

@@ -33,24 +33,50 @@ namespace EnergyEvse {
 class EVSEManufacturer
 {
 public:
+    EVSEManufacturer(EnergyEvseManager * aInstance) { mInstance = aInstance; }
+    EnergyEvseManager * GetInstance() { return mInstance; }
+    EnergyEvseDelegate * GetDelegate()
+    {
+        if (mInstance)
+        {
+            return mInstance->GetDelegate();
+        }
+        return nullptr;
+    }
+
     /**
      * @brief   Called at start up to apply hardware settings
      */
-    CHIP_ERROR Init(EnergyEvseManager * aInstance);
+    CHIP_ERROR Init();
 
     /**
      * @brief   Called at shutdown
      */
-    CHIP_ERROR Shutdown(EnergyEvseManager * aInstance);
+    CHIP_ERROR Shutdown();
 
     /**
      * @brief   Main Callback handler from delegate to user code
      */
     static void ApplicationCallbackHandler(const EVSECbInfo * cb, intptr_t arg);
 
 private:
+    EnergyEvseManager * mInstance;
+
+    int64_t mLastChargingEnergyMeter    = 0;
+    int64_t mLastDischargingEnergyMeter = 0;
 };
 
+/** @brief Helper function to return the singleton EVSEManufacturer instance
+ *
+ * This is needed by the EVSEManufacturer class to support TestEventTriggers
+ * which are called outside of any class context. This allows the EVSEManufacturer
+ * class to return the relevant Delegate instance in which to invoke the test
+ * events on.
+ *
+ * This function is typically found in main.cpp or wherever the singleton is created.
+ */
+EVSEManufacturer * GetEvseManufacturer();
+
 } // namespace EnergyEvse
 } // namespace Clusters
 } // namespace app

examples/energy-management-app/energy-management-common/include/EnergyEvseDelegateImpl.h

@@ -31,6 +31,68 @@ namespace app {
 namespace Clusters {
 namespace EnergyEvse {
 
+/* Local state machine Events to allow simpler handling of state transitions */
+enum EVSEStateMachineEvent
+{
+    EVPluggedInEvent,        /* EV has been plugged in */
+    EVNotDetectedEvent,      /* EV has been unplugged or detected as not connected */
+    EVNoDemandEvent,         /* EV has stopped asking for demand */
+    EVDemandEvent,           /* EV has asked for demand*/
+    ChargingEnabledEvent,    /* Charging has been enabled */
+    DischargingEnabledEvent, /* Discharging has been enabled */
+    DisabledEvent,           /* EVSE has been disabled */
+    FaultRaised,             /* Fault has been raised */
+    FaultCleared,            /* Fault has been cleared */
+};
+
+/**
+ * Helper class to handle all of the session related info
+ */
+class EvseSession
+{
+public:
+    EvseSession(EndpointId aEndpoint) { mEndpointId = aEndpoint; }
+    /**
+     * @brief This function records the start time and provided energy meter values as part of the new session.
+     *
+     * @param chargingMeterValue    - The current value of the energy meter (charging) in mWh
+     * @param dischargingMeterValue - The current value of the energy meter (discharging) in mWh
+     */
+    void StartSession(int64_t chargingMeterValue, int64_t dischargingMeterValue);
+
+    /**
+     * @brief This function updates the session Duration to allow read attributes to return latest values
+     */
+    void RecalculateSessionDuration();
+
+    /**
+     * @brief This function updates the EnergyCharged meter value
+     *
+     * @param chargingMeterValue    - The value of the energy meter (charging) in mWh
+     */
+    void UpdateEnergyCharged(int64_t chargingMeterValue);
+
+    /**
+     * @brief This function updates the EnergyDischarged meter value
+     *
+     * @param dischargingMeterValue - The value of the energy meter (discharging) in mWh
+     */
+    void UpdateEnergyDischarged(int64_t dischargingMeterValue);
+
+    /* Public members - represent attributes in the cluster */
+    DataModel::Nullable<uint32_t> mSessionID;
+    DataModel::Nullable<uint32_t> mSessionDuration;
+    DataModel::Nullable<int64_t> mSessionEnergyCharged;
+    DataModel::Nullable<int64_t> mSessionEnergyDischarged;
+
+private:
+    EndpointId mEndpointId = 0;
+
+    uint32_t mStartTime                     = 0; // Epoch_s - 0 means it hasn't started yet
+    int64_t mSessionEnergyChargedAtStart    = 0; // in mWh - 0 means it hasn't been set yet
+    int64_t mSessionEnergyDischargedAtStart = 0; // in mWh - 0 means it hasn't been set yet
+};
+
 /**
  * The application delegate.
  */
@@ -74,15 +136,41 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
      */
     Status HwRegisterEvseCallbackHandler(EVSECallbackFunc handler, intptr_t arg);
 
+    /**
+     * @brief    Decides if a timer is needed based on EVSE state and sets a callback if needed
+     *
+     * In order to ensure the EVSE restarts charging (if enabled) after power loss
+     * this should be called after the EVSE is initialised
+     * (e.g. HwSetMaxHardwareCurrentLimit and HwSetCircuitCapacity have been called)
+     * and the persisted attributes have been loaded, and time has been synchronised.
+     *
+     * If time isn't sync'd yet it will call itself back periodically (if required)
+     * until time is sync'd.
+     *
+     * It is also called when a EnableCharging or EnableDischarging command
+     * is recv'd to schedule when the EVSE should be automatically disabled based
+     * on ChargingEnabledUntil / DischargingEnabledUntil expiring.
+     */
+    Status ScheduleCheckOnEnabledTimeout();
+
     // -----------------------------------------------------------------
     // Internal API to allow an EVSE to change its internal state etc
     Status HwSetMaxHardwareCurrentLimit(int64_t currentmA);
+    int64_t HwGetMaxHardwareCurrentLimit() { return mMaxHardwareCurrentLimit; }
     Status HwSetCircuitCapacity(int64_t currentmA);
     Status HwSetCableAssemblyLimit(int64_t currentmA);
+    int64_t HwGetCableAssemblyLimit() { return mCableAssemblyCurrentLimit; }
     Status HwSetState(StateEnum state);
+    StateEnum HwGetState() { return mHwState; };
     Status HwSetFault(FaultStateEnum fault);
     Status HwSetRFID(ByteSpan uid);
     Status HwSetVehicleID(const CharSpan & vehID);
+    Status HwDiagnosticsComplete();
+    Status SendEVConnectedEvent();
+    Status SendEVNotDetectedEvent();
+    Status SendEnergyTransferStartedEvent();
+    Status SendEnergyTransferStoppedEvent(EnergyTransferStoppedReasonEnum reason);
+    Status SendFaultEvent(FaultStateEnum newFaultState);
 
     // ------------------------------------------------------------------
     // Get attribute methods
@@ -96,10 +184,10 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     CHIP_ERROR SetFaultState(FaultStateEnum);
 
     DataModel::Nullable<uint32_t> GetChargingEnabledUntil() override;
-    CHIP_ERROR SetChargingEnabledUntil(uint32_t);
+    CHIP_ERROR SetChargingEnabledUntil(DataModel::Nullable<uint32_t>);
 
     DataModel::Nullable<uint32_t> GetDischargingEnabledUntil() override;
-    CHIP_ERROR SetDischargingEnabledUntil(uint32_t);
+    CHIP_ERROR SetDischargingEnabledUntil(DataModel::Nullable<uint32_t>);
 
     int64_t GetCircuitCapacity() override;
     CHIP_ERROR SetCircuitCapacity(int64_t);
@@ -128,7 +216,7 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     DataModel::Nullable<Percent> GetNextChargeTargetSoC() override;
 
     DataModel::Nullable<uint16_t> GetApproximateEVEfficiency() override;
-    CHIP_ERROR SetApproximateEVEfficiency(uint16_t) override;
+    CHIP_ERROR SetApproximateEVEfficiency(DataModel::Nullable<uint16_t>) override;
 
     /* SOC attributes */
     DataModel::Nullable<Percent> GetStateOfCharge() override;
@@ -143,10 +231,11 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
 
 private:
     /* Constants */
-    static constexpr int DEFAULT_MIN_CHARGE_CURRENT          = 6000;                  /* 6A */
-    static constexpr int DEFAULT_USER_MAXIMUM_CHARGE_CURRENT = kMaximumChargeCurrent; /* 80A */
-    static constexpr int DEFAULT_RANDOMIZATION_DELAY_WINDOW  = 600;                   /* 600s */
-    static constexpr int kMaxVehicleIDBufSize                = 32;
+    static constexpr int kDefaultMinChargeCurrent                     = 6000;                  /* 6A */
+    static constexpr int kDefaultUserMaximumChargeCurrent             = kMaximumChargeCurrent; /* 80A */
+    static constexpr int kDefaultRandomizationDelayWindow             = 600;                   /* 600s */
+    static constexpr int kMaxVehicleIDBufSize                         = 32;
+    static constexpr int kPeriodicCheckIntervalRealTimeClockNotSynced = 30;
 
     /* private variables for controlling the hardware - these are not attributes */
     int64_t mMaxHardwareCurrentLimit                = 0; /* Hardware current limit in mA */
@@ -155,28 +244,54 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     int64_t mActualChargingCurrentLimit             = 0;
     StateEnum mHwState                              = StateEnum::kNotPluggedIn; /* Hardware state */
 
+    /* Variables to hold State and SupplyState in case a fault is raised */
+    StateEnum mStateBeforeFault             = StateEnum::kUnknownEnumValue;
+    SupplyStateEnum mSupplyStateBeforeFault = SupplyStateEnum::kUnknownEnumValue;
+
     /* Callback related */
     EVSECallbackWrapper mCallbacks = { .handler = nullptr, .arg = 0 }; /* Wrapper to allow callbacks to be registered */
     Status NotifyApplicationCurrentLimitChange(int64_t maximumChargeCurrent);
     Status NotifyApplicationStateChange();
+    Status GetEVSEEnergyMeterValue(ChargingDischargingType meterType, int64_t & aMeterValue);
+
+    /* Local State machine handling */
+    Status CheckFaultOrDiagnostic();
+    Status HandleStateMachineEvent(EVSEStateMachineEvent event);
+    Status HandleEVPluggedInEvent();
+    Status HandleEVNotDetectedEvent();
+    Status HandleEVNoDemandEvent();
+    Status HandleEVDemandEvent();
+    Status HandleChargingEnabledEvent();
+    Status HandleDischargingEnabledEvent();
+    Status HandleDisabledEvent();
+    Status HandleFaultRaised();
+    Status HandleFaultCleared();
 
     /**
      * @brief Helper function to work out the charge limit based on conditions and settings
      */
     Status ComputeMaxChargeCurrentLimit();
 
+    /**
+     * @brief This checks if the charging or discharging needs to be disabled
+     *
+     * @params pointer to SystemLayer
+     * @params pointer to EnergyEvseDelegate
+     */
+    static void EvseCheckTimerExpiry(System::Layer * systemLayer, void * delegate);
+
     /* Attributes */
     StateEnum mState             = StateEnum::kNotPluggedIn;
     SupplyStateEnum mSupplyState = SupplyStateEnum::kDisabled;
     FaultStateEnum mFaultState   = FaultStateEnum::kNoError;
     DataModel::Nullable<uint32_t> mChargingEnabledUntil;    // TODO Default to 0 to indicate disabled
     DataModel::Nullable<uint32_t> mDischargingEnabledUntil; // TODO Default to 0 to indicate disabled
     int64_t mCircuitCapacity           = 0;
-    int64_t mMinimumChargeCurrent      = DEFAULT_MIN_CHARGE_CURRENT;
+    int64_t mMinimumChargeCurrent      = kDefaultMinChargeCurrent;
     int64_t mMaximumChargeCurrent      = 0;
     int64_t mMaximumDischargeCurrent   = 0;
-    int64_t mUserMaximumChargeCurrent  = DEFAULT_USER_MAXIMUM_CHARGE_CURRENT; // TODO update spec
-    uint32_t mRandomizationDelayWindow = DEFAULT_RANDOMIZATION_DELAY_WINDOW;
+    int64_t mUserMaximumChargeCurrent  = kDefaultUserMaximumChargeCurrent; // TODO update spec
+    uint32_t mRandomizationDelayWindow = kDefaultRandomizationDelayWindow;
     /* PREF attributes */
     uint8_t mNumberOfWeeklyTargets = 0;
     uint8_t mNumberOfDailyTargets  = 1;
@@ -193,11 +308,11 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     /* PNC attributes*/
     DataModel::Nullable<CharSpan> mVehicleID;
 
-    /* Session SESS attributes */
-    DataModel::Nullable<uint32_t> mSessionID;
-    DataModel::Nullable<uint32_t> mSessionDuration;
-    DataModel::Nullable<int64_t> mSessionEnergyCharged;
-    DataModel::Nullable<int64_t> mSessionEnergyDischarged;
+    /* Session Object */
+    EvseSession mSession = EvseSession(mEndpointId);
+
+    /* Helper variable to hold meter val since last EnergyTransferStarted event */
+    int64_t mMeterValueAtEnergyTransferStart;
 };
 
 } // namespace EnergyEvse

examples/energy-management-app/energy-management-common/include/EnergyEvseManager.h

@@ -46,6 +46,8 @@ class EnergyEvseManager : public Instance
     CHIP_ERROR Init();
     void Shutdown();
 
+    CHIP_ERROR LoadPersistentAttributes();
+
     EnergyEvseDelegate * GetDelegate() { return mDelegate; };
 
 private: