Complete implementation guide for using MQTT 5.0 protocol features with MQTT X.

mqttx-mqtt5/
├── SKILL.md                           # Main skill guide
├── README.md                          # This file
├── assets/                            # Code templates
│   ├── mqtt5-basic.go.tmpl           # Basic MQTT 5.0 connection
│   ├── mqtt5-advanced.go.tmpl        # Advanced features (aliases, shared subs)
│   └── mqtt5-auth.go.tmpl            # Enhanced authentication examples
├── references/                        # Documentation
│   ├── mqtt5-features.md             # Detailed feature reference
│   └── mqtt311-vs-mqtt5.md           # Protocol comparison guide
└── scripts/                           # Helper scripts
    └── check-mqtt5-support.sh        # Broker compatibility checker

# Check if your broker supports MQTT 5.0
./scripts/check-mqtt5-support.sh tcp://localhost:1883

# Copy and run the basic template
cp assets/mqtt5-basic.go.tmpl main.go
go run main.go

# Use advanced template for shared subscriptions, topic aliases
cp assets/mqtt5-advanced.go.tmpl main.go
go run main.go

# Enhanced authentication examples (JWT, OAuth 2.0, SHA-256)
cp assets/mqtt5-auth.go.tmpl main.go
go run main.go

• When to use MQTT 5.0 vs MQTT 3.1.1
• Complete configuration guide
• Working examples for all features
• Troubleshooting common issues
• Migration from MQTT 3.1.1

mqtt5-features.md:

• User properties explained
• Topic aliases optimization
• Session expiry control
• Shared subscriptions for load balancing
• Enhanced authentication methods
• Request-response patterns

mqtt311-vs-mqtt5.md:

• Side-by-side feature comparison
• Code examples showing differences
• Migration checklist
• Performance comparison
• When to choose each version

• User properties (custom metadata)
• Topic aliases (bandwidth optimization)
• Session expiry (flexible persistence)
• Shared subscriptions (load balancing)
• Enhanced authentication (JWT, OAuth, SHA-256)
• Request-response patterns
• Reason codes (better error handling)

• Plain username/password
• SHA-256 challenge-response
• JWT (JSON Web Token)
• OAuth 2.0 with token refresh

• Bandwidth optimization strategies
• Horizontal scaling with shared subscriptions
• Migration from MQTT 3.1.1
• Broker compatibility checking
• Performance tuning

• Connection with MQTT 5.0
• User properties configuration
• Session expiry settings
• Basic publish/subscribe
• Metrics and monitoring

Use when: Learning MQTT 5.0 basics or simple applications

• Shared subscriptions (load balancing)
• Topic aliases (bandwidth optimization)
• Multiple sessions with workers
• User properties in messages
• Session persistence demonstration

Use when: Building scalable systems or optimizing bandwidth

• JWT authentication
• OAuth 2.0 authentication
• SHA-256 challenge-response
• Multiple authenticated sessions
• Shared subscriptions with auth

Use when: Implementing secure authentication or integrating with auth providers

mqtt5Config := mqttx.DefaultMQTT5Config()
mqtt5Config.SessionExpiry = 30 * time.Minute
mqtt5Config.UserProperties = map[string]string{
    "app": "my-app",
    "version": "1.0.0",
}

opts := mqttx.DefaultOptions()
opts.WithMQTT5(mqtt5Config)

// Multiple workers subscribe to shared topic
session.SubscribeShared("workers", "tasks/process", handler, 1)

// Messages automatically distributed among workers

jwtProvider := mqttx.NewJWTAuthProvider(jwtToken)
authManager := mqttx.NewMQTT5AuthManager(jwtProvider)
method, data, _ := authManager.StartAuth()
auth := mqttx.NewMQTT5Auth(method, data)
opts.WithEnhancedAuth(auth)

./scripts/check-mqtt5-support.sh tcp://broker.example.com:1883

Expected output for full support:

✓ MQTT 5.0 connection successful
✓ User properties supported
✓ Shared subscriptions supported
✓ Session expiry interval supported
✓ Topic aliases supported
✓ Request response info supported
✓ Maximum packet size negotiation supported

Success rate: 100%

Each template includes built-in tests:

• Basic: Connection, session expiry, user properties
• Advanced: Shared subscriptions, topic aliases, load balancing
• Auth: JWT, OAuth, SHA-256 authentication

// Measure bandwidth savings with topic aliases
longTopic := "sensors/building/floor/room/device/metric"
// First publish: full topic
// Subsequent: 2-byte alias (96% reduction)

• Use topic aliases for bandwidth savings
• Session expiry for battery-powered devices
• User properties for sensor metadata

Template: mqtt5-advanced.go.tmpl

• Shared subscriptions for load balancing
• User properties for task routing
• Session persistence for reliability

Template: mqtt5-advanced.go.tmpl

• Enhanced authentication (JWT/OAuth)
• User properties for correlation IDs
• Request-response patterns

Template: mqtt5-auth.go.tmpl

• Session expiry for connection recovery
• User properties for metadata
• QoS settings for reliability

Template: mqtt5-basic.go.tmpl

Check:

1. Broker version (needs MQTT 5.0 support)
2. Run compatibility checker
3. Review broker configuration

Solution:

# Test broker
./scripts/check-mqtt5-support.sh tcp://your-broker:1883

# Or fallback to MQTT 3.1.1
opts.ProtocolVersion = mqttx.MQTT311

Check:

1. Broker supports shared subscriptions
2. Syntax: $share/<group>/<topic>
3. Broker configuration

Solution:

# Mosquitto: Add to mosquitto.conf
allow_shared_subscriptions true

# EMQX: Usually enabled by default

Check:

1. Auth method supported by broker
2. Token not expired (for JWT/OAuth)
3. Broker authentication plugin enabled

Solution:

// Check authentication state
if authManager.State() == mqttx.AuthStateFailed {
    log.Println("Authentication failed")
}

• Enable for high-frequency topics
• Set reasonable maximum (50-100)
• Monitor alias usage

• Keep keys short
• Limit number of properties
• Use for routing/filtering only

• Scale workers based on load
• Monitor distribution fairness
• Use stateless handlers

• Match to reconnect patterns
• Balance persistence vs memory
• Clean up test sessions

• Quick Start - MQTT basics
• TLS Security - Secure MQTT 5.0
• Multi-Session - Multiple MQTT 5.0 sessions
• Events - Event-driven MQTT 5.0

• MQTT 5.0 Specification
• MQTT.org

• Mosquitto 2.x
• EMQX 5.x
• HiveMQ 4.x

• MQTT 5.0 Essentials
• Shared Subscriptions

• /workspace/mqtt5.go - MQTT 5.0 configuration
• /workspace/mqtt5_auth.go - Enhanced authentication
• /workspace/types.go - MQTT5Options structure

• /workspace/examples/mqtt5_auth/main.go - Complete authentication example

Found an issue or have a suggestion? The skill documentation and templates can be improved based on real-world usage.

Part of MQTT X library. See main repository for license information.