OpenWiFi 2.0 SDK
OpenWiFi services follow the OpenAPI 3.0 definition. The complete API is described here: OpenWiFi SDK OpenAPI
OpenWiFi devices are Access Points or Switches (and other forms in the future), that support the uCentral configuration schema. Devices contact a controller using the uCentral protocol.
The communication between the controller and the devices use the uCentral protocol. This protocol is defined in this document.
A device is configured by ingesting a uCentral configuration. That configuration will be provided by the SDK Gateway as a result of a command through the API. Command processing occurs when the device's configuration is older than what is known in the SDK Gateway. The uCentral schema is a JSON document containing parameters to set on a particular device.
In order to speak to the Gateway, you must implement a client that uses the OpenAPI definition for the gateway. You can find its definition here. You cannot talk to a device directly.
serialNumberThroughout the API, the serialNumber of the device is used as the key. The serialNumber is actual the MAC address of the device, without its :. The serialNumber is guaranteed to be unique worldwide. The device uses its serial number to identify itself to the controller.
The configuration can be supplied when the device is created. After the device is created, the only way to modify the configuration is by using the /device/{serialNumber}/configure endpoint. The Gateway maintains the versioning of the configuration through the use of a uuid. The Gateway maintains that number and will ignore anything your supply. The controller also does minimum validation on the configuration: it must be a valid JSON document and must have a uuid field which will be ignored.
Device capabilities are uploaded to the Gateway when the device performs its initial connection. Capabilities tell the Gateway what the device is able to support. The Gateway uses this information to provide a configuration matched to the device type.
The Gateway will send commands to the devices. These commands are kept in a table and are sent at the appropriate time or immediately when the device connects.
For example, you could ask a device to change its configuration, however it might be unreachable. Upon next device connection, this configure command will be sent. The list of commands is retrieved using the /commands endpoint.
Several commands maybe sent to a device: reboot, configure, factory reset, firmware upgrade, LEDs, trace, message request, etc. The API endpoint /device/{serialNumber}/{command} details all the available commands.
For each device, a number of collections are collected and kept in the database. Here's a brief list:
logs: device specific logs are kept. A device amy also send something it wants added into its own logs. crashlogs are a special type of logs created after a device has had a hard crash.
statistics: statistics about the device. This is current la JSON document and will be documented at a later date.
healthchecks: periodically, a device will run a self-test and report its results. These includes anything that maybe going wrong with the current device configuration. A sanity level is associated to the degree of health of the device. 100 meaning a properly operating device.
status: tells you where the device is and how much data is used for protocol communication.
This API is meant for an operator who would have to help a subscriber in configuring devices, reboot, manage firmware, etc.
OpenWiFi 2.0 SDK
This uses OpenAPI definition 3.0 and can be found here. All endpoints begin with /api/v1.
API endpoints are secured with bearer-token authentication using end-point /oauth2.
Once you obtain access-token, you will need to pass it in the headers under Authorization: Bearer <place your token here>.
The API revolves around devices, commands, and default_configurations.
To retrieve a list of devices to know what is available and then use the endpoint device to access all device specific information.
To retrieve commands and default_configurations follow those endpoints.
Most operations rely on the serialNumber of a device. That serialNumber is unique and generated on the device. Serial Number matches the device's MAC address.
devices: The list of all devices in the system. This maybe very large, pagination is recommended.
commands: The list of commands issued by the system. This list could also be large.
default_configurations: A list of default configurations used to supply existing devices.
A device is a physical (or potentially logical) entity using the ucentral protocol. Currently, APs and Switches are the only devices used. A device has several attributes. Additionally, other collections are supported for each device:
logs: Specific for a device. Logs originate from the device or associated with the device by some mechanism.
healthchecks: Reports from the device coming periodically after device self tests.
statistics: Periodically produced by the devices and document actual state data from each device.
capabilities: This details the actual data model supported by the device.
The device entry point is also used to query about the status of the device and used to inject certain commands for a specific device.
Commands supported for each device:
reboot: This will force the device to reboot.
configure: Configure sends a new configuration to a device.
factory: Forces the device to perform a factory-reset.
upgrade: Forces the device to do a firmware upgrade.
leds: Ask the device to flash its LEDs or turn them on or off.
trace: Performs a remove LAN trace. Once the trace is completed, the produced file may be removed using the file endpoint.
command: Performs a proprietary command. The meaning depends on the device.
request: Request an immediate message of type state or healthcheck.
The file end point is used to retrieve and remove files produced by the Gateway. Currently this is limited to the results of a trace command. The file name will always match the uuid of the command that produced it. If several files are needed, the files will be named uuid, uuid.1, uuid.2, etc.
All dates should use the format defined in RFC3339. All times are UTC based. Here is an example:
when parameterMost commands use a when parameter to suggest to the device when to perform the command. This is a suggestion only. The device may decide to perform the command when it is optimal for itself. It maybe busy doing something and decline to do a reboot for several minutes for example. The device may reply with the actual when it will perform the command.
The gateway manages the configuration UUID. So if you set a UUID for a configuration, it will be ignored. The gateway uses UUID as versioning. The UUID is unique within a single device. The resulting UUID or a configuration change is returned as part of the configure command.