Skip to content

OTA updates

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

There's a script that does just that:

GitHub logo ota_updater.py GitHub logo OTA updater README

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 payload to $implementation/ota/firmware/<md5 checksum>, either as binary or as a Base64 encoded string

  3. If OTA is disabled, Homie for ESP8266 reports 403 to $implementation/ota/status and aborts the OTA

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

  5. If the checksum is not a valid MD5, Homie for ESP8266 reports 400 BAD_CHECKSUM to $implementation/ota/status and aborts the OTA

  6. Homie starts to flash the firmware

  7. The firmware is updating. Homie for ESP8266 reports progress with 206 <bytes written>/<bytes total>

  8. When all bytes are flashed, the firmware is verified (including the MD5 if one was set)

  9. Homie for ESP8266 either reports 200 on success, 400 if the firmware in invalid or 500 if there's an internal error

  10. On this fork, the maintained OTA helper publishes firmware with MQTT QoS 1

  11. Duplicate retransmissions of the same firmware are tolerated safely

  12. Overlapping retransmitted chunks are trimmed before they reach flash

  13. If MQTT disconnects during OTA, the update is aborted cleanly and must be retried

  14. Homie for ESP8266 reboots on success as soon as the device is idle

For devices built with HOMIE_CONVENTION_VERSION=5, run the helper with --homie-version 5. The helper will publish to homie/5/<device-id>/... when the default base topic is used:

python scripts/ota_updater/ota_updater.py --homie-version 5 -i kitchen-light firmware.bin

If you use a custom Homie v5 domain, pass the domain as --base-topic; the helper appends the required /5/ segment unless it is already present.

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": "192.168.1.20",
    "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!"
  }
}