mqtt

Purpose

This skill allows the AI to interact with MQTT, a lightweight pub/sub protocol, for efficient IoT communication. Use it to publish telemetry data or subscribe to device updates, enabling real-time interactions in constrained environments.

When to Use

Use this skill for scenarios requiring low-bandwidth, real-time messaging, such as sending sensor data from IoT devices, remote device control, or telemetry monitoring. Avoid it for high-throughput needs like file transfers, where HTTP is more suitable.

Key Capabilities

• Publish messages to topics with configurable Quality of Service (QoS) levels (0, 1, or 2).
• Subscribe to topics and handle incoming messages asynchronously.
• Support for retained messages, last will and testament, and wildcard subscriptions (e.g., "#" for all subtopics).
• Secure connections via TLS and authentication methods like username/password.

Usage Patterns

To use MQTT, first connect to a broker using a client library. Establish a connection with credentials, then publish or subscribe. For example, in a loop: connect, subscribe, process messages, and disconnect. Use environment variables for sensitive data, like $MQTT_BROKER_URL for the broker address. Always handle reconnections for unstable networks.

Common Commands/API

Use the Paho MQTT library for Python interactions. Import it as follows:

import paho.mqtt.client as mqtt

To connect to a broker:

• Command: client.connect(broker_address, port=1883)
• Example with auth: client.username_pw_set(username='$MQTT_USERNAME', password='$MQTT_PASSWORD')

To publish a message:

• API: client.publish(topic, payload, qos=1)
• Example: client.publish('sensors/temp', '22.5', qos=1)

To subscribe:

• API: client.subscribe(topic, qos=1)
• Example: client.subscribe('commands/device1', qos=1)

Config format: Use a JSON file for settings, e.g., {"broker": "$MQTT_BROKER_URL", "topic": "sensors/temp"}. CLI tools like mosquitto_pub can be invoked via subprocess: subprocess.run(['mosquitto_pub', '-h', '$MQTT_BROKER_URL', '-t', 'sensors/temp', '-m', '22.5']).

Integration Notes

Integrate MQTT by wrapping it in your AI agent's code. Set environment variables for keys, e.g., export $MQTT_API_KEY for token-based auth. For multi-service setups, use a broker like HiveMQ or Mosquitto; connect via client.connect('$MQTT_BROKER_URL'). Ensure TLS for secure endpoints (e.g., client.tls_set()). If combining with other skills, like a database, publish data on success: e.g., after inserting into a DB, run client.publish('db/updates', json.dumps(data)).

Error Handling

Handle common errors explicitly. For connection issues, catch ConnectionRefusedError and retry with exponential backoff: e.g., time.sleep(5). For publish failures, check return codes (e.g., if client.publish() returns >0, log and retry). Subscription errors might involve invalid topics; validate with if '/' not in topic: raise ValueError('Invalid topic'). Use callbacks for message errors, like in on_message handler: if error: print('Error: ', error). Always clean up with client.disconnect() in a finally block.

Concrete Usage Examples

Example 1: Publish sensor data To publish a temperature reading to an MQTT topic, first set env vars: export MQTT_BROKER_URL='broker.example.com'. Then, in code:

client = mqtt.Client()
client.connect(os.environ['MQTT_BROKER_URL'])
client.publish('sensors/temperature', '25.0', qos=1)
client.disconnect()

This sends a message to the broker for IoT dashboard updates.

Example 2: Subscribe to device commands To subscribe and react to commands, use:

def on_message(client, userdata, message):
    print(f"Received: {message.payload.decode()}")
client = mqtt.Client()
client.on_message = on_message
client.connect(os.environ['MQTT_BROKER_URL'])
client.subscribe('commands/device1', qos=1)
client.loop_forever()

This keeps the client listening for commands to control an IoT device.

Graph Relationships

• Related to cluster: iot
• Related to tags: iot, mqtt
• Connections: Can integrate with other iot skills, such as for data processing or device management.