MQTT Topic Checklist - Quick Developer Reference¶

🚀 Quick Start¶

Choose Your Message Type¶

dt/ - IoT device data
cmd/ - IoT device commands
emit/ - Service events/requests
echo/ - Service responses/confirmations
call/ - RPC calls
meta/ - Schema/config (retained)

Build Topics Correctly¶

// ✅ CORRECT - Use topic builder
import { topicForCommand } from '../core/messaging';
const topic = topicForCommand({
  kind: 'emit',
  application: 'ABS', 
  context: 'BSS',
  recipientId: 'plan-123',
  command: 'SERVICE_REQUEST'
});

// ❌ WRONG - Don't hand-craft
const topic = 'emit/abs/service/plan-123/request';

📋 Pre-Flight Checklist¶

Before Publishing¶

[ ] Used topic builder, not hand-crafted topics
[ ] Included proper ABS envelope with plan_id, timestamp, correlation_id
[ ] Set appropriate QoS (1 for most service messages)
[ ] Added trace_id user property for tracing
[ ] Used correct message type (emit for requests, echo for responses)

Message Envelope¶

[ ] timestamp in ISO 8601 format
[ ] plan_id for service plan context
[ ] correlation_id for request-response tracking
[ ] actor identifies who sent the message
[ ] data contains the actual payload

MQTT Properties¶

[ ] QoS 1 for important messages
[ ] message-expiry-interval set (300s recommended)
[ ] correlation-data for RPC patterns
[ ] trace_id user property for distributed tracing

🎯 Common Patterns¶

IoT Device Communication¶

# Data from device
dt/arm/bms/ph-mnl1/F7/BAT001

# Command to device  
cmd/arm/ssc/ph-mnl1/F7/STN001

# Schema definition (retained)
meta/arm/bms/ph-mnl1/F7/BAT001

Service Communication¶

# Service request
emit/abs/service/plan/P123/access_request

# Service response
echo/abs/service/plan/P123/access_granted

# Payment processing
emit/odoo/payment/invoice/INV-456/process
echo/odoo/payment/invoice/INV-456/completed

ABS Platform Specific¶

# Customer interactions
emit/abs/customer/plan/{plan_id}/service_request
echo/abs/customer/plan/{plan_id}/service_granted

# Agent calculations
emit/abs/agent/{agent_type}/{plan_id}/calculation
echo/abs/agent/{agent_type}/{plan_id}/result

# FSM events
emit/abs/fsm/{cycle}/{plan_id}/transition

🔧 Code Templates¶

Basic Service Request¶

const envelope = {
  timestamp: new Date().toISOString(),
  plan_id: 'plan-123',
  correlation_id: generateUUID(),
  actor: { type: 'customer', id: 'cust-456' },
  data: { /* your data */ }
};

const topic = topicForCommand({
  kind: 'emit',
  application: 'ABS',
  context: 'service',
  recipientId: 'plan-123',
  command: 'ACCESS_REQUEST'
});

await client.publish(topic, JSON.stringify(envelope), { qos: 1 });

Request-Response Pattern¶

// Request
const correlationId = generateUUID();
await client.publish(emitTopic, payload, {
  qos: 1,
  properties: {
    responseTopic: echoTopic,
    correlationData: Buffer.from(correlationId),
    userProperties: { trace_id: correlationId }
  }
});

// Response
await client.publish(echoTopic, responsePayload, {
  qos: 1,
  properties: {
    correlationData: Buffer.from(correlationId)
  }
});

Load Balanced Processing¶

// Subscribe for load balancing
await client.subscribe('$share/workers/emit/abs/+/+/+/+');

// Handle messages
client.on('message', async (topic, payload) => {
  const envelope = JSON.parse(payload.toString());
  // Process message

  // Send echo response
  const echoTopic = topic.replace('emit/', 'echo/');
  await client.publish(echoTopic, JSON.stringify({
    ...envelope,
    data: { status: 'processed' }
  }));
});

⚠️ Common Mistakes¶

DON'T¶

❌ Hand-craft topic strings
❌ Use QoS 0 for critical messages
❌ Forget correlation IDs for request-response
❌ Mix IoT (dt/cmd) and service (emit/echo) patterns
❌ Skip message validation
❌ Hardcode domain/service names

DO¶

✅ Use the topic builder functions
✅ Include proper ABS envelope
✅ Set appropriate QoS levels
✅ Add tracing properties
✅ Validate all incoming messages
✅ Use constants for domain/service names

📊 QoS Guidelines¶

Message Type	QoS	Retain
IoT telemetry	1	No
IoT commands	1-2	No
Service events	1	No
Service responses	1	No
Schema/config	1	Yes

🔍 Debugging¶

Check Topic Format¶

# Correct formats
dt/arm/bms/ph-mnl1/F7/DEV42        ✅
emit/abs/service/plan/P123/request ✅  
echo/abs/service/plan/P123/granted ✅

# Wrong formats  
data/arm/bms/device42              ❌
gatt/abs/plan/request              ❌ (legacy)
abs/service/request                ❌ (missing parts)

Validate Messages¶

import { validateEnvelope } from '../core/messaging';

const validation = validateEnvelope(message);
if (!validation.valid) {
  console.error('Invalid message:', validation.errors);
  return;
}

Trace Messages¶

# Subscribe to trace specific messages
mosquitto_sub -h broker -t '+/+/+/+/+' -F '%t: %p' | grep 'trace-abc-123'

Need more details? See the full MQTT Topic Conventions Guide