Device profiles

[jacoscaz]

Hi! As I slowly work on a TypeScript / Node.js implementation of a Homie Controller, I was starting to look at the general concept of device profiles, which appears to be lacking from V5 of the spec.

I got here because I am planning to integrate my controller with Apple's HomeKit, which imposes certain requirements when it comes to the shape of a connected device. Window coverings must have a 0 - 100 position, for example. Mapping Homie devices to any other domain, including Apple HomeKit's, cannot be automated without the ability to make a few assumptions about their shapes.

Even leaving integrations aside, the same assumptions enabled by having devices declare which profiles they implement would dramatically simplify some UX and UI work in prioritising certain properties over others, depending on the nature of a device. In turn, this would also help with accessibility work.

Perusing through past discussions I stumbled into 1 and then into 2 and 3, both indicating that some thought and some work have already been put into this concept. Why is it not a part of the convention? Has there been further discussion that resulted into the deliberate choice of not supporting device profiles? Or is it simply a matter of time and interest?

Is there anyone else interested in pushing forward with device profiles?

[Tieske]

See https://github.com/homieiot/homie5-device-profiles

I rewrote what was done in this PR homieiot/homie5-device-profiles#8

TLDR; a lot needs to be done, but yes, we need profiles

[jacoscaz]

I don't know how I managed to miss that repo; thank you for pointing me to it.

At first glance and compared to my own investigations into how I would apply device profiles to the current V5 draft, the separation between capability profiles and device profiles feels to me like somewhat of an unbalanced tradeoff in terms of expressiveness vs. complexity, with too strong a bias towards the latter.

The waning interest by @schaze and this comment of yours, which I quote, make me wonder whether we could look for a different tradeoff.

I also don't like the overall result so far. I do like the strictness of the profiles I wrote, to be completely identical across implementations. But the massive wall of text it became and the number of rules and relations are too complicated.

Personally, having put some thought and done some prototyping in the last few weeks, I would suggest going for the simpler option of modelling profiles at the node level. The primary reason behind this approach is that a node doesn't necessarily have to represent a physical part of the device but can also represent a logical view of it, much like views in relational databases. Complex hierarchy of physical nodes, mirroring very complex devices, can still be complemented by simpler views that facilitate modelling across quasi-but-not-perfectly compatible domains.

As an example, I've recently been adding remote control capabilities to my window shutters via Shelly Wave Shutters. Using the Homie topology I would model each device as follows, mirroring their modelling at the Z-Wave level:

• node: multilevel switch
  • property: target position: 0 - 100 (% of opening) (read/write)
  • /* .... other properties .... */
• node: electric meter
  • property: power: number (power consumption in W) (read-only)
  • /* .... other properties .... */
• node: motor
  • property: state: 0 | 1 (whether motor is active or not) (read-only)
  • direction: 'OPENING' | 'CLOSING' (direction of rotation) (read-only)
  • property: current position: 0 - 100 (% of opening) (read-only)
  • /* .... other properties .... */

This representation closely matches what I'm getting via Z-Wave and is very powerful and expressive. However, it is also fairly complex, hard to map to other domains and hard to adequately represent in terms of UX and UI.

So, I would add is an additional complementary node:

• node: window covering with profiles ['window_covering']
  • property: target position: 0 - 100 (% of opening) (mandatory) (read/write) (duplicate)
  • property: current position: 0 - 100 (% of opening) (mandatory) (read-only) (duplicate)
  • property: state: 0 | 1 (whether motor is active or not) (mandatory) (read-only) (duplicate)

This node effectively duplicates a subset of the information already present in other nodes but does so in a way that would match a hypothetical window_covering profile. This way, controllers dealing with complex devices would simultaneously retain the ability to monitor and/or control any possible aspect of the device (if guided by human or, these days, a reasonably capable LLM) while still having access to a "known quantity" safely assumed to have certain characteristics.

That said, in most cases devices are simple enough that I do not think they would require dedicated, logical nodes in order to implement profiles. They would likely only require one node implementing whatever profile describes that specific class of devices. Property duplication would only take place in those cases in which a device is so complex that its actual, physical structure / topology does not match a profile.

