# MQTT V1 {% hint style="danger" %} This method is deprecated, please use [mqtt-v2](https://docs.high-mobility.com/docs/vehicle-data/mqtt-v2 "mention") {% endhint %} The MQTT Auto API broker enables you to subscribe to vehicle data updates and get them pushed to your application using the [MQTT protocol](https://mqtt.org/). This tutorial will help you get started step by step. ### Introduction to MQTT [MQTT](https://mqtt.org/) 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. {% hint style="info" %} **ENDPOINT URL** The MQTT broker URL is `mqtt.high-mobility.com:8883` for live vehicle data. To consume data from a simulator, connect to the sandbox broker URL on `sandbox.mqtt.high-mobility.com:8883`. {% endhint %} ### 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. Here's an example of the JSON that would be sent for the odometer data: Topic: `live/level13/1FBBEDED80595912588FF4FF/VFXXXXXXXXXXXXXXX/diagnostics/get/odometer` ```json { "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" } } } } ``` #### Topic breakdwon ``` 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 ``` #### Message 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](https://github.com/highmobility/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} } ``` {% hint style="info" %} Our system is designed to guarantee at-least-once delivery of each message. Please consider the possibility that a `message_id` is delivered more than once. {% endhint %} ### Authentication The authentication is done using Client Certificates. Visit application page at , go to Streaming section and enable and download MQTT Certificate. ### 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 example shows how the terminal tool `mosquitto_sub` is used to both connect and subscribe to all messages: ```bash 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' ``` 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 {% hint style="info" %} 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. {% endhint %} ### 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. Replace `live` with `sandbox` if you are working with the simulator. * 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. {% hint style="info" %} **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. {% endhint %} 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](https://docs.high-mobility.com/docs/oauth-2.0) or the [Fleet Clearance](https://docs.high-mobility.com/docs/getting-started/fleet-clearance) guide depending on your specific application.