carconnectivity-plugin-mqtt 0.10.4

CarConnectivity plugin for publishing data to MQTT

CarConnectivity Plugin for MQTT

CarConnectivity will become the successor of WeConnect-python in 2025 with similar functionality but support for other brands beyond Volkswagen!

CarConnectivity is a python API to connect to various car services. If you want to publish the data collected from your vehicle in a standard protocol such as MQTT this plugin will help you. This Client enables you to integrate with the MQTT Broker of your choice (e.g. your home automation solution such as ioBroker, FHEM or Home Assistant)

How to install

Install using PIP

If you want to use CarConnectivity-mqtt, the easiest way is to obtain it from PyPI. Just install instead using:

pip3 install carconnectivity-plugin-mqtt

Connectors & Plugins

In order to connect vehciles from various brands, you need to install connector, e.g. with:

pip3 install carconnectivity-connector-volkswagen
pip3 install carconnectivity-connector-skoda
pip3 install carconnectivity-connector-seatcupra

Install using pipx (alternative)

pipx is a tool to help you install and run end-user applications written in Python. pipx creates an isolated environment for each application and its associated packages.

pipx install carconnectivity-plugin-mqtt

Important

When using pipx, connectors and plugins need to be explicitly installed in the carconnectivity-mqtt environment. Otherwise the connectors or plugins will not be found due to the isolation. You can do that with e.g.:

pipx inject carconnectivity-plugin-mqtt carconnectivity-connector-volkswagen

Create config file

Create a carconnectivity.json config file like this (Example if you have a Volkswagen and a MySkoda account). A documentation of all possible config options can be found here.

{
    "carConnectivity": {
        "log_level": "error", // set the global log level, you can set individual log levels in the connectors and plugins
        "connectors": [
            {
                "type": "skoda", // Definition for a MySkoda account
                "config": {
                    "interval": 600, // Interval in which the server is checked in seconds
                    "username": "[e-mail]", // Username of your MySkoda Account
                    "password": "testpassword123" // Password of your MySkoda Account
                }
            },
            {
                "type": "volkswagen", // Definition for a Volkswagen account
                "config": {
                    "interval": 300, // Interval in which the server is checked in seconds
                    "username": "[e-mail]", // Username of your Volkswagen Account
                    "password": "testpassword123" // Username of your Volkswagen Account
                }
            }
        ],
        "plugins": [
            {
                "type": "mqtt", // Definition for the MQTT Connection
                "config": {
                    "broker": "192.168.0.123", // Broker hostname or IP address
                    "username": "testuser", // Broker username to login
                    "password": "testuser" // Broker password to login
                }
            }
        ]
    }
}

Startup

When using docker-compose configure CarConnectivity-MQTT like that:

carconnectivity-mqtt carconnectivity.json

If you face challenges the WebUI can help you find the problems: CarConnectivity-plugin-webui. Install it with:

pip3 install carconnectivity-plugin-webui

and add a plugin of "type": "webui" to your configuration.

Updates

If you want to update, the easiest way is:

pip3 install carconnectivity-plugin-mqtt --upgrade
pip3 install carconnectivity-connector-volkswagen --upgrade
pip3 install carconnectivity-connector-skoda --upgrade
pip3 install carconnectivity-connector-seatcupra --upgrade

If you want to try pre-releases (e.g. alpha releases) you can do so by

pip3 install --pre carconnectivity-connector-volkswagen

or with an exact version like

pip3 install carconnectivity-connector-volkswagen==0.9.2a1

With Docker

There is also a Docker image to easily host CarConnectivity-MQTT: See on Dockerhub

Other

Home Assistant

The easiest way to work with home assistant is to use the prepackaged carconnectivity-addon.

Manual install with Home Assistant

To make Auto Discovery and further features available in Home Assistant also install CarConnectivity-plugin-mqtt_homeassistant

pip3 install carconnectivity-plugin-mqtt_homeassistant

and add it to your config:

            {
                "type": "mqtt", // Definition for the MQTT Connection
                "config": {
                    "broker": "192.168.0.123", // Broker hostname or IP address
                    "username": "testuser", // Broker username to login
                    "password": "testuser" // Broker password to login
                }
            },
            {
                "type": "mqtt_homeassistant", // Definition for the MQTT Home Assistant Compatibility
                "config": {}
            }

Times

By default the times coming from the car are UTC isoformat. You can convert times to your local timezone by adding convert-times to your config. Convert times will use the timezone specified in TZ variable. You can format times in your local format by adding timeformat to your config. This will use the default Date/Time format of your locale setting (LC_ALL variable). If you want to set a specific format add e.g. timeformat '%a %d %b %Y %T' to your config.

...
  carconnectivity-mqtt:
    image: "tillsteinbach/carconnectivity-mqtt:edge"
    environment:
      - TZ=Europe/Berlin
      - LANG=de_DE
      - LC_ALL=de_DE
...

Using Miles or Farenheit

CarConnectivity will guess your desired temperature or range/speed unit based on the systems locale. If it does not match what you want, you can set a different locale in your carconnectivity.json json config.

Credentials

If you do not want to provide your username or password inside the configuration you have to create a ".netrc" file at the appropriate location (usually this is your home folder):

# For MQTT broker
machine mymqttbroker
login [e-mail]
password testpassword123

In this case the configuration needs to look like this:

{
    "carConnectivity": {
        "connectors": [
            ...
        ]
        "plugins": [
            {
                "type": "mqtt",
                "config": {
                    "broker": "mymqttbroker"
                }
            }
        ]
    }
}

You can also provide the location of the netrc file in the configuration.

{
    "carConnectivity": {
        "connectors": [
            ...
        ]
        "plugins": [
            {
                "type": "mqtt",
                "config": {
                    "broker": "mymqttbroker"
                    "netrc": "/some/path/on/your/filesystem"
                }
            }
        ]
    }
}

Known Issues

Some MQTT Brokers cannot deal with large messages or have a standard limit configured that is too small to receive very large messages such as vehicle images. There are some solutions to this problem:

• Configure a larger maximum message size in the broker to fix the main problem
• If not possible to increase message size, check whether you can switch to MQTT v5. In this protocol version the broker can signal its maximum message size to the client
• If this is not possible you can also run CarConnectivity without support for images.