Connection monitor

The quality of a connection can be monitored by making use of the connectionMonitor service. The methods provided by this service enable the retrieval of a connector's current status. This information can be used to diagnose issues caused by poor connections, or to confirm the stability of the connection before proceeding.

Retrieving ConnectorInformation messages

The connectionMonitor service offers two methods with which ConnectorInformation messages can be retrieved. The first method is getConnectorInformation, which returns a single ConnectorInformation message, representing the status of the connector at the time of the request. The second method, openConnectorInformationStream, opens an incoming stream which will return a ConnectorInformation message each second.

A ConnectorInformation message contains the following fields:

Field	Description
connected	A boolean indicating whether the connector has an active internet connection.
connected_since	The unix timestamp in milliseconds indicating when the connector last established a connection (e.g. 1721649049837).
latency	A measurement of the time in milliseconds it takes for data to travel to the connector and back.
healthy	A boolean indicating the likelihood of potential issues arising from a poor connection.

The healthy field serves as an estimate of a connection's quality, and might therefore not be a suitable indicator in all circumstances. The value of the healthy field is determined by evaluating the number of the last 10 latency values that exceed 500 ms, with recent measurements given greater weight. If less than 25% of these weighted measurements exceed 500 ms, the healthy field will be set to true.

If this estimate is insufficient for an application, a more suitable indicator can be calculated with the measurements provided by the ConnectorInformation messages.

Note

The latency field of a ConnectorInformation message is only updated when the value changes by more than 50 ms.

Python example

In the Python example below, ConnectorInformation messages are being received for 5 seconds. These messages are then used to determine the average latency and if the connection was healthy in the past 5 seconds.

Python

from openobd import *
import time


class ConnectionMonitorExample(OpenOBDFunction):

    def run(self):
        # Define how many ConnectorInformation messages should be saved at a time
        SAMPLE_SIZE = 5

        # Create a ConnectionMonitor object, which will keep receiving and storing ConnectorInformation messages
        connection_monitor = ConnectionMonitor(self.openobd_session, sample_size=SAMPLE_SIZE)

        # Wait for ConnectorInformation messages to arrive before retrieving them
        time.sleep(SAMPLE_SIZE)
        connector_info_list = connection_monitor.get_connector_info_list()

        # For each ConnectorInformation message that has been received, check its 'healthy' and 'latency' fields
        connection_healthy = True
        total_latency = 0
        for connector_info in connector_info_list:
            if not connector_info.healthy:
                connection_healthy = False
            total_latency += connector_info.latency

        # Print whether the connector had a healthy connection
        if connection_healthy:
            print(f"The connection was healthy for the last {SAMPLE_SIZE} seconds.")
        else:
            print(f"The connection was not always healthy in the last {SAMPLE_SIZE} seconds.")

        # Print the average latency
        average_latency = total_latency / len(connector_info_list)
        print(f"The connector had an average latency of {average_latency} ms.")

        # Stop receiving ConnectorInformation messages
        connection_monitor.stop_stream()

        # Close the session with a successful result
        self.result = ServiceResult(result=[Result.RESULT_SUCCESS])