[Tieske]

have you seen the $target attribute in homie5?

You can have a position that has a value of the actual position, and a $target attribute. From that most info can be derived; opening/closing, motor active or not. This is pretty much the exact use-case of that attribute.

mirroring their modelling at the Z-Wave level

This feels like mapping a profile to specific hardware, I think it should map to a functionality independent of hardware. And that is the hard part.

[jacoscaz]

Hello!

have you seen the $target attribute in homie5?

Indeed I had, though yesterday I failed to account for it in my examples. Thank you for reminding me of it. I will make better examples in the rest of this post.

This feels like mapping a profile to specific hardware, I think it should map to a functionality independent of hardware. And that is the hard part.

I agree, that is the hard part, but that's exactly the reason behind my argument for "logical" nodes. I think I did a bad job at illustrating it yesterday, let me try again.

The starting point of my argument is that having separate capability-level and device-level profiles would likely lead to an exceedingly complex specification, as mentioned in homieiot/homie5-device-profiles#8 . The solution I propose is focusing solely on node-level profiles.

In the majority of cases, implementors would simply expose a node implementing the profile matching the type of device. For example, in the case of a simple shutter controller:

• device: shutter controller
  • node: default implementing profiles ['window_covering']
    • property: position: 0 - 100 (% of opening) (mandatory) (read/write)
    • property: state: 0 | 1 (whether motor is active or not) (mandatory) (read-only)

However, profiles generally cover the minimal subset of functionality that is assumed to be present in devices of a given type. In the specific case of my shutter controllers, for example, the Z-Wave modelling follows a much more hardware-specific hierarchy:

• device: shutter controller
  • node: motor
    • property: position_a: 0 - 100 (% of opening) (mandatory) (read/write)
    • property: state_a: 0 | 1 (whether motor is active or not) (mandatory) (read-only)
    • property: position_b: 0 - 100 (% of opening) (mandatory) (read/write)
    • property: state_b: 0 | 1 (whether motor is active or not) (mandatory) (read-only)
  • node: electric meter
    • property: power
  • node: configuration
    • property: swapped_inputs
    • property: swapped_outputs
  • node: alarms
    • property: heat_warning
    • property: overcurrent_warning

I agree that this hierarchy is exceedingly hardware-specific and cannot be taken as a reference point for how a profile should look. However, I also believe that profiles and hardware-specific hierarchies should not be mutually exclusive and that the spec should accomodate for both. So, how do we reconcile the two?

The solution, in my opinion, could be allowing implementors to duplicate information between nodes, so that a hardware-specific hierarchy could be complemented by "logical" nodes implementing specific profiles:

• device: shutter controller
  • node: default implementing profiles ['window_covering'] (THIS IS THE "LOGICAL" NODE)
    • property: position: 0 - 100 (% of opening) (mandatory) (read/write) (duplicate)
    • property: state: 0 | 1 (whether motor is active or not) (mandatory) (read-only) (duplicate)
  • node: motor
    • property: position_a: 0 - 100 (% of opening) (mandatory) (read/write)
    • property: state_a: 0 | 1 (whether motor is active or not) (mandatory) (read-only)
    • property: position_b: 0 - 100 (% of opening) (mandatory) (read/write)
    • property: state_b: 0 | 1 (whether motor is active or not) (mandatory) (read-only)
  • node: electric meter
    • property: power
  • node: configuration
    • property: swapped_inputs
    • property: swapped_outputs
  • node: alarms
    • property: heat_warning
    • property: overcurrent_warning

With this approach, integrations and UX/UI work could benefit from the assumptions implicit in nodes implementing specific profiles while maintaining the spec's wonderful capability to model any hierarchy and topology.

[schaze]

This is actually exactly the way I defined my smarthome profiles. It is all done on a node level.
A light bulb might have the following definition:

• node: switch
  type: homie-homecontrol/v1/type=switch
• node: dimmer
  type: homie-homecontrol/v1/type=dimmer
• node: colorlight
  type: homie-homecontrol/v1/type=colorlight

