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

Add subheading for "Property command topic" #145

Merged
merged 7 commits into from
Nov 29, 2018
Merged

Add subheading for "Property command topic" #145

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0909252
Add subheading for "Property command topic"
Nov 29, 2018
d557fba
Update convention.md
Nov 29, 2018
3adfcf5
Update convention.md
Nov 29, 2018
90eedd0
Update convention.md
Nov 29, 2018
91e2e07
Update convention.md
Nov 29, 2018
40aeb15
Update convention.md
Nov 29, 2018
4a14278
Update convention.md
Nov 29, 2018
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
15 changes: 8 additions & 7 deletions convention.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,20 +282,21 @@ Recommended unit strings:

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.

* `homie` / `device ID` / `node ID` / `property ID` / **`set`**: the device can subscribe to this topic if the property is **settable** from the controller, in case of actuators.
#### Property command topic

Homie is state-based.
You don't tell your smartlight to `turn on`, but you tell it to put its `power` state to `on`.
This especially fits well with MQTT, because of retained message.
* `homie` / `device ID` / `node ID` / `property ID` / **`set`**: The device must subscribe to this topic if the property is **settable** (in case of actuators for example).

For example, a `kitchen-light` device exposing a `light` node would subscribe to `homie/kitchen-light/light/power/set` and it would receive:
The assigned and processed payload must be reflected by the Homie device in the property topic `homie` / `device ID` / `node ID` / `property ID` as soon as possible.
davidgraeff marked this conversation as resolved.
Show resolved Hide resolved

A Homie controller publishes to the `set` command topic with non-retained messages only.
ThomDietrich marked this conversation as resolved.
Show resolved Hide resolved

To give an example: A `kitchen-light` device exposing the `light` node with a settable `power` property subscribes to the topic `homie/kitchen-light/light/power/set` for commands:

```java
homie/kitchen-light/light/power/set ← "true"
```

The device would then turn on the light, and update its `power` state.
This provides pessimistic feedback, which is important for home automation.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I would keep "pessimistic feedback" in the document.

Copy link
Member Author

Choose a reason for hiding this comment

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

I have changed the wording, maybe you can come up with a different approach. I'd rather not have the original sentence, the statement is made without any proof.

Copy link
Collaborator

Choose a reason for hiding this comment

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

How about:

After the device successfully received and processed the command, pessimistic feedback is given by publishing the new state of the property:

Copy link
Member Author

Choose a reason for hiding this comment

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

As soon as feedback is given (publishing happened), it is neither pessimistic nor optimistic feedback, it is just feedback. The process/procedure itself (publish to prop/set -> processing -> publish to prop) is pessimistic feedback and that isn't conveyed in this sentence.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Completely correct. Okay let's leave it out. I'll edit my other comment.

Following a pessimistic feedback pattern, the device updates its `power` state as soon as turning on the light worked.
davidgraeff marked this conversation as resolved.
Show resolved Hide resolved

```java
homie/kitchen-light/light/power → "true"
Expand Down