cariflex/tools/EVerest-main/lib/everest/ocpp/doc/networkconnectivity

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:

std::promise<ocpp::ConfigNetworkResult> promise();
std::future<ocpp::ConfigNetworkResult> future = promise.get_future();
return future;

If the network was setup successfully, you can set the values in the promise with

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 std::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).

External ConnectivityManager (optional)

The ConnectivityManager lives in the ocpp namespace and is not tied to a specific OCPP version. This design allows the websocket connection to be established before a protocol version is determined. During the websocket handshake the CSMS selects the OCPP protocol version (e.g. OCPP 1.6, OCPP2.0.1 or OCPP2.1). An integrating application can use this information to instantiate the appropriate version-specific ChargePoint and inject the already-connected ConnectivityManager into it.

By default, when no external ConnectivityManager is provided, libocpp creates and manages one internally. However, you can provide your own instance of ConnectivityManagerInterface (or the concrete ConnectivityManager) to take full control over websocket connectivity.

Note: External ConnectivityManager injection is currently only supported for ocpp::v2::ChargePoint. Support for ocpp::v16::ChargePoint is not yet implemented and will follow in a future release.

Typical flow with an external ConnectivityManager

1. Create a ConnectivityManager.
2. Create all version-specific ChargePoint instances (e.g. both ocpp::v16::ChargePoint and ocpp::v2::ChargePoint), passing the shared ConnectivityManager to each.
3. Register a websocket_connected_callback on the ConnectivityManager that inspects the negotiated OcppProtocolVersion and calls start() on the matching ChargePoint. start() automatically sets the message callback in the ConnectivityManager, so messages are routed to the correct version.
4. On subsequent reconnects (where start() was already called for that version), forward the event via on_websocket_connected() instead.
5. Because the CSMS may select a different protocol version on every websocket handshake, the integrating application must be prepared to switch between ChargePoint instances at any reconnect. When a version switch occurs, stop() should be called on the previously active ChargePoint and start() on the newly selected one.

Creating and injecting a ConnectivityManager

// 1. Create a version-independent ConnectivityManager
auto connectivity_manager = std::make_shared<ocpp::ConnectivityManager>(device_model, evse_security);

// 2. Create all ChargePoint instances, each receiving the shared ConnectivityManager
auto charge_point_v16 = std::make_unique<ocpp::v16::ChargePoint>(
    /* ... */, connectivity_manager, /* ... */);

auto charge_point_v2 = std::make_unique<ocpp::v2::ChargePoint>(
    evse_connector_structure, device_model, database_handler, evse_security,
    connectivity_manager, message_log_path, callbacks);

Wiring up websocket event callbacks

The websocket connected callback must handle both the initial start() call and subsequent reconnects. It also needs to handle potential version switches:

// Track which ChargePoint is currently active and started
ocpp::OcppProtocolVersion active_version = ocpp::OcppProtocolVersion::Unknown;

connectivity_manager->set_websocket_connected_callback(
    [&](int configuration_slot,
        const ocpp::v2::NetworkConnectionProfile& profile,
        const ocpp::OcppProtocolVersion version) {

        if (version != active_version) {
            // Version changed — stop the previously active ChargePoint (if any)
            if (active_version == ocpp::OcppProtocolVersion::v16) {
                charge_point_v16->stop();
            } else if (active_version != ocpp::OcppProtocolVersion::Unknown) {
                charge_point_v2->stop();
            }

            // Start the ChargePoint for the newly negotiated version.
            // start() sets the message callback in the ConnectivityManager
            // so that incoming messages are routed to the correct ChargePoint.
            if (version == ocpp::OcppProtocolVersion::v16) {
                charge_point_v16->start();
            } else {
                charge_point_v2->start();
            }
            active_version = version;
        } else {
            // Same version as before — just notify the active ChargePoint
            if (version == ocpp::OcppProtocolVersion::v16) {
                charge_point_v16->on_websocket_connected(configuration_slot, profile, version);
            } else {
                charge_point_v2->on_websocket_connected(configuration_slot, profile, version);
            }
        }
    });

connectivity_manager->set_websocket_disconnected_callback(
    [&](int configuration_slot,
        const ocpp::v2::NetworkConnectionProfile& profile,
        auto /*version*/) {
        if (active_version == ocpp::OcppProtocolVersion::v16) {
            charge_point_v16->on_websocket_disconnected(configuration_slot, profile);
        } else {
            charge_point_v2->on_websocket_disconnected(configuration_slot, profile);
        }
    });

connectivity_manager->set_websocket_connection_failed_callback(
    [&](ocpp::ConnectionFailedReason reason) {
        if (active_version == ocpp::OcppProtocolVersion::v16) {
            charge_point_v16->on_websocket_connection_failed(reason);
        } else {
            charge_point_v2->on_websocket_connection_failed(reason);
        }
    });

