Homie for ESP8266

The Homie for ESP8266 documentation

Welcome to the Homie for ESP8266 documentation. You'll find comprehensive guides and documentation to help you start working with Homie for ESP8266 as quickly as possible. Let's jump right in!

Get Started    

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

OTA/configuration updates

OTA updates

Homie for ESP8266 supports OTA, if enabled in the configuration, and if a compatible OTA entity is set up.

It works this way:

  1. During startup of the Homie for ESP8266 device, it reports the current firmware's MD5 to $fw/checksum (in addition to $fw/name and $fw/version). The OTA entity may or may not use this information to automatically schedule OTA updates
  2. The OTA entity publishes the latest available firmware MD5 to $implementation/ota/checksum
    • If OTA is disabled, Homie for ESP8266 reports 403 to $implementation/ota/status and aborts the OTA
    • If OTA is enabled and the latest available checksum is the same as what is currently running, Homie for ESP8266 reports 304 and aborts the OTA
    • If the checksum is not a valid MD5, Homie for ESP8266 reports 400 BAD_CHECKSUM to $implementation/ota/status and aborts the OTA
    • Otherwise, Homie for ESP8266 reports 202 and subscribes to $implementation/ota/firmware
  3. The OTA entity publishes the firmware to $implementation/ota/firmware. It can do so as a binary or as a Base64 encoded string
    • The firmware is updating. Homie for ESP8266 reports progress with 206 <bytes written>/<bytes total>
    • When all bytes are flashed, the firmware is verified (including the MD5 if one was set)
      • Homie for ESP8266 either reports 200 on success, 400 if the firmware in invalid or 500 if there's an internal error
  4. Homie for ESP8266 reboots on success as soon as the device is idle

See Homie implementation specifics for more details on status codes.

OTA entities projects

See Community projects.

Configuration updates

In normal mode, you can get the current config.json, published on $implementation/config with wifi.password, mqtt.username and mqtt.password stripped. You can update the configuration on-the-fly by publishing incremental JSON updates to $implementation/config/set. For example, given the following config.json:

  "name": "Kitchen light",
  "wifi": {
    "ssid": "Network_1",
    "password": "I'm a Wi-Fi password!"
  "mqtt": {
    "host": "",
    "port": 1883
  "ota": {
    "enabled": false
  "settings": {

You can update the name and Wi-Fi password by sending the following incremental JSON:

  "name": "Living room light",
  "wifi": {
    "password": "I'am a new Wi-Fi password!"

OTA/configuration updates