diff --git a/doc/networkconnectivity/README.md b/doc/networkconnectivity/README.md index 5f73d5ddc..45e9fb5c1 100644 --- a/doc/networkconnectivity/README.md +++ b/doc/networkconnectivity/README.md @@ -1,14 +1,14 @@ # Network connection profile interface -libocpp automatically tries to connect using the given network connection profiles. +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. +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 +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(configure_network_connection_profile_callback(configuration_slot, NetworkConnectionProfile))` @@ -19,24 +19,24 @@ std::future future = promise.get_future(); return future; ``` -If the network was setup successfully, you can set the values in the promise with +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. +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. +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. +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. @@ -52,4 +52,52 @@ in these callbacks, so you can keep the network connection in use (e.g. not disa 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. -![Sequence diagram](networkconnectivity_libocpp.png) \ No newline at end of file +```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(configure_network_connection_profile_callback(
configuration_slot, NetworkConnectionProfile)) +note over core: ... possible delay ... +core ->> core: Setup network, e.g. setup modem +core ->>- libocpp: promise.set_value(status,
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,
e.g. disable modem +else timeout reached, next network connection profile selected + libocpp -->> core: std::future(configure_network_connection_profile_callback(
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(configure_network_connection_profile_callback(
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(configure_network_connection_profile_callback(
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(configure_network_connection_profile_callback(
configuration_slot, NetworkConnectionProfile)) (see 1) +``` diff --git a/doc/networkconnectivity/networkconnectivity_libocpp.png b/doc/networkconnectivity/networkconnectivity_libocpp.png deleted file mode 100644 index 9bf773ddb..000000000 Binary files a/doc/networkconnectivity/networkconnectivity_libocpp.png and /dev/null differ diff --git a/doc/networkconnectivity/networkconnectivity_libocpp.puml b/doc/networkconnectivity/networkconnectivity_libocpp.puml deleted file mode 100644 index c5dc81778..000000000 --- a/doc/networkconnectivity/networkconnectivity_libocpp.puml +++ /dev/null @@ -1,54 +0,0 @@ -@startuml -'https://plantuml.com/sequence-diagram -!pragma teoz true -participant csms -autonumber "" -skinparam sequenceArrowThickness 2 - -== libocpp wants to connect to network connection profile == - -{start} libocpp -> core: std::future(configure_network_connection_profile_callback(\nconfiguration_slot, NetworkConnectionProfile)) -activate core #DarkSalmon -core -> core: Setup network, e.g. setup modem -{end} core -> libocpp: promise.set_value(status,\nip_address, etc) - -deactivate core -{start} <-> {end}: ... possible delay ... - -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, \ne.g. disable modem -else timeout reached, next network connection profile selected - libocpp --> core: std::future(configure_network_connection_profile_callback(\nconfiguration_slot, NetworkConnectionProfile)) (see 1) -end - - -== 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(configure_network_connection_profile_callback(\nconfiguration_slot, NetworkConnectionProfile)) (see 1) - - -== 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(configure_network_connection_profile_callback(\nconfiguration_slot, NetworkConnectionProfile)) (see 1) - - -== Network is disconnected (websocket timeout) == - -libocpp -> libocpp: disconnect csms -libocpp -> core: websocket_disconnected_callback(configuration_slot, NetworkConnectionProfile) -libocpp --> core: std::future(configure_network_connection_profile_callback(\nconfiguration_slot, NetworkConnectionProfile)) (see 1) - - -@enduml \ No newline at end of file