MQTT V1

Use the MQTT Auto API broker to subscribe and stream live vehicle data updates over MQTT

This method is deprecated, please use MQTT V2

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.

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 for live vehicle data. To consume data from a simulator, connect to the sandbox broker URL on sandbox.mqtt.high-mobility.com:8883.

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

{
   "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.

{
   "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}
}

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.

Authentication

The authentication is done using Client Certificates. Visit application page at http://console.high-mobility.com, 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:

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

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.

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.

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.