Automation for homie

[schaze]

Hi,
I am working on what I call an automation controller for homie. It is a rewrite of a service I am already running my complete smarthome with since about 2-3 years. It will be part of my overall smarthome solution I am building.

The intention of this post is to let you know in case this might be useful for anyone and to get some feedback. :-)

It consists of basically 2 main parts:

• rule engine
  • rules can be defined in yaml to handle things like "when switch is pushed, turn the light on)
  • also includes a lua scripting runtime to handle more complex rules
• virtual device manager
  • publish virtual homie devices that can be used for things like holding configurations for automations
  • create composite properties that aggregate values of other device properties using different functions (like max or a boolean AND or OR)

In addition it is also able to use normal mqtt topics as input or output for rules and virtual devices.
I have the rule engine mainly done in rust and am currently working on the virtual device manager.

The code is not yet published but here are some examples:

Rules

Rules look like the following:

• name: A human readable name for the rule
• triggers: A list of different trigger definitions that will cause rule to trigger
• actions: A list of actions to be executed when the rule is triggered

Triggers

There are the follwing triggers:

• Property trigger: a property publishes a certain or any value - for retained and non-retained properties
  • properties can be specified directly via homie_domain/device-id/node-id/prop-id or
  • via a query on any of their device, node and property description attributes
• Property changed: a property value changes from a certain/any value to a certain/any value - only for retained properties
  • properties can be specified directly via homie_domain/device-id/node-id/prop-id or
  • via a query on any of their device, node and property description attributes
• Timer: A timer with a certain id triggers
• Cron: Specify an interval via cron expression at which the rule should trigger
• MQTT: Subscibes to any arbitrary mqtt topic and triggers based on the value published
• Solar event: Define a solar event like "sunrise" with optional time delta when the rule should trigger
• On set: A set message was sent to a virtual device (so you can handle the internal virtual device logic in a lua script action in the rule)

All triggers support a list of conditions that can be specified in addition to the trigger. E.g. Timer triggers but only while a certain other property has a certain value or it is a specific time of day.

Actions

The following actions are supported:

• Set: Set a property to a certain value
• Map set: Set a property to a value mapped from the triggering value
• Toggle: Toggle a boolean property
• Run script: Execute a lua script (defined in the yaml or later on in lua files in a certain folder) with more complex logic to handle the action/rule
• Timer: create a timer with a specified id, duration and optional repetition interval
• Cancel timer: Cancel a timer with a certain id
• MQTT: publish a value to a certain mqtt topic

Examples

This is a simple rule that will toggle a zigbee light group whenever a button on a certain switch sends (any) value or a xiaomi magic cube flipped by 180 degrees.

name 'ez-lights'
triggers:
  - subjects:
      - switch-77/button-2/action 
    condition:
      type: triggered
  - subjects:
      - cube-23/cube/gesture
    condition:
      type: triggered
      triggervalue: flip180
actions:
  - type: set
    target: group-4/switch/action
    value: 'toggle'

Here is a rule that will execute on a 5min time to give a reminder to close the window again. If the window is closed in the meantime (state property goes back to 'false'), the timer will be cancelled and no notification happens.

name: window_open_notify
trigger:
  - queries:
      - node:
          id: contact
        property:
          id: state
    changed: {}
action:
  - type: run
    script: |-
      --- get the reference to the property that triggered the rule
      local prop = event.prop
      local desc=homie:get_device_description(prop)
      print("==> Window open. Please close:", desc.name)
    timer:
      id: window-timer
      duration: 300
      triggerbound: true
      cancelcondition:
        Bool: false

Virtual devices

A virtual device is a basically a definition of a homie device description with additional options.

Extra options:

• predefined node types from my smarthome definition that will generate the node and property definitions without having to specify everything from scratch (from_smarthome)
• option to simply pass through the set value (meaning the device will publish the requested set value immediately as the property value)
• option to read the state of the property from mqtt on start of the virtual device before it is set to ready. (in case of a service restart this will restore the property value from mqtt again)

Examples

Virtual device aggregating all window contacts into one property to check if any is open

---
id: windows
name: Indicates if any windows are currently opened
nodes:
  - id: window-contacts
    name: window contact statess
    properties:
      - id: state
        datatype: boolean
        compound_spec:
          members:
            - oeq0429851/contact/state
            - oeq0706187/contact/state
            - meq0753071/contact/state
            - req0227787/contact/state
            - oeq0431016/contact/state
            - oeq0429971/contact/state
            - meq0753110/contact/state
            - meq0753061/contact/state
            - oeq0706059/contact/state
            - oeq0706161/contact/state
            - meq0753104/contact/state
            - oeq2132349/contact/state
            - sensor-70/contact/state
          aggregate_function: or

id: glob-settings
name: Global Settings
nodes:
  - from_smarthome: 
      type: switch
    id: auto-shutter
    name: Raise shutters in the morning automatically
    pass_through: true
    property_opts:
      read_value_from_mqtt: true
      read_timeout: 10000

About homecontrol:

The solution I am building is called homie homecontrol - which is actually finished (for me at least) for v4 since years, but I never had the time to publish it all. The old one is completely based on nodejs. Now I started to rewrite it all for v5 with my rust library. But e.g. for things like the Dashboard or the NodeRed Plugin I will still most stay with nodejs, so my plan will also be to bring the node-homie library to full v5 compliance.
The whole system is designed to be a solution based on different single services only coupled via the homie protocol. This means things like zigbee devices (e.g. via a hue bridge) or other smarthome solutions publish their devices via mqtt homie and then you have at the heart the above mentioned automation controller to automate things.

The great thing is as long as everyone follows the homie convention this can be extended by anybody.

[Tieske]

Are you building all of this in a single application? Or when you mention the 2 main parts; logic controller, and virtual device manager, would they become 2 separate applications coupled only via Homie?
imho the latter is the more powerful option.

[schaze]

When I developed the v4 version, I initially considered separating the "Virtual Device Controller" and the "Automation Controller" into two distinct applications, each loosely coupled only via the Homie protocol. However, I quickly realized that combining them into a single application made far more sense for several reasons, which I believe still are valid today:

1. Logic Implementation for Virtual Devices
   Virtual devices often require logic to handle more complex tasks, which necessitates a rule engine or similar functionality. For instance, to handle /set messages for a virtual property, you may need to implement logic or execute actions. A common scenario is creating a virtual device that acts as a proxy for a device or service exposing only an HTTP API endpoint. In this case, you’d need to:

   • Send an HTTP request upon receiving a /set message.
   • Update the virtual property’s state based on the result of the HTTP call.
     Without a rule engine integrated directly into the virtual device manager, you would need to implement many predefined logic options which will never be as flexible as e.g. a few lines of integrated lua code. So in the end you wind up writing another rule engine just for the virtual devices.

2. Internal State Updates
   The Homie protocol doesn’t provide a mechanism to update and publish the internal value of a virtual property from an external application managing the virtual device. This makes it impractical to separate the virtual device logic into another application, as you don't have the ability to properly manage and synchronize the virtual property states. You could define some protocol spec for this via mqtt but this would also add another roundtrip via mqtt for every update which impacts performance.

That said, basic "dummy" devices that simply accept /set messages and publish the received values—or even compound/aggregate devices that rely solely on predefined aggregation logic—would work without a rule engine. However, the moment you require more complex functionality, integrating the logic into the same application becomes essential.

For these reasons, the application is (and will remain) a combined solution.
However, this design still allows flexibility: if you only need virtual devices without any rules, the rule engine won’t allocate significant resources. This ensures that the application can adapt to varying use cases without forcing unnecessary overhead.