feat(EnergyNode): Enhancement to set per phase A limit when only W is set (EVerest#1942)

mlitre · web-flow · commit cb7426cb5080 · 2026-03-13T15:17:06.000Z
We can now configure the energy node to convert the total W power to a
current per phase limit. This is only useful for top level energy nodes.

Furthermore, we've replaced the use of the mutex for the monitor.

Signed-off-by: Martin Litre &lt;mnlitre@gmail.com&gt;
diff --git a/modules/EnergyManagement/EnergyNode/CMakeLists.txt b/modules/EnergyManagement/EnergyNode/CMakeLists.txt
@@ -18,9 +18,15 @@ target_link_libraries(${MODULE_NAME}
 target_sources(${MODULE_NAME}
     PRIVATE
         "energy_grid/energyImpl.cpp"
+        "energy_grid/energy_schedule_utils.cpp"
         "external_limits/external_energy_limitsImpl.cpp"
 )
 
 # ev@c55432ab-152c-45a9-9d2e-7281d50c69c3:v1
 # insert other things like install cmds etc here
+
+# Add tests subdirectory
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
 # ev@c55432ab-152c-45a9-9d2e-7281d50c69c3:v1
diff --git a/modules/EnergyManagement/EnergyNode/EnergyNode.hpp b/modules/EnergyManagement/EnergyNode/EnergyNode.hpp
@@ -29,6 +29,8 @@ namespace module {
 struct Conf {
     double fuse_limit_A;
     int phase_count;
+    bool enhance_external_schedule;
+    double nominal_voltage_V;
 };
 
 class EnergyNode : public Everest::ModuleBase {
diff --git a/modules/EnergyManagement/EnergyNode/energy_grid/energyImpl.cpp b/modules/EnergyManagement/EnergyNode/energy_grid/energyImpl.cpp
@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
-// Copyright 2022 - 2022 Pionix GmbH and Contributors to EVerest
+// Copyright Pionix GmbH and Contributors to EVerest
 
 #include "energyImpl.hpp"
+#include "energy_schedule_utils.hpp"
 #include <chrono>
 #include <date/date.h>
 #include <date/tz.h>
@@ -11,60 +12,59 @@ namespace module {
 namespace energy_grid {
 
 void energyImpl::init() {
+    auto energy_state_handle = energy_state.handle();
 
-    // UUID must be unique also beyond this charging station -> will be handled on framework level and above later
-    energy_flow_request.uuid = mod->info.id;
-    energy_flow_request.node_type = types::energy::NodeType::Generic;
+    energy_state_handle->energy_flow_request.uuid = mod->info.id;
+    energy_state_handle->energy_flow_request.node_type = types::energy::NodeType::Generic;
 
     source_cfg = mod->info.id + "/module_config";
 
     // Initialize with sane defaults
-    energy_flow_request.schedule_import = get_local_schedule();
-    energy_flow_request.schedule_export = get_local_schedule();
+    energy_state_handle->energy_flow_request.schedule_import = get_local_schedule();
+    energy_state_handle->energy_flow_request.schedule_export = get_local_schedule();
 
     for (auto& entry : mod->r_energy_consumer) {
         entry->subscribe_energy_flow_request([this](types::energy::EnergyFlowRequest e) {
             // Received new energy_flow_request object from a child. Update in the cached object and republish.
-            std::scoped_lock lock(energy_mutex);
+            auto energy_state_handle = energy_state.handle();
 
             bool child_found = false;
-            for (auto& child : energy_flow_request.children) {
+            for (auto& child : energy_state_handle->energy_flow_request.children) {
                 if (child.uuid == e.uuid) {
                     child = e;
                     child_found = true;
                 }
             }
 
             if (!child_found) {
-                energy_flow_request.children.push_back(e);
+                energy_state_handle->energy_flow_request.children.push_back(e);
             }
 
-            publish_complete_energy_object();
+            publish_complete_energy_object(*energy_state_handle);
         });
     }
 
     if (!mod->r_powermeter.empty()) {
         mod->r_powermeter[0]->subscribe_powermeter([this](types::powermeter::Powermeter p) {
             EVLOG_debug << "Incoming powermeter readings: " << p;
-            std::scoped_lock lock(energy_mutex);
-            energy_flow_request.energy_usage_root = p;
-            publish_complete_energy_object();
+            auto energy_state_handle = energy_state.handle();
+            energy_state_handle->energy_flow_request.energy_usage_root = p;
+            publish_complete_energy_object(*energy_state_handle);
         });
     }
 
     if (!mod->r_price_information.empty()) {
         mod->r_price_information[0]->subscribe_energy_pricing(
             [this](types::energy_price_information::EnergyPriceSchedule p) {
                 EVLOG_debug << "Incoming price schedule: " << p;
-                std::scoped_lock lock(energy_mutex);
-                energy_pricing = p;
-                publish_complete_energy_object();
+                auto energy_state_handle = energy_state.handle();
+                energy_state_handle->energy_pricing = p;
+                publish_complete_energy_object(*energy_state_handle);
             });
     }
 }
 
 types::energy::ScheduleReqEntry energyImpl::get_local_schedule_req_entry() {
-    // local schedule of this module
     types::energy::ScheduleReqEntry local_schedule;
     auto tp = date::utc_clock::now();
 
@@ -84,52 +84,39 @@ std::vector<types::energy::ScheduleReqEntry> energyImpl::get_local_schedule() {
 }
 
 void energyImpl::set_external_limits(types::energy::ExternalLimits& l) {
-    std::scoped_lock lock(energy_mutex);
-
-    energy_flow_request.schedule_import = l.schedule_import;
-    if (not energy_flow_request.schedule_import.empty()) {
-        // add limits from our own fuse settings
-        for (auto& e : energy_flow_request.schedule_import) {
-            if (!e.limits_to_root.ac_max_current_A.has_value() ||
-                e.limits_to_root.ac_max_current_A.value().value > mod->config.fuse_limit_A)
-                e.limits_to_root.ac_max_current_A = {static_cast<float>(mod->config.fuse_limit_A), source_cfg};
-
-            if (!e.limits_to_root.ac_max_phase_count.has_value() ||
-                e.limits_to_root.ac_max_phase_count.value().value > mod->config.phase_count)
-                e.limits_to_root.ac_max_phase_count = {mod->config.phase_count, source_cfg};
-        }
+    auto energy_state_handle = energy_state.handle();
+
+    // Process import schedule
+    energy_state_handle->energy_flow_request.schedule_import = l.schedule_import;
+    if (not energy_state_handle->energy_flow_request.schedule_import.empty()) {
+        module::energy_grid::process_schedule_with_limits(
+            energy_state_handle->energy_flow_request.schedule_import, source_cfg, mod->config.fuse_limit_A,
+            mod->config.phase_count, mod->config.nominal_voltage_V, mod->config.enhance_external_schedule);
     } else {
         // At least add our local config limit even if the external limit did not set an import schedule
-        energy_flow_request.schedule_import = get_local_schedule();
+        energy_state_handle->energy_flow_request.schedule_import = get_local_schedule();
     }
 
-    energy_flow_request.schedule_export = l.schedule_export;
-
-    if (not energy_flow_request.schedule_export.empty()) {
-        // add limits from our own fuse settings
-        for (auto& e : energy_flow_request.schedule_export) {
-            if (!e.limits_to_root.ac_max_current_A.has_value() ||
-                e.limits_to_root.ac_max_current_A.value().value > mod->config.fuse_limit_A)
-                e.limits_to_root.ac_max_current_A = {static_cast<float>(mod->config.fuse_limit_A), source_cfg};
-
-            if (!e.limits_to_root.ac_max_phase_count.has_value() ||
-                e.limits_to_root.ac_max_phase_count.value().value > mod->config.phase_count)
-                e.limits_to_root.ac_max_phase_count = {mod->config.phase_count, source_cfg};
-        }
+    // Process export schedule
+    energy_state_handle->energy_flow_request.schedule_export = l.schedule_export;
+    if (not energy_state_handle->energy_flow_request.schedule_export.empty()) {
+        module::energy_grid::process_schedule_with_limits(
+            energy_state_handle->energy_flow_request.schedule_export, source_cfg, mod->config.fuse_limit_A,
+            mod->config.phase_count, mod->config.nominal_voltage_V, mod->config.enhance_external_schedule);
     } else {
         // At least add our local config limit even if the external limit did not set an export schedule
-        energy_flow_request.schedule_export = get_local_schedule();
+        energy_state_handle->energy_flow_request.schedule_export = get_local_schedule();
     }
 
-    energy_flow_request.schedule_setpoints = l.schedule_setpoints;
+    energy_state_handle->energy_flow_request.schedule_setpoints = l.schedule_setpoints;
 }
 
-void energyImpl::publish_complete_energy_object() {
-    // join the different schedules to the complete array (with resampling)
-    types::energy::EnergyFlowRequest energy_complete = energy_flow_request;
+void energyImpl::publish_complete_energy_object(const EnergyState& state) {
+    // This method is always called from contexts that already hold the energy_state lock
+    types::energy::EnergyFlowRequest energy_complete = state.energy_flow_request;
 
-    if (not energy_flow_request.schedule_export.empty() and not energy_pricing.schedule_export.empty()) {
-        merge_price_into_schedule(energy_complete.schedule_export, energy_pricing.schedule_export);
+    if (not state.energy_flow_request.schedule_export.empty() and not state.energy_pricing.schedule_export.empty()) {
+        merge_price_into_schedule(energy_complete.schedule_export, state.energy_pricing.schedule_export);
     }
 
     publish_energy_flow_request(energy_complete);
@@ -181,16 +168,18 @@ void energyImpl::merge_price_into_schedule(std::vector<types::energy::ScheduleRe
 }
 
 void energyImpl::ready() {
+    auto energy_state_handle = energy_state.handle();
     // publish own limits at least once
-    publish_energy_flow_request(energy_flow_request);
+    publish_energy_flow_request(energy_state_handle->energy_flow_request);
     mod->signalExternalLimit.connect([this](types::energy::ExternalLimits& l) { set_external_limits(l); });
 }
 
 void energyImpl::handle_enforce_limits(types::energy::EnforcedLimits& value) {
+    auto energy_state_handle = energy_state.handle();
 
     // route to children if it is not for me
     // FIXME: this sends it to all children, we could do a lookup on which branch it actually is
-    if (value.uuid != energy_flow_request.uuid) {
+    if (value.uuid != energy_state_handle->energy_flow_request.uuid) {
         for (auto& entry : mod->r_energy_consumer) {
             entry->call_enforce_limits(value);
         }
diff --git a/modules/EnergyManagement/EnergyNode/energy_grid/energyImpl.hpp b/modules/EnergyManagement/EnergyNode/energy_grid/energyImpl.hpp
@@ -14,7 +14,7 @@
 
 // ev@75ac1216-19eb-4182-a85c-820f1fc2c091:v1
 // insert your custom include headers here
-#include <mutex>
+#include <everest/util/async/monitor.hpp>
 // ev@75ac1216-19eb-4182-a85c-820f1fc2c091:v1
 
 namespace module {
@@ -48,27 +48,34 @@ class energyImpl : public energyImplBase {
     virtual void ready() override;
 
     // ev@3370e4dd-95f4-47a9-aaec-ea76f34a66c9:v1
-    std::mutex energy_mutex;
-    // subtree including children
-    types::energy::EnergyFlowRequest energy_flow_request;
+    // Energy state protected by monitor for thread-safe access
+    struct EnergyState {
+        // subtree including children
+        types::energy::EnergyFlowRequest energy_flow_request;
 
-    // contains only the pricing informations last update
-    types::energy_price_information::EnergyPriceSchedule energy_pricing;
+        // contains only the pricing informations last update
+        types::energy_price_information::EnergyPriceSchedule energy_pricing;
+    };
+
+    everest::lib::util::monitor<EnergyState> energy_state;
 
     types::energy::ScheduleReqEntry get_local_schedule_req_entry();
     std::vector<types::energy::ScheduleReqEntry> get_local_schedule();
 
-    void publish_complete_energy_object();
+    void publish_complete_energy_object(const EnergyState& state);
     void set_external_limits(types::energy::ExternalLimits& l);
     void merge_price_into_schedule(std::vector<types::energy::ScheduleReqEntry>& schedule,
                                    const std::vector<types::energy_price_information::PricePerkWh>& price);
-
     std::string source_cfg;
     // ev@3370e4dd-95f4-47a9-aaec-ea76f34a66c9:v1
 };
 
 // ev@3d7da0ad-02c2-493d-9920-0bbbd56b9876:v1
 // insert other definitions here
+// Standalone function for schedule processing (used by tests)
+void process_schedule_with_limits(std::vector<types::energy::ScheduleReqEntry>& schedule, const std::string& source,
+                                  double fuse_limit_A, int phase_count, double nominal_voltage_V,
+                                  bool enhance_with_current_limits);
 // ev@3d7da0ad-02c2-493d-9920-0bbbd56b9876:v1
 
 } // namespace energy_grid
diff --git a/modules/EnergyManagement/EnergyNode/energy_grid/energy_schedule_utils.cpp b/modules/EnergyManagement/EnergyNode/energy_grid/energy_schedule_utils.cpp
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Pionix GmbH and Contributors to EVerest
+
+#include "energy_schedule_utils.hpp"
+
+namespace module {
+namespace energy_grid {
+
+void process_schedule_with_limits(std::vector<types::energy::ScheduleReqEntry>& schedule, const std::string& source,
+                                  double fuse_limit_A, int phase_count, double nominal_voltage_V,
+                                  bool enhance_with_current_limits) {
+
+    for (auto& entry : schedule) {
+        // Enhance with current limits from power if enabled
+        if (enhance_with_current_limits) {
+            // Determine phase count to use (schedule entry takes priority over module config)
+            int effective_phase_count = phase_count;
+
+            if (entry.limits_to_root.ac_max_phase_count.has_value() &&
+                entry.limits_to_root.ac_max_phase_count.value().value > 0) {
+                effective_phase_count = entry.limits_to_root.ac_max_phase_count.value().value;
+            } else if (entry.limits_to_leaves.ac_max_phase_count.has_value() &&
+                       entry.limits_to_leaves.ac_max_phase_count.value().value > 0) {
+                effective_phase_count = entry.limits_to_leaves.ac_max_phase_count.value().value;
+            }
+
+            // Default to 1 phase if no valid phase count is available
+            if (effective_phase_count <= 0) {
+                effective_phase_count = 1;
+            }
+
+            // Calculate current from power for limits_to_root (only if not already set)
+            if (entry.limits_to_root.total_power_W.has_value() &&
+                entry.limits_to_root.total_power_W.value().value > 0 && nominal_voltage_V > 0 &&
+                !entry.limits_to_root.ac_max_current_A.has_value()) {
+
+                float calculated_current = static_cast<float>(entry.limits_to_root.total_power_W.value().value /
+                                                              (nominal_voltage_V * effective_phase_count));
+                entry.limits_to_root.ac_max_current_A = {calculated_current, source};
+            }
+
+            // Note: limits_to_leaves current limits are not modified to match fuse limit behavior
+        }
+
+        // Apply fuse limit to limits_to_root (as a safety constraint)
+        if (!entry.limits_to_root.ac_max_current_A.has_value() ||
+            entry.limits_to_root.ac_max_current_A->value > fuse_limit_A) {
+            entry.limits_to_root.ac_max_current_A = {static_cast<float>(fuse_limit_A), source};
+        }
+
+        // Apply phase count limit to limits_to_root (as a safety constraint, same model as fuse limit)
+        if (phase_count > 0 && (!entry.limits_to_root.ac_max_phase_count.has_value() ||
+                                entry.limits_to_root.ac_max_phase_count->value > phase_count)) {
+            entry.limits_to_root.ac_max_phase_count = {phase_count, source};
+        }
+    }
+}
+
+} // namespace energy_grid
+} // namespace module
diff --git a/modules/EnergyManagement/EnergyNode/energy_grid/energy_schedule_utils.hpp b/modules/EnergyManagement/EnergyNode/energy_grid/energy_schedule_utils.hpp
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Pionix GmbH and Contributors to EVerest
+
+#ifndef ENERGY_SCHEDULE_UTILS_HPP
+#define ENERGY_SCHEDULE_UTILS_HPP
+
+#include <generated/types/energy.hpp>
+#include <string>
+#include <vector>
+
+namespace module {
+namespace energy_grid {
+
+/**
+ * @brief Processes energy schedule entries with limits and fuse constraints
+ *
+ * This function applies fuse limits to schedule entries and optionally enhances
+ * them with current limits calculated from power values.
+ *
+ * @param schedule The schedule entries to process
+ * @param source The source identifier for any modifications made
+ * @param fuse_limit_A The fuse limit in amperes to apply as a safety constraint
+ * @param phase_count The default phase count to use for calculations
+ * @param nominal_voltage_V The nominal voltage to use for power-to-current calculations
+ * @param enhance_with_current_limits If true, calculates current limits from power values
+ */
+void process_schedule_with_limits(std::vector<types::energy::ScheduleReqEntry>& schedule, const std::string& source,
+                                  double fuse_limit_A, int phase_count, double nominal_voltage_V,
+                                  bool enhance_with_current_limits);
+
+} // namespace energy_grid
+} // namespace module
+
+#endif // ENERGY_SCHEDULE_UTILS_HPP
diff --git a/modules/EnergyManagement/EnergyNode/manifest.yaml b/modules/EnergyManagement/EnergyNode/manifest.yaml
@@ -12,6 +12,23 @@ config:
     type: integer
     minimum: 0
     maximum: 3
+  enhance_external_schedule:
+    description: >-
+      When enabled, calculates per-phase current limits from total_power_W
+      and adds them to ac_max_current_A when processing external schedules.
+      ac_max_current_A is only enhanced in case it was not specified as part of
+      the external schedules. Uses nominal_voltage_V for calculations.
+    type: boolean
+    default: false
+  nominal_voltage_V:
+    description: >-
+      Nominal voltage in volts used for power to current calculations when
+      enhance_external_schedule is enabled.
+      This allows configuration for different regions (e.g., 120V, 230V, 400V).
+    type: number
+    minimum: 1.0
+    maximum: 1000.0
+    default: 230.0
 provides:
   energy_grid:
     description: This is the chain interface to build the energy supply tree
diff --git a/modules/EnergyManagement/EnergyNode/tests/CMakeLists.txt b/modules/EnergyManagement/EnergyNode/tests/CMakeLists.txt
diff --git a/modules/EnergyManagement/EnergyNode/tests/energy_node_tests.cpp b/modules/EnergyManagement/EnergyNode/tests/energy_node_tests.cpp
