There was an incompatible change in the ArduinoJson library, so Homie-ESP8266 fails to build.

This releases fixes this by setting the dependency to ArduinoJson-library to minor version 6.11.x.

Please note that this may result in a downgrade of the used ArduinoJson library - and you may perform this downgrade manually in your platformio directory.

Long time awaited Version 3.0 which supports Homie convention v.3.0.1.

Many thanks to all contributors and people who reported issues and asked for features.

Upgrade Guide

To support new features and changes in the Homie convention 3.x some signatures have changed.

HomieNode

Constructor:

HomieNode(const char* id, const char* name, const char* type, bool range = false, uint16_t lower = 0, uint16_t upper = 0, const HomieInternals::NodeInputHandler& nodeInputHandler = [](const HomieRange& range, const String& property, const String& value) { return false; });

instead of

HomieNode(const char* id, const char* type, const HomieInternals::NodeInputHandler& nodeInputHandler = [](const String& property, const HomieRange& range, const String& value) { return false; });

So, you need to insert a new parameter on second place that gives a descriptive name of your node.

Also, ranges are now on Node level in the v3.x convention. So if you use ranges, then you need to enable them and give lower and upper range limit in the HomieNode constructor.

handleInput()

virtual bool handleInput(const HomieRange& range, const String& property, const String& value);

instead of

virtual bool handleInput(const String& property, const HomieRange& range, const String& value);

So, the HomieRange& is now on first place. This changes was done intentionally to reflect the change how ranges are handled in convention 3.x . However, in many case you can just change the signature of your own handleInput() method and you are fine.

PropertyInterface

The PropertyInterface now offers methods to advertise more details about the property as specified in the convention 3.x:

  PropertyInterface& setName(const char* name);
  PropertyInterface& setUnit(const char* unit);
  PropertyInterface& setDatatype(const char* datatype);
  PropertyInterface& setFormat(const char* format);
  PropertyInterface& setRetained(const bool retained = true);

homie-esp8266 does not enforce the correct usage of these methods. So it is your own responsibility to comply with the convention, especially the rules defined in https://homieiot.github.io/specification/spec-core-v3_0_1/#payload . (Note that the v4.x convention is compatible regarding these rules and gives some more recommendations in https://homieiot.github.io/specification/spec-core-v4_0_0/#property-attributes)

New features

Since the v2.0.1 release some new features have been added.

Note: Most of them were also available in the v2-development branch, but not released yet.

• Disable Config mode or MDNS support
  • Disabling the configuration mode makes the binary much smaller. This is especially important, if you want wo use OTA-updates on devices with 1 MB flash only.
  • See https://homieiot.github.io/homie-esp8266/docs/3.0.0/advanced-usage/compiler-flags/
• Run loop also if disconnected:
  • Any HomieNode can set a flag, to run its own loop() also, if not connected to MQTT.
  • This can be useful if the node performs some tasks that is not only visible on MQTT. For example controlling effects on an LED strip.
  • Use setRunLoopDisconnected(bool) to set it. (defaults to false)
• [...some more...]

Fix #545

After more than 6 months of development + 6 months of testing and perfecting, the long awaited v2.0.0 Homie for ESP82666 is finally ready for a beta release! There are a lot of new features that should take your IoT ESP8266 devices to a whole new level. Before going into the details, I would like to thanks all the awesome contributors who made this release possible. In particular:

• @Bee-Certain for his donation
• @euphi for his extensive tests, the broadcast channel addition and his participation in autoregistration of nodes
• @flaviostutz for his work on transparent proxy in configuration mode
• @jpmens for his active participation in both the Homie ecosystem and in discussions
• @mrpace2 who did a great job of enhancing the OTA process
• @pevma for his donation and for providing me an ESP32
• @sumnerboy for his participation and for his donation
• @unaiur who allowed autoregistration of nodes and the configuration UI to be embedded
• @benzino77 for the static IP support (and more)
• @ThomDietrich for work on the Homie Convention and striving for better.
• @timpur for devoting his effort to the progress of Homie ESP8266 and the Homie community
• @marvinroger for development of v2 and creating the Homie Community
• All other contributors and people who reported issues and asked for features

The v2 is obviously a breaking release. Sketches are indeed not backward compatible with the v1. The v2 also conforms to the new Homie convention v2.0.1.

📝 Documentation

The documentation was moved to https://github.com/homieiot/homie-esp8266/. I recommend you read it all, even if you come from Homie for ESP8266 v1, because a lot of things changed.

The new documentation script will allow you to access the documentation of every release released from now on, including the old v1.5.0 version, with the very same link.

✨ Features

• Static IP, custom BSSID and channel support
• MQTT is now provided by the AsyncMqttClient library, which is asynchronous, and this is actually the biggest change in the v2. Change that you won't notice... What this means is that the network code is not blocking anymore, everything is handled in another "thread", so your code cannot be blocked (in v1, if the MQTT server was unavailable, your code blocked for ~7 seconds) and can handle way more messages without crashing. In other words: the v2 is more bulletproof.
• Custom settings! 🎉 In configuration mode, you're now able to provide custom settings, booleans, numbers, strings... That you can also change in normal mode through a special MQTT topic.
• OTA is now done over MQTT. No need for an HTTP server serving the firmwares anymore, the only requirements for Homie for ESP8266 are a Wi-Fi connection, and an MQTT broker.
• Standalone mode. It was a requested feature (#125) to allow the device to operate without being configured first. It was already possible with the v1, but the device would still boot into configuration mode and spawn an AP, which was insecure.
• Broadcast channel allows you to receive broadcasts, so that a controller can trigger anything on every Homie devices.
• Range properties allows you to define a property with multiple endpoints. Useful for a LED strip for example, where you would have a range property led ranging from 1 to 10, for example.
• Optimized for battery-powered sensors. The Wi-Fi and MQTT connection are way faster than on the v1, and a new Homie.prepareToSleep() function allows to cleanly disconnect from the broker in order to deep sleep safely.
• And a lot more...

🌐 Setup UI

The setup UI sources are now available on its own repo, marvinroger/homie-esp8266-setup. It makes use of Vue.js instead of, previously, React. The new online address is http://setup.homie-esp8266.marvinroger.fr/.

🔧 Homie v2.1.0

Dont forget Homie ESP8266 v2.1.0 is also on its way

@timpur

This beta fixes a compilation issue from the previous beta.

Some refactoring has been done on the codebase, see https://github.com/marvinroger/homie-esp8266/pull/432

@euphi:

Due to recent progress with the webserver, but also with arduiono platform etc. projects need to be changed to compile

This is the latest version that compiles, until further stabilization.

After more than 6 months of development, the long awaited v2.0.0 Homie for ESP82666 is finally ready for a beta release! There are a lot of new features that should take your IoT ESP8266 devices to a whole new level. Before going into the details, I would like to thanks all the awesome contributors who made this release possible. In particular:

• @Bee-Certain for his donation
• @euphi for his extensive tests, the broadcast channel addition and his participation in autoregistration of nodes
• @flaviostutz for his work on transparent proxy in configuration mode
• @jpmens for his active participation in both the Homie ecosystem and in discussions
• @mrpace2 who did a great job of enhancing the OTA process
• @pevma for his donation and for providing me an ESP32
• @sumnerboy for his participation and for his donation
• @unaiur who allowed autoregistration of nodes and the configuration UI to be embedded
• @benzino77 for the static IP support (and more)
• All other contributors and people who reported issues and asked for features

The v2 is obviously a breaking release. Sketches are indeed not backward compatible with the v1. The v2 also conforms to the new Homie convention v2.

📝 Documentation

The documentation was moved to http://marvinroger.github.io/homie-esp8266/. I recommend you read it all, even if you come from Homie for ESP8266 v1, because a lot of things changed.

The new documentation script will allow you to access the documentation of every release released from now on, including the old v1.5.0 version, with the very same link.

✨ Features

• Static IP, custom BSSID and channel support
• MQTT is now provided by the AsyncMqttClient library, which is asynchronous, and this is actually the biggest change in the v2. Change that you won't notice... What this means is that the network code is not blocking anymore, everything is handled in another "thread", so your code cannot be blocked (in v1, if the MQTT server was unavailable, your code blocked for ~7 seconds) and can handle way more messages without crashing. In other words: the v2 is more bulletproof.
• Custom settings! 🎉 In configuration mode, you're now able to provide custom settings, booleans, numbers, strings... That you can also change in normal mode through a special MQTT topic.
• OTA is now done over MQTT. No need for an HTTP server serving the firmwares anymore, the only requirements for Homie for ESP8266 are a Wi-Fi connection, and an MQTT broker.
• Standalone mode. It was a requested feature (#125) to allow the device to operate without being configured first. It was already possible with the v1, but the device would still boot into configuration mode and spawn an AP, which was insecure.
• Broadcast channel allows you to receive broadcasts, so that a controller can trigger anything on every Homie devices.
• Range properties allows you to define a property with multiple endpoints. Useful for a LED strip for example, where you would have a range property led ranging from 1 to 10, for example.
• Optimized for battery-powered sensors. The Wi-Fi and MQTT connection are way faster than on the v1, and a new Homie.prepareToSleep() function allows to cleanly disconnect from the broker in order to deep sleep safely.
• And a lot more...

🌐 Setup UI

The setup UI sources are now available on its own repo, marvinroger/homie-esp8266-setup. It makes use of Vue.js instead of, previously, React. The new online address is http://setup.homie-esp8266.marvinroger.fr/.

🐛 Report bugs!

This new release brings a lot of new stuff, so there's probably something broken somewhere. Let's work on making this v2 stable!

Thanks to everyone involved.

New features

• BREAKING - require Arduino for ESP8266 >= 2.2.0: mDNS querying available instead of having to explicitely specify MQTT / OTA servers host / port (#28)
• Add error reason to the JSON configuration API response

Fixes

• The MQTT connection fail reason was always UNKNOWN, this is fixed
• Fix an issue with the configuration API, happening most often in the new 2.2.0 release of Arduino for ESP8266 (#69)

Web UI

The v1.x.x Web setup is not hosted anymore. You can download it as homie-esp8266-v1-setup.zip below.

Fixes

• Fix an issue where the configuration API would never accept a request

Thanks to everyone involved.

New features

• Implement the $uptime device property, refreshed by default every two minutes (#52)
• The ability to subscribe a node to every properties. This is useful for a led strip for example: you will not want to do node.subscribe("1"); node.subscribe("2"); ... if you have a thousand LED. So now, with a fourth parameter to the HomieNode constructor, you can subscribe to everything. See the LedStrip example for a concrete use case (#62)

Fixes

• Fix an issue where reconnecting to the MQTT with SSL enabled would crash (#54)

Web UI

• The default hardware device ID was not used if the device ID was not set in the Web UI. This is fixed (#63)

Misc

• The AP IP is now configurable from the Constants.hpp file (#56)
• Callbacks are now std::function - thanks to @rschaten (#59)
• More dynamic allocations avoided when logging

This is kind of a big one. Thanks to everyone involved.

New features

• You can now set the base topic used on MQTT if you don't want the default devices/ base topic (#44)
• You can also set the device ID to be used on the MQTT topic if you don't want the default hardware ID (#45)
• Breaking change (not in the API so still 1.x.x): The new OTA version string sent to the server is now of the following format: device-id=firmware-name=current-device-version=version-advertised-by-$ota (eg. da828fe0=sub2-relay=1.0.0=1.1.0). This makes it easier to parse server-side (#50)

Fixes

• A lot of work has been done to improve the stability of the MQTT connection when using SSL. Huge thanks to @jpmens which has been very active at testing, he helped a lot 👍 (#46)

Note: This required a lot of changes in the code, the most notable being most of the dynamic allocations were removed. In other words, there are now hard limits for things like the firmware name (see Limits.hpp and customize it if you need to).

• SSL/TLS fingerprint verification now works for MQTT (#42)

Note: The way the verification is done is not very secure due to some limitations of PubSubClient. Consider it as more secure than no fingerprint at all, but not bulletproof.

Docs

• The documentation was moved from the Wiki to the repo. So now, whenever you download a copy of the library, you have an up-to-date documentation for your current Homie library version

Web UI

• Polyfills are now included in the Web UI, so more web browsers are compatible (#48)
• The Web UI is updated to reflect the latest changes in the library
• It is visually cleaner
• SSL is now configurable from the Web UI

New features

• You can now set your own LED pin if you don't want to use the built-in LED (#39)
• Option to show / hide passwords in the configuration app (#32)

Fixes

• Setup handlers was called before the MQTT connection was done. This is now fixed (#40)

Misc

• 2 new examples added

New features

• Custom branding allows you to change the default Homie text in the AP name, hostname and MQTT client ID to what you want. Thanks to @vixns

Fixes

• Configuration mode was blocking at boot for ~5 seconds while scanning for Wi-Fi networks. This is now async

The framework has been tested on real hardware for weeks, and everything is stable.