Create a Device

These are instructions for creating a device that can communicate with the Storm sensor project. This will make the device compatible with whatever GUI that is used for the platform.

Overview

This document describes the MQTT communication protocol for devices to integrate with the Breeze GUI. The GUI periodically pings for devices and manages device discovery, value updates, and parameter control.

Topic Structure

Discovery Topics

• publish_all_connected: GUI publishes to this topic every 30 seconds
• device_connected: Devices must publish to this topic to announce their presence
• device_meta: Devices must publish their metadata to this topic
• publish_meta/[device_id]: GUI requests metadata for a specific device

Device-specific Topics

• [base_topic]/[device_id]: Topic for device value updates
• [base_topic]/parameters/[device_id]: Topic for parameter control

Communication Flow

1. Initial Discovery

   • GUI publishes { value: "1" } to publish_all_connected every 30 seconds
   • Your device should subscribe to publish_all_connected
   • When your device receives this message, respond by publishing to device_connected:

     {
       "id": "your_device_id"
     }
   • Important: If a device misses two consecutive calls to publish_all_connected (60 seconds total without response), it will be automatically removed from the GUI

2. Metadata Exchange

   • After receiving your device_connected message, GUI will request metadata by publishing to publish_meta/[your_device_id]
   • Your device should publish metadata to device_meta:

     {
       "id": "your_device_id",
       "name": "Your Device Name",
       "base_topic": "your/base/topic",
       "datatype": "float",
       "unit": "°C",
       "minValue": 0,
       "maxValue": 100,
       "parameters": {
         "parameter1": {
           "datatype": "float",
           "min": 0,
           "max": 100
         }
       }
     }

3. Value Updates

   • After metadata exchange, publish your values to [base_topic]/[device_id]:

     {
       "value": 23.5
     }
   • Values should be published whenever they change

4. Parameter Control

   • Subscribe to [base_topic]/parameters/[device_id] to receive parameter updates
   • GUI will publish parameter changes in this format:

     {
       "parameter1": {
         "value": 42
       }
     }
   • Apply the parameter changes as needed

Required Fields

Metadata Message

• id: Your device's unique identifier
• name: Display name for your device
• base_topic: Your device's unique base topic
• datatype: Type of your main value ("float", "int", etc.)
• minValue: Minimum value your device can output
• maxValue: Maximum value your device can output

Value Message

• value: Single value or array of values

Example Implementation

Here's a Python example showing the basic communication flow:

import paho.mqtt.client as mqtt
import json

class BreezeDevice:
    def __init__(self, device_id, name, base_topic):
        self.device_id = device_id
        self.metadata = {
            "id": device_id,
            "name": name,
            "base_topic": base_topic,
            "datatype": "float",
            "unit": "°C",
            "minValue": 0,
            "maxValue": 100,
            "parameters": {
                "setpoint": {
                    "datatype": "float",
                    "min": 0,
                    "max": 100
                }
            }
        }

    def on_connect(self, client, userdata, flags, rc):
        # Subscribe to necessary topics
        client.subscribe("publish_all_connected")
        client.subscribe(f"{self.metadata['base_topic']}/parameters/{self.device_id}")

    def on_message(self, client, userdata, msg):
        if msg.topic == "publish_all_connected":
            # Respond to discovery request
            client.publish("device_connected",
                         json.dumps({"id": self.device_id}))
            client.publish("device_meta", json.dumps(self.metadata))
        elif msg.topic.endswith(f"parameters/{self.device_id}"):
            # Handle parameter updates
            params = json.loads(msg.payload)
            print(f"Received parameter update: {params}")

    def publish_value(self, client, value):
        message = {
            "value": value
        }
        client.publish(f"{self.metadata['base_topic']}/{self.device_id}",
                      json.dumps(message))

# Usage
device = BreezeDevice("device1", "Temperature Sensor", "sensors/temp")
client = mqtt.Client()
client.on_connect = device.on_connect
client.on_message = device.on_message
client.connect("localhost", 1883)
client.loop_start()

# Publish values periodically
while True:
    device.publish_value(client, 23.5)
    time.sleep(1)

## Testing Your Device

1. Use MQTT Explorer or similar tool to:
   - Monitor the `publish_all_connected` topic
   - Verify your device responds correctly to discovery
   - Check your metadata format
   - Test parameter control messages

2. Common Issues:
   - Missing required metadata fields
   - Wrong topic structure
   - Malformed JSON messages