Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Here is the current postman collection for testing purposes:
OpenWiFi 2.0 SDK
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.
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.
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 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.
Returns the current RRM data model.
Data model
Returns the device topology.
Device topology
Perform some system-wide commands.
Command details
Successful command execution
Returns the RRM provider info.
Success
Set the device topology.
The device topology
Success
Returns the RRM algorithm list.
Success
Run channel optimizer and return the new channel allocation.
The assignment algorithm to use:
The RF zone
Do not apply changes
Channel allocation
Run tx power optimizer and return the new tx power allocation.
The assignment algorithm to use:
The RF zone
Do not apply changes
Tx power allocation
Run a specific RRM algorithm now.
The algorithm name
The algorithm arguments
The RF zone
Do not apply changes
Success
Returns the system info from the running service.
Get a value
Success
Returns the device configuration by applying all configuration layers.
The device serial number
Device configuration
Modify the AP layer of the network configuration for the given AP. Any existing fields absent from the request body will be preserved.
The device serial number
The device AP configuration
Success
Set the AP layer of the network configuration for the given AP.
The device serial number
The device AP configuration
Success
Set the zone layer of the network configuration for the given zone.
The RF zone
The device zone configuration
Success
Returns the device layered configuration.
Device layered configuration
Set the network layer of the device configuration.
The device network configuration
Success
OpenWiFi services follow the OpenAPI 3.0 definition. The complete API is described here:
The communication between the controller and the devices use the uCentral protocol. This protocol is defined in this .
In order to speak to the Gateway, you must implement a client that uses the OpenAPI definition for the gateway. You can find its . You cannot talk to a device directly.
Setting the list of preferences
QRCode
"1,2,3"
Succesful posting of response.
Selecting this option means the newest record will be returned. Use limit to select how many.
Return only the ids.
Return only the ids.
"id1,id2,id3,id4,id5"
Name matching
Name matching
Successfully retrieved the avatar
The requested operation was performed.
The requested operation was performed.
The requested operation was performed.
Get a value
Successful command execution
successful operation
The requested operation was performed.
successful operation
The requested operation was performed.
User id and password
The requested operation was performed.
successful operation
The requested operation was performed.
Command details
Successful command execution
The requested message
The requested operation was performed.
The requested message
The requested operation was performed.
Pagination start (starts at 1. If not specified, 1 is assumed)
Maximum number of entries to return (if absent, no limit is assumed)
Filter the results
used when a user is trying to change her password. This will be the new password.
A user forgot her password. She needs to present her e-mail address in the userId and set this to true
A user forgot her password. She needs to present her e-mail address in the userId and set this to true
"refresh_token"
User id and password
successful operation
used when a user is trying to change her password. This will be the new password.
A user forgot her password. She needs to present her e-mail address in the userId and set this to true
A user forgot her password. She needs to present her e-mail address in the userId and set this to true
"refresh_token"
User id and password
successful operation
User details (some fields are ignored during creation)
User details (some fields are ignored during update)
User details (some fields are ignored during creation)
User details (some fields are ignored during update)
Selecting this option means the newest record will be returned. Use limit to select how many.
Return only the ids.
Return only the ids.
"id1,id2,id3,id4,id5"
Name matching
Name matching