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 Configuration 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,
    "mdns": "mqtt",
    "base_topic": "devices/",
    "auth": true,
    "username": "user",
    "password": "pass",
    "ssl": true,
    "fingerprint": "CF 05 98 89 CA FF 8E D8 5E 5C E0 C2 E4 F7 E6 C3 C7 50 DD 5C"
  "ota": {
    "enabled": true,
    "host": "",
    "port": 80,
    "mdns": "ota",
    "path": "/custom_ota",
    "ssl": true,
    "fingerprint": "CF 05 98 89 CA FF 8E D8 5E 5C E0 C2 E4 F7 E6 C3 C7 50 DD 5C"

The above JSON contains every field that can be customized.

Here are the rules:

  • name, wifi.ssid, wifi.password, mqtt.host (or mqtt.mdns) and ota.enabled are mandatory
  • wifi.password can be "" if connecting to an open network
  • If mqtt.auth is true, mqtt.username and mqtt.password must be provided
  • If a mdns field is set, the device will ignore the host and port fields and query for the corresponding mDNS service and get the first IP and port found

Default values if not provided:

  • device_id: the hardware device ID (eg. 1a2b3c4d)
  • mqtt.port: 1883
  • mqtt.base_topic: devices/
  • mqtt.auth: false
  • mqtt.ssl: false
  • ota.host: same as mqtt.host
  • ota.port: 80
  • ota.path: /ota
  • ota.ssl: false

host fields can be either an IP or an hostname.

The SSL fingerprints can be of the following format:

  • CF 05 98 89 CA FF 8E D8 5E 5C E0 C2 E4 F7 E6 C3 C7 50 DD 5C
  • CF:05:98:89:CA:FF:8E:D8:5E:5C:E0:C2:E4:F7:E6:C3:C7:50:DD:5C
  • cf 05 98 89 ca ff 8e d8 5e 5c e0 c2 e4 f7 e6 c3 c7 50 dd 5c
  • cf:05:98:89:ca:ff:8e:d8:5e:5c:e0:c2:e4:f7:e6:c3:c7:50:dd:5c