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",
  "device_stats_interval": 60,
  "wifi": {
    "ssid": "Network_1",
    "password": "I'm a Wi-Fi password!",
    "bssid": "DE:AD:BE:EF:BA:BE",
    "channel": 1,
    "ip": "192.168.1.5",
    "mask": "255.255.255.0",
    "gw": "192.168.1.1",
    "dns1": "8.8.8.8",
    "dns2": "8.8.4.4"
  },
  "mqtt": {
    "host": "192.168.1.10",
    "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
  • bssid, channel, ip, mask, gw, dns1, dns2 are not mandatory and are only needed to if there is a requirement to specify particular AP or set Static IP address. There are some rules which needs to be satisfied:
  • bssid and channel have to be defined together and these settings are independand of settings related to static IP
  • to define static IP, ip (IP address), mask (netmask) and gw (gateway) settings have to be defined at the same time
  • to define second DNS dns2 the first one dns1 has to be defined. Set DNS without ip, mask and gw does not affect the configuration (dns server will be provided by DHCP). It is not required to set DNS servers.

Default values if not provided:

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

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