> For the complete documentation index, see [llms.txt](https://docs.high-mobility.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.high-mobility.com/changelog/readme/notes/migrate-from-mqtt-v1-to-mqtt-v2-enterprise.md).

# Migrate from MQTT V1 to MQTT V2 (Enterprise)

### Overview

High Mobility is introducing **MQTT V2 (Enterprise)**, a new streaming broker that will replace the original MQTT V1 broker. MQTT V2 offers **higher throughput**, improved batching, and uses newer MQTT protocol features. As part of this upgrade, some internal routing was refactored and the **message schema changed**.

This guide explains what changed and how to migrate a live application safely without data loss.

### Availability & compatibility

* **MQTT V2 is available in sandbox and production.** You can explore the new broker in sandbox first.
* MQTT V1 will continue to work during a transition period, but **customers should plan to migrate**.

### What changed?

#### 1. New broker endpoint

<table><thead><tr><th width="133.977294921875">Version</th><th width="362.93115234375">Broker host</th><th>Environments notes</th></tr></thead><tbody><tr><td>MQTT V1</td><td><p><code>mqtt.high-mobility.com:8883</code> (prod) </p><p><code>sandbox.mqtt.high-mobility.com:8883</code> (sandbox)</p></td><td>Separate hosts per env.</td></tr><tr><td>MQTT V2</td><td><code>mqtt-v2.high-mobility.com:8883</code></td><td>Same host for live &#x26; sandbox topics.</td></tr></tbody></table>

#### 2.  Topic structure simplified

<table><thead><tr><th width="134.03179931640625">Version</th><th>Topic format</th></tr></thead><tbody><tr><td>MQTT V1</td><td><code>{env}/{level}/{app_id}/{vin}/{capability}/{action}/{property}</code></td></tr><tr><td>MQTT V2</td><td><code>{env}/{level}/{application_uuid}</code></td></tr></tbody></table>

**Implication:**

* In V1 you subscribed to many subtopics (often using wildcards).
* In V2 you subscribe to **one topic per application**.
* In V2 you may use MQTT shared subscription to spread workload between multiple clients.

Example:

* V1 all-data subscription:  `live/level13/99AE714401B6CED29AF51490/#`
* V2 all-data subscription: `live/level13/1317b06f-8240-4677-8324-4e5a99d7a6a5`

#### 3. Message schema is now batched

In MQTT V1, each message represented one property update:

```json
{
  "message_id": "...",
  "version": 1,
  "vin": "...",
  "capability": "diagnostics",
  "property": "odometer",
  "data": { ...single property payload... }
}
```

In MQTT V2, **multiple data points are bundled into one message**. Each property is an array of 1..n items.

```json
{
  "version": 2,
  "application_id": "00000000-0000-0000-0000-000000000000",
  "message_id": "4F02FFB0...",
  "vin": "EXV10000000000",
  "data": {
    "diagnostics": {
      "odometer": [
        {
          "data": { "unit": "kilometers", "value": 19201.01 },
          "timestamp": "2025-08-12T16:07:48.000Z"
        },
        {
          "data": { "unit": "kilometers", "value": 19205.01 },
          "timestamp": "2025-08-12T16:10:18.000Z"
        }
      ]
    },
    "vehicle_location": {
      "coordinates": [
        {
          "data": { "latitude": 11.572, "longitude": 8.487 },
          "timestamp": "2025-08-12T16:07:48.000Z"
        }
      ]
    }
  }
}

```

{% hint style="info" %}
**Core principle:** batched forwarding in V2 reflects the OEM/car batch boundaries, instead of splitting into single-property messages like V1. This batching is best-effort, if a batch is too large for a single MQTT message, it may be divided across multiple messages.\
\
**Schema reference:** [Streaming Schema V2](/api-references/data/streaming-schema-v2.md)
{% endhint %}

#### 4. Authentication & certificates

Both versions use client certificates, but V2 needs a new Enterprise MQTT client certificate.

### Experiment with MQTTV2 in Sandbox instance

You may spend some time using MQTTV2 in a sandbox, it allows you to get familiars with the new broker, authentication and data payload.

### Live migration plan(recommended)

#### Step 0 — Prepare your consumer for batching

Before switching production traffic:

1. Update parsing logic to handle:
   * one message containing **multiple capabilities**
   * each property as an **array of entries**
2. Ensure deduplication by `message_id` (at-least-once delivery still applies).
3. If order matters, sort by each item’s `timestamp` (messages are not guaranteed chronological).&#x20;

#### Step 1 — Download a V2 client certificate (without switching yet)

In Console:

1. Go to **API Credentials → Streaming**.
2. Add/download a **MQTT V2 (Enterprise)** client certificate **without changing** the current streaming method.
3. Keep your existing V1 certificate active.

<figure><img src="/files/uaBOcKjGPB6ez5WWPTd4" alt=""><figcaption></figcaption></figure>

#### Step 2 — Deploy a second consumer pointing to MQTT V2

Using the new credentials:

* Connect to: `mqtt-v2.high-mobility.com:8883`
* Subscribe to: `live/level13/{application_uuid}`

{% hint style="info" %}
**Keep your V1 consumer running at the same time.**

While you migrate and during propagation, some vehicles may still stream via V1. Running both consumers prevents data gaps.
{% endhint %}

#### Step 3 — Switch streaming method in Console

* Back in **Streaming settings**, select **MQTT V2 (Enterprise)** as the streaming method.
* Click **Save and update**.

**Propagation delay:**\
It takes about **1 hour** for all vehicles to start using the new method. During this window, data may still arrive on V1.

#### Step 4 — Validate and turn off MQTT V1 client

After 1 hour:

1. Confirm you’re receiving data in V2.
2. Watch your V1 consumer:
   * If no new data arrives for a reasonable buffer period, it’s safe to shut it down.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.high-mobility.com/changelog/readme/notes/migrate-from-mqtt-v1-to-mqtt-v2-enterprise.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.