This will be boring so just imagine having to write it. However, I think this could help you understand everything else.
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 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 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 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.
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.
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 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 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 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.
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.crashlogsare 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. Asanitylevel 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 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.