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

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)
    • Homie for ESP8266 either reports 200 on success, 400 if the firmware in invalid or 500 if there's an internal error
  9. 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!"