Skip to content

Latest commit

 

History

History
133 lines (88 loc) · 3.02 KB

6.-Configuration-API.md

File metadata and controls

133 lines (88 loc) · 3.02 KB
Raw

Configuration API

When in configuration mode, the device exposes a 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 file system 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-xxxxxxxx AP spawned in configuration mode
  3. Follow the instructions

You can see the sources of the Web UI here and the built version here

Alternatively, you can use this curl command to send the config to the device:

curl -X PUT http://homie.config/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 200 OK HTTP code is returned. If anything goes wrong, a return code != 200 will be returned, with a JSON error field indicating the error.

API endpoints

GET /heart

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

Response

200 OK (application/json)

{ "heart": "beat" }

GET /device-info

Get some information on the device.

Response

200 OK (application/json)

{
  "device_id": "52a8fa5d",
  "homie_version": "1.0.0",
  "firmware": {
    "name": "awesome-device",
    "version": "1.0.0"
  },
  "nodes": [
    {
      "id": "light",
      "type": "light"
    }
  ]
}

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" }