When in configuration mode, the device exposes a HTTP JSON API to send the configuration to it. When you send a valid configuration to the /config endpoint, the configuration file is stored in the filesystem at /homie/config.json.

If you don't want to mess with JSON, you have a Web UI / app available:

Quick instructions to use the Web UI / app:

  1. Open the Web UI / app
  2. Disconnect from your current Wi-Fi AP, and connect to the Homie-xxxxxxxxxxxx AP spawned in configuration mode
  3. Follow the instructions

You can see the sources of the Web UI here.

Alternatively, you can use this curl command to send the configuration to the device. You must connect to the device in configuration mode (i.e. the device is an Access Point). This method will not work if not in configuration mode:

curl -X PUT http://192.168.123.1/config --header "Content-Type: application/json" -d @config.json

This will send the ./config.json file to the device.

Error handling

When everything went fine, a 2xx HTTP code is returned, such as 200 OK, 202 Accepted, 204 No Content and so on. If anything goes wrong, a return code != 2xx will be returned, with a JSON error field indicating the error, such as 500 Internal Server error, 400 Bad request and so on.

Endpoints

API base address: http://192.168.123.1

GET /heart

This is useful to ensure we are connected to the device AP.

Response

204 No Content

GET /device-info

Get some information on the device.

Response

200 OK (application/json)

{
  "hardware_device_id": "52a8fa5d",
  "homie_esp8266_version": "2.0.0",
  "firmware": {
    "name": "awesome-device",
    "version": "1.0.0"
  },
  "nodes": [
    {
      "id": "light",
      "type": "light"
    }
  ],
  "settings": [
    {
      "name": "timeout",
      "description": "Timeout in seconds",
      "type": "ulong",
      "required": false,
      "default": 10
    }
  ]
}

type can be one of the following:

  • bool: a boolean
  • ulong: an unsigned long
  • long: a long
  • double: a double
  • string: a string

Note about settings

If a setting is not required, the default field will always be set.

GET /networks

Retrieve the Wi-Fi networks the device can see.

Response

In case of success

200 OK (application/json)

{
  "networks": [
    { "ssid": "Network_2", "rssi": -82, "encryption": "wep" },
    { "ssid": "Network_1", "rssi": -57, "encryption": "wpa" },
    { "ssid": "Network_3", "rssi": -65, "encryption": "wpa2" },
    { "ssid": "Network_5", "rssi": -94, "encryption": "none" },
    { "ssid": "Network_4", "rssi": -89, "encryption": "auto" }
  ]
}

In case the initial Wi-Fi scan is not finished on the device

503 Service Unavailable (application/json)

{
  "error": "Initial Wi-Fi scan not finished yet"
}
PUT /config

Save the config to the device.

Request body

(application/json)

See JSON configuration file.

Response

In case of success

200 OK (application/json)

{
  "success": true
}

In case of error in the payload

400 Bad Request (application/json)

{
  "success": false,
  "error": "Reason why the payload is invalid"
}

In case the device already received a valid configuration and is waiting for reboot

403 Forbidden (application/json)

{
  "success": false,
  "error": "Device already configured"
}
PUT /wifi/connect

Initiates the connection of the device to the Wi-Fi network while in configuation mode. This request is not synchronous and the result (Wi-Fi connected or not) must be obtained by with GET /wifi/status.

Request body

(application/json)

{
  "ssid": "My_SSID",
  "password": "my-passw0rd"
}

Response

In case of success

202 Accepted (application/json)

{
  "success": true
}

In case of error in the payload

400 Bad Request (application/json)

{
  "success": false,
  "error": "Reason why the payload is invalid"
}
GET /wifi/status

Returns the current Wi-Fi connection status.

Helpful when monitoring Wi-Fi connectivity after PUT /wifi/connect.

Response

200 OK (application/json)

{
  "status": "connected"
}

status might be one of the following:

  • idle
  • connect_failed
  • connection_lost
  • no_ssid_available
  • connected along with a local_ip field
  • disconnected
PUT /proxy/control

Enable/disable the device to act as a transparent proxy between AP and Station networks.

All requests that don't collide with existing API paths will be bridged to the destination according to the Host HTTP header. The destination host is called using the existing Wi-Fi connection (established after a PUT /wifi/connect) and all contents are bridged back to the connection made to the AP side.

This feature can be used to help captive portals to perform cloud API calls during device enrollment using the ESP8266 Wi-Fi AP connection without having to patch the Homie firmware. By using the transparent proxy, all operations can be performed by the custom JavaScript running on the browser (in SPIFFS location /data/homie/ui_bundle.gz).

HTTPS is not supported.

Important: The HTTP requests and responses must be kept as small as possible because all contents are transported using RAM memory, which is very limited.

Request body

(application/json)

{
  "enable": true
}

Response

In case of success

200 OK (application/json)

{
  "success": true
}
In case of error in the payload

400 Bad Request (application/json)

{
  "success": false,
  "error": "Reason why the payload is invalid"
}