Optionally, if your system requires interface setup (e.g. modem activation), set the network configuration callback:

connectivity_manager->set_configure_network_connection_profile_callback(
    [](const int32_t configuration_slot,
       const ocpp::v2::NetworkConnectionProfile& profile) {
        std::promise<ocpp::ConfigNetworkResult> promise;
        // ... set up the network interface ...
        ocpp::ConfigNetworkResult result;
        result.success = true;
        result.interface_address = "eth0"; // optional: bind to specific interface or IP
        promise.set_value(result);
        return promise.get_future();
    });

Note: start() automatically calls set_message_callback on the ConnectivityManager, ensuring that incoming OCPP messages are routed to the correct ChargePoint instance. The set_logging method is called automatically by ChargePoint::initialize(). You do not need to call either of these yourself.

When to use an external ConnectivityManager

• When a single application needs to support multiple OCPP versions and switch between them at runtime based on the CSMS's protocol selection
• When the OCPP protocol version is not known ahead of time and should be determined by the websocket handshake before starting a version-specific ChargePoint
• When you want to implement a custom connectivity strategy (e.g. custom reconnection logic by implementing ConnectivityManagerInterface)

Version switching responsibility

When multi-version support is implemented (see note above), the application will be responsible for implementing the version-switching logic (i.e. deciding which ChargePoint to start()/stop() based on the negotiated protocol version). libocpp does not currently provide a built-in orchestrator for this, because the v16 and v2 ChargePoint implementations do not share a common interface and applications may need to manage additional version-specific state during a switch (e.g. active transactions, UI state). Such an orchestrator may be provided in the future.

Default (internal) behavior

If you do not provide a ConnectivityManager, libocpp creates one internally and automatically registers the websocket event callbacks. In this case, the on_websocket_connected, on_websocket_disconnected, and on_websocket_connection_failed methods on ChargePoint are called automatically and you do not need to call them. This is sufficient when the OCPP protocol version is known at compile time or configuration time.

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.

Internal ConnectivityManager (default)

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)

External ConnectivityManager

sequenceDiagram
participant csms
participant core
participant connectivity_manager as ConnectivityManager<br>(external)
participant cp_v16 as ChargePoint v16
participant cp_v2 as ChargePoint v2
autonumber

note over core: 1. Initialization — create all components upfront
core ->> connectivity_manager: create ConnectivityManager(device_model, evse_security)
core ->> cp_v16: create ChargePoint(..., connectivity_manager, ...)
core ->> cp_v2: create ChargePoint(..., connectivity_manager, ...)
core ->> connectivity_manager: set_websocket_connected_callback(version_dispatch)
core ->> connectivity_manager: set_websocket_disconnected_callback(version_dispatch)
core ->> connectivity_manager: set_websocket_connection_failed_callback(version_dispatch)

note over core: 2. First connection — version unknown
core ->> connectivity_manager: connect()
connectivity_manager ->> csms: websocket handshake (offering supported OCPP versions)
csms ->> connectivity_manager: ACK (selected OCPP version, e.g. v2)

note over core: 3. Connected callback triggers start() for negotiated version
connectivity_manager ->> core: websocket_connected_callback(slot, profile, v2)
core ->> core: active_version = Unknown → v2 (first time or version changed)
core ->> cp_v2: start()
note over cp_v2: start() sets message_callback<br>in ConnectivityManager

note over core: 4. Reconnect with same version
connectivity_manager ->> csms: websocket handshake
csms ->> connectivity_manager: ACK (v2 again)
connectivity_manager ->> core: websocket_connected_callback(slot, profile, v2)
core ->> core: active_version == v2, no change
core ->> cp_v2: on_websocket_connected(slot, profile, v2)

note over core: 5. Reconnect with different version (CSMS switches to v16)
connectivity_manager ->> csms: websocket handshake
csms ->> connectivity_manager: ACK (v16)
connectivity_manager ->> core: websocket_connected_callback(slot, profile, v16)
core ->> core: active_version v2 → v16 (version changed)
core ->> cp_v2: stop()
core ->> cp_v16: start()
note over cp_v16: start() sets message_callback<br>in ConnectivityManager

note over core: 6. Disconnection — forwarded to active ChargePoint
connectivity_manager ->> core: websocket_disconnected_callback(slot, profile)
core ->> cp_v16: on_websocket_disconnected(slot, profile)

note over core: 7. Network disconnected externally
core ->> cp_v16: on_network_disconnected(ocpp_interface)
cp_v16 ->> connectivity_manager: on_network_disconnected(ocpp_interface)