408 extend network connection profiles (#769)

* Extended the connection_state_changed_callback with the actual network connectivity slot info Added on_network_disconnected that will switch to the next network connection profile when invoked Extended the configure network connectivity profile callback with a cpp future / promise mechanism Added networkconnectivity documentation. These were originally added in PR 410 and have been updated to match the current implementation. Added on_try_switch_network_connection_profile function to try to switch to a higher priority network connection profile Signed-off-by: Wilco den Besten <[email protected]> * Fix after rebase on main: use cached values Signed-off-by: Wilco den Besten <[email protected]> * Fix incorrect comparsion Signed-off-by: Wilco den Besten <[email protected]> * Added new network profile functions to Chargepoint to retrieve the cached network profile information as that's helpful when using the newly added optional functions Signed-off-by: Wilco den Besten <[email protected]> * Fix missing break causing an indefinite wait for a std::future Signed-off-by: Wilco den Besten <[email protected]> * Add function description to newly added functions Signed-off-by: Wilco den Besten <[email protected]> * Processed review comments Signed-off-by: Wilco den Besten <[email protected]> * Remove std::optional from the split on_network_disconnected function Signed-off-by: Wilco den Besten <[email protected]> * Replace puml with inline mermaid Signed-off-by: Wilco den Besten <[email protected]> --------- Signed-off-by: Wilco den Besten <[email protected]>
EVerest · Oct 30, 2024 · 3c0d64c · 3c0d64c
1 parent 478e92d
commit 3c0d64c
Show file tree

Hide file tree

Showing 11 changed files with 536 additions and 71 deletions.
diff --git a/config/v201/component_config/standardized/InternalCtrlr.json b/config/v201/component_config/standardized/InternalCtrlr.json
@@ -752,6 +752,24 @@
           "description": "If enabled the transactions that were active before shutdown will be resumed, if possible",
           "default": false,
           "type": "boolean"
+      },
+      "NetworkConfigTimeout": {
+          "variable_name": "NetworkConfigTimeout",
+          "characteristics": {
+              "supportsMonitoring": true,
+              "dataType": "integer",
+              "minLimit": 1
+          },
+          "attributes": [
+              {
+                  "type": "Actual",
+                  "mutability": "ReadWrite"
+              }
+          ],
+          "description": "Timeout value in seconds to wait for a response from a network configuration request",
+          "minimum": 1,
+          "default": "60",
+          "type": "integer"
       }
   },
   "required": [

diff --git a/doc/networkconnectivity/README.md b/doc/networkconnectivity/README.md
@@ -0,0 +1,103 @@
+# Network connection profile interface
+
+libocpp automatically tries to connect using the given network connection profiles.
+However, if you want more control, you can use the callbacks provided for the network connection.
+
+libocpp will automatically connect to the network profile with the highest priority.
+If this fails, it will network profile with the second highest priority, and so on.
+
+## Set up interface (optional)
+
+A callback can be implemented to set up the interface. For example, if the interface is a modem, it must first be
+be activated before it is possible to connect to this interface. To do this, you can implement the callback
+`std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(configuration_slot, NetworkConnectionProfile))`
+
+In the implementation of this callback, you have to create a promise and return the future to the promise:
+```cpp
+std::promise<ocpp::v201::ConfigNetworkResult> promise();
+std::future<ocpp::v201::ConfigNetworkResult> future = promise.get_future();
+return future;
+```
+
+If the network was setup successfully, you can set the values in the promise with
+```cpp
+promise.set_value(configNetworkResult);
+```
+This way, libocpp knows that it can connect to the given interface and will try to do so.
+A timeout can be configured using `NetworkConfigTimeout' to wait longer or shorter than the default 60 seconds.
+
+### Bind to a specific interface
+
+In some cases there are multiple network interfaces available and you may want to connect to a specific one.
+In `ConfigNetworkResult` you can specify which interface you want the websocket to bind to.
+Sometimes an interface has more than one IP address (in the case of a local/auto link for example).
+In this case you want the websocket to bind to a specific IP address. The `interface_address` in ConfigNetworkResult supports both.
+It will bind to the given network interface (a string containing the name of the interface) or the given ip address (a string containing the ip address in human readable format).
+
+## Connect to higher network connection profile priority (optional)
+
+Normally, when libocpp is connected with a network connection profile, it will not disconnect.
+However, there may be a situation where libocpp is connected to a profile with priority 2 or lower, and you find out at system level that an interface (with a higher priority) has changed and is now up.
+A call is added so that you can suggest that libocpp switch to this profile: `bool on_try_switch_network_connection_profile(const int32_t configuration_slot)`.
+libocpp will inform the caller by the return value if it tries to switch to this profile.
+
+## Disconnected / connected callbacks
+
+libocpp provides two callbacks for when the websocket is connected and disconnected. It will provide the network slot
+in these callbacks, so you can keep the network connection in use (e.g. not disable the modem), or disable the network connection (example again: disable the modem).
+
+## Sequence diagram
+
+'core' can be read as any application that implements libocpp
+
+For step 9, ping is one way to check if a CSMS is up, but you of course can implement a way to check this yourself.
+
+```mermaid
+sequenceDiagram
+participant csms
+participant libocpp
+participant core
+autonumber
+
+note over csms,libocpp:  libocpp wants to connect to network connection profile
+
+libocpp ->>+ core: std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(<br>configuration_slot, NetworkConnectionProfile))
+note over core: ... possible delay ...
+core ->> core: Setup network, e.g. setup modem
+core ->>- libocpp: promise.set_value(status,<br>ip_address, etc)
+
+alt within timeout
+
+    %% core ->> libocpp: on_network_update (ip address)
+    libocpp ->> csms: connect websocket (ip address)
+    csms ->> libocpp: ACK
+    libocpp ->> core: websocket_connected_callback(configuration_slot, NetworkConnectionProfile)
+    core ->> core: disable unneeded interfaces, <br>e.g. disable modem
+else timeout reached, next network connection profile selected
+    libocpp -->> core: std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(<br>configuration_slot, NetworkConnectionProfile)) (see 1)
+end
+
+
+note over libocpp:  CSMS is connected via connection profile prio 2 (for example modem) but prio 1 (for example eth0) comes up
+
+loop until prio 1 csms is found
+    core ->> csms: ping
+end
+
+core ->> libocpp: on_try_switch_networkconnectionprofile(configuration_slot)
+libocpp -->> core: std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(<br>configuration_slot, NetworkConnectionProfile)) (see 1)
+
+
+note over csms,libocpp:  Network is disconnected (for example networkcable removed)
+
+core ->> libocpp: disconnect csms (on_network_disconnected(configuration_slot, OCPPInterfaceEnum)
+libocpp ->> core: websocket_disconnected_callback(configuration_slot, NetworkConnectionProfile)
+libocpp -->> core: std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(<br>configuration_slot, NetworkConnectionProfile)) (see 1)
+
+
+note over csms,libocpp:  Network is disconnected (websocket timeout)
+
+libocpp ->> libocpp: disconnect csms
+libocpp ->> core: websocket_disconnected_callback(configuration_slot, NetworkConnectionProfile)
+libocpp -->> core: std::future<ConfigNetworkResult>(configure_network_connection_profile_callback(<br>configuration_slot, NetworkConnectionProfile)) (see 1)
+```
diff --git a/include/ocpp/v201/charge_point.hpp b/include/ocpp/v201/charge_point.hpp
@@ -11,7 +11,6 @@
 
 #include <ocpp/v201/average_meter_values.hpp>
 #include <ocpp/v201/charge_point_callbacks.hpp>
-#include <ocpp/v201/connectivity_manager.hpp>
 #include <ocpp/v201/ctrlr_component_variables.hpp>
 #include <ocpp/v201/database_handler.hpp>
 #include <ocpp/v201/device_model.hpp>
@@ -109,6 +108,34 @@ class ChargePointInterface {
     /// \brief Disconnects the the websocket connection to the CSMS if it is connected
     virtual void disconnect_websocket() = 0;
 
+    ///
+    /// \brief Can be called when a network is disconnected, for example when an ethernet cable is removed.
+    ///
+    /// This is introduced because the websocket can take several minutes to timeout when a network interface becomes
+    /// unavailable, whereas the system can detect this sooner.
+    ///
+    /// \param configuration_slot   The slot of the network connection profile that is disconnected.
+    ///
+    virtual void on_network_disconnected(int32_t configuration_slot) = 0;
+
+    ///
+    /// \brief Can be called when a network is disconnected, for example when an ethernet cable is removed.
+    ///
+    /// This is introduced because the websocket can take several minutes to timeout when a network interface becomes
+    /// unavailable, whereas the system can detect this sooner.
+    ///
+    /// \param ocpp_interface       The interface that is disconnected.
+    ///
+    virtual void on_network_disconnected(OCPPInterfaceEnum ocpp_interface) = 0;
+
+    /// \brief Switch to a specific network connection profile given the configuration slot.
+    ///
+    /// Switch will only be done when the configuration slot has a higher priority.
+    ///
+    /// \param configuration_slot Slot in which the configuration is stored
+    /// \return true if the switch is possible.
+    virtual bool on_try_switch_network_connection_profile(const int32_t configuration_slot) = 0;
+
     /// \brief Chargepoint notifies about new firmware update status firmware_update_status. This function should be
     ///        called during a Firmware Update to indicate the current firmware_update_status.
     /// \param request_id   The request_id. When it is -1, it will not be included in the request.
@@ -316,6 +343,26 @@ class ChargePointInterface {
     /// \return vector of composite schedules, one for each evse_id including 0.
     virtual std::vector<CompositeSchedule> get_all_composite_schedules(const int32_t duration,
                                                                        const ChargingRateUnitEnum& unit) = 0;
+
+    /// \brief Gets the configured NetworkConnectionProfile based on the given \p configuration_slot . The
+    /// central system uri of the connection options will not contain ws:// or wss:// because this method removes it if
+    /// present. This returns the value from the cached network connection profiles. \param
+    /// network_configuration_priority \return
+    virtual std::optional<NetworkConnectionProfile>
+    get_network_connection_profile(const int32_t configuration_slot) = 0;
+
+    /// \brief Get the priority of the given configuration slot.
+    /// \param configuration_slot   The configuration slot to get the priority from.
+    /// \return The priority if the configuration slot exists.
+    ///
+    virtual std::optional<int> get_configuration_slot_priority(const int configuration_slot) = 0;
+
+    /// @brief Get the network connection priorities.
+    /// Each item in the vector contains the configured configuration slots, where the slot with index 0 has the highest
+    /// priority.
+    /// @return The network connection priorities
+    ///
+    virtual const std::vector<int>& get_network_connection_priorities() const = 0;
 };
 
 /// \brief Class implements OCPP2.0.1 Charging Station
@@ -413,8 +460,10 @@ class ChargePoint : public ChargePointInterface, private ocpp::ChargingStationBa
     void init_certificate_expiration_check_timers();
     void scheduled_check_client_certificate_expiration();
     void scheduled_check_v2g_certificate_expiration();
-    void websocket_connected_callback(const int security_profile);
-    void websocket_disconnected_callback();
+    void websocket_connected_callback(const int configuration_slot,
+                                      const NetworkConnectionProfile& network_connection_profile);
+    void websocket_disconnected_callback(const int configuration_slot,
+                                         const NetworkConnectionProfile& network_connection_profile);
     void websocket_connection_failed(ConnectionFailedReason reason);
     void update_dm_availability_state(const int32_t evse_id, const int32_t connector_id,
                                       const ConnectorStatusEnum status);
@@ -799,6 +848,12 @@ class ChargePoint : public ChargePointInterface, private ocpp::ChargingStationBa
     virtual void connect_websocket() override;
     virtual void disconnect_websocket() override;
 
+    void on_network_disconnected(int32_t configuration_slot) override;
+
+    void on_network_disconnected(OCPPInterfaceEnum ocpp_interface) override;
+
+    bool on_try_switch_network_connection_profile(const int32_t configuration_slot) override;
+
     void on_firmware_update_status_notification(int32_t request_id,
                                                 const FirmwareStatusEnum& firmware_update_status) override;
 
@@ -883,6 +938,12 @@ class ChargePoint : public ChargePointInterface, private ocpp::ChargingStationBa
     std::vector<CompositeSchedule> get_all_composite_schedules(const int32_t duration,
                                                                const ChargingRateUnitEnum& unit) override;
 
+    std::optional<NetworkConnectionProfile> get_network_connection_profile(const int32_t configuration_slot) override;
+
+    std::optional<int> get_configuration_slot_priority(const int configuration_slot) override;
+
+    const std::vector<int>& get_network_connection_priorities() const override;
+
     /// \brief Requests a value of a VariableAttribute specified by combination of \p component_id and \p variable_id
     /// from the device model
     /// \tparam T datatype of the value that is requested

diff --git a/include/ocpp/v201/charge_point_callbacks.hpp b/include/ocpp/v201/charge_point_callbacks.hpp
@@ -3,6 +3,7 @@
 #include <cstdint>
 #include <memory>
 
+#include <ocpp/v201/connectivity_manager.hpp>
 #include <ocpp/v201/device_model.hpp>
 
 #include <ocpp/v201/messages/BootNotification.hpp>
@@ -84,8 +85,7 @@ struct Callbacks {
     std::optional<std::function<SetNetworkProfileStatusEnum(
         const int32_t configuration_slot, const NetworkConnectionProfile& network_connection_profile)>>
         validate_network_profile_callback;
-    std::optional<std::function<bool(const NetworkConnectionProfile& network_connection_profile)>>
-        configure_network_connection_profile_callback;
+    std::optional<ConfigureNetworkConnectionProfileCallback> configure_network_connection_profile_callback;
     std::optional<std::function<void(const ocpp::DateTime& currentTime)>> time_sync_callback;
 
     /// \brief callback to be called to congfigure ocpp message logging
@@ -135,7 +135,9 @@ struct Callbacks {
         transaction_event_response_callback;
 
     /// \brief Callback function is called when the websocket connection status changes
-    std::optional<std::function<void(const bool is_connected)>> connection_state_changed_callback;
+    std::optional<std::function<void(const bool is_connected, const int configuration_slot,
+                                     const NetworkConnectionProfile& network_connection_profile)>>
+        connection_state_changed_callback;
 
     /// \brief Callback functions called for get / set / clear display messages
     std::optional<std::function<std::vector<DisplayMessage>(const GetDisplayMessagesRequest& request)>>