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.