Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Here is the current postman collection for testing purposes:
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
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
Pagination start (starts at 1. If not specified, 1 is assumed)
Maximum number of entries to return (if absent, no limit is assumed)
Maximum number of entries to return (if absent, no limit is assumed)
Maximum number of entries to return (if absent, no limit is assumed)
"112233445566, 11223344*, *5566"The venue to for the search.
"112233aabbcc"The venue to for the search.
Maximum number of entries to return (if absent, no limit is assumed)
"112233445566, 11223344*, *5566"The requested operation was performed.
Return a list of boards
The requested operation was performed.
"10.2.2.2,10.3.4.3"List of country codes.
The requested operation was performed.
"value should be 0 for a post"Get a value
Successful command execution
Command details
Successful command execution
"112233aabbcc"Pagination start (starts at 1. If not specified, 1 is assumed)
Maximum number of entries to return (if absent, no limit is assumed)
The venue to for the search.
return extended information
"serialNumber:a,created:d"return extended information
Delete a default default configuration
Succesfull file retrieval
Change RADIUS configuration pool config
this must be the base64 encoded of the entire content of the certificate file, including the -----BEGIN lines
this must be the base64 encoded of the entire content of the key file, including the -----BEGIN lines
each entry must be the base64 encoded of the entire content of the ca files, including the -----BEGIN lines
this must be the base64 encoded of the entire content of the certificate file, including the -----BEGIN lines
this must be the base64 encoded of the entire content of the key file, including the -----BEGIN lines
each entry must be the base64 encoded of the entire content of the ca files, including the -----BEGIN lines
this must be the base64 encoded of the entire content of the certificate file, including the -----BEGIN lines
this must be the base64 encoded of the entire content of the key file, including the -----BEGIN lines
each entry must be the base64 encoded of the entire content of the ca files, including the -----BEGIN lines
List of logs for this device
Successfully deleted commands for the device.
Successfully deleted health checks for the device.
Array of statistics for this device
The requested operation was performed.
0=any kind of logs (default) 1=normal logs only 2=crash logs only
Successfully deleted logs for the device.
"10.2.2.2,10.3.4.3"List of country codes.
Delete a specific command
Delete command success
Successful command execution
List of logs for this device
Get a list of blacklisted devices.
Pagination start (starts at 1. If not specified, 1 is assumed)
List blacklisted devices
Command details
Successfull ping os a device
Retrieve a default configuration.
Default configurations included
Retrieve the lists of all default configurations.
List of defautl configurations included
Pagination start (starts at 1. If not specified, 1 is assumed)
Add blacklisted device
The requested operation was performed.
Pagination start (starts at 1. If not specified, 1 is assumed)
Add blacklisted devices
The requested operation was performed.
Session information
Message request details
Create a default configuration.
Information used to create the new device
The requested operation was performed.
Update a default configuration
Configuration details
The requested operation was performed.
Message request details
The command was submitted succesfully.
Selecting this option means the newest record will be returned. Use limit to select how many.
Selecting this option means the last healthcheck will be returned. All other parameters will be ignored.
Array of device health checks for this device
Get a list of blacklisted devices.
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
List blacklisted devices
Selecting this option means the Last Statistics block
Selecting this option means the newest record will be returned. Use limit to select how many.
Array of statistics for this device
0=any kind of logs (default) 0=normal logs only 1=crash logs only
Selecting this option means the newest record will be returned. Use limit to select how many.
Array of device logs for this device
Get a value
Successful command execution
Status for the given device
Command details
Successful command execution
Returns a specific command
List commands
Retrieve all the inforamtion about a single device
Device information
Command details
Command details
Get a list of commands.
Selecting this option means the newest record will be returned. Use limit to select how many.
List commands
Command details
Command details
Command details
Command details
Command details
only applies to the blink pattern
Message request details
0 - means to stop streaming, values 1-120 in seconds.
how long should the telemetry run
set to true to start kafka telemetry, false to start websocket telemetry
only valid when terminating a stream
Command details
Information used to create the new device
Successful device creation will return the device record with the proper device ID
Information used to create the new device
Successful device creation will return the device record with the proper device ID
Scan details
Get a list of devices.
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
Supply a list of devices comma separated
"serial1,serial2,serial3"only serial numbers of full device details
return the number of devices
"countOnly=true"Return extra information with the device information
return extended information
"serialNumber:a,created:d"return extended information
return extended information
List devices
"The root entity cannot be deleted.""The root entity cannot be deleted.""The root entity cannot be deleted.""The root entity cannot be deleted.""10.2.2.2,10.3.4.3"List of country codes.
The requested operation was performed.
Information used to modify the new policy.
this is a list of UUID and UUID Patterns to control by this policy
A JSON document describing the policy
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Get a value
Successful command execution
Information used to modify a map
Information used to modify management role
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue""during creation, must be set to 1. The real uuid will be returned in the created object"Information used to create management role
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue""should be set to 0 when creating a new operator"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
Supply a list of policies comma separated
"serial1,serial2,serial3"return the number of policies
Return a list of Venues
this is a list of UUID and UUID Patterns to control by this policy
A JSON document describing the policy
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"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
Return only maps I created
Return only maps shared with Me
Return a list of Venues
Command details
Successful command execution
Successfull completion
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
Supply a list of devices comma separated
"serial1,serial2,serial3"return the number of roles
Return a list of elements
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new location
Information used to modify the new location
The operator
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
Supply a list of operators comma separated
"serial1,serial2,serial3"return the number of operators
Successfully retrieved operator list
Success
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"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
Supply a list of operators comma separated
"serial1,serial2,serial3"return the number of operators
Successfully retrieved operator list
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue""should be set to 0 when creating a new operator""each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new entity
Information used to modify the new entity
Success
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Succesful retrieve a management policy
this is a list of UUID and UUID Patterns to control by this policy
A JSON document describing the policy
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new location
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to modify the new location
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new entity
Information used to modify the new entity
Successfull retrieval of a map
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
Supply a list of devices comma separated
"serial1,serial2,serial3"return the number of devices
Return a list of elements
Success
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"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
Supply a list of Locations comma separated
"uuid1,uuid2,uuid3"return the number of Locations
return only the UUIDs of Locations
Return a list of Locations
Information used to create the new policy
this is a list of UUID and UUID Patterns to control by this policy
A JSON document describing the policy
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new entity
Information used to modify the new entity
success
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
Supply a list of operator contacts comma separated
"uuid1,uuid2,uuid3"return the number of operator contacts
return only the UUIDs of operator contacts
Return a list of operator contacts
"When creating the root entity, the uuid 0000-0000-0000 must be entered. When creating a non-root entity, uuid must be 1"Information used to create the new entity
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
Supply a list of Locations comma separated
"uuid1,uuid2,uuid3"return the number of Locations
return only the UUIDs of Locations
Return a list of Locations
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"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
Supply a list of devices comma separated
"serial1,serial2,serial3"only serial numbers of full device details
return the number of devices
return extended information
return extended information
"serialNumber:a,created:d"return extended information
return the list of devices under RRM
return the list of devices under RRM
return RRM settings for a specific device
return the resolved configuration for a specific device
Return a list of elements
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
Supply a list of contacts comma separated
"uuid1,uuid2,uuid3"return the number of contacts
return only the UUIDs of contacts
Return a list of contacts
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
Supply a list of devices comma separated
"serial1,serial2,serial3"return the number of devices
"When modifying the root entity, the uuid 0000-0000-0000 must be entered."Information used to modify the new entity
Information used to create the new policy
"When looking for the root entity, the uuid 0000-0000-0000 must be entered."Success
The operator
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
Supply a list of operators comma separated
"serial1,serial2,serial3"return the number of operators
list of subscriber devices
Succesful retrieve configuratiopn or part of the configuration
"should be set to 0 when creating a new operator"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
Supply a list of devices comma separated
"serial1,serial2,serial3"return the number of devices
Return a list of elements
If empty, then this is the root entity, otherwise this points to a parent entity
The list of UUID of the venues for this entity
The list of UUID of the contacts for the entity
The list of UUID of the locations associated with thit entiry
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
"When modifying the root entity, the uuid 0000-0000-0000 must be entered."Information used to modify the new entity
If empty, then this is the root entity, otherwise this points to a parent entity
The list of UUID of the venues for this entity
The list of UUID of the contacts for the entity
The list of UUID of the locations associated with thit entiry
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
"When creating the root entity, the uuid 0000-0000-0000 must be entered. When creating a non-root entity, uuid must be 1"Information used to create the new entity
If empty, then this is the root entity, otherwise this points to a parent entity
The list of UUID of the venues for this entity
The list of UUID of the contacts for the entity
The list of UUID of the locations associated with thit entiry
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
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
Supply a list of Venues comma separated
"serial1,serial2,serial3"return the number of devices
return the devices under a venue
return the devices under a venue and its children. Must select getDevices=true as well.
Return a list of venues.
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of OWAnalytics Boards created for this venue
"When looking for the root entity, the uuid 0000-0000-0000 must be entered."Information used to modify the new venue
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of OWAnalytics Boards created for this venue
Return venue information or list of serial number updated
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of OWAnalytics Boards created for this venue
"each uuid is preceded by ent, or ven to say that the elemenet is entity or venue"Information used to create the new venue
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of UUID of the venues for this entity
The list of OWAnalytics Boards created for this venue
Successfully deleted Firmware for the device.
The requested operation was performed.
Pagination start (starts at 1. If not specified, 1 is assumed)
Success.
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
Return current device list and current firmware
"You must set {serialNumber} to 000000000000"Return current device list and current firmware
"You must set {serialNumber} to 000000000000"List of device history upgrade.
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
List firmwares
Get a value
Successfull command execution
The exact current verion of the firmware on that device.
The exact current verion of the firmware on that device.
Specify lits of serial numbers to retrive age for
"select=serial1,serial2,serial4,serial5."The recommended latest version to update to.
"this is in seconds. a 0 means we cannot determine the age. something like 'unknown' should be shown to the user."Command details
Successfull command execution
SerialNumber of the device
Get information about a connected device.
"aabbccdd1234"Get a Firmware.
A Firmware definition
Firmware details
Successfully updated firmware
Get a list of firmwares.
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
Return only the latest firmware
List firmwares
A full analysis report
Created a firmware entry.