DOCSEARCHbyAlgolia
Submit Docs

Homie Convention Documentation

repository·develop·Indexed 20 days ago

https://github.com/homieiot/convention

A standardized MQTT topic convention for IoT devices that enables automatic discovery, configuration, and interoperability. It defines a hierarchical topology of devices, nodes, and properties, specifying strict rules for MQTT topic IDs, payload types (including ISO 8601 and color formats), QoS settings, and device state management via the $state and $description attributes.

Tokens
9K
Snippets
20
Records
42
Agent score
72%

What's inside Homie Convention

  1. What is the Homie Convention?

    develop

    The Homie Convention is a lightweight messaging convention built on top of MQTT designed to interconnect IoT devices. It provides a standardized way for IoT devices and controlling entities to announce themselves and their data on a communication channel.

    Key benefits include:

    • Automatic Discovery: Devices and services can be discovered without manual configuration.
    • Standardized Interaction: Controllers can interact with devices without needing to know their internal hardware or implementation details.
    • Interoperability: By using a common topic convention, devices can work across different controller applications.

  2. Understand the Homie Root Topic and Auto-Discovery

    develop

    Root Topic Structure

    The root topic follows the pattern [homie-domain]/5/.

    • The homie-domain defaults to homie but can be customized for branding or public brokers.
    • The 5 represents the major version and cannot be customized.

    Auto-Discovery

    Homie 5 controllers perform auto-discovery by subscribing to the wildcard topic: +/5/+/$state

    Controllers can restrict discovery to a specific homie-domain. A zero-length payload published to a $state topic indicates that a device has been removed.

  3. Handle version compatibility

    develop

    Homie assumes compatibility based on the major version (e.g., version 5). The base topic includes this major version to allow controllers to subscribe only to compatible devices.

    Backward Compatibility (v5 Controller $\rightarrow$ v5 Device)

    Controllers should be aware of unsupported features in older minor versions of the specification they subscribe to.

    Forward Compatibility (v5 Controller $\rightarrow$ v5 Device with higher minor version)

    Controllers should:

    • Ignore unknown fields, properties, or attributes within an object (device, node, or property) while keeping the object itself.
    • Ignore the entire object if a known field, property, or attribute contains an illegal value (e.g., illegal characters in a topic, unknown data type, unknown/illegal format, or missing required elements).

  4. Extend Homie functionality with Extensions

    develop

    The core Homie convention focuses on discoverability. For complex scenarios, devices may support Extensions.

    • Identification: Every extension is identified by a unique ID consisting of a reverse domain name and a suffix (e.g., org.example.our-feature).
    • Reserved Terms: The term homie is reserved and must not be used as a suffix or part of the domain name.
    • Licensing: Every extension must be published with a license. The recommended license is CCA 4.0.

  5. Understand Homie Convention Roles

    develop

    The Homie convention defines two primary roles for entities interacting via an MQTT broker:

    • Device: An implementation that publishes the representation of a physical appliance or logical entity (e.g., a coffee machine or a protocol bridge) to an MQTT broker.
    • Controller: An implementation that discovers and interacts with devices (e.g., a mobile app or an automation engine).

    Note: The term "device" is often used as shorthand for the combination of the physical appliance, the computer managing its MQTT representation, and the representation itself.

  6. Understand the Homie Topology: Devices, Nodes, and Properties

    develop

    The Homie convention uses a hierarchical structure to model IoT devices:

    1. Devices: The top-level entity (e.g., a bridge or a single smart plug). Devices can have children, forming a tree structure.
    2. Nodes: Independent or logically separable parts of a device (e.g., a car having wheels, engine, and lights nodes).
    3. Properties: Basic characteristics of a node, typically represented by numbers or finite states (e.g., an engine node having a speed property).

    Attributes (prefixed with $) are used to characterize devices, nodes, and properties, enabling automatic discovery.

  7. Define a Vector datatype

    develop

    A Vector datatype represents a mathematical dimension n (where n is a natural number > 0).

    Payload Rules:

    • Vector payloads are represented as string literal representations of 64-bit signed floating point numbers in the format (f1, ..., fn).
    • Valid entries range from $2^{-1074}$ to $(2^{-2^{52}}) \ast 2^{1023}$.
    • An empty string ("") is not a valid payload.
    • Payload validity depends on the specific property format definition.

  8. Design considerations for Homie devices

    develop

    When designing device interfaces using the Homie convention, developers should account for the following:

    Eventual Consistency

    Because MQTT does not guarantee the order of message delivery, devices must be designed with eventual consistency in mind. The system assumes that once all messages have been received, the state will eventually become consistent, even if messages arrive in an unexpected order.

    Unambiguous Device State

    Devices should specify an unambiguous state. While a GUI might represent a device in a simplified way (e.g., a single slider), the underlying Homie state should avoid ambiguity.

    Example: Dimmable Light

    • Ambiguous approach: A GUI uses a switch (on/off) and a slider (0-100%). If the light is at 0% and the user turns the switch 'on', the state is unclear.
    • Unambiguous approach: The device uses an on/off setting and a brightness setting of 1-100%. This removes the 0% ambiguity, allowing the GUI to map these values to its own interface logic.

  9. Represent Empty String Values

    develop

    Because MQTT treats an empty string payload as a "delete" instruction, Homie represents an actual empty string using a 1-character string containing a single byte value 0 (Hex: 0x00, Dec: 0).

    This representation is only valid in these three specific locations:

    1. homie / 5 / [device ID] / [node ID] / [property ID] (reported property values for string types)
    2. homie / 5 / [device ID] / [node ID] / [property ID] / set (setting property values for string types)
    3. homie / 5 / [device ID] / [node ID] / [property ID] / $target (the target property value for string types)

    Note: There is no way to represent a 1-character string with a single byte 0 outside of these locations. If needed elsewhere, use an application-level escape mechanism.

  10. Core design principles of Homie

    develop

    The Homie convention is guided by several architectural principles to ensure scalability and ease of use:

    • Separation of Concerns: Uses MQTT as the central bus and Homie as the topic convention. This allows developers to write device drivers once and use them across multiple competing controller applications.
    • Message Bus: Relies exclusively on the industry-standard MQTT protocol rather than proprietary protocols.
    • Low Barrier to Entry: Users only need an MQTT server to start. Developers can use existing Homie libraries to begin coding quickly.
    • Resource Awareness: Designed to support resource-constrained devices (as long as they are MQTT capable), while assuming controllers have more resources to manage multiple device representations.
    • No Control Logic: Homie defines the means of interaction but does not implement logic engines (like 'if-this-then-that'). Logic is implemented as a separate layer.
    • No GUI Specifications: Homie does not dictate how a user interface should look. It provides metadata/hints in device descriptions that GUIs can use to render appropriately.
    • Debuggability: Uses simple, basic types transmitted in plain text over MQTT topics to make troubleshooting straightforward.

  11. Use nested Node Attributes for coordinate systems

    develop

    Extensions can define nested attributes for nodes. A common pattern is defining a $coordinate-system nesting attribute.

    If $coordinate-system is used, the following rules apply:

    1. Required Attribute: $coordinate-system/$handedness (Enum: [left_handed, right_handed]).
    2. Optional Attributes:
      • $coordinate-system/$first-axis-name (String, Default: "x-Axis")
      • $coordinate-system/$second-axis-name (String, Default: "y-Axis")
      • $coordinate-system/$third-axis-name (String, Default: "z-Axis")
      • $coordinate-system/$axis-unit (String)

    Topic Construction Example: If the base topic is homie, device ID is super-car, and node is wheels, the attribute topics would be: homie/super-car/wheels/$coordinate-system/$handedness

    homie/super-car/wheels/$coordinate-system/$handedness → "left_handed"
homie/super-car/wheels/$coordinate-system/$first-axis-name → "Pitch"
homie/super-car/wheels/$coordinate-system/$second-axis-name → "Yaw"
homie/super-car/wheels/$coordinate-system/$third-axis-name → "Roll"
homie/super-car/wheels/$coordinate-system/$axis-unit → "meter"

  12. Use the Meta extension to add tags and metadata

    develop

    The eu.epnw.meta extension allows you to attach simple annotations (tags) or complex key-value structures (metadata) to any Homie item (devices, nodes, or properties).

    • Tags: A simple comma-separated list of strings used for quick annotations. Tags must not contain commas.
    • Metadata: A hierarchical structure using mainkeys and subkeys. Metadata allows you to define specific attributes (like how a property should be treated by a voice assistant) using a topic-based ID system.

    This extension is compatible with Homie 3.0.1 and 4.x.

    Extension ID: eu.epnw.meta
$extensions entry: eu.epnw.meta:1.1.0:[3.0.1;4.x]