Getting started with MQTT
The MQTT Auto API broker enables you to subscribe to vehicle data updates and get them pushed to your application using the MQTT protocol. This tutorial will help you get started step by step.
Beta
The MQTT broker is currently in beta. Have a look at the Beta section to see what is supported today.
Introduction to MQTT
MQTT is an asynchronous message protocol built on the publish/subscribe pattern. On the server side, there is a data broker that delivers messages to connected clients that have subscribed to receive updates. At its core, it enables you to:
- Move from poll-based to push-based API usage.
- Subscribe to any data updates for vehicles that you have access to through a single TCP/TLS connection.
- Work with a well-established standard, MQTT, with excellent tools for all platforms and operating systems.
- Continue to work with data payloads based on the Auto API JSON schema.
- Provide advanced use-cases that rely on events and car data updates being streamed second-by-second.
Endpoint URL
The MQTT broker URL is
mqtt.high-mobility.com:8883
Beta
As the MQTT broker for Auto API is currently in beta, there are a few things to note before starting to use it.
- No support yet for the car simulator. Only data for live cars are published.
- The following brands are supported at the moment: Peugeot, Citroën, DS Automobiles, Opel, Vauxhall, Fiat, Alfa Romeo and Jeep.
- Support for further brands that are supported in production mode is coming.
Topic and message structure
All messages that are published are divided into different topics. By looking at the topic structure you can determine the type of data that is being sent and for which vehicle.
topic:
/{environment}/{auto_api_level}/{app_id}/
{vin}/{capability}/{action}/{property}
breakdown:
environment:
- live # live vehicle data
- sandbox # simulator vehicle data
auto_api_level: level13 # latest version of the Auto API
app_id: Your unique App ID e.g. 9FBBEDED80595912588FF4FF
vin: Vehicle Identification Number
capability: Auto API capability
action:
- get # data published by the vehicle
- set # currently not supported
property: Auto API property
Here is the JSON format that is used for every message that is published. All data
objects, that hold the specific car data payload, are formatted according to the Auto API JSON schema.
{
"message_id": {Unique Message ID: string},
"version": 1,
"vin": {Vehicle Identification Number: string},
"capability": {Auto API Capability: string},
"property": {Auto API Property: string},
"data": {Auto API Schema: object}
}
Here's an example of the JSON that would be sent for the odometer data:
Topic: /live/level13/1FBBEDED80595912588FF4FF/VFXXXXXXXXXXXXXXX/diagnostics/get/odometer
{
"message_id": "B10BB67D6B4D2EBAB49FD3F81D41111C2AC0D6E0816DE47F87DCDD1388F3D911",
"version":1,
"vin": "VFXXXXXXXXXXXXXXX",
"capability": "diagnostics",
"property": "odometer",
"data": {
"diagnostics": {
"odometer": {
"data": {
"unit": "kilometers",
"value": 100
},
"timestamp": "2021-11-01T10:33:10.000Z"
}
}
}
}
Create a Cloud App
In the Production tab you will find your apps for retrieving data from our live environment. In the app details page you are going to set the permissions it requires and manage its credentials. Let's see how to create a new app.
Heads up
Currently it's not possible to use MQTT with an app in the Develop section, which are connected to the car simulators.
- Go to the Production tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
- Select the permissions that your app needs by clicking the "Select Permissions" button. Select the data points that you want to consume and hit "Save".
- Fill in all app information and click "Submit for review". Once done we will enable your application for live data access as soon as we have performed our app verification procedures. You will get notified as soon as it's done and it usually takes less than 48h.
Get Client Certificate
The first thing your app code needs to do is to provide credentials to the server. This is done through X.509 formatted client certificates which you can generate in your application detail view.
- Select the app you created in the previous steps.
- Choose "MQTT certificates" in the left menu section.
- Generate a new client certificate, which creates a new certificate with a unique client ID.
- You will receive the following files:
4.1 Certificate Authority root certificate
4.2 Client Certificate certificate
4.3 Client Certificate private key
Helper image to find the certificates from the production cloud app menu:
Connect
Once you have your authentication credentials you can go ahead and connect to the MQTT broker on mqtt.high-mobility.com:8883
. You can use any preferred MQTT client software or library to do this, just make sure to pass in the root certificate, client certificate and private key before connecting.
The following parameters are needed for the connection:
clientId | The Certificate ID that is listed in MQTT Certificates page. The Certificate ID is also included in the downloaded certificate file name. Example: "75374841-d7a5-4db7-b9b5-8a5f60eed79d" |
cleanSession | Set to false if you wish to receive missed messages since the last connection |
QoS | Set to 1 in order to guarantee that a message is delivered at least once |
CONNECTIONS
Each client certificate can be used for one active connection. If multiple active clients are needed, it's possible to get several client certificates issued for a single App ID.
The following example shows how the terminal tool mosquitto_sub
is used to both connect and subscribe to all messages:
mosquitto_sub --disable-clean-session
--cafile root.pem
--cert certificate.pem.crt
--key private.pem.key
-h mqtt.high-mobility.com
-p 8883
-q 1
-t 'live/level13/1FBBEDED80595912588FF4FF/#'
-i '75374841-d7a5-4db7-b9b5-8a5f60eed79d'
Subscribe
Once you have connected, go ahead and subscribe to any topic path that matches your App ID. Here are a few common use-cases:
- To subscribe to all data updates, pass in
live/level13/{app_id}/#
. The hashtag in the end is a wildcard for all topics underneath that path. - To subscribe to only specific properties for all cars, pass in the plus sign as a wildcard to match any VIN. Here's an example of only subscribing to odometer data:
live/level13/{app_id}/+/diagnostics/get/odometer
In MQTT, #
is used as a wildcard sign when it's at the end of the topic. When the wildcard is in the middle of the topic path, +
should be used.
HEADS UP
It's only possible to subscribe to one topic.
Please note that the the data is not guaranteed to be delivered in a chronological order. The timestamp of each MQTT message payload will always tell you at what time the data was generated in the vehicle.
You will now get vehicle data delivered to you for all vehicles that have approved access grants. To receive an access grant, have a look at the OAuth2 Consent Flow or the Fleet Clearance guide depending on your specific application.