Depending on what the light bulb supports all or only some of them will be there. If it is only a white dimming bulb colorlight will not be there or if it is only a plug or a non-dimmable bulb you would have only a switch node and nothing else.
Based on the available node types you can take assumptions for what components a UI shows to control the device.

Actual Device definition as an example:

{
  "name": "wz_stehlampe_papier_1",
  "version": -2478458571223613400,
  "homie": "5.0",
  "root": "dev-deconz2homie",
  "parent": "dev-deconz2homie",
  "nodes": {
    "switch": {
      "name": "On/Off switch",
      "type": "homie-homecontrol/v1/type=switch",
      "properties": {
        "action": {
          "name": "Change state",
          "datatype": "enum",
          "format": "toggle",
          "settable": true,
          "retained": false
        },
        "state": {
          "name": "On/Off state",
          "datatype": "boolean",
          "format": "off,on",
          "settable": true,
          "retained": true
        }
      }
    },
    "dimmer": {
      "name": "Brightness control",
      "type": "homie-homecontrol/v1/type=dimmer",
      "properties": {
        "action": {
          "name": "Change Brightness",
          "datatype": "enum",
          "format": "brighter,darker",
          "settable": true,
          "retained": false
        },
        "brightness": {
          "name": "Brightness Level",
          "datatype": "integer",
          "format": "0:100",
          "settable": true,
          "retained": true,
          "unit": "%"
        }
      }
    },
    "colorlight": {
      "name": "colorlight",
      "type": "homie-homecontrol/v1/type=colorlight",
      "properties": {
        "color": {
          "name": "Color",
          "datatype": "color",
          "format": "xyz",
          "settable": true,
          "retained": true
        },
        "color-temperature": {
          "name": "Color temperature",
          "datatype": "integer",
          "format": "153:555",
          "settable": true,
          "retained": true
        }
      }
    }
  }
}

[schaze]

I created a whole dashboard application for homie with this: https://github.com/homie-homecontrol/hc-dashboard

[jacoscaz]

@schaze that's super cool! And, I'm happy to see that the node-level approach worked so well! Would you be interested in working on a collection of profiles to later put forward as a (proposed) attachment to the spec? We could start from your own if you'd like!

[schaze]

@jacoscaz: I would be interested as long as we keep on a node level and do not add additional topics to the spec on mqtt level. My initial idea was to only have a few definitions of different type profiles (on a node level) that uses the homie5 spec as is. Besides these points I am opinionated on some things regarding the profiles but in general open on how to approach it. I would welcome more input since the ones I have are pretty much based only on my needs and I have no real grip on how useful they are for someone else.
@Tieske: I know this differs quite a bit of what you intended with work we (pretty much you) did on the profiles so far - but would you also be on board with this?

[jacoscaz]

I would be interested as long as we keep on a node level and do not add additional topics to the spec on mqtt level. My initial idea was to only have a few definitions of different type profiles (on a node level) that uses the homie5 spec as is.

@schaze this is exactly where I am at. I don't want to change the spec. The underlying principles feel very solid and I think it's a brilliant spec. However, I am myself working on both a) a dashboard and b) bridging with the HomeKit ecosystem and none of these two can be done without profiles. I also 100% agree on keeping profiles at the node level as a nice, balanced compromise that allows implementors to model devices however they see fit while also offering the option of adding "typed" nodes to project subsets of their devices into known shapes.

[dcj]

I just found/saw this thread....

I am beginning to think about how to bridge Matter to Homie.

The Matter "data model" is complex, IMO because the domain it is attempting to represent is itself complex, and I am quite the Matter-newbie, so I have a lot to learn before I can be at all confident to define any sort of reasonable Matter->Homie mapping.

AFAICT, Matter has "nodes" (what I think of as a physical device), and nodes contain "clusters", one of which may be a "composed cluster", and a "cluster" generally has some number of "endpoints".
(When thinking in the context of both Matter and Homie, I'm afraid I am going to need to be precise about a Matter-Node vs a Homie-Node...)

Very roughly (and with no confidence at all), I am thinking:

• The Matter bridge would be a Homie-root-device, with MANY children
• Each Matter node would be a Homie-child-device
• Not sure yet about Matter clusters and endpoints, maybe a cluster is a Homie-child-device of the Matter-node-Homie-child-device, and that the Matter-endpoints are Homie-nodes within the cluster-Homie-child-device. Or not, IDK yet...

Anyway, just wanted to mention my thinking/effort and I will contemplate the seemingly related thinking to HomeKit in this issue

[Tieske]

Matter derives from Zigbee. Which came later than Zwave, hence zigbee and matter have a more complex model. And zwave has some legacy to deal with, due to their over simplified structure.

The main thing is the separation of physical and logical devices, which is something that Homie doesn't have to care about since it only caters for functional devices (relations in the physical world are represented in Homie as parent-child-device relations)

zigbee/matter	meaning	dimmer-module	2-relay module
device/node	a physical device/module	hw device	hw device
endpoint	a logical device within a physical device	1: a light	2: 2 switches
cluster	a grouping that serves a single functionality	2: dimmer + switch	1: switch (per endpoint)

This is a hardware model, where there is a distinction between physical devices and logical devices. Homie doesn't have the distinction, but does allow you to model it through child devices.

Mapping it to Homie:

zigbee	homie
device	device (container; device with child devices)
endpoint	device (typed; dimmable-light/switch)
clusters	node (dimmer node, or switch node)

Examples of mapping the devices to homie:

2-relay module	homie
the physical module	device (container)
for each relay	1 homie child-device (typed)
on/off capability	1 node of on/off type (per child-device)

dimmer-module	homie
the physical module	none, since there is only 1 device, there is no need for a parent
dimmer module	1 homie device; dimmable-light
on/off + dimmer	2 nodes: a switch and a dimmer

[Tieske]

@Tieske: I know this differs quite a bit of what you intended with work we (pretty much you) did on the profiles so far - but would you also be on board with this?

I don't think they are that different. What I wrote also is on Node level, same thing. Just more elaborate.

I do think however that device profiles are also needed;

• Say I have 2 devices, they both have a power switch and a level control. One is a dimmable light, the other a variable-speed pump. How would I tell the difference? imho we should label the device with a profile (even if the profiles are identical, just named differently)
• Also; nodes aren't necessarily independent. One could influence the other. That behavior should be documented to be consistent across implementations. The place to do this would be a device profile imho.

As for adding topics to the spec; I agree we shouldn't add anything to the spec. However, I think we do need a topic to identify a device or node profile (see my proposal in the discussion wrt namespacing the type). This is very powerful considering that we can query the MQTT server for only the devices/nodes we need. It can be specified in an extension, doesn't need to go in the spec. I named it $profile in my docs.

[jacoscaz]

Say I have 2 devices, they both have a power switch and a level control. One is a dimmable light, the other a variable-speed pump. How would I tell the difference? imho we should label the device with a profile (even if the profiles are identical, just named differently)

I think I see what you mean but, IMHO, being able to discriminate whether a device is a pump or a dimmable light doesn't necessarily have to depend on implementing different device-level profiles.

For example, the nature of a device could be inferred by looking at $description.name and $decription.type, assuming we could use the latter to generically indicate the class of the device (light, pump, ...) and reserve the $profile topic for signalling implementation of profiles.

Furthermore, does a dimmable light need to be controllable or would it be acceptable for a possible implementation to only report on the current brightness level? Should that difference even matter when defining the nature of a device? IMHO, no, it should not. A light is a light, regardless of whether it can also be controlled or merely polled for its state. Profiles as descriptors of (available) functionality should not be used to define the nature of a device.

Eventually, in the long term, I do expect device-level profiles to emerge as a separate concept. In the short term, however, I think working on node-level profiles alone would be a better compromise between expressive power and simplicity.

As for adding topics to the spec; I agree we shouldn't add anything to the spec. However, I think we do need a topic to identify a device or node profile (see my proposal in the discussion wrt namespacing the type). This is very powerful considering that we can query the MQTT server for only the devices/nodes we need. It can be specified in an extension, doesn't need to go in the spec. I named it $profile in my docs.

Yes, agreed!

(I'll be on a break until wednesday 23/04 but following with interest)