Skip to content

MQTT Integration Guide

This guide provides a comprehensive overview of integrating MQTT messaging into ABS Platform services.

Quick Start

  1. Review the topic conventions: Start with Topic Conventions to understand the messaging structure
  2. Use the quick reference: Keep Quick Reference handy for development
  3. Follow the patterns below for common integration scenarios

Integration Patterns

Service-to-Service Communication

Use the emit/echo pattern for reliable service communication:

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

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

IoT Device Integration

Handle device telemetry and commands:

// Subscribe to device data
await client.subscribe('dt/arm/+/+/+/+');

// Process device commands
const cmdTopic = 'cmd/arm/ssc/ph-mnl1/F7/STN001';
await client.publish(cmdTopic, JSON.stringify(command), { qos: 1 });

ABS Platform Patterns

Follow ABS-specific envelope structure:

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

Best Practices

  1. Always use topic builders - Never hand-craft topic strings
  2. Include proper correlation IDs - Essential for request-response patterns
  3. Set appropriate QoS levels - Use QoS 1 for important messages
  4. Add tracing properties - Include trace_id for distributed tracing
  5. Validate all messages - Use envelope validation functions

Common Pitfalls

  • ❌ Mixing IoT (dt/cmd) and service (emit/echo) patterns
  • ❌ Forgetting correlation IDs for request-response
  • ❌ Using QoS 0 for critical messages
  • ❌ Hard-coding topic strings instead of using builders

Additional Resources