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.

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

Add subheading for "Property command topic" #145

Merged
merged 7 commits into from
Nov 29, 2018
Merged
Changes from all commits
Commits
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
16 changes: 9 additions & 7 deletions convention.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,20 +282,22 @@ 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:
A Homie controller publishes to the `set` command topic with non-retained messages only.

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.
This property state update not only informs other devices about the change but closes the control loop for the commanding controller, important for deterministic interaction with the client device.

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.

In response the device will turn on the light and upon success update its `power` property state accordingly:

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