Implementation guideline for client/controller developer

[ThomDietrich]

Derived from #28 (comment)

Besides all the technical definitions of the Homie convention, we should give simple checklist-like instructions for developers on how to comply with the Homie convention. There are many (technical and logical) details that need to be handled, which are not easily described in the convention itself.

I believe the guideline will further clarify the benefits of the Homie convention and ease the adaption for unacquainted developers.

@marvinroger Please label with "help wanted"

[marvinroger]

Do you think we need to write this guideline before releasing the v3?

[ThomDietrich]

No. Would be useful but it doesn't influence the convention. Can be v3.0.1 ;)

[timpur]

@ThomDietrich I'm happy to write up draft from my experience of implementing the discovery process and I hope @davidgraeff can help me with that and ofcause anyone else who want to contribute.

[timpur]

#93 (comment)

It is absolutely not about the semantic of an input or output. It is just about controllers knowing of all available inputs and ouputs and their data types (int, bool, string, etc).

Just to calcify @davidgraeff, this would have nothing to do with the spec, but more as help on how to use the spec if a dev wants it. It will help future people like you and me know where to start to discover all the homie devices :P as the title says: a guideline

[ThomDietrich]

Exactly. The guideline will help developers on both sides (controller and client/device) implement MQTT communication in compliance with the Homie convention.

As I wrote before I believe a simple item list would be enough. The simpler the better.

[ingoogni]

I'm getting utterly confused by this opening and closing and moving of discussion. Can't we have a decent mailinglist or even Gitter (meh) for discussing things. This is worse than USENET 30y ago.

@davidgraeff thanks for "It is just about controllers knowing of all available inputs and ouputs and their data types (int, bool, string, etc" that clarifies somewhat.
What does homie does not do yet? What is not possible yet? Does it need programming? Is it a matter of standardising certain types of topics? Is there an MQTT auto-discovery convention? Would that be useful? Who should adapt?

(I don't use it as everything I build is made to fit and "hardwired" (even in software) yet still interested)

[ThomDietrich]

This is the way how issue ticket systems work for thousands to millions of projects on all kinds of platforms. They normally work quite well as long as people don't mix issues and discuss one single topic in one single issue.

Is it a matter of standardising certain types of topics? Is there an MQTT auto-discovery convention?

I'm confused. This IS the purpose of Homie :)

[davidgraeff]

@ingoogni The spec is definitely not written for someone that has never seen MQTT before or has never thought about M2M communication. It does its best to introduce to the topic though and I would say it does a good job. All your questions are actually answered explicitly or implicit.

There is only one point, that I had to made up while implementing the controller side. And that is the response time. The MQTT broker does acknowledge a subscription, but it does not tell if there's any value for the given topic. I have decided to wait a maximum of 200ms for a value to arrive and otherwise assume there is none. The entire tree discovery has a time limit of 1500ms in my implementation.

[fermuch]

There is only one point, that I had to made up while implementing the controller side. And that is the response time. The MQTT broker does acknowledge a subscription, but it does not tell if there's any value for the given topic. I have decided to wait a maximum of 200ms for a value to arrive and otherwise assume there is none. The entire tree discovery has a time limit of 1500ms in my implementation.

Does this need to be standarized, or is it different for every project? On my implementation I wait until every device is $state = ready, then wait 500ms for all pending messages to arrive, to assume a full discovery.

[davidgraeff]

A recommended time could be added for implementors. The connection can't be influenced of course. Sometimes it just takes longer.

[timpur]

Also, should we be defining which discovery attributes need to be published first and in order? eg $homie first then $node then $properties, then all the rest? (As order of how i see discovery done)

This would help most when a new device is added to the network, ensuring that a clean discovery is made?

@davidgraeff i was hoping to work with you to define how to discover a homie device, would be nice to get another opinion on they they precise as the best way, because there more than one...

[davidgraeff]

Hm. The order of published topics doesn't matter actually if everything happens within 200ms (e.g. the timeout of an attribute). There are even two contradicting scenarios:

The device is already known

Every node and property is retained. We expect the worst case: The device has a whole set of new nodes and some old nodes removed. --> It would be less confusing for the controller if first device, then nodes, then properties are published.

The device is new to the network

It would be less confusing for the controller if first properties, then nodes, then the device is published. As soon as the device/$homie topic appears, the controller starts to parse all the (already available) sub topics.

[davidgraeff]

I would say this does not belong to the spec repository, but to the website. Any disagreements?

I suggest adding implementation notes here: https://github.com/homieiot/convention-website/tree/master/docs/Implementations somewhere.

[marvinroger]

It’s not part of the convention, indeed. 👍

[davidgraeff]

@marvinroger Could you use https://github-issue-mover.appspot.com/ or similar to move this Issue to the webpage repo?

[marvinroger]

This issue was moved to homieiot/convention-website#3

[ThomDietrich]

@marvinroger @davidgraeff @jamesmyatt I feel this is really a part of the convention rather than cosmetics that would be discussed in the website repo.

[ThomDietrich]

An example how this document could look like:

Homie Implementation Guideline and Best Practices

...

Set

Homie device implementation guideline: ...

Homie client/controller implementation guideline: ...

FAQ

• Why are messages on the set topic not retained? Retained set commands #150
  • Because reasons a, b and c.
  • For use case "..." it is recommended to do this and that.

[mjcumming]

@ThomDietrich have you done anymore work on this?