[EEVSE] Add test script and SDK updates for TC_EEVSE_2.7 (project-chip#39565)

* Added new TestEvent trigger codes to python and C++

* Added TE trigger support for SoC

* Updated Energy Management App zap file to enable SoC, BatteryCapacity and other attributes needed in 1.5

* Initial version of TC_EEVSE_2_7 basic steps 1-7

* regen_all to get .matter file update

* Restyled by clang-format

* Added more test steps to 2.7 and used feature_guard and mark_all_remaining_steps_skipped() if not present

* Enabled SoC and other features in Delegate example.

* Added steps 9-10d (passing)

* Moved charging target functions from EEVSE_2_3.py into EEVSE_Utils.py

* fixed import issues missed in the move

* Added steps 11a-d (failing due to delegate implementation - spec says if SoC is present then the nextEnergyRequired should be null)

* Restyled by isort

* Fix cast issue seen on some platforms

* Refactored ComputeChargingSchedule to split out DetermineRequiredEnergy and ComputeStartTime to better support SoC based charging.

* Fixed incorrect constraint check now that SoC reporting is enabled TC_EEVSE_2_3 was failing.

* Fixed major typo!

* Added steps 12a-14d. Fixed setting of NextStartTime to Null if SoC > TargetSoC

* Finished test steps for 2.7

* Enforce TargetSoC to be null if we fall back to AddedEnergy charging mode (Step 17d failed)

* Fixed Lint failures

* Things spotted during self-review, and re-fix 2.3 test which was failing. Removed TODO around setting voltage with sensible EU default

* Noticed that kMinimumChargeCurrent appears in autogen field index so renamed variable to kMinimumChargeCurrentLimit

* Apply suggestions from code review

Co-authored-by: Sergio Soares <[email protected]>

* Fixed things which got broken after applying code review changes via GitHub

* Corrected battery capacity to be 70kWh not 7kWh

* Added comments per review about Matter Epoch date

* Added Gemini code review suggestions

* Revert "Fixed incorrect constraint check now that SoC reporting is enabled TC_EEVSE_2_3 was failing."

This reverts commit 3dad7c3.

* Per review comment - this probably should have been InvalidCommand.

* Reworked TC_EEVSE_2.3 to handle kSoCReporting which started failing if TargetSoC was not included in SetTargets. Added new matter mark_step_range_skipped() into matter_testing.py

* Added decorator and FeatureMap logging

* Updated TestSteps for TC_EEVSE_2.7

* Restyled by isort

* fixed lint error 2.3 & 2.7

* Restyled by isort

---------

Co-authored-by: Restyled.io <[email protected]>
Co-authored-by: Sergio Soares <[email protected]>

Author: 3 people

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

@@ -129,6 +129,15 @@ class EVSEManufacturer : public DEMManufacturerDelegate
      */
     static void ApplicationCallbackHandler(const EVSECbInfo * cb, intptr_t arg);
 
+    /**
+     * @brief   Helper functions used by ComputeChargingSchedule
+     */
+    CHIP_ERROR DetermineRequiredEnergy(EnergyEvseDelegate * dg, int64_t & requiredEnergy_mWh,
+                                       DataModel::Nullable<Percent> & targetSoC,
+                                       DataModel::Nullable<int64_t> & targetAddedEnergy_mWh);
+
+    CHIP_ERROR ComputeStartTime(EnergyEvseDelegate * dg, DataModel::Nullable<uint32_t> & startTime_epoch_s,
+                                uint32_t targetTime_epoch_s, uint32_t now_epoch_s, int64_t requiredEnergy_mWh);
     /**
      * @brief   Simple example to demonstrate how an EVSE can compute the start time
      *          and duration of a charging schedule

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

@@ -36,6 +36,10 @@ namespace EnergyEvse {
 // chip::app::Clusters::EnergyEvse::TargetDayOfWeekBitmap)
 constexpr uint8_t kAllTargetDaysMask = 0x7f;
 
+// A sensible minimum limit for mains voltage (100V) to avoid accidental use
+// of 100mV instead of 100000mV
+constexpr int64_t kMinimumMainsVoltage_mV = 100000;
+
 /* Local state machine Events to allow simpler handling of state transitions */
 enum EVSEStateMachineEvent
 {
@@ -214,6 +218,8 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     // Internal API to allow an EVSE to change its internal state etc
     Status HwSetMaxHardwareCurrentLimit(int64_t currentmA);
     int64_t HwGetMaxHardwareCurrentLimit() { return mMaxHardwareCurrentLimit; }
+    Status HwSetNominalMainsVoltage(int64_t voltage_mV);
+    int64_t HwGetNominalMainsVoltage() { return mNominalMainsVoltage; }
     Status HwSetCircuitCapacity(int64_t currentmA);
     Status HwSetCableAssemblyLimit(int64_t currentmA);
     int64_t HwGetCableAssemblyLimit() { return mCableAssemblyCurrentLimit; }
@@ -282,7 +288,10 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
 
     /* SOC attributes */
     DataModel::Nullable<Percent> GetStateOfCharge() override;
+    CHIP_ERROR SetStateOfCharge(DataModel::Nullable<Percent>);
     DataModel::Nullable<int64_t> GetBatteryCapacity() override;
+    CHIP_ERROR SetBatteryCapacity(DataModel::Nullable<int64_t>);
+
     /* PNC attributes*/
     DataModel::Nullable<CharSpan> GetVehicleID() override;
     /* Session SESS attributes */
@@ -304,7 +313,9 @@ class EnergyEvseDelegate : public EnergyEvse::Delegate
     int64_t mCableAssemblyCurrentLimit              = 0; /* Cable limit detected when cable is plugged in, in mA */
     int64_t mMaximumChargingCurrentLimitFromCommand = 0; /* Value of current maximum limit when charging enabled */
     int64_t mActualChargingCurrentLimit             = 0;
-    StateEnum mHwState                              = StateEnum::kNotPluggedIn; /* Hardware state */
+    int64_t mNominalMainsVoltage                    = 230000; /* Assume a sensible default mains voltage */
+
+    StateEnum mHwState = StateEnum::kNotPluggedIn; /* Hardware state */
 
     /* Variables to hold State and SupplyState in case a fault is raised */
     StateEnum mStateBeforeFault             = StateEnum::kUnknownEnumValue;

examples/energy-management-app/energy-management-common/energy-evse/src/EVSEManufacturerImpl.cpp

@@ -46,6 +46,8 @@ using namespace chip::app::Clusters::PowerSource::Attributes;
 
 using Protocols::InteractionModel::Status;
 
+constexpr int64_t kMaxRequiredEnergy_mWh = 1000000000000; // 1000 MWh
+
 CHIP_ERROR EVSEManufacturer::Init(chip::EndpointId powerSourceEndpointId)
 {
     /* Manufacturers should modify this to do any custom initialisation */
@@ -78,6 +80,9 @@ CHIP_ERROR EVSEManufacturer::Init(chip::EndpointId powerSourceEndpointId)
     /*
      * This is an example implementation for manufacturers to consider
      *
+     * For Manufacturer to specify the hardware mains voltage in mV:
+     *  dg->HwSetNominalMainsVoltage(230000);       // 230V
+     *
      * For Manufacturer to specify the hardware capability in mA:
      *  dg->HwSetMaxHardwareCurrentLimit(32000);    // 32A
      *
@@ -123,7 +128,7 @@ CHIP_ERROR EVSEManufacturer::Shutdown()
 
 CHIP_ERROR FindNextTarget(const BitMask<EnergyEvse::TargetDayOfWeekBitmap> dayOfWeekMap, uint16_t minutesPastMidnightNow_m,
                           uint16_t & targetTimeMinutesPastMidnight_m, DataModel::Nullable<Percent> & targetSoC,
-                          DataModel::Nullable<int64_t> & addedEnergy_mWh, bool bAllowTargetsInPast)
+                          DataModel::Nullable<int64_t> & targetAddedEnergy_mWh, bool bAllowTargetsInPast)
 {
     EnergyEvse::Structs::ChargingTargetScheduleStruct::Type entry;
 
@@ -170,11 +175,11 @@ CHIP_ERROR FindNextTarget(const BitMask<EnergyEvse::TargetDayOfWeekBitmap> dayOf
 
                     if (chargingTarget.addedEnergy.HasValue())
                     {
-                        addedEnergy_mWh.SetNonNull(chargingTarget.addedEnergy.Value());
+                        targetAddedEnergy_mWh.SetNonNull(chargingTarget.addedEnergy.Value());
                     }
                     else
                     {
-                        addedEnergy_mWh.SetNull();
+                        targetAddedEnergy_mWh.SetNull();
                     }
                 }
             }
@@ -190,6 +195,141 @@ CHIP_ERROR FindNextTarget(const BitMask<EnergyEvse::TargetDayOfWeekBitmap> dayOf
     return bFound ? CHIP_NO_ERROR : CHIP_ERROR_NOT_FOUND;
 }
 
+/**
+ * @brief   DetermineRequiredEnergy based on if we know vehicle SoC, BatteryCapacity
+ *          and TargetSoC or fallback to addedEnergy target.
+ *
+ *  Output: requiredEnergy_mWh - how much energy is needed to charge
+ *          Note this could be 0 if the vehicleSoC > targetSoC
+ */
+CHIP_ERROR EVSEManufacturer::DetermineRequiredEnergy(EnergyEvseDelegate * dg, int64_t & requiredEnergy_mWh,
+                                                     DataModel::Nullable<Percent> & targetSoC,
+                                                     DataModel::Nullable<int64_t> & targetAddedEnergy_mWh)
+{
+    DataModel::Nullable<Percent> vehicleSoC;
+    DataModel::Nullable<int64_t> batteryCapacity_mWh;
+
+    if (!targetSoC.IsNull())
+    {
+        if (GetEvseInstance()->HasFeature(Feature::kSoCReporting))
+        {
+            // We support SoCReporting, but it doesn't mean the Vehicle supports it
+            vehicleSoC          = dg->GetStateOfCharge();
+            batteryCapacity_mWh = dg->GetBatteryCapacity();
+            if (!vehicleSoC.IsNull() && !batteryCapacity_mWh.IsNull())
+            {
+                // If the current SoC is already >= targetSoC - we don't need to charge, set to 0.
+                requiredEnergy_mWh = std::max<int64_t>(
+                    0, static_cast<int64_t>((targetSoC.Value() - vehicleSoC.Value()) * batteryCapacity_mWh.Value() / 100));
+                ChipLogProgress(AppServer, "EVSE: Vehicle reports current SoC: %d    ----- target SoC: %d", vehicleSoC.Value(),
+                                targetSoC.Value());
+                // Since we are charging using SoC then always null out the NextAddedEnergy target
+                // to indicate that the SoC target is being followed (per spec)
+                // NextChargeAddedEnergy is set by the caller based on targetAddedEnergy_mWh
+                targetAddedEnergy_mWh.SetNull();
+
+                return CHIP_NO_ERROR;
+            }
+            // ELSE we don't have VehicleSoC and Battery Capacity so we have to
+            // fallback to AddedEnergy charging below
+        }
+        else
+        {
+            // Cluster does not support SoC Reporting so target SoC is only allowed to be 100%
+            if (targetSoC.Value() != 100)
+            {
+                ChipLogError(AppServer, "EVSE WARNING: TargetSoC is not 100%% and we don't know the EV SoC!");
+            }
+
+            // We don't know the Vehicle SoC so we must charge now
+            // Let's assume an unreasonably large battery size which
+            // ComputeStartTime uses to recognise it needs to start now
+            requiredEnergy_mWh = kMaxRequiredEnergy_mWh;
+
+            return CHIP_NO_ERROR;
+        }
+    }
+
+    // Unable to charge using TargetSoC - Fallback to using AddedEnergy method
+    // Check we have a AddedEnergy target
+    if (targetAddedEnergy_mWh.IsNull())
+    {
+        ChipLogError(AppServer,
+                     "EVSE ERROR: Cannot use TargetSoC (maybe missing VehicleSoC/BatteryCapacity?) or AddedEnergy has not been "
+                     "provided - assume large battery!");
+
+        requiredEnergy_mWh = kMaxRequiredEnergy_mWh;
+        return CHIP_NO_ERROR;
+    }
+
+    // Otherwise just use targetAddedEnergy_mWh
+    requiredEnergy_mWh = targetAddedEnergy_mWh.Value();
+
+    // According to spec if we can't use SoC for charging (falling back to AddedEnergy)
+    // then NextTargetSoC should be Null is set by the caller based on targetSoC
+    targetSoC.SetNull();
+
+    return CHIP_NO_ERROR;
+}
+/**
+ * @brief   Compute the start time based on required energy
+ *
+ *  Simple optimizer - assume a flat tariff throughout the day
+ */
+CHIP_ERROR EVSEManufacturer::ComputeStartTime(EnergyEvseDelegate * dg, DataModel::Nullable<uint32_t> & startTime_epoch_s,
+                                              uint32_t targetTime_epoch_s, uint32_t now_epoch_s, int64_t requiredEnergy_mWh)
+{
+
+    uint32_t chargingDuration_s;
+    uint32_t tempStartTime_epoch_s;
+
+    if (requiredEnergy_mWh == 0)
+    {
+        // If we don't need to charge, then ensure we do not set a NextStartTime
+        // (spec says this should be NULL if we don't plan to schedule a charge)
+        startTime_epoch_s.SetNull();
+        return CHIP_NO_ERROR;
+    }
+
+    // Compute power from nominal voltage and maxChargingRate
+    // GetMaximumChargeCurrent returns mA, but to help avoid overflow
+    // We use V (not mV) and compute power to the nearest Watt
+    uint32_t power_W = static_cast<uint32_t>((dg->HwGetNominalMainsVoltage() * dg->GetMaximumChargeCurrent()) / 1000000);
+    if (power_W == 0)
+    {
+        ChipLogError(AppServer, "EVSE Error: MaxCurrent = 0Amp - Can't schedule charging");
+        startTime_epoch_s.SetNull();
+        return CHIP_ERROR_INTERNAL;
+    }
+
+    // Time to charge(seconds) = (3600 * Energy(mWh) / Power(W)) / 1000
+    // to avoid using floats we multiply by 36 and then divide by 10 (instead of x3600 and dividing by 1000)
+    chargingDuration_s =
+        static_cast<uint32_t>((static_cast<uint64_t>(requiredEnergy_mWh) * 36) / (static_cast<uint64_t>(power_W) * 10));
+
+    // Add in 15 minutes leeway to account for slow starting vehicles
+    // that need to condition the battery or if it is cold etc
+    chargingDuration_s += (15 * 60);
+
+    // A price optimizer can look for cheapest time of day
+    // However for now we'll start charging as late as possible
+    tempStartTime_epoch_s = targetTime_epoch_s - chargingDuration_s;
+
+    if (tempStartTime_epoch_s < now_epoch_s)
+    {
+        // we need to turn on the EVSE now - it won't have enough time to reach the target
+        startTime_epoch_s.SetNonNull(now_epoch_s);
+        // TODO call function to turn on the EV
+    }
+    else
+    {
+        // we turn off the EVSE for now
+        startTime_epoch_s.SetNonNull(tempStartTime_epoch_s);
+        // TODO have a periodic timer which checks if we should turn on the charger now
+    }
+    return CHIP_NO_ERROR;
+}
+
 /**
  * @brief   Simple example to demonstrate how an EVSE can compute the start time
  *          and duration of a charging schedule
@@ -215,18 +355,16 @@ CHIP_ERROR EVSEManufacturer::ComputeChargingSchedule()
     DataModel::Nullable<uint32_t> startTime_epoch_s;
     DataModel::Nullable<uint32_t> targetTime_epoch_s;
     DataModel::Nullable<Percent> targetSoC;
-    DataModel::Nullable<int64_t> addedEnergy_mWh;
+    DataModel::Nullable<int64_t> targetAddedEnergy_mWh;
 
-    uint32_t power_W;
-    uint32_t chargingDuration_s;
     uint32_t tempTargetTime_epoch_s;
-    uint32_t tempStartTime_epoch_s;
+    int64_t requiredEnergy_mWh;
     uint16_t targetTimeMinutesPastMidnight_m;
 
     // Initialise the values to Null - if the FindNextTarget finds one, then it will update the value
     targetTime_epoch_s.SetNull();
     targetSoC.SetNull();
-    addedEnergy_mWh.SetNull();
+    targetAddedEnergy_mWh.SetNull();
     startTime_epoch_s.SetNull(); // If we FindNextTarget this will be computed below and set to a non null value
 
     /* We can only compute charging schedules if the EV is plugged in and the charging is enabled
@@ -239,7 +377,7 @@ CHIP_ERROR EVSEManufacturer::ComputeChargingSchedule()
         while (searchDay < 2)
         {
             err = FindNextTarget(dayOfWeekMap, minutesPastMidnightNow_m, targetTimeMinutesPastMidnight_m, targetSoC,
-                                 addedEnergy_mWh, (searchDay != 0));
+                                 targetAddedEnergy_mWh, (searchDay != 0));
             if (err == CHIP_ERROR_NOT_FOUND)
             {
                 // We didn't find one for today, try tomorrow
@@ -265,68 +403,18 @@ CHIP_ERROR EVSEManufacturer::ComputeChargingSchedule()
                 ((now_epoch_s / 60) + targetTimeMinutesPastMidnight_m + (searchDay * 1440) - minutesPastMidnightNow_m) * 60;
             targetTime_epoch_s.SetNonNull(tempTargetTime_epoch_s);
 
-            if (!targetSoC.IsNull())
+            /* Determine requiredEnergy based on if we support SoC Reporting or fallback to AddedEnergy target */
+            if (DetermineRequiredEnergy(dg, requiredEnergy_mWh, targetSoC, targetAddedEnergy_mWh) == CHIP_NO_ERROR)
             {
-                if (targetSoC.Value() != 100)
-                {
-                    ChipLogError(AppServer, "EVSE WARNING: TargetSoC is not 100%% and we don't know the EV SoC!");
-                }
-                // We don't know the Vehicle SoC so we must charge now
-                // TODO make this use the SoC featureMap to determine if this is an error
-                startTime_epoch_s.SetNonNull(now_epoch_s);
-            }
-            else
-            {
-                // We expect to use AddedEnergy to determine the charging start time
-                if (addedEnergy_mWh.IsNull())
-                {
-                    ChipLogError(AppServer, "EVSE ERROR: Neither TargetSoC or AddedEnergy has been provided");
-                    return CHIP_ERROR_INTERNAL;
-                }
-                // Simple optimizer - assume a flat tariff throughout the day
-                // Compute power from nominal voltage and maxChargingRate
-                // GetMaximumChargeCurrent returns mA, but to help avoid overflow
-                // We use V (not mV) and compute power to the nearest Watt
-                power_W = static_cast<uint32_t>((230 * dg->GetMaximumChargeCurrent()) /
-                                                1000); // TODO don't use 230V - not all markets will use that
-                if (power_W == 0)
-                {
-                    ChipLogError(AppServer, "EVSE Error: MaxCurrent = 0Amp - Can't schedule charging");
-                    return CHIP_ERROR_INTERNAL;
-                }
-
-                // Time to charge(seconds) = (3600 * Energy(mWh) / Power(W)) / 1000
-                // to avoid using floats we multiply by 36 and then divide by 10 (instead of x3600 and dividing by 1000)
-                chargingDuration_s = static_cast<uint32_t>(((addedEnergy_mWh.Value() / power_W) * 36) / 10);
-
-                // Add in 15 minutes leeway to account for slow starting vehicles
-                // that need to condition the battery or if it is cold etc
-                chargingDuration_s += (15 * 60);
-
-                // A price optimizer can look for cheapest time of day
-                // However for now we'll start charging as late as possible
-                tempStartTime_epoch_s = tempTargetTime_epoch_s - chargingDuration_s;
-
-                if (tempStartTime_epoch_s < now_epoch_s)
-                {
-                    // we need to turn on the EVSE now - it won't have enough time to reach the target
-                    startTime_epoch_s.SetNonNull(now_epoch_s);
-                    // TODO call function to turn on the EV
-                }
-                else
-                {
-                    // we turn off the EVSE for now
-                    startTime_epoch_s.SetNonNull(tempStartTime_epoch_s);
-                    // TODO have a periodic timer which checks if we should turn on the charger now
-                }
+                ComputeStartTime(dg, startTime_epoch_s, tempTargetTime_epoch_s, now_epoch_s, requiredEnergy_mWh);
             }
         }
     }
 
     // Update the attributes to allow a UI to inform the user
     dg->SetNextChargeStartTime(startTime_epoch_s);
     dg->SetNextChargeTargetTime(targetTime_epoch_s);
-    dg->SetNextChargeRequiredEnergy(addedEnergy_mWh);
+    dg->SetNextChargeRequiredEnergy(targetAddedEnergy_mWh);
     dg->SetNextChargeTargetSoC(targetSoC);
 
     return err;