### Legacy Firmware $fw Attributes Example Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_legacy_firmware_extension.md Shows how to implement the $fw/name and $fw/version attributes to provide firmware details in a backward-compatible manner. ```mqtt homie/super-car/$fw/name → "weatherstation-firmware" homie/super-car/$fw/version → "1.0.0" ``` -------------------------------- ### Declaring Device Extensions Source: https://context7.com/homieiot/convention/llms.txt Example of publishing the device description document, including extensions with versioning. ```json PUBLISH homie/5/super-car/$description → { "homie": "5.0", "name": "Supercar", "version": 3, "extensions": [ "org.homie.legacy-firmware:0.1.1:[4.x]", "org.homie.legacy-stats:0.1.1:[4.x]", "eu.epnw.meta:1.1.0:[3.0.1;4.x]" ], "nodes": { ... } } ``` -------------------------------- ### Legacy Firmware Attributes Example Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_legacy_firmware_extension.md Demonstrates the usage of $localip and $mac device attributes for backward compatibility with older Homie versions. ```mqtt homie/super-car/$localip → "192.168.0.10" homie/super-car/$mac → "DE:AD:BE:EF:FE:ED" ``` -------------------------------- ### Property Data Types and Formats Examples Source: https://context7.com/homieiot/convention/llms.txt Illustrates various Homie data types and their corresponding format constraints for MQTT payloads. ```json "datatype": "integer", "format": "2:6:2" PUBLISH → "4" ``` ```json "datatype": "float", "format": "0:" PUBLISH → "23.7" ``` ```json "datatype": "enum", "format": "low,medium,high" PUBLISH → "medium" ``` ```json "datatype": "boolean", "format": "close,open" PUBLISH → "open" ``` ```json "datatype": "color", "format": "rgb,hsv" PUBLISH → "rgb,100,200,50" PUBLISH → "hsv,300,50,75" ``` ```json "datatype": "color", "format": "xyz" PUBLISH → "xyz,0.25,0.34" ``` ```json "datatype": "datetime" PUBLISH → "2024-06-15T14:30:00Z" ``` ```json "datatype": "duration" PUBLISH → "PT12H5M46S" ``` ```json "datatype": "json", "format": "{\"anyOf\":[{\"type\":\"array\"},{\"type\":\"object\"}]}" PUBLISH → "{\"temp\":21.5,\"humidity\":60}" ``` -------------------------------- ### Meta Extension - Add Tags to Property Source: https://context7.com/homieiot/convention/llms.txt Example of adding tags to a property using the Meta extension. Tags are comma-separated strings. ```mqtt # Add tags to a property PUBLISH homie/super-car/engine/temperature/$tags → "Lighting,Switchable,Thermostat" ``` -------------------------------- ### Homie Logging Examples Source: https://github.com/homieiot/convention/blob/develop/convention.md Devices can send log messages using the '$log' topic with a specific level. These messages should be non-retained and used sparingly. ```mqtt homie/5/my-device/$log/warn → "battery low" ``` ```mqtt homie/5/my-device/$log/error → "sensor value is out of range" ``` -------------------------------- ### Homie Property Set Command Example Source: https://github.com/homieiot/convention/blob/develop/convention.md A Homie device subscribes to the 'set' topic to receive commands for settable properties. The device must reflect the processed payload in its property topic. ```mqtt homie/5/kitchen-light/light/power/set ← "true" ``` ```mqtt homie/5/kitchen-light/light/power → "true" ``` -------------------------------- ### Publishing Broadcast Message Source: https://context7.com/homieiot/convention/llms.txt Example of publishing a non-retained broadcast message to a custom domain. ```mqtt PUBLISH myhome/5/$broadcast/maintenance/start → "Rebooting hub in 60s" (non-retained) ``` -------------------------------- ### Legacy Stats Attributes Example Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_legacy_stats_extension.md Illustrates the publishing of legacy stats attributes. The $stats/interval attribute dictates the refresh rate for other stats attributes. ```text homie/super-car/$stats/interval → "60" homie/super-car/$stats/uptime → "120" ``` -------------------------------- ### Homie Broadcast Topic Examples Source: https://github.com/homieiot/convention/blob/develop/convention.md A controller can broadcast messages to all Homie devices using the '$broadcast' topic. Devices are free to react to these non-retained messages. ```mqtt homie/5/$broadcast/alert ← "Intruder detected" ``` ```mqtt homie/5/$broadcast/security/alert ← "Intruder detected" ``` -------------------------------- ### Set $coordinate-system/$axis-unit Attribute Source: https://github.com/homieiot/convention/blob/develop/extensions/extension_template.md Example of setting the unit for the coordinate axes. This is an optional attribute within the $coordinate-system node. ```mqtt homie/super-car/wheels/$coordinate-system/$axis-unit → "meter" ``` -------------------------------- ### Publish Property Value to MQTT Topic Source: https://github.com/homieiot/convention/blob/develop/convention.md Example of publishing a property value to its corresponding MQTT topic. The value is a string representation of the actual data type. ```text homie/5/super-car/engine/temperature → "21.5" ``` -------------------------------- ### Set $coordinate-system/$first-axis-name Attribute Source: https://github.com/homieiot/convention/blob/develop/extensions/extension_template.md Example of setting the name for the first axis of a coordinate system. This is an optional attribute within the $coordinate-system node. ```mqtt homie/super-car/wheels/$coordinate-system/$first-axis-name → "Pitch" ``` -------------------------------- ### Set $coordinate-system/$handedness Attribute Source: https://github.com/homieiot/convention/blob/develop/extensions/extension_template.md Example of setting the handedness of a coordinate system for a node attribute. This attribute is required if $coordinate-system is used. ```mqtt homie/super-car/wheels/$coordinate-system/$handedness → "left_handed" ``` -------------------------------- ### Set $coordinate-system/$second-axis-name Attribute Source: https://github.com/homieiot/convention/blob/develop/extensions/extension_template.md Example of setting the name for the second axis of a coordinate system. This is an optional attribute within the $coordinate-system node. ```mqtt homie/super-car/wheels/$coordinate-system/$second-axis-name → "Yaw" ``` -------------------------------- ### Homie Alert Topic Examples Source: https://github.com/homieiot/convention/blob/develop/convention.md Devices can publish alerts using the '$alert' topic with a specific alert ID. Alerts are retained messages and can be removed by deleting the topic. ```mqtt homie/5/mydevid/$alert/childlost = "Sensor xyz in livingroom hasn't reported updates for 3 hours" ``` ```mqtt homie/5/mydevid/$alert/battery = "Battery is low, at 8%" ``` -------------------------------- ### Set $coordinate-system/$third-axis-name Attribute Source: https://github.com/homieiot/convention/blob/develop/extensions/extension_template.md Example of setting the name for the third axis of a coordinate system. This is an optional attribute within the $coordinate-system node. ```mqtt homie/super-car/wheels/$coordinate-system/$third-axis-name → "Roll" ``` -------------------------------- ### Publish Initial Property Value and State Source: https://context7.com/homieiot/convention/llms.txt After publishing the device description, publish the initial value for new properties and set the device state to 'ready'. These messages should be retained with QoS 2. ```mqtt PUBLISH homie/5/super-car/battery/level → "87" (retained, QoS 2) PUBLISH homie/5/super-car/$state → "ready" (retained, QoS 2) ``` -------------------------------- ### Device State and Description Topics Source: https://github.com/homieiot/convention/blob/develop/convention.md Publish the device's current state and its JSON description document to the respective topics. The `$description` document should only be updated when the device state is 'init', 'disconnected', or 'lost'. ```mqtt homie/5/super-car/$state → "init" homie/5/super-car/$description → following JSON document; ``` -------------------------------- ### Publish Device Description (JSON) Source: https://context7.com/homieiot/convention/llms.txt Publish the device description, including nodes and properties, to the $description topic. This is typically done once when the device is first initialized or updated. ```mqtt PUBLISH homie/5/super-car/$description → { "homie": "5.0", "name": "Supercar", "version": 8, "nodes": { "engine": { ... }, "lights": { ... }, "battery": { "name": "Battery", "properties": { "level": { "name": "Battery Level", "datatype": "integer", "unit": "%", "format": "0:100", "settable": false, "retained": true } } } } } ``` -------------------------------- ### Meta Extension - Define Mainkey Display Name and Value Source: https://context7.com/homieiot/convention/llms.txt Defines the display name and value for a specific mainkey (e.g., HomeKit or Alexa). ```mqtt # Define each mainkey's display name and value PUBLISH homie/super-car/engine/temperature/$meta/homekit/$key → "HomeKit" PUBLISH homie/super-car/engine/temperature/$meta/homekit/$value → "Fan.v2" PUBLISH homie/super-car/engine/temperature/$meta/alexa/$key → "Alexa" PUBLISH homie/super-car/engine/temperature/$meta/alexa/$value → "Fan" ``` -------------------------------- ### Device Hierarchy - Parent/Child Devices Source: https://context7.com/homieiot/convention/llms.txt Demonstrates how to structure devices in a hierarchy using 'root', 'parent', and 'children' fields in the description document. The LWT is only set on the root device. ```mqtt # ZWave bridge (root device) PUBLISH homie/5/bridge/$description → { "homie": "5.0", "name": "ZWave Bridge", "version": 1, "children": ["dualrelay"] } PUBLISH homie/5/bridge/$state → "ready" # Dual relay (child of bridge) PUBLISH homie/5/dualrelay/$description → { "homie": "5.0", "name": "Dual Relay", "version": 1, "root": "bridge", "children": ["light1", "light2"] } PUBLISH homie/5/dualrelay/$state → "ready" # Individual lights (leaf children) PUBLISH homie/5/light1/$description → { "homie": "5.0", "name": "Light 1", "version": 1, "root": "bridge", "parent": "dualrelay" } PUBLISH homie/5/light1/$state → "ready" # If bridge loses connection, LWT fires: # homie/5/bridge/$state → "lost" # Controller treats dualrelay, light1, light2 as also "lost" ``` -------------------------------- ### Homie Dimmable Light Control with $target Source: https://github.com/homieiot/convention/blob/develop/convention.md Demonstrates controlling a dimmable light property using the '$target' attribute for gradual changes. The device updates the property topic as the change progresses. ```mqtt homie/5/kitchen-light/light/brightness/set ← 100 ``` ```mqtt homie/5/kitchen-light/light/brightness/$target → 100 ``` ```mqtt homie/5/kitchen-light/light/brightness → 20 (after 1 second) ``` ```mqtt homie/5/kitchen-light/light/brightness → 40 (after 2 seconds) ``` ```mqtt homie/5/kitchen-light/light/brightness → 60 (after 3 seconds) ``` ```mqtt homie/5/kitchen-light/light/brightness → 80 (after 4 seconds) ``` ```mqtt homie/5/kitchen-light/light/brightness → 100 (after 5 seconds) ``` -------------------------------- ### Device Description Document Source: https://context7.com/homieiot/convention/llms.txt The device publishes a JSON document to $description describing its nodes and properties. This document should only change while the device is in 'init', 'disconnected', or 'lost' state. ```json { "homie": "5.0", "name": "Supercar", "version": 7, "nodes": { "engine": { "name": "Car Engine", "properties": { "speed": { "name": "Engine Speed", "datatype": "integer", "unit": "rpm", "format": "0:8000", "settable": false, "retained": true }, "temperature": { "name": "Engine Temperature", "datatype": "float", "unit": "°C", "format": "-20:120", "settable": false, "retained": true } } }, "lights": { "name": "Car Lights", "properties": { "power": { "name": "Lights Power", "datatype": "boolean", "format": "off,on", "settable": true, "retained": true }, "color": { "name": "Light Color", "datatype": "color", "format": "rgb,hsv", "settable": true, "retained": true } } } } } ``` -------------------------------- ### Define Mainkey Name and Value Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_meta_extension.md For each mainkey ID, specify its actual name and value. The key name is a string, and the value can be any string. ```mqtt homie/super-car/engine/temperature/$meta/homekit/$key → "HomeKit" homie/super-car/engine/temperature/$meta/homekit/$value → "Fan.v2" homie/super-car/engine/temperature/$meta/alexa/$key → "Alexa" homie/super-car/engine/temperature/$meta/alexa/$value → "Fan" ``` -------------------------------- ### Signal Device Reconfiguration Source: https://context7.com/homieiot/convention/llms.txt Initiates a device reconfiguration by publishing the '$state' attribute as 'init'. The device will then make changes and return to 'ready'. ```mqtt # Step 1 — Signal reconfiguration PUBLISH homie/5/super-car/$state → "init" (retained, QoS 2) ``` -------------------------------- ### Define Mainkey IDs and Tags for a Property Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_meta_extension.md Use these attributes to assign tags and advertise mainkey identifiers for a property. Tags are comma-separated strings, and mainkey IDs must be valid topic IDs. ```mqtt homie/super-car/engine/temperature/$meta/$mainkey-ids → "alexa,homekit" homie/super-car/engine/temperature/$tags → "Lighting,Switchable,Thermostat" ``` -------------------------------- ### Define Subkey Name and Value Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_meta_extension.md For each subkey ID, specify its actual name and value. The key name is a string, and the value can be any string. ```mqtt homie/super-car/engine/temperature/$meta/alexa/type/$key → "type" homie/super-car/engine/temperature/$meta/alexa/type/$value → "oscillating" homie/super-car/engine/temperature/$meta/alexa/step-speed/$key → "stepSpeed" homie/super-car/engine/temperature/$meta/alexa/step-speed/$value → "3" ``` -------------------------------- ### Legacy Firmware Extension Attributes Source: https://context7.com/homieiot/convention/llms.txt Required device attributes added by the legacy firmware extension for backwards compatibility. ```mqtt # Required device attributes added by this extension PUBLISH homie/super-car/$localip → "192.168.0.10" (retained) PUBLISH homie/super-car/$mac → "DE:AD:BE:EF:FE:ED" (retained) PUBLISH homie/super-car/$fw/name → "weatherstation-firmware" (retained) PUBLISH homie/super-car/$fw/version → "1.0.0" (retained) ``` -------------------------------- ### Logging Topic Structure Source: https://context7.com/homieiot/convention/llms.txt Devices send log messages to this topic structure. All log messages must be non-retained. ```mqtt PUBLISH homie/5/my-device/$log/debug → "Connecting to sensor on I2C" (non-retained, QoS 0) ``` ```mqtt PUBLISH homie/5/my-device/$log/info → "Sensor initialized" (non-retained, QoS 0) ``` ```mqtt PUBLISH homie/5/my-device/$log/warn → "Battery low" (non-retained, QoS 0) ``` ```mqtt PUBLISH homie/5/my-device/$log/error → "Sensor value out of range" (non-retained, QoS 0) ``` ```mqtt PUBLISH homie/5/my-device/$log/fatal → "Unrecoverable I2C failure" (non-retained, QoS 0) ``` -------------------------------- ### Set Property Value - /set Command Topic Source: https://context7.com/homieiot/convention/llms.txt Controllers publish to the /set topic to change a property's value. The device must then confirm the accepted value by publishing to the property's main topic. ```mqtt PUBLISH homie/5/super-car/lights/power/set → "true" (non-retained, QoS 1) PUBLISH homie/5/super-car/lights/power → "true" (retained, QoS 2) PUBLISH homie/5/super-car/lights/color/set → "rgb,255,0,0" (non-retained, QoS 1) PUBLISH homie/5/super-car/lights/color → "rgb,255,0,0" (retained, QoS 2) ``` -------------------------------- ### Device State Transitions Source: https://context7.com/homieiot/convention/llms.txt A device signals its lifecycle state by publishing to the $state topic. The 'lost' state is set via MQTT Last Will (LWT). After connecting, the device transitions through 'init' to 'ready'. A clean disconnect publishes 'disconnected'. ```mqtt # Device comes online — set LWT first (before connecting), then publish init LWT topic: homie/5/super-car/$state LWT payload: lost LWT retained: true LWT QoS: 1 ``` ```mqtt # After connecting, transition through init → ready PUBLISH homie/5/super-car/$state → "init" (retained, QoS 2) # ... publish $description and property values ... PUBLISH homie/5/super-car/$state → "ready" (retained, QoS 2) ``` ```mqtt # Clean disconnect PUBLISH homie/5/super-car/$state → "disconnected" (retained, QoS 2) # then disconnect from broker ``` -------------------------------- ### Discover Homie 5 Devices Source: https://context7.com/homieiot/convention/llms.txt Controllers subscribe to this topic to discover all Homie 5 devices on the network. This can be restricted to a specific domain. ```mqtt SUBSCRIBE: +/5/+/$state ``` ```mqtt SUBSCRIBE: myhome/5/+/$state ``` -------------------------------- ### Device Description JSON Document Source: https://github.com/homieiot/convention/blob/develop/convention.md The JSON description document outlines the Homie convention version, description document version, device name, type, nodes, and relationships to parent/child devices. The 'root' field is required for non-root devices, and 'parent' is required if the parent is not the root device. ```json { "homie": "5.0", "name": "Supercar", "version": 7, "nodes": { "wheels": { ... }, "engine": { ... }, "lights": { ... } } } ``` -------------------------------- ### Define Subkey IDs for a Mainkey Source: https://github.com/homieiot/convention/blob/develop/extensions/documents/homie_meta_extension.md Advertise subkey identifiers for a mainkey. Subkey IDs must be valid topic IDs and are comma-separated. ```mqtt homie/super-car/engine/temperature/$meta/alexa/$subkey-ids → "type,step-speed" ``` -------------------------------- ### Slow Transitions with $target Attribute Source: https://context7.com/homieiot/convention/llms.txt For gradual changes, the device first acknowledges the target value using the $target attribute. It then publishes intermediate values during the transition before publishing the final value. ```mqtt PUBLISH homie/5/kitchen-light/light/brightness/set → "100" (non-retained, QoS 1) PUBLISH homie/5/kitchen-light/light/brightness/$target → "100" (retained, QoS 2) PUBLISH homie/5/kitchen-light/light/brightness → "20" (after 1s, retained) PUBLISH homie/5/kitchen-light/light/brightness → "40" (after 2s, retained) PUBLISH homie/5/kitchen-light/light/brightness → "60" (after 3s, retained) PUBLISH homie/5/kitchen-light/light/brightness → "80" (after 4s, retained) PUBLISH homie/5/kitchen-light/light/brightness → "100" (after 5s, retained) ``` -------------------------------- ### Meta Extension - Declare Mainkey IDs Source: https://context7.com/homieiot/convention/llms.txt Declares the mainkey IDs for a property, which are topic-safe identifiers for semantic annotations. ```mqtt # Declare mainkey IDs (these are topic-safe IDs, not the display names) PUBLISH homie/super-car/engine/temperature/$meta/$mainkey-ids → "alexa,homekit" ``` -------------------------------- ### Meta Extension - Add Subkeys to Mainkey Source: https://context7.com/homieiot/convention/llms.txt Adds subkeys to a mainkey, allowing for more detailed semantic annotations. Subkeys are also topic-safe IDs. ```mqtt # Add subkeys to a mainkey PUBLISH homie/super-car/engine/temperature/$meta/alexa/$subkey-ids → "type,step-speed" PUBLISH homie/super-car/engine/temperature/$meta/alexa/type/$key → "type" PUBLISH homie/super-car/engine/temperature/$meta/alexa/type/$value → "oscillating" PUBLISH homie/super-car/engine/temperature/$meta/alexa/step-speed/$key → "stepSpeed" PUBLISH homie/super-car/engine/temperature/$meta/alexa/step-speed/$value → "3" ``` -------------------------------- ### Alert Topic - $alert Source: https://context7.com/homieiot/convention/llms.txt Devices publish user-facing alerts to the $alert topic. Alerts are retained and can be resolved by publishing an empty payload to clear the retained topic. ```mqtt # Raise alerts PUBLISH homie/5/mydevid/$alert/childlost → "Sensor xyz hasn't reported for 3 hours" PUBLISH homie/5/mydevid/$alert/battery → "Battery is low, at 8%" # Resolve alert (publish empty payload to delete retained topic) PUBLISH homie/5/mydevid/$alert/battery → "" ``` -------------------------------- ### Broadcast Topic - $broadcast Source: https://context7.com/homieiot/convention/llms.txt Controllers use the $broadcast topic to send non-retained messages to all Homie devices. Subtopics must use valid ID characters. ```mqtt # Broadcast a security alert to all devices PUBLISH homie/5/$broadcast/alert → "Intruder detected" (non-retained) # Multi-level broadcast subtopic PUBLISH homie/5/$broadcast/security/alert → "Intruder detected" (non-retained) ``` -------------------------------- ### Legacy Stats Extension Attributes Source: https://context7.com/homieiot/convention/llms.txt Required and optional stats attributes for the legacy stats extension. The device must refresh all stat values periodically. ```mqtt # Required stats attributes PUBLISH homie/super-car/$stats/interval → "60" (retained) PUBLISH homie/super-car/$stats/uptime → "3600" (retained, refreshed every 60s) # Optional stats attributes (must also be refreshed every interval if published once) PUBLISH homie/super-car/$stats/signal → "85" # Wi-Fi signal % PUBLISH homie/super-car/$stats/cputemp → "42.1" # °C PUBLISH homie/super-car/$stats/cpuload → "12" # % averaged over interval PUBLISH homie/super-car/$stats/battery → "78" # % PUBLISH homie/super-car/$stats/freeheap → "42680" # bytes PUBLISH homie/super-car/$stats/supply → "3.28" # Volts ``` -------------------------------- ### Publishing Property Values Source: https://context7.com/homieiot/convention/llms.txt Devices report property state by publishing to the property topic. Retained properties use retained messages with QoS 2. Non-retained (event) properties use non-retained messages with QoS 0. ```mqtt # Retained sensor readings (QoS 2, retained) PUBLISH homie/5/super-car/engine/speed → "3500" (retained, QoS 2) PUBLISH homie/5/super-car/engine/temperature → "87.3" (retained, QoS 2) PUBLISH homie/5/super-car/lights/power → "true" (retained, QoS 2) PUBLISH homie/5/super-car/lights/color → "rgb,255,140,0" (retained, QoS 2) ``` ```mqtt # Non-retained event (doorbell press): QoS 0, not retained PUBLISH homie/5/doorbell/button/press → "true" (non-retained, QoS 0) ``` -------------------------------- ### Define a Homie Property Object Source: https://github.com/homieiot/convention/blob/develop/convention.md Defines the structure of a Homie Property object, including its name, unit, datatype, and format. This JSON is part of the node's $description document. ```json "temperature": { "name": "Engine temperature", "unit": "°C", "datatype": "float", "format": "-20:120" } ... ``` -------------------------------- ### Representing Empty String Values Source: https://context7.com/homieiot/convention/llms.txt Uses a null byte (0x00) payload to represent an actual empty string value for a retained string-type property. Publishing an empty string payload deletes the retained topic. ```mqtt # Represents an actual empty string value for a string-type property # Payload is a single byte: 0x00 (hex) PUBLISH homie/5/my-device/info/label → "\x00" (retained, QoS 2) # This is NOT how to represent empty string — this DELETES the retained topic: # PUBLISH homie/5/my-device/info/label → "" ← DO NOT USE for empty string values ``` -------------------------------- ### Define a Homie Node Object Source: https://github.com/homieiot/convention/blob/develop/convention.md Defines the structure of a Homie Node object, including its name, type, and exposed properties. This JSON is typically published to the $description topic for the node. ```json "engine": { "name": "Car engine", "properties": { "speed": { ... }, "direction": { ... }, "temperature": { ... } } } ... ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.