homieiot / convention Goto Github PK

Anyone have ideas for homie V3.1?
Some Outstanding Discussions:

• Stats implemented as a Node
• #53
• Bits that didn't get addressed from #62
• #51 and #65
• #72

What, I think, needs to be changed:

@marvinroger

• Background:

  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.

I would talk about attributes after devices, nodes, properties are introduced. Therefore we can talk about attributes all at once.

• Base:

I would make a "base" headline, where we talk about the root homie/ topic and where we say that Attributes are topics that are prefixed with a $.

• Remove $signal and $fw/versionchecksum. This is implementation-specific, and can be sent to $implementation/signal and $implementation/fwchecksum if needed

• Make the $format regex simple (without delimiter and flags)

• Rename $range to $array

• In the LED strip example, make all "array elements" share the same datatype, format, etc.

• Parsing tips for developers

• Web UI where we could create devices, nodes and properties and see the resulting MQTT messages, for reference

Wondering if its better to use the last will to post information about unexpected connection lost

Currently disconnecting correctly and unexpected are the same = false at $online

Wondering if its better to use a number, 1 = online, 0 = offline and -1 = unexpected connection lost ??

Tell me what you think.
Tim.

Hey!

I'm using ranged properties (as per your SDK for homie on esp8266).

zoneNode.advertiseRange("on", 1, 3).settable(zoneOnHandler);

What would be the standard message to MQTT to send range 1 with value X?
eg. devices/c40f46e0/zone/on[1]/set ??

Sorry I just couldn't find any documentation on how to handle it.

Kind regards,
Luke

In case you have a node property of type enumeration, but this enumeration has many elements, it can be useful to still use integer values for MQTT communication. However, also in these cases you want to announce the possible values with their meaning.

The current 3.0 convention allows to announce enumerations with their possible allowed values, but no mapping of integer values to a meaning.

As an example, in my ESP_Homie_WS2812FX Node there is a "mode" property that allows all modes from the WS2812FX lib. However, when setting a new mode, I still want to receive the new mode as integer, because it is much easier to parse.

So, for the announcement there should be a way to announce the mapping of the integer to it's corresponding mode name, e.g 46: Fire Flicker, 47: Fire Flicker (soft) etc.

What is your opinion about this?

• Don't use integer, when you want something else, so send a string with the mode's name.
• Lets extend the enum "format", so you can give each allowed enumeration value a description string.
• Add a new dataype map that maps allowed integer values to a string.

homie / homie version / device ID / $ device attribute would make it easier for clients to subscribe to versions they're compatible with.

You might even go so far as to use something like homie / major / minor / patch / device ID, following the semVar convention. That would look something like homie/2/1/0/someDeviceId.

This would also allow devices to support backwards-compatibility, to a certain extent.

The convention now states a limited list of device properties.
I would however want to add a few more: a device could have a battery level, cpu load, free memory, temperature,...

For not to break the convention, I now create a "device-node" with the node properties as above, which I find not entirely correct.

(It is working however, so if the community -and off course you Marvin- doesn't agree with me, I'll stick to my current solution.)

Any plans for the final release of the convention?

Also @marvinroger can you add me as contributer please :)

In my pursuit to make a Homie Addon for Home Assistant, ive discovered that not having $nodes like $properties make a huge difference in how you discover nodes... So i propose a small change to add this to v2 as v2.0.1

Its also such an easy thing for implementations to implement so i see no reason not to. I know v3.0.0 has but thats a whole redesign and breaking changes to implement and will take time...

@marvinroger @ThomDietrich

Hello, are you familiar with OCF and Iotivity?

It seems that there are similarities in the mission of Homie and OCF.

i am looking for an framework, with mqtt, rest and an ui support, your framework looks nice, is there any support for rest ?

Thank in advance
BR Lars

In the past days, working with the Homie Convention, I on occasions thought, this [...] is missing, on deeper though it was not. But, there is always a but, I now ran into an "omission" that I think would be a useful addition to the convention:

homie / device ID / node ID / property / property attribute

• Topic: $interval
• Direction: Device --> Controller (Device <--- Controler?)
• Description: A string containing the description of the temporal behaviour of a node's property. The interval at which messages are published or (not completely sure here) messages are, expected, to be received in case of a settable property.
• Valid Values: A string containing the interval in seconds (float)... ---see EDITs
  EDIT A string containing a value or or one of the strings "on-change", "once", "on-request" (other strings ...?)
• Retained: Yes
• Required: No

EDIT: as intervals do not have to be seconds but can also be other units as meters or °C another property attribute may be needed: $intervalunit
(see in discussion below)

Property attribute:
$interval is an attribute of a property, not a property of a node (although a node could have). It tells us something about the data being published. My CO2 sensor measures every 5 seconds, I have the data published ever 10 seconds and a min, avg, max every 5 minutes.

Some use cases:

Monitoring;
A client can be written that monitors the timely arrival of data packets and responds to the situation.

Time series;
Even if it would be easy to add time stamps to data it is a bit clumsy to write time series to a database row by row by time stamp. Easier is it to write only a start and or end time and write the data to an array in the DB, that though needs a regular and known interval for the data. A published $interval is this and makes it possible to for a client to note missed packets and write null data in such an array. A round robin database can use $interval for setting the 'heartbeat'.
A series Timestamps itself will not tell us whether they come in at the set or required interval.

State changes;
During a process the state of a sensor can change and with it its publishing frequency. With a (re-)published interval clients can adapt.

Stale Data;
As all messages are published retained a newly active client can determine by use of the $interval whether the first dataset received by the broker is stale and discard it in that case.

Shouldn't the $signal be treated same as the $uptime in v2?

Therefore I propose:
$signal/value
$signal/interval

From #27 (comment)

Hey guys, great progress so far!
I did a little brainstorming with a colleague today and we found room for two improvements I'd like to discuss with you:

1. Property class/category: A property is a distinct reading or characteristic value produced by a node of a device. The other side of the network, the discovering entity, needs to know about the nature of this value (e.g. to show a thermometer in a GUI). We are already providing attributes to characterize its unit, range, pretty name and "set'ability" but not a clear type.
   A not-settable property with the unit "°C" does at best imply that the property is a temperature reading of a thermometer, not e.g. a thermostat or a nominal temperature. The discovering entity should not have to resort to guessing and interpreting of the other attributes.
   I propose a counted number of property classes to characterize the nature of a property. The $class or $category attribute is required but can be "Unspecified"/"Other"/"" for special non-trivial properties. The classes list can be extended over time and the discovering entity is allowed to ignore the provided class if unknown.

2. Conversion Attribute: When working with embedded systems or low-energy micro controllers, we can not expect the device to be capable to convert a raw sensor reading into a final human-comprehendible value. An example would be a temperature sensor reading between [0..255] which would map onto a degree Celcius value with decimal places.
   I propose the introduction of a $conversion property attribute. The published String value is either "x"/"" for no conversion or the right hand of an f(x) formula, e.g. x / 255 * 50 - 20.

Both points are of course open for discussion. What do you think?

Thoughts on adding a $location device property? This would prevent having to overload the $name field with location info and possibly make searching easier.. or does this belong 'outside' of homie?

I like that property/settable indicates that a property can be set. However, it may not be obvious for the front-end app to figure out which values or ranges that the property can be set to, so I suggest the following:

homie/686f6d6965/switch/$properties → on:settable[true,false]
indicates that a switch "on" can be set to "true" or "false"

homie/686f6d6965/temperature/$properties → temperature:settable[60-100]
indicates that the temperature (for example, a sous vide machine) can be set between 60 to 100 (unit defined elsewhere)

This would make settable properties more clear and obvious.

Some of the mandatory attributes are device specific / implementation specific. Some are not required for the working of the Homie Convention.

I would like to update some of the attributes mandatory flag. This will allow for an slimmer Homie Convention.

$name => Optional, Device ID may be used when no name is given.
$localip => Optional, Device specific. (not all devices have a IP)
$mac => Optional, Device specific. (not all devices have a MAC address)
$stats/uptime => Optional. (is this required for sensor valid time?)
$stats/signal => Optional. Is already defined as optional.
$stats/interval => Optional. Not required for the correct operation.
$fw/name => Optional. Implementation specific.
$fw/version => Optional. Implementation specific.
$fw/checksum => Optional. Is already defined as optional.
$implementation => Optional. It should be adequate to use $homie attribute.

A simple table may be used for showing what is required for given features.

I do not know the inner workings of the Homie Convention, but my general ide is that there are to many mandatory attributes that do not need to be mandatory.

I wonder if its a good idea to use MQTT as a store of devices properties: that's not its purpose.
Retain feature purpose is not for mimicing a database. There is no magic into this: datas are stored somewhere and how it is stored can make this model not scalable.

I've been thinking about how I would implement an actual LED strip. And, if each LED was individually controllable (brightness and color), property arrays just don't fit.

Indeed, a LED is a node more than a property (a LED node would have a color and brightness property). Therefore, it makes more sense to move the array semantics to node level instead of property level.

What do you think of a "get" topic extension?

For interacting devices it's not really an issue, but for sensors it would make sense to request a measurement externally.
In the Arduino/ESP8266 framework, the sensor examples are all working on a fixed hardcoded time base. A workaround could be to put the interval into the config json and update this via MQTT. But imho it would be simpeler if a property state can be requested by a ".../topic/property/get"-command (void payload).

Hi,

I downloaded the most dev branch and tried the LightOnOff sketch but it does not compile without making some changes to it. In the end the following sketch is what worked.

`#include <Homie.h>

const int PIN_RELAY = 5;

HomieNode lightNode("light", "switch");

bool lightOnHandler(HomieRange range, String value) {
if (value != "true" && value != "false") return false;

bool on = (value == "true");
digitalWrite(PIN_RELAY, on ? HIGH : LOW);
lightNode.setProperty("on").send(value);
Serial << "Light is " << (on ? "on" : "off") << endl;

return true;
}

void setup() {
Serial.begin(115200);
Serial << endl << endl;
pinMode(PIN_RELAY, OUTPUT);
digitalWrite(PIN_RELAY, LOW);

Homie_setFirmware("awesome-relay", "1.0.0");

lightNode.advertise("on").settable(lightOnHandler);

Homie.setup();
}

void loop() {
Homie.loop();
}`

The change I made was changing Homie.setNodeProperty(lightNode, "on").send(value) to lightNode.setProperty("on").send(value).

The issue now is when I try and send a message to the node it never gets received.

On my MQTT server, I see all the properties being received from homie/relay/* but when I sent homie/relay/light/on/set with true nothing is received.

Thank you,

Mike

Hi,
I'm starting to play with homie (and in particular the esp8266 implementation) and I have a very simple use case which i'm not sure how to do.
My garage door motor is a simple one, where I have a simple contact. I wired a relay on my motor, which is in turned driven by the ESP8266 I/Os. Was the relay is closed, the garage door starts to move. So my program currently just receives an MQTT message, and put the relay "on" for some seconds. I'm not able to choose if it will go up, go down, unable to send any smarter command.
So far so good.
I wish to convert my simple but not satisfactory LUA code to C++ using homie and platformio.
How should I configure this node to have a simple "rising edge" button with no state, but just an isolated order ?
Seems like a node with a switch property is not correct, because it would have an "on" and "off" state but mine is stateless.
Thanks for your opinion.
Regards.

Been working with Homie a couple of days now. Small stumble was what the topics were. Suggest the following

devices/686f6d6965/temperature/temperature → 12.07
devices/686f6d6965/humidity/humidity → 79

become

devices/686f6d6965/temperatureNode/temperature → 12.07
devices/686f6d6965/humidityNode/humidity → 79

Got it all working and very impressed!

It would be pretty hard to sell an industrial-automation product where all the nodes start with homie. Something generic, not tied into the idea of home-automation, would probably be better.

Hi!

This issue is mainly here to see what your thoughts are on some points which occurred to me while implementing this scheme. I quite like the idea, I can see this getting some momentum someday ;)

• You seem to have considered some auto detection for nodes, by providing the $nodes device property. But the one thing I can't find out that way (nor any other) is which node is settable. Do you think there might be benefit to adding a way to determine that by inspection?
• You don't mention any QoS or retention policy for node properties (and their setters!) would they normally be retained or not, or is that a case by case decision? Same for QoS. I assume you've thought about that, it would be nice to have a note in the readme. (Actually, suggested QoS for device properties would be nice too)
• You have a $uptime device property. It would be nice to have a suggestion how to handle that one, do you normally update it every second, every minute? Both could cost resources on a small device. If a controller doesn't know the policy it doesn't know how far our the time is.
• It would be nice to have a policy for 'on demand' values. For example I like to let the controller decide when to check temperature. It would make something like the $uptime easier/more reliable to, you ask for a time when you want to know it, when you get it it will be pretty much accurate.

Just thoughts :)

Cheers!

1 Charset
Should probably note that all messages are text (not binary data, which could be sent via MQTT), and note the character set. The ID and examples suggest using ASCII, with one exception.

The exception: units uses the degree mark in the table, but not in the example (plain "C" is used for degrees C in example). Should be consistent and unambiguous.

I kinda like not having to parse UTF-8 (or other extended character sets) on a tiny machine, so "degC", "degF" would work better for me.

2. Angle unit?
There is also a simple degree unit defined but for what purpose? If the idea is to convey angles, how about "degA" to make it less ambiguous?

3. Missing major units?
Units doesn't have time (sec) or weight/mass (lb/kg)...
Flow (eg: gal/hour) is very useful for home automation

4. Protocol version
homie/$homie seems odd; why not be more clear and use homie/$version instead?

5. Small tweaks of wording
Slight rephrase on required aspect of $checksum: "No, depending of your implementation" => "No, depends on your implementation",

6. Meaning of $fw/checksum
Also, do you have in mind the checksum as computed before flashing by the toolchain and somehow embedded, or a checksum calculated by the firmware itself on it's own flash memory?

7. Better name in example
In device attributes example:

homie/686f6d6965/$fw/name → 1.0.0
homie/686f6d6965/$fw/version → 1.0.0

having a real name might make better sense, like "temphum.ino"

8. $property ranges

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 -.

The ranges need to be better defined. The first thing is that I initially thought it meant something like:
0,3,[5-7],10 as shorthand for 0,3,5,6,7,10 but a much later example clarified:

homie/ledstrip-device/ledstrip/$properties → led[1-3]
homie/ledstrip-device/ledstrip/led_1/$name → Red LEDs
homie/ledstrip-device/ledstrip/led_2/$name → Green LEDs
homie/ledstrip-device/ledstrip/led_3/$name → Blue LEDs

So it's meant to generate/define multiple strings from a pattern. In this case, it needs to be defined a bit better, like "[start#-end#] where start# and end# are non-negative integers with end# >= start#, and identifiers will be generated by iterating from start# to end#". So it would not work for, say, "base[01-15]" to describe base01, base02, ... base15 but only for base1, base2, base15, right?

This seems like it's kinda conflating the concept of naming and the concept of [numerically indexed] arrays.

In your example, I actually prefer enumerating "led_red,led_green,led_blue" to "led[1-3]" meaning led_1, led_2, led_3. The latter is a few character shorter, but the attributes of each needs to be described anyway so that's hardly a large overhead.

What if you get "led[0-149]" (eg: a strip of 50 RGB leds)? Is the controller supposed to expand that into 150 id's and deal with it meaningfully?

I'm thinking that there should be a small and enumerable number of property id's. If you want an array of Device-definable size, add that functionality explicitly rather than sort of handling it in the $property id's.

9. Naming.
In your examples:

homie/686f6d6965/$name → Bedroom temperature sensor
homie/686f6d6965/$nodes → temperature,humidity # (I added this to the examples)
homie/686f6d6965/temperature/$name → Bedroom Temperature Node
homie/686f6d6965/temperature/degrees/$name → Bedroom Temperature
homie/686f6d6965/humidity/$name → Bedroom Humidity Node
homie/686f6d6965/humidity/percentage/$name → Bedroom Humidity

This redundantly describes things at every level, which may or may not be appropriate.
We get

homie/686f6d6965/humidity/percentage/
mapping to
homie/"Bedroom temperature sensor"/"Bedroom Humidity Node"/"Bedroom Humidity"

I wonder if a more hierarchical decomposition with less redundancy might work better?

homie/686f6d6965/$name → Bedroom sensor 1
homie/686f6d6965/temperature/$name → Environmental
homie/686f6d6965/temperature/degrees/$name → Temperature
homie/686f6d6965/humidity/percentage/$name → Humidity

This uses hierarhical context:

homie/"Bedroom sensor 1"/"Environmental"/"Humidity"

One effect of this is that one could replicate the node definitions for a standard sensor device:

"Kitchen sensor 2"/"Environmental"/"Humidity"
"Living room sensor 1"/"Environmental"/"Humidity"

where the latter two levels were the same as for the bedroom; only the device name needs to change between the otherwise identical devices. And if you move a physical device to another room, all you have to change is the device name; you don't have to chase down all the substructure names.

This may be just a suggested change in the examples, suggesting to the user that there IS hierarchical structure or context available when a Controller is understanding a device, so there's no need to treat each property as standalone.

10 formats
This is somewhat complicated to parse. You could skip ahead and check: if it has a colon then it's a range, if it has a comma then it's an enum, and if it starts with "regex:" then it's a regex. Or you could check the datatype and parse the format accordingly. I think it would be good to think more on the purpose of the $format and how it would be used. Is it to tell the Controller which formats should be considered errors for a read? Or is it to tell the Controller which formats the Device will accept so the Controller can detect errors on intended writes? In the case of a range or an enum, it could be used to populate choices for a user interface, but for regex's that's kinda ungainly.

If you are allowing regex's then you need to define which kind of regex's are allowed (perl? python? php has two kinds. etc) because they come in flavors. And parsing a regex is going to be hard on the Device end (maybe the Controller end too), as the libraries are large. And they can be notoriously hard for humans to read, create and avoid mistakes.

I kinda suggest just dropping the regex's as too much complexity for too little gain. The simpler ranges and enums are much easier and more valuable. However I might suggest defining ranges with a comma rather than a colon: "min#,max#" just to keep things simple - assuming that you will be looking at the $datatype to interpret the comonents of the $format, rather than parsing the $format itself; in some cases this allows more code reuse.

11. Comma Escaping in enumeration $format
Should give example of comma escaping for enum $format (phrasing of eg in description sounds as if it is an example of that, but is not). Is the idea that an enum value of comma as the second enumerated valuse is like this: "first,,,,third" (first & fourth comma = separator, middle two comma = embedded comma)? Or 3 commas for first or last value? An escape like \ prefix is easier to understand and to parse, like "first,\,,third"

(If one even really wants a comma as an enum value; maybe drop the concept of comma as an enum value and thus the need for escaping?)

12. Consistant set/read state names
Towards the end I read:

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

Why on vs true? Seems like an unnecessary confusion. Pick one or the other and stick with it.
Either use a boolean set AND read as "true" or "false", or use an enum (on, off) and
use that for setting and reading.

We could consider the boolean case as just a predefined enum of (true, false).

13. Special ID's and heirarchy

Note for things like $stats and $fw we see:

$fw/name
$fw/version
$fw/checksum

In these cases, would it make more sense to use an underscore instead?

$fw_name
$fw_version
$fw_checksum

That is, do you really want or need to use an extra level of MQTT hierarchy for these?

If so, give an example to help people understand how it's useful to be organized that way. And consider being more consistent by using $ prefixed id's for the substructure too, since these are predefined magic names rather than arbitrary user chosen ones:

$fw/$name
$fw/$version
$fw/$checksum

(By contrast, "alert" in the following is NOT a predefined magic name, but is user chosen, so it's not implied that all levels after the first $ prefixed id are also magic predefined names)

homie/$broadcast/alert ← Intruder detected

Derived from #41

The super-car example is in my personal opinion not the most intuitive example. It is cool and fun but might lack the needed comparability. The Homie convention is probably mostly used for small dedicated sensor node or small device applications.

The weather station had the issue of missing settable properties, the super-car is too complex to comprehend. I'm not sure about the perfect device.

After we decided on a better example, We could move the example out of the convention into a separate Example section, where we can describe the device and device aspects first, then illustrate how the announcement and interaction process could look like. In combination with #51 this should lead to a clear understanding of the Convention.

I need to add the ability to set the background color of the device in the GUI from the infrastructure.yml. Currently, colors are hard-coded per node type.

Colors might be set in a group field, a device field or a node field. A device color takes precedence over a group color, and a node color takes precedence over a group or device color.

Hi, I'm an openhab user converting to openhab2 and an ESP8266 enthusiast. OH2 is based on the Eclipse SmartHome project, and their new binding architecture looks like it would mesh well with the Homie conventions. I've got a couple of Homie devices piped in using a direct MQTT binding, but a more robust, auto-discoverable binding could make adding these $10 devices a breeze!

Since OH2 now supports device discovery, the manual configuration process could be bypassed which could open up a new user base for homie-based devices. My MVP feature set would be auto-discovery (listen for new device/+/... topics) and categorization (switch, dimmer, read-only sensor) based on the Homie device's $nodes. There would have to be some possibly brittle mapping of $node:types to Openhab Item types to pull it off, but I don't think that's a show-stopper.

TL;DR:
My question is whether or not you know of anyone working on this yet... I'll gladly jump into another project if it exists! Otherwise, I'll link you the project/repo once I've got the binding started!

By the way, huge thanks for the great project! I've got an LED lighted flower arrangement that's been running Homie firmware for months. I've never had to restart it manually; it reattached to my MQTT broker even after I had to re-flash my RPi (it was down for days)... no problems at all!

Hi ,

Am pretty new to home automation and ws8266. I have setup the following

WS2812B based LED strip and has 60 LEDs
NodeMCU with WS8266
I have connected the 5v 4amp power supply to volt(red wire) and gnd(white) of LED strip
And from the same power supply i have fed the power to 3-5v logic shifter through the 5v input and gnd
using the power out at the end of the led strip i have powered the nodeMCU Vin and gnd pins
I have connected D4 of nodeMCU to DataIn(green cable) of the LEDstrip through the Logic shifter

The following is my code

#include <Homie.h>
#include <Adafruit_NeoPixel.h>

#define FW_NAME "led-control"
#define FW_VERSION "1.0.0"

#define PIN            4
#define LED_COUNT      60

Adafruit_NeoPixel strip = Adafruit_NeoPixel(LED_COUNT, PIN, NEO_GRB + NEO_KHZ800);
int delayval = 500; 
int showType = 0;
int SoffitR;
int SoffitG;
int SoffitB;
int numPixels = LED_COUNT;

HomieNode ledNode("led", "led");

bool lightOnHandler(HomieRange range, String value) {
  Serial.print("Light On Handler");
  if (value == "off") {
    colorWipe(strip.Color(0, 0, 0), 50);    // Black/off
    //Homie.setNodeProperty(ledNode, "color").send("0,0,0,0");
    ledNode.setProperty("color").send("0,0,0,0");
  } else if (value == "red") {
    colorWipe(strip.Color(255, 0, 0), 50);  // Red
    ledNode.setProperty("color").send("0,255,0,0");
  } else if (value == "green") {
    colorWipe(strip.Color(0, 255, 0), 50);  // Green
    ledNode.setProperty("color").send("0,0,255,0");
  } else if (value == "blue") {
    colorWipe(strip.Color(0, 0, 255), 50);  // Blue
    ledNode.setProperty("color").send("0,0,255,0");
  } else {
      //value.trim();
      Serial.print (value);
      //Serial.flush();
      // split string at every "," and store in proper variable
      // convert final result to integer
      SoffitR = value.substring(0,value.indexOf(',')).toInt();
      SoffitG = value.substring(value.indexOf(',')+1,value.lastIndexOf(',')).toInt();
      SoffitB = value.substring(value.lastIndexOf(',')+1).toInt();
      colorWipe(strip.Color(SoffitR, SoffitG, SoffitB), 50);
      ledNode.setProperty("color").send(value);
      Serial.print("Value Set to LED");
  }
  return true;
}

int i;

void colorWipe(uint32_t c, uint8_t wait) {
for(uint16_t i=0; i<strip.numPixels(); i++) { //<strip.numPixels
strip.setPixelColor(i, c);
strip.show();
delay(wait);
}
}

void setup() {
  Serial.begin(115200);
  Serial.println(FW_NAME FW_VERSION);
  
  strip.begin();

  Homie_setFirmware(FW_NAME, FW_VERSION);
  ledNode.advertise("color").settable(lightOnHandler);

  Homie.setup();

}

void loop() {
  Homie.loop();
}

I have uploaded the json config also through ESP8266 uploader
{
"name": "LED for TV Stand",
"device_id": "family-room-tv-led",
"wifi": {
"ssid": "ABCDEF",
"password": "mypassword"
},
"mqtt": {
"host": "192.168.0.123",
"port": 1883,
"base_topic": "devices/",
"auth": true,
"username": "username",
"password": "password"
},
"ota": {
"enabled": true
}
}

this is my openhab config item
String TVLedLightColor (All) {mqtt=">[broker:devices/family-room-tv-led/led/color/set:command:*:default]"}

When i try to set a color this is what it shows in the Serial Monitor
Hardware device ID: 6001942bdf7c
• Device ID: family-room-tv-led
• Name: LED for TV Stand
• Wi-Fi:
◦ SSID: ABCDEF
◦ Password not shown
• MQTT:
◦ Host: 192.168.0.123
◦ Port: 1883
◦ Base topic: devices/
◦ Auth? yes
◦ Username: username
◦ Password not shown
• OTA:
◦ Enabled? yes
↕ Attempting to connect to Wi-Fi...
✔ Wi-Fi connected, IP: 192.168.0.125
Triggering WIFI_CONNECTED event...
↕ Attempting to connect to MQTT...
Sending initial information...
✔ MQTT ready
Triggering MQTT_READY event...
Calling setup function...
〽 Sending statistics...
• Wi-Fi signal quality: 76%
• Uptime: 1s
Calling global input handler...
Calling node input handler...
Calling property input handler...
Light On Handler79,255,73Value Set to LED

The bolded text or my debug code
But still the light does not come on. LED strip is off. Please can you tell what else can i try?

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"

I think that it would be great to know the last 'set' time of a sensor. Currently I'm having issues with a device where the temperature is having issues reading, however since I only send the temperature when I get a read, it's hard to know when my device is "stalled". The wifi / mqtt connection is all good, but it would be great to know approximately how stale the data in the retained mqtt topics is.

Tasks for release of v3.0.

[ ] Clean up branches
[ ] Talk about final additions for v3.0
[ ] Review and clean up formatting.

Anything else? Lets talk.

@ThomDietrich @bodiroga @bertmelis @ingoogni @euphi @marvinroger

Can you provide a LICENSE.txt file in this repository, expressing your intention for this to be an open source convention (assuming this is your intention)?

Hello @marvinroger,

Somewhere in comments we already discussed that branching in this repository should be addressed. I want to restart that discussion. Here's my first suggestion, which is open for discussion:

1. Introduce a strict versioning system - Homie is a convention to be followed by other development projects. It is hence important to add unambiguous version numbers for every convention revision. A developer needs to be able to state "The app conforms with the Homie convention v2.1.3". I suggest to implement semantic versioning: http://semver.org (should be a perfect fit)

2. Work in the main branch only - Currently there is an outdated master branch, an unclear v2.0 branch and a redesign branch. That is neither intuitive nor visible to a reader. As the convention is steadily evolving, we should present the latest revision to the interested developer/user. (With the option to switch to other versions, see 5)

3. Use tags to mark versions - A homie version is a fixed state of the document, hence tags are perfectly fine for the job. (Other branching models suggest branches in order to allow e.g. hotfixes)

4. Version every commit - Almost every commit will change details of the Homie convention, it is therefore needed to increment the version number as the MAJOR.MINOR.PATCH system of semver suggests. (Exceptions are of course commits with language changes only)

5. GitHub releases for stable tags - GitHub offers the releases tab to publish versions and add a release note. That should be used to announce and document the stable and noteworthy releases (e.g. v1.5.0, v2.0.0, v2.1.0)

6. Link the "Tags" tab in the first part of the convention - For readers to quickly find all available homie versions, the tags tab should be highlighted in the first part of the convention document.

Everyone, please add your comments, criticism and feedback!
Best! Thomas 🍻

There's a discussion in homieiot/homie-esp8266#467 about how to be more flexible in Node configuration.

As this is not the implementation-specific but belongs to the convention, I opened a new issue here.

As far as I understood the proposal of @ingoogni, nodes should be independent from devices (e.g. a node can be distributed over several devices).

I still think this proposal is beyond "lightweight", but it may be ok if you somehow define "virtual" nodes that can be distributed over several devices.

We need a color datatype. It could support multiple formats (RGB, hue...)

Hello, can you confirm how the homie data described here for the MQTT broker is configured into the homie-esp8266 and the homie-server i.e.
MQTT topic ESP8266 (config) homie-server (infrastructure.yml)
devices/device ID JSON “device_id” devices: -id
devices/device ID/$name JSON “name” ?
devices/device ID/$nodes NomieNode(id,type) nodes: -id type

And regarding the "node type", is there a prescribed list of these recognised by the homie-server e.g. shutters, temperature, heater, light.

Hello, first: Thank you for great work! you make my develop a lot easier!

Please can you point me out, how to remote for example LED strip?
I didn't find any topic where I should publish values.

Also do you have any toggle button example just for sending status of button? I looked into itead sonoff button, but I am not wise from it :-(

Thank you very much!

I'm trying to adapt my device to the Homie convention, and I find difficulties. For dealing with very simple actuators/sensors Homie seems to work perfectly, but with more complex devices, I'm not sure if it fits well. As you are considering a revision of Homie convention for v2, I would like to share my thoughts just in case could be of help.

My device is an irrigation controller with a customizable number of actuators. Each actuators can be assigned to one or more irrigations programs (number also customizable). Actuators can also be open/close on demand. My MQTT messages have the following structure:

    {prefix}/{action}/{node}/{property} {payload}

In Homie there is only one action (set), and goes at the end:

    {prefix}/{node}/{property}{action} {payload}

This order change is irrelevant and I'm not questioning it. The point is that my device uses 5 types of actions:

STATE
Informative messages sent by the device for reporting information. These messages do not imply problems.

ALERT
Informative messages sent by the device when problems or special conditions are detected.

GET
Messages sent to the device for requesting information.

SET
Messages sent to the device for changing the value of a property (i.e. for modifying an irrigation program).

DO
Messages sent to the device for immediate action (i.e. closing an electro-valve, starting an irrigation program, immediately saving into flash memory the device state, etc.)

Examples:

device_456/STATE/clock/time → 18:55:37
INFORMATIVE: Device clock current time is 18h:55m:37s

device_456/GET/clock/battery
REQUEST: Device is asked to inform about clock battery voltage. It will respond with
device_456/STATE/clock/battery → 3.048

device_456/ALERT/actuator/3/state → lost
ALERT: Device informs that connectivity with wireless actuator #3 is lost.

device_456/DO/actuator/6/running → on
ACTION: Device is asked to open actuator #6 and start irrigation.

device_456/SET/program/3/actuator/7/start-time → 19:00:00
CHANGE: Device is asked to set start time 19h:00m:00s for actuator #7 in program #3.

My SET and STATE messages naturally maps the Homie convention for changing values or reporting values. But for the other three types I can not find a clean mapping:

1. No difference between 'normal' information and 'exceptional' information. For instance, no possibility to distinguish between a periodic normal message reporting battery voltage, form an exceptional message reporting battery low:

   device_456/STATE/clock/battery → 3.024
   device_456/ALERT/clock/battery → 2.487

2. There is no way for requesting for the value of a property. For instance, I can not interrogate the device for the battery voltage:

   device_456/GET/clock/battery

Instead, I have to trust on MTTQ retention and assume that last send value is valid.

3. As a consequence of previous issue, the device will be forced to periodically having to send a message for reporting battery state. My device doesn't send periodic information, only when the value changes (i.e actuator is opened because an irrigation program has started). Other values (i.e battery voltage) are only send on request or when exceptional conditions. So I fully supports cranphin comment (issue #4) that it would be nice to have a policy for 'on demand' values.

4. No differentiation between setting the value of a node's property (my CHANGE messages) from requesting the device to perform some action (my DO messages). This problem is not important as both types (CHANGE and DO) can be mapped to Homie 'set' messages but, semantically, are different.

Hope this can be of any help for Homie V2.

Can we define which topics are considered announcements in the documentation?

This would be useful to understand what topics would be defined by the time the device state turns to ready.

My understanding is that when the state goes to ready, every node is defined along with all the properties to the level that we know what all the topics are.

I want to support multiple tenants and I'm wondering how to do that within the convention.

For example I have multiple customers, each with their own devices. It makes sense expose this as a topic hierarchy so that I can correctly set permissions on topic subtrees.

Option 1: Have multiple base topics

Instead of the "homie" base topic, give each tenant their own:

customer1/device-f0e1d2/$homie
customer1/device-a9b8c7/$homie
customer2/device-f0e1d2/$homie
customer2/device-a9b8c7/$homie

Nothing in the convention forbids this that I can see. It's a little weird though, because I would want a homie agent that can "see" all the customers' base topics.

Options 2: Splice in groups

By allowing devices to exist at arbitrary depths, we could support grouping.

homie/customer1/device-f0e1d2/$homie
homie/customer1/device-a9b8c7/$homie
homie/customer2/location1/device-f0e1d2/$homie
homie/customer2/location1/device-a9b8c7/$homie
homie/customer2/location2/device-d6e5f4/$homie

This is forbidden by the current convention, but is more flexible. If this were allowed in the convention, it wouldn't make device discovery any more difficult. An agent just needs to look for a topic ending in /$homie to know that it's found a device.

Imagine a water consumption meter which is read out by an esp8266. the esp counts pulses as total consumption and calculaties the current flow.
Would you split up consumption and flow into separate nodes of would you see them as different properties of 1 node.

Hi there,

is there any known implementation or example of the homie-convention in python? I would like to use certain homie-esque features like …/set command, uptime, local ip, etc. on systems that are able to run python scripts. I would also be interested in your thoughts about this idea.

Keep up the good work and thanks for all your efforts!

Best regards,
Jan

Attributes topics have the "$" prefix.
I would like us to prefix the command topics, e.g. "set", with "!" or another appropriate character.

The reason is to make it easier to distinguish the calls going to the device from the controller.
Distinguish between state updates and commands.
(Command topics will not have the Retain bit set.)

Examples:

1. Setting light intensity from the controller to 50%

• Controller publish
  CTR: homie/686f6d6965/light/intensity/!set "50"
• Device receives, and applies the change, then sends a property update
  DEV: homie/686f6d6965/light/intensity "50"

2. Update device publishing interval to every 2.0 seconds

• Controller publish
  CTR: homie/686f6d6965/$interval/!set "2.0"
• Device receives, and applies the change, then sends a attribute update
  DEV: homie/686f6d6965/$interval "2.0"

3. Reboot device (implementation specific)

• Controller publish
  CTR: homie/686f6d6965/$implementation/!reboot ""
• Device reboots

Currently, the v2 draft only defines the $ota topic. I think the OTA mechanism from the v2 homie-esp8266 "reference implementation" should be added to the spec. That is, $implementation/ota subtopics should be mentioned.

• $implementation/ota/enabled
• $implementation/ota/payload

I would even suggest to move these topics from the $implementation tree to the $ota tree because IMO Homie firmware updates should not be specific to a particular implementation. Generic tools like homie-ota should be usable out-of-the-box for any Homie device, whether it runs homie-esp8266 or some other Homie runtime.

Hi guys,

I'm 1-2 days user of Homie and I like it very much! I faced some difficulties I want to suggest some features that would be useful to everyone:

1. homie//$implementation/reboot - for easy reboot
2. homie//$implementation/report (or register) - to force a concrete device to report its nodes/properties
3. react on broadcasted register message - to notify all devices to re-register - for easier inventory.
4. homie//somenode/someproperty/get - to get last value that was set. Similar to #25. This will consume more memory but it will be very useful. For example imagine a simple node in NODE-RED that is able to query property's value.
5. Include some MQTT topic/payload samples for SET properties and SET config under Convention section. For example initially it was not obvious to me that homie//$implementation/config/set expects a JSON formatted string. Also it is not clear that HomieSetting represents a real key/value pair under "settings" section in the setting file and can be modified via a call to homie//$implementation/config/set. For example in http://marvinroger.github.io/homie-esp8266/develop/advanced-usage/custom-settings/ add information that "percentage" setting can be set publishing MQTT message like this:
   topic: homie//$implementation/config/set
   payload: '{"settings":{ "percentage": 50 }}'

Retained MQTT values are not always useful (imagine MQTT broker was rebooted). I think a "controller" (like node-red) should be able to control more aspects of homie device.

In all cases - great work!

Thanks.

Hi First of all big thank you for the homie. That is what i have been looking for. I was running ESPEasy for a while but seems like it is highly unreliable. My issue with Homie currently is I am having trouble saving config at MQTT setup point. Even I click Next the browser does not move.
I have tried https://community.openhab.org/t/framework-homie-for-esp8266/8674/37
and re-uploaded https://github.com/marvinroger/homie-esp8266/blob/develop/examples/IteadSonoff/IteadSonoff.ino
I can see in serial monitor everything is working until MQTT setup after entering all the information it does not move to the next stage. Am I missing something?
I have tried on Safari, Chrome, Firefox and Internet Explorer all same result. Please help

Currently, if you define a range property you get a subtopic for every range item which is fine.
However, if you have a lot of items its get quite a lot of work and traffic to set them all.
In my opinion, it would be a good thing if one could set them all with one message.
Assume this setup:

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

Doing this:

homie/ledstrip-device/ledstrip/led → on

Should be equivalent to this:

homie/ledstrip-device/ledstrip/led_1 → on
homie/ledstrip-device/ledstrip/led_2 → on
homie/ledstrip-device/ledstrip/led_3 → on

Regarding the format of messages published to this batch topic I suggest the following:

<value>

=> Set all items to value

1-2:<value>

=> Set items 1 and 2 to value, don't modify item 3

1-2:<value>
3:<value2>

=> Set items 1 and 2 to value and item 3 to value2

Forgive me if this is possible and I haven't figured it out yet .... but is there not any way to SET the interval value for the device? As in to configure how often to send the stats? I guess I just assumed this was possible, as I don't see what the interval config is even really for if it's not settable ... ?

Reason being ... use case scenario would be outputting data on a dashboard ... so when the user is viewing dashboard for a device, we would want to update the interval to say, every 15 seconds to give a better UI experience, whereas, when just storing stats, we would only want it set to every 300 seconds (5 minutes) instead

Am I missing something here?