Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added Attributes to node properties #27

Merged
merged 4 commits into from
Aug 4, 2017
Merged

Added Attributes to node properties #27

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3ebeee7
Added description of property attributes
Jul 31, 2017
5473108
Corrections suggested in the PR.
Jul 31, 2017
a0fb66f
Differentiated between properties and attributes
Jul 31, 2017
3954576
Changes discussed in PR
Aug 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 135 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**Please note this v2 branch is a work-in-progress. It might change before the final release.**

Version: **2.0.0**.
Version: **2.1.0**.
Copy link
Member

@marvinroger marvinroger Aug 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As written in the above line, the v2 is not yet final, so we don't even need to bump the version. 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest to version the smaller increments anyways. As the final version is still a v2, what about 2.0.1 for the changes discussed here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say no, but as the v2 is already widely used, let's keep it this way.


Homie is a lightweight MQTT convention for the IoT.

Expand All @@ -18,7 +18,7 @@ You can find an implementation of the Homie convention:

## Background

An instance of a physical piece of hardware (an Arduino, an ESP8266...) is called a **device**. A device has **device properties**, like the current local IP, the Wi-Fi signal, etc. A device can expose multiple **nodes**. For example, a weather device might expose a `temperature` node and an `humidity` node. A node can have multiple **node properties**. The `temperature` node might for example expose a `degrees` property containing the actual temperature, and an `unit` property. Node properties can be **ranges**. For example, if you have a LED strip, you can have a node property `led` ranging from `1` to `10`, to control LEDs independently. Node properties can be **settable**. For example, you don't want your `degrees` property to be settable in case of a temperature sensor: this depends on the environment and it would not make sense to change it. However, you will want the `degrees` property to be settable in case of a thermostat.
An instance of a physical piece of hardware (an Arduino, an ESP8266...) is called a **device**. A device has **attributes**, like the current local IP, the Wi-Fi signal, etc. A device can expose multiple **nodes**. For example, a weather device might expose a `temperature` node and an `humidity` node. A node can have multiple **properties**. The `temperature` node might for example expose a `degrees` property containing the actual temperature, and an `unit` property. Node properties can be **ranges**. For example, if you have a LED strip, you can have a node property `led` ranging from `1` to `10`, to control LEDs independently. Node properties can be **settable**. For example, you don't want your `degrees` property to be settable in case of a temperature sensor: this depends on the environment and it would not make sense to change it. However, you will want the `degrees` property to be settable in case of a thermostat.
Copy link
Collaborator

@ThomDietrich ThomDietrich Jul 31, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example is not a good fit anymore. Unit is now it's dedicated attribute after all.
To illustrate the usage well we need more levels.

I'm not an expert on weather stations but how about something along this example:

  • homie/
    • weatherstation/
      • central/
        • temperature
        • humidity
      • windsensor/
        • direction
        • speed
    • coffeemachine/
      • ...

...Plus all the additional attributes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've modified the example to be more precise. Basically added a new property for the battery level to the example.

Copy link
Collaborator

@ThomDietrich ThomDietrich Aug 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be aware that you missed out on the "central" and "windsensor" nodes. With the text as it is right now the meaning of nodes and properties doesn't get clear.


## QoS and retained messages

Expand All @@ -35,14 +35,17 @@ An ID MAY contain only lowercase letters from `a` to `z`, numbers from `0` to `9
To efficiently parse messages, Homie defines a few rules related to topic names. The base topic you will see in the following convention will be `homie/`. You can however choose whatever base topic you want.

* `homie` / **`device ID`**: this is the base topic of a device. Each device must have an unique device ID which adhere to the [ID format](#id-format).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"a unique"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

* Attributes are topics that are prefixed with a `$`. These sub-topics add meta-data to Devices, Nodes and Properties describing their parent topic.

### Device properties

* `homie` / **`device ID`** / `$` **`device property`**: a topic starting with a `$` after the base topic of a device represents a device property. A device property MUST be one of these:
### Device attributes
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My suggestion was to move the sentence from above regarding the device below this headline and rename the headline to "Device". For the new reader it is pretty confusing that there is a headline e.g. "Node ...." and it immediately addresses attributes while the Node is not yet discussed. I'd suggest four big headlines "Homie Base", "Devices", "Nodes", "Properties".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added the heading "Devices", containing everything that describes devices in general

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks but it's still not how I imagine it. Feel free to ask if my suggestion wasn't clear. Also I'm not saying that my suggestion is the only and best solution, so let me know if you disagree with anything ;)


* `homie` / **`device ID`** / `$` **`device attribute`**: a topic starting with a `$` after the base topic of a device represents a device attribute. A device attribute MUST be one of these:


<table>
<tr>
<th>Property</th>
<th>Topic</th>
<th>Direction</th>
<th>Description</th>
<th>Retained</th>
Expand Down Expand Up @@ -139,6 +142,13 @@ To efficiently parse messages, Homie defines a few rules related to topic names.
<td>Yes or No, depending of your implementation</td>
<td>No</td>
</tr>
<tr>
<td>$nodes</td>
<td>Device → Controller</td>
<td>Nodes the device exposes, with format `id` separated by a `,` if there are multiple nodes. For ranges, define the range after the `id`, within `[]` and separated by a `-`.</td>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you replace the ` with <code> tags? The ` doesn't work in HTML arrays.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strange, in my Atom-Markdown preview this works as expected. I've changed it.

<td>Yes</td>
<td>Yes</td>
</tr>
</table>

For example, a device with an ID of `686f6d6965` with a temperature and an humidity sensor would send:
Expand All @@ -152,15 +162,14 @@ homie/686f6d6965/$fw/name → 1.0.0
homie/686f6d6965/$fw/version → 1.0.0
```

### Node properties

* `homie` / **`device ID`** / **`node ID`** / **`property`**: `node ID` is the ID of the node, which must be unique on a per-device basis, and which adhere to the [ID format](#id-format). `property` is the property of the node that is getting updated, which must be unique on a per-node basis, and which adhere to the [ID format](#id-format).
### Node attributes

Properties starting with a `$` are special properties. It must be one of the following:
* `homie` / **`device ID`** / **`node ID`** / **`node attribute`**: `node ID` is the ID of the node, which must be unique on a per-device basis, and which adhere to the [ID format](#id-format).
* A node is made discoverable via its node attributes. It must be one of the following:

<table>
<tr>
<th>Property</th>
<th>Topic</th>
<th>Direction</th>
<th>Description</th>
<th>Retained</th>
Expand All @@ -173,35 +182,148 @@ Properties starting with a `$` are special properties. It must be one of the fol
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>$name</td>
<td>Device → Controller</td>
<td>Friendly name of the Node</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>$properties</td>
<td>Device → Controller</td>
<td>Properties the node exposes, with format <code>id</code> separated by a <code>,</code> if there are multiple nodes. For ranges, define the range after the <code>id</code>, within <code>[]</code> and separated by a <code>-</code>. For settable properties, add <code>:settable</code> to the <code>id</code></td>
<td>Properties the node exposes, with format <code>id</code> separated by a <code>,</code> if there are multiple nodes. For ranges, define the range after the <code>id</code>, within <code>[]</code> and separated by a <code>-</code>.</td>
<td>Yes</td>
<td>Yes</td>
</tr>
</table>

### Property attributes
* `homie` / **`device ID`** / **`node ID`** / **`property`** / **`property attribute`**: `property` is the property of the node that is getting updated, which must be unique on a per-node basis, and which adhere to the [ID format](#id-format).
* A property is made discoverable via its property attributes. It must be one of the following:
<table>
<tr>
<th>Topic</th>
<th>Direction</th>
<th>Description</th>
<th>Valid values</th>
<th>Retained</th>
<th>Required</th>
</tr>
<tr>
<td>$settable</td>
<td>Device → Controller</td>
<td>Specifies whether the property is settable (<code>true</code>) or readonly (<code>false</code>)</td>
<td><code>true</code>,<code>false</code></td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>$unit</td>
<td>Device → Controller</td>
<td>A string containing the unit of this property. You are not limited to the recommended values, although they are the only well known ones that will have to be recognized by any Homie consumer.</td>
<td>
Recommended: <br>
<code>°C</code> Degree Celsius<br>
<code>°F</code> Degree Fahrenheit<br>
<code>°</code> Degree<br>
<code>L</code> Liter<br>
<code>gal</code> Galon<br>
<code>V</code> Volts<br>
<code>W</code> Watt<br>
<code>A</code> Ampere<br>
<code>%</code> Percent<br>
<code>m</code> Meter<br>
<code>ft</code> Feet<br>
<code>Pa</code> Pascal<br>
<code>psi</code> PSI<br>
<code>#</code> Count or Amount
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I miss a recommendation for (air) pressure. I propose Hectopascal (Unit hPa), because it is a (derived) SI-unit, other than Bar or mBar. You may add "PSI" as imperial unit.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added Pascal Pa(all other units are also listed in their in basic unit) and psi.

</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>$datatype</td>
<td>Device → Controller</td>
<td>Describes the format of data.</td>
<td><code>integer</code>, <code>float</code>, <code>boolean</code> (<code>true</code> or <code>false</code>), <code>string</code>, <code>enum</code> </td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>$name</td>
<td>Device → Controller</td>
<td>Friendly name of the property.</td>
<td>Any String </td>
<td>Yes</td>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Format of boolean should be defined. (What is allowed, is it case sensitive?) "true" and "false" or also "TRUE", "FALSE", 0, 1?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I've added this to the datatype.

<td>Yes</td>
</tr>
<tr>
<td>$range</td>
<td>Device → Controller</td>
<td>
Describes what are valid values for this property.
</td>
<td>
<ul>
<li><code>from:to</code> Describes a range of values e.g. <code>10:15</code>. <br>Valid for datatypes <code>integer</code>, <code>float</code> </li>
<li><code>value,value,value</code> for enumerating all valid values. Escape <code>,</code> by using <code>,,</code>. e.g. <code>A,B,C</code> or <code>ON,OFF,PAUSE</code>. <br>Valid for datatypes <code>enum</code> </li>
<li><code>regex:/pattern/flags</code> to provide a regex that can be used to match the value. e.g. <code>regex:/[A-Z][0-9]+/g</code>. <br>Valid for datatype <code>string</code></li>
</ul>
</td>
<td>Yes</td>
<td>Yes</td>
</tr>


</table>


For example, our `686f6d6965` above would send:

```
homie/686f6d6965/temperature/$type → temperature
homie/686f6d6965/temperature/$properties → degrees,unit
homie/686f6d6965/temperature/unit → c
homie/686f6d6965/temperature/degrees/$settable → false
homie/686f6d6965/temperature/degrees/$unit → C
homie/686f6d6965/temperature/degrees/$datatype → float
homie/686f6d6965/temperature/degrees/$range → -20.0:60
homie/686f6d6965/temperature/degrees → 12.07

homie/686f6d6965/humidity/$type → humidity
homie/686f6d6965/humidity/$properties → percentage
homie/686f6d6965/humidity/percentage/$settable → false
homie/686f6d6965/humidity/percentage/$unit → %
homie/686f6d6965/humidity/percentage/$datatype → integer
homie/686f6d6965/humidity/percentage/$range → 0:100
homie/686f6d6965/humidity/percentage → 79
```

A LED strip would look like this. Note that the topic for a range properties is the name of the property followed by a `_` and the index getting updated:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term range is now used in two different meanings in the convention.

  1. To allow "arrays" of properties.
  2. To define allowed value range

--> possible Solution: change $range to $valuerange
An alternative would be to change to range term (as used in the "old" convention) to something else, e.g. vector .

Copy link
Contributor Author

@gorootde gorootde Aug 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, this might get somehow confusing. I've changed the $range to $format, as "range" is the wrong term anyways. e.g. a regex is definitely not a "range", nor are enums.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$format seems perfect. @euphi ?

```
homie/ledstrip-device/ledstrip/$type → ledstrip
homie/ledstrip-device/ledstrip/$properties → led[1-3]:settable
homie/ledstrip-device/ledstrip/$properties → led[1-3]

homie/ledstrip-device/ledstrip/led_1/$settable → true
homie/ledstrip-device/ledstrip/led_1/$unit →
homie/ledstrip-device/ledstrip/led_1/$name → Red LEDs
homie/ledstrip-device/ledstrip/led_1/$datatype → enum
homie/ledstrip-device/ledstrip/led_1/$range → on,off
homie/ledstrip-device/ledstrip/led_1 → on

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I don't think it is a good idea to set the attribute of each property range-index individually. $settable, $unit, $datatype and $range (or $valuerange) should be the same for the complete range of the property and thus be defined on property level.
Ranges (or vectors) should simplify things and not make them more complicated. If you need individual attributes, use individual properties.

There may be a use for naming each ranged property:

  • I/O modules of industrial automation systems usually use formal names based on a simple numbering scheme (comparable to homie's range (or vector)), but allow to set an optional symbolic name.

homie/ledstrip-device/ledstrip/led_2/$settable → true
homie/ledstrip-device/ledstrip/led_2/$unit →
homie/ledstrip-device/ledstrip/led_1/$name → Green LEDs
homie/ledstrip-device/ledstrip/led_2/$datatype → enum
homie/ledstrip-device/ledstrip/led_2/$range → on,off
homie/ledstrip-device/ledstrip/led_2 → off

homie/ledstrip-device/ledstrip/led_3/$settable → true
homie/ledstrip-device/ledstrip/led_3/$unit →
homie/ledstrip-device/ledstrip/led_1/$name → Blue LEDs
homie/ledstrip-device/ledstrip/led_3/$datatype → enum
homie/ledstrip-device/ledstrip/led_3/$range → on,off
homie/ledstrip-device/ledstrip/led_3 → on
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following (unchanged) section is inconsistent with the LED example. I like the new definition with "On" or "Off" as state, so I propose to update the following section to make use of it. (No more "On"-state that is set to true or false).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it inconsistent? It describes how a client can set a property of the homie device, and how the device gives feedback about whether the value has been processed or not. Please clarify.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The next section in README.MD is unchanged and thus somehow inconsistent:

Homie is state-based. You don't tell your smartlight to turn on, but you tell it to put it's on state to true. This especially fits well with MQTT, because of retained message.

For example, a kitchen-light device exposing a light node would subscribe to homie/kitchen-light/light/on/set and it would receive:

homie/kitchen-light/light/on/set ← true

According to your propasal it is better to use

homie/kitchen-light/light/state/set ← on

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed. Alternatively homie/kitchen-light/light/power/set ← on

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed too. @Kwave feel free to choose between state and power. 😉

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok done. Replaced "on" with power in all topics.

Expand Down