mqtt-development — скилл для Claude Code: правила MQTT

---
name: mqtt-development
description: Best practices and guidelines for MQTT messaging in IoT and real-time communication systems
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# 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