mqtt-development

mindrally

•

6155 months ago

Source Raw

Best practices and guidelines for MQTT messaging in IoT and real-time communication systems

Quick Install

npxskills add mindrally/skills--skill mqtt-development

Instructions

MQTT Development

You are an expert in MQTT (Message Queuing Telemetry Transport) protocol development for IoT and real-time messaging systems. Follow these best practices when building MQTT-based applications.

Core Principles

MQTT is designed as an extremely lightweight publish/subscribe messaging transport
Ideal for connecting remote devices with small code footprint and minimal network bandwidth
MQTT requires up to 80% less network bandwidth than HTTP for transmitting the same amount of data
A minimal MQTT control message can be as little as two data bytes

Architecture Overview

Components

Message Broker: Server that receives messages from publishing clients and routes them to destination clients
Clients: Any device (microcontroller to server) running an MQTT library connected to a broker
Topics: Hierarchical strings used to filter and route messages
Subscriptions: Client registrations for specific topic patterns

Topic Design Best Practices

Topic Structure

Use hierarchical topic structures with forward slashes as level separators
Maximum of seven forward slashes (/) in topic names for AWS IoT Core compatibility
Do NOT prefix topics with a forward slash - it counts towards topic levels and creates confusion
Use meaningful, descriptive topic segments

Topic Naming Conventions

{organization}/{location}/{device-type}/{device-id}/{data-type}

Example: acme/building-1/sensor/temp-001/temperature

Wildcard Usage

Single-level wildcard (+): Matches one topic level - prefer for device subscriptions
Multi-level wildcard (#): Matches all remaining levels - use sparingly
Never allow a device to subscribe to all topics using #
Reserve multi-level wildcards for server-side rules engines
Use single-level wildcards (+) for device subscriptions to prevent unintended consequences

Quality of Service (QoS) Levels

QoS 0 - At Most Once

Fire and forget - no acknowledgment
Fastest but least reliable
Use for: Sensor data where occasional loss is acceptable, high-frequency telemetry

QoS 1 - At Least Once

Guaranteed delivery, may have duplicates
Balance of reliability and performance
Use for: Important notifications, commands that can be safely repeated

QoS 2 - Exactly Once

Guaranteed single delivery using four-way handshake
Highest overhead but most reliable
Use for: Financial transactions, critical commands, state changes

Choosing QoS

Match QoS to your reliability requirements
Consider bandwidth constraints - higher QoS means more overhead
Publisher and subscriber QoS are independent - broker delivers at lower of the two

Session Management

Clean Sessions

cleanSession=true: No session state preserved, suitable for transient clients
cleanSession=false: Broker stores subscriptions and queued messages for offline clients

Persistent Sessions

Enable for devices with intermittent connectivity
Broker stores undelivered messages (based on QoS) for later delivery
Set appropriate session expiry intervals
Consider message queue limits on the broker

Keep-Alive

Configure keep-alive interval based on network conditions
Broker uses keep-alive to detect dead connections
Shorter intervals = faster detection, more overhead
Typical values: 30-60 seconds for stable networks, 10-15 for mobile

Last Will and Testament (LWT)

Configure LWT message for each client
Broker publishes LWT when client disconnects unexpectedly
Use for: Device status updates, alerts, cleanup triggers
LWT topic typically: {base-topic}/status with payload offline

Security Best Practices

Transport Security

MQTT sends credentials in plain text by default
Always use TLS to encrypt connections in production
Default unencrypted port: 1883
Encrypted port: 8883
Verify broker certificates to prevent MITM attacks

Authentication

Use strong client credentials (username/password or certificates)
Implement OAuth, TLS 1.3, or customer-managed certificates where supported
Rotate credentials regularly
Consider client certificate authentication for high-security scenarios

Authorization

Implement topic-level access control
Clients should only access topics they need
Use ACLs (Access Control Lists) on the broker
Separate read and write permissions per topic

Message Design

Payload Format

Use efficient serialization (JSON for readability, binary for efficiency)
Keep payloads small - MQTT is designed for constrained environments
Include timestamps in messages for time-series data
Consider schema versioning for payload format changes

Message Properties

Use retained messages for current state (last known value)
Set appropriate message expiry for time-sensitive data
Use user properties for metadata without polluting payload

Client Implementation

Connection Handling

Implement automatic reconnection with exponential backoff
Handle connection loss gracefully
Queue messages during disconnection for later delivery
Use connection pooling for multi-threaded applications

Subscription Management

Subscribe to specific topics, avoid broad wildcards
Unsubscribe when no longer needed
Handle subscription acknowledgment failures
Resubscribe after reconnection if using clean sessions

Publishing Best Practices

Validate messages before publishing
Handle publish failures appropriately
Use batching for high-frequency publishing where supported
Consider message ordering requirements

Broker Configuration

Scalability

Configure appropriate connection limits
Set message queue sizes based on expected load
Implement clustering for high availability
Use load balancers for horizontal scaling

Monitoring

Track connection counts and rates
Monitor message throughput and latency
Alert on queue depth and memory usage
Log authentication failures

Testing

Unit Testing

Mock MQTT client for isolated testing
Test message serialization/deserialization
Verify QoS handling logic

Integration Testing

Test with real broker in test environment
Verify reconnection scenarios
Test LWT functionality
Load test with realistic device counts

Common Patterns

Request/Response

Use correlated topics: request/{id} and response/{id}
Include correlation ID in message
Implement timeouts for responses

Device Shadow/Twin

Maintain desired and reported state
Use separate topics for state updates
Handle state synchronization on reconnection

Command and Control

Use dedicated command topics per device
Implement command acknowledgment
Handle command queuing for offline devices

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360