YMS Integration Guide: MQTT API

Introduction

This guide outlines programming interfaces to interact with the Blip Rover platform which uses vision AI to provide live updates of move operations in the yard. The software tools enable partners, customers, and 3rd party management systems to send and receive yard events in real time. Blip's preferred method of broadcasting event information is a listener + subscriber model based on MQTT protocol. REST webhooks based integration is also available. The platform can injest inbound events from 3rd party systems in the same way.

The current data flow is basically as follows:

• Blip Rover Platform → MQTT → Your Mgmt System
  Events : Asset location in yard, Terminal tractor location at drop

• YMS → MQTT → Blip or YMS → Webhook → Blip
  Events : Ingate / outgate, Move queue (optional) 

Publishing Ingate & Outgate Events

1. MQTT Connection Details

Broker Host : rover-mq.blipai.com
Protocol : MQTT v3.1.1 or v5 (mqtts://)
Port : 8883 (TLS / SSL required)
QoS Level : 1 (Wait for PUBACK)

Publish Topic : blip-api/yms/<site-id>
Username : <blip provided username> (usually same as site-id)
Password : <blip provided password>

Note: Each site is assigned a unique topic and requires client authorization to publish. E.g. username 'txu-walgreens-longbeach' will publish to
blip-api/yms/txu-walgreens-longbeach

2. Message Payload (JSON)

{

 "ID": "43824762",

 "asset_num": "TCKU6448776",

 "type": "exit",

 "utc_dt": "2026-08-31 17:06:16"

}

• ID (string): Unique event/transaction identifier (used for 24-hour deduplication).

• asset_num (string): Container or chassis identifier (spaces are automatically stripped).

• type (string): "entry" or "exit".

• utc_dt (string): UTC timestamp formatted as YYYY-MM-DD HH:mm:ss.

3. Client Implementation Example (Python paho-mqtt)

# This is a publish-only example. 

# Refer to the script in the next section for a complete example
# that combines publishing and subscription into a single routine

import ssl

import json

import paho.mqtt.client as mqtt

BROKER = "rover-mq.blipai.com"

PORT = 8883

SITE_ID = "<your-site-id>"

USERNAME = "<your-username>"

PASSWORD = "<your-password>"

PUB_TOPIC = f"blip-api/yms/{SITE_ID}/pub"

client = mqtt.Client(client_id="<any chosen client id", protocol=mqtt.MQTTv311)

client.username_pw_set(USERNAME, PASSWORD)

client.tls_set(cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLS_CLIENT)

client.connect(BROKER, PORT, keepalive=60)

client.loop_start()

payload = {

   "ID": "43824762",

   "asset_num": "TCKU6448776",

   "type": "exit",

   "utc_dt": "2026-08-31 17:06:16"

}

# Publish with QoS 1 and wait for broker acknowledgment

info = client.publish(PUB_TOPIC, json.dumps(payload), qos=1)

info.wait_for_publish()

print("Gate event delivered successfully.")

client.loop_stop()

client.disconnect()

Subscribing To Asset Movement Events

1. MQTT connection details - refer to previous section

2. Message Payload (JSON)

Asset location

{

 "event_id": "43824762",

 "asset": {"type":"trailer", "id":"TCKU6448776,

 "location": {"spot":"B006", "lat":33.820359, "lon":-118.246694},

 "utc_dt": "2026-08-31 17:06:16"

}

• ID (string): Unique event/transaction identifier (used for 24-hour deduplication).

• asset_num (string): Container or chassis identifier (spaces are automatically stripped).

• location (string): a parking spot is defined

• utc_dt (string): UTC timestamp formatted as YYYY-MM-DD HH:mm:ss.

Terminal tractor location

{

 "event_id": "51453425",

 "asset": {"type":"tractor", "id":"541-004,

 "asset_type": "tractor",

 "location": {"spot":"N019", "lat":33.820359, "lon":-118.246694},

 "utc_dt": "2026-08-31 17:06:16"

}

3. Client Implementation Example (Python paho-mqtt)

# Complete pub+sub example

import ssl

import json

import paho.mqtt.client as mqtt

BROKER = "rover-mq.blipai.com"

PORT = 8883

SITE_ID = "<your-site-id>"

USERNAME = "<your-username>"

PASSWORD = "<your-password>"

PUB_TOPIC = f"blip-api/yms/{SITE_ID}/pub"

SUB_TOPIC = f"blip-api/yms/{SITE_ID}/sub"

# ---- Callbacks ----------------------------------------------------------

def on_connect(client, userdata, flags, rc):

    if rc == 0:

        print("Connected to broker.")

        # Subscribe as soon as we're connected (recommended for QoS 1)

        result, mid = client.subscribe(SUB_TOPIC, qos=1)

        if result == mqtt.MQTT_ERR_SUCCESS:

            print(f"Subscribe requested (mid={mid})")

        else:

            print(f"Subscribe failed: {result}")

    else:

        print(f"Connect failed with code {rc}")

def on_subscribe(client, userdata, mid, granted_qos):

    print(f"SUBACK received: mid={mid}, granted_qos={granted_qos}")

def on_message(client, userdata, msg):

    print(f"[{msg.topic}] QoS={msg.qos} payload={msg.payload.decode()}")

def on_publish(client, userdata, mid):

    print(f"PUBACK received: mid={mid}")

# ---- Client setup -------------------------------------------------------

client = mqtt.Client(client_id="<any chosen client id>", protocol=mqtt.MQTTv311)

client.username_pw_set(USERNAME, PASSWORD)

client.tls_set(cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLS_CLIENT)

client.on_connect   = on_connect

client.on_subscribe = on_subscribe

client.on_message   = on_message

client.on_publish   = on_publish

client.connect(BROKER, PORT, keepalive=60)

client.loop_start()          # background thread drives the network loop

# ---- Publish ------------------------------------------------------------

payload = {

    "ID": "43824762",

    "asset_num": "TCKU6448776",

    "type": "exit",

    "utc_dt": "2026-08-31 17:06:16",

}

info = client.publish(PUB_TOPIC, json.dumps(payload), qos=1)

info.wait_for_publish()      # blocks until PUBACK (QoS 1)

print("Gate event delivered successfully.")

# ---- Event loop that runs forever and keeps receiving messages ----------

import time

try:

    while True:

        time.sleep(1)

except KeyboardInterrupt:

    pass

client.loop_stop()

client.disconnect()