wlan-cloud-ucentralgw/THEBASICS.md

Understanding the gateway

This will be boring so just imagine having to write it. However, I think this could help you understand everything else.

The whole uCentral system

So uCentral is a protocol, a schema, and a whole system. No wonder you are confused. Let's split the system in its components:

The controller

The controller responds to API calls. The APi calls may be used to reboot a device, force a firmware upgrade, set the configuration for a device, look at the logs for a device. The controller receives connection requests from the devices.

The devices

The 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

The communication between the controller and the devices use the uCentral protocol. This protocol is defined in this document.

Device configuration

A device is configured by ingesting a uCentral configuration. That configuration will be provided by the controller as a result of a command through the API of because the device's configuration is too old for what is known in the controller. The uCentral is a JSON document containing parameters to set on a particular device.

Talking to the controller

In order to speak to the controller, 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.

API Basics

The serialNumber

Throughout 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

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 controller maintains the versioning of the configuration through the use of a uuid. The controller 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

Device capabilities are uploaded to the controller when the device does its initial connection. Capabilities tell the controller what the device is able to support. The controller can use this information in order to provide a better configuration for the device.

The command queue

The controller will send commands to the devices. These commands are kept in a table and are sent at the appropriate time or immediately when the connects. For example, you could ask a device to change its configuration, however it is unreachable. So the next time the device connects, this configure command will be sent at that time. You can get the list of commands using the /commands endpoint.

The commands

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.

Device specific collections

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.

The API is for an operator

This API is really meant for an operator who would have to help a subscriber in configuring her devices, reboot, manage the firmware, etc. The API should be the lowest level anyone should go in managing a device. Someone could be an entire firmware management system with the existing API.