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 mqttTo 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.