Provisioning - qtoggle/espqtoggle GitHub Wiki

About

When it comes to an espQToggle device, the provisioning mechanism represents the process of setting up the following aspects of the device:

Provisioning can be done in two ways:

Automatic Provisioning

Device will automatically attempt to fetch provisioning information based on the config_name attribute. At every boot, it will try to download the following file:

http://provisioning.qtoggle.io/config/espqtoggle/{config_name}.json

If the file is present and valid, it will be used for provisioning. A special version field will allow the device to tell whether there is a new provisioning file available or its existing provisioning information is up-to-date.

For a list of available configurations, clients (frontends or any other consumer) can download the following file:

http://provisioning.qtoggle.io/config/available.json

Manual Provisioning

Manual provisioning can be done via API, using the /provisioning API endpoint. In fact, the expected content of the manual provisioning request is identical to that of the provisioning files used by automatic provisioning.

Manual provisioning makes sense in the following cases:

  • a device is being configured for a particular use case
  • testing while adding support for a device type
  • there's simply no support (yet) for a given device

Backup & Restore

While one could use the provisioning endpoints to backup and restore a device, there are a few differences from the backup & restore mechanism described by the qToggle API:

  • the device name and display name won't be overwritten
  • the Wi-Fi and IP attributes won't be overwritten
  • ports will not be reset to their initial state, but rather simply updated using supplied attributes

Provisioning File Format

A provisioning file is in fact a JSON file containing a dictionary with keys and associated configuration for all the aspects that should be covered by the file. All elements in the root dictionary (including version) are optional. Configuration corresponding to missing ones will be left untouched.

The file format has been designed to match the qToggle API recommendations for backup files.

Here's the general format of a provisioning file:

{
    "version": number,
    "peripherals": [...],
    "system": {...},
    "device": {...},
    "ports": [...],
    "webhooks": {...},
    "reverse": {...}
}
  • version: a number that represents the version of the provisioning file (increased at each change)
  • peripherals: the list of peripherals to be configured
  • system: the system configuration
  • device: attributes to be set on the device (see Device)
  • ports: a list of ports with their attributes (see Ports)
  • webhooks: webhooks parameters (currently not supported)
  • reverse: reverse parameters (currently not supported)

Device

Any attributes specified in this dictionary will be used to update the device attributes. There are however some exceptions:

  • name will be ignored (device name cannot be changed via provisioning)
  • display_name will only be used if device has no current display name (the display name will not be overwritten by provisioning)

Ports

Each element in the list of ports is a dictionary with port attributes. Normally, any attribute specified in the dictionary will be used to update the attribute of the corresponding port. However, there are some important remarks:

  • the id attribute must be present, so that the port can be identified
  • if the virtual attribute is present, the port will be created using details supplied in the remaining attributes (it will be deleted first, if already exists)
  • non-modifiable attributes will be silently ignored (unless virtual is true and attributes such as type are required)
  • existing ports that are not found in the list will be left untouched

API Endpoint

The /provisioning endpoint is exposed by devices running espQToggle; keep in mind though that it is not a standard qToggle API endpoint.

This API function requires admin access level.

GET /provisioning

Returns the currently provisioned configuration.

Response has the format indicated in Provisioning File Format. The version field will be missing when using the API endpoint, though.

PUT /provisioning

Performs a manual provisioning by supplying the provisioning file.

This API function requires admin access level.

Request has the same body format and meaning as GET /provisioning.

Response has no body.