Crate homie5

Expand description

this is a very low level implemenation of the homie5 protocol in rust. it aims to be as flexible and unopinionated as possible. there is no direct dependency to a mqtt library. homie5 provides a basic support for a protocol implementation for homie v5 with a clearly defined interface point to a mqtt library. the library provides fully typed support for all homie5 datatypes.

due to this, the usage of the library is a bit more involved as with a completly ready to use homie library. benefit is however that you can use the library basically everywhere from a simple esp32, raspberrypi to a x86 machine.

you can find working examples for both device and controller use case in the examples/ folder:

controller_example.rs: implements a homie5 controller that will discover all homie5 devices on a mqtt broker and print out the devices and their property updates (more information).
device_example.rs: implements a simple lightdevice with state and brightness control properties (more information).

both examples use rumqttc as a mqtt client implementation and provide a best practice in homie5 usage and in how to integrate the 2 libraries.

Modules§

client: This module provides MQTT primitives for library-agnostic message handling.
device_description: This module provides all types and tools to create (builders) and manage homie device, node and property descriptions.
extensions

Structs§

CustomDomain
DeviceRef: Identifies a device via homie-domain and the device id
DeviceSubscriptionIterator
Homie5ControllerProtocol: The Homie5ControllerProtocol struct provides the core functionality for generating MQTT subscription and publish commands required for interacting with Homie 5 devices.
Homie5DeviceProtocol: Represents the Homie v5 protocol implementation for a device, providing methods for publishing state, logging, and handling properties.
HomieID: Represents a validated Homie ID.
InvalidHomieDomainError: Error type returned when a string fails to validate as a custom homie-domain.
InvalidHomieIDError: Error type returned when a string fails to validate as a Homie ID.
NodeRef: Identifies a node of a device via its DeviceRef and its node id
PropertyPointer
PropertyRef: Identifies a property of a node via its NodeRef and the property id
TopicBuilder

Enums§

DeviceDisconnectStep: Represents the steps required to disconnect a Homie device.
DeviceLogLevel
DevicePublishStep: Represents the steps required to publish a Homie device.
DeviceReconfigureStep: Represents the steps required to reconfigure a Homie device.
Homie5Message: Represents all possible MQTT message types according to the Homie 5 protocol. These messages define the interactions between devices, their attributes, and the broker.
Homie5ProtocolError: Represents various errors that can occur while handling the Homie v5 protocol.
Homie5ValueConversionError
HomieColorValue: Represents color values supported by the Homie protocol.
HomieDataType: Datatypes in the homie protocol
HomieDeviceStatus: Reflects the current state of the device.
HomieDomain
HomieValue: Represents the various data types supported by the Homie protocol.

Constants§

DEFAULT_HOMIE_DOMAIN: The default mqtt root topic: “homie”
DEVICE_ATTRIBUTES: A list of all the device attributes to be published or subscribed to
DEVICE_ATTRIBUTE_ALERT: Device alert attribute topic: “$state”
DEVICE_ATTRIBUTE_DESCRIPTION: Device description attribute topic: “$description”
DEVICE_ATTRIBUTE_LOG: Device log attribute topic: “$log”
DEVICE_ATTRIBUTE_STATE: Device state attribute topic: “$state”
HOMIE_TOPIC_BROADCAST: Broadcast topic: “$broadcast”
HOMIE_UNIT_AMPERE: unit for electric current in amperes
HOMIE_UNIT_COUNT_AMOUNT: unit for countable amounts
HOMIE_UNIT_CUBIC_METER: unit for volume in cubic meters
HOMIE_UNIT_DEGREE: unit for generic degrees
HOMIE_UNIT_DEGREE_CELSIUS: unit for degrees in Celsius
HOMIE_UNIT_DEGREE_FAHRENHEIT: unit for degrees in Fahrenheit
HOMIE_UNIT_FEET: unit for length in feet
HOMIE_UNIT_GALLON: unit for volume in gallons
HOMIE_UNIT_HERTZ: unit for frequency in hertz
HOMIE_UNIT_HOURS: unit for time in hours
HOMIE_UNIT_KELVIN: unit for temperature in kelvin
HOMIE_UNIT_KILOPASCAL: unit for pressure in kilopascals
HOMIE_UNIT_KILOWATT: unit for power in kilowatts
HOMIE_UNIT_KILOWATTHOUR: unit for energy in kilowatt-hours
HOMIE_UNIT_LITER: unit for volume in liters
HOMIE_UNIT_LUX: unit for illuminance in lux
HOMIE_UNIT_METER: unit for length in meters
HOMIE_UNIT_MILI_AMPERE: unit for electric current in milliamperes
HOMIE_UNIT_MINUTES: unit for time in minutes
HOMIE_UNIT_MIRED: unit for color temperature in mireds (reciprocal megakelvin)
HOMIE_UNIT_PASCAL: unit for pressure in pascals
HOMIE_UNIT_PERCENT: unit for percentage
HOMIE_UNIT_PSI: unit for pressure in pounds per square inch
HOMIE_UNIT_SECONDS: unit for time in seconds
HOMIE_UNIT_VOLT: unit for voltage in volts
HOMIE_UNIT_WATT: unit for power in watts
HOMIE_VERSION: Homie major version used in the mqtt topic creation: “5”
HOMIE_VERSION_FULL: Homie protocol verison used in the device description: “5.0”
PROPERTY_ATTRIBUTE_TARGET: Property $target attribute topic under which the device can publish the desired target state
PROPERTY_SET_TOPIC: Property set attribute topic under which a set action is published to alter the devices state: “set”

Traits§

AsNodeId
AsPropPointer
ToTopic: This trait provides the capability to provide a mqtt topic for an object defining where it is published on the broker

Functions§

homie_device_disconnect_steps: Provides an iterator that yields all the necessary steps for disconnecting a device in order.
homie_device_publish_steps: Provides an iterator that yields all the necessary steps for publishing a device in order.
homie_device_reconfigure_steps: Provides an iterator that yields all the necessary steps for reconfiguring a device in order.
homie_str_to_vecu8
parse_mqtt_message: Parses an incoming MQTT message into a Homie5Message.