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 1 commit
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
100 changes: 96 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ 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).
* `homie` / **`device ID`** / **`node ID`** / **`property`** / **`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). `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).

Properties starting with a `$` are special properties. It must be one of the following:

Expand All @@ -176,32 +176,124 @@ Properties starting with a `$` are special properties. It must be one of the fol
<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>

#### Attributes
An attribute describes various aspects of a property and therefore makes it auto-discoverable by any other device. A property can be described using the following attributes:
<table>
<tr>
<th>Attribute</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>#</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>string</code>, <code>enum</code> </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/</code> to provide a regex that can be used to match the value. e.g. <code>/[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 → LED Status
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 → LED Status
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 → LED Status
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