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    

JSON configuration file

To configure your device, you have two choices: manually flashing the configuration file to the SPIFFS at the /homie/config.json (see Uploading files to file system), so you can bypass the configuration mode, or send it through the HTTP JSON API.

Below is the format of the JSON configuration you will have to provide:

  "name": "The kitchen light",
  "device_id": "kitchen-light",
  "wifi": {
    "ssid": "Network_1",
    "password": "I'm a Wi-Fi password!"
  "mqtt": {
    "host": "",
    "port": 1883,
    "base_topic": "devices/",
    "auth": true,
    "username": "user",
    "password": "pass"
  "ota": {
    "enabled": true
  "settings": {
    "percentage": 55

The above JSON contains every field that can be customized.

Here are the rules:

  • name, wifi.ssid, wifi.password, mqtt.host and ota.enabled are mandatory
  • wifi.password can be null if connecting to an open network
  • If mqtt.auth is true, mqtt.username and mqtt.password must be provided

Default values if not provided:

  • device_id: the hardware device ID (eg. 1a2b3c4d5e6f)
  • mqtt.port: 1883
  • mqtt.base_topic: homie/
  • mqtt.auth: false

The mqtt.host field can be either an IP or an hostname.

JSON configuration file