Migrate from MQTT V1 to MQTT V2 (Enterprise)

A migration guide for High Mobility’s new MQTT V2 Enterprise broker, outlining endpoint/topic/schema/auth changes and a safe parallel-run rollout to switch from MQTT V1 without data loss.

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

Version	Broker host	Environments notes
MQTT V1	mqtt.high-mobility.com:8883 (prod) sandbox.mqtt.high-mobility.com:8883 (sandbox)	Separate hosts per env.
MQTT V2	mqtt-v2.high-mobility.com:8883	Same host for live & sandbox topics.

2. Topic structure simplified

Version	Topic format
MQTT V1	{env}/{level}/{app_id}/{vin}/{capability}/{action}/{property}
MQTT V2	{env}/{level}/{application_uuid}

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:

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

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

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

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).

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.

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}

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.

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.