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.

AWS S3 Streaming

Apart from MQTT, we also offer data streaming directly into your AWS S3 buckets. Have a look at the AWS S3 Guide for further details.

Table of Contents

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.

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. A detailed breakdown of each property is found in our API References.

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

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 "Live data" 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.

  1. Go to the Production tab, click the big plus (+) button, select "Fleet" or "Driver" as the type and then select Cloud App.
  2. 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".
  3. 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.

You can also perform this steps "Develop mode" if you intend to connect to sandbox data. Sandbox apps require no review.

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.

  1. Select the app you created in the previous steps.
  2. Choose "MQTT certificates" in the left menu section.
  3. Generate a new client certificate, which creates a new certificate with a unique client ID.
  4. You will receive the following files:
    4.1 Certificate Authority root certificate
    4.2 Client Certificate certificate
    4.3 Client Certificate private key

1 year expiry

The certificates are valid for 12 months. Make sure to generate a new certificate in time and to update your client configuration.

Helper image to find the certificates from the production cloud app menu:

MQTT Certificates

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:

clientIdThe 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"
cleanSessionSet to false if you wish to receive missed messages since the last connection
QoSSet 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. 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.

Shared Subscriptions

If you are consuming data from many vehicles, one single subscription might not be enough to keep your MQTT queue from getting overloaded. For this reason, we always recommend you to implement the shared subscription feature of MQTT.

Shared subscriptions enable multiple MQTT clients to share a single subscription on the broker side and consume all messages. Each MQTT library has its own interface to use this feature and we recommend you to look into your specific documentation.