CarConnectivity Python API

The geofences section allows you to predefine geofences used for location-based services. Each geofence entry requires a name, latitude, longitude, and radius (in meters).

You can optionally provide:

• location: Detailed address information including display_name, house_number, road, neighbourhood, city, postcode, state, and country.
• charging_station: Data about a charging station at that location, including name, operator_id, operator_name, address, max_power (in kW), and num_spots.

"geofences": [
    {
        "name": "Home",
        "latitude": 53.625193,
        "longitude": 10.100695,
        "radius": 40,
        "location": {
            "display_name": "Home",
            "city": "Berlin",
            "country": "Deutschland"
        },
        "charging_station": {
            "name": "Home Wallbox",
            "operator_id": "myhome",
            "max_power": 11.0
        }
    }
]

The initialization section allows you to predefine data that is not supplied by connectors. This can improve user experience by ensuring additional data is available immediately. If a connector later provides this same data, the connector's data will override the predefined values.

You can define data per VIN (Vehicle Identification Number) within the garage object. Supported data includes:

• range_wltp: Can be provided as an object with val and uni (e.g., {"val": 550, "uni": "km"}) or as a raw number (assumed to be in km).
• battery: Includes total_capacity and available_capacity (in kWh).
• fuel_tank: Includes available_capacity (for hybrid/combustion vehicles).
• drives: Supports primary and secondary drive definitions.

"initialization": {
    "garage": {
        "TMBLJ9NY8SF008152": {
            "drives": {
                "primary": {
                    "range_wltp": {"val": 550, "uni": "km"},
                    "battery": {
                        "total_capacity": 82.0,
                        "available_capacity": 77.0
                    }
                }
            }
        }
    }
}

CarConnectivity is configured via a .json file. The structure requires a top-level carConnectivity object containing a log_level, a list of connectors, and a list of plugins.

Each item in the connectors and plugins arrays must include:

• type: A string identifying the specific connector or plugin.
• config: An object containing the configuration parameters specific to that type.

Note that while you can set a global log_level in the carConnectivity section, individual connectors and plugins can override this with their own specific log levels.

{
    "carConnectivity": {
        "log_level": "error",
        "connectors": [
            {
                "type": "skoda",
                "config": {
                    "interval": 600,
                    "username": "test@test.de",
                    "password": "testpassword123"
                }
            }
        ],
        "plugins": [
            {
                "type": "database",
                "config": {
                    "db_url": "sqlite:///carconnectivity.db"
                }
            }
        ]
    }
}

To add new location-based capabilities to the car connectivity ecosystem, you must extend the LocationService abstract base class. A concrete implementation of LocationService is required to provide actual logic for resolving coordinates, finding gas stations, and finding charging stations.

When implementing a subclass, you must provide implementations for the following methods, otherwise they will raise NotImplementedError:

• get_types(): Returns a list of (ServiceType, int) tuples representing the supported connector types and their associated priorities.
• location_from_lat_lon(latitude, longitude, location): Converts raw latitude and longitude into a Location object.
• gas_station_from_lat_lon(latitude, longitude, radius, location): Searches for the nearest gas station within a specified radius (in meters).
• charging_station_from_lat_lon(latitude, longitude, radius, charging_station): Searches for the nearest charging station within a specified radius (in meters).

To use specific car brand connectors, you must define them in a carconnectivity.json configuration file. Each connector is defined within the carConnectivity.connectors array. You specify the type (matching the connector name) and a config object containing the credentials or settings required by that specific connector.

Note: Detailed configuration options (like username or password) vary by connector; refer to the specific connector's README for its required schema.

{
    "carConnectivity": {
        "connectors": [
            {
                "type": "volkswagen",
                "config": {
                    "username": "test@test.de",
                    "password": "testpassword123"
                }
            },
            {
                "type": "skoda",
                "config": {
                    "username": "test@test.de",
                    "password": "testpassword123"
                }
            }
        ]
    }
}

The Observable class implements a publish-subscribe pattern used to react to changes in vehicle data. Objects inheriting from or using Observable can maintain a list of observers that are notified when specific ObserverEvent flags are triggered.

Key Concepts:

• Observers: Callables that accept two arguments: element (the Observable instance) and flags (the ObserverEvent that triggered the notification).
• Events (ObserverEvent): A bitwise flag indicating what happened (e.g., a value changed, or an object was enabled/disabled).
• Priority (ObserverPriority): Observers can be registered with different priority levels. When notifying, observers are triggered in order of their priority.
• Transactions: You can register observers to be notified only at the end of a transaction using the on_transaction_end parameter. Use transaction_end() to trigger these notifications.
• Delayed Notifications: If delay_notifications is set to True, calls to notify() will buffer the flags instead of immediately calling observers. Setting delay_notifications = False will trigger all buffered notifications.

from carconnectivity.observable import Observable, ObserverEvent, ObserverPriority

class MyData(Observable):
    def update_value(self, new_val):
        # ... logic to update value ...
        self.notify(ObserverEvent.VALUE_CHANGED)

# Usage
data = MyData()

def my_callback(element, flags):
    print(f"Event received: {flags}")

data.add_observer(my_callback, ObserverEvent.VALUE_CHANGED, priority=ObserverPriority.USER_HIGH)
data.update_value(10)