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.
/oauth2
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
User Id and password.
/users
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,id5No body
/user/{id}
root, admin, subscriber, csr, system, installer, noc, accountinginternal, normal, gmail, facebook, linkedin, instagramNo body
/user/{id}
root, admin, subscriber, csr, system, installer, noc, accountinginternal, normal, gmail, facebook, linkedin, instagramNo body
/securityProfiles
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
No body
Get a list of firmwares.
/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 firwares
/firmware/{id}
/firmware/{id}
/revisionHistory/{serialNumber}
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
/revisionHistory/{serialNumber}
Pagination start (starts at 1. If not specified, 1 is assumed)
No body
/firmwareAge
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./connectedDevices
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
Get a list of devices.
/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,serial3only serial numbers of full device details
return the number of devices
countOnly=trueReturn extra information with the device information
Get a list of commands.
/commands
Selecting this option means the newest record will be returned. Use limit to select how many.
Create a default configuration.
/default_configuration/{name}
Update a default configuration
/default_configuration/{name}
/device/{serialNumber}
AP, SWITCH, IOT, MESH/device/{serialNumber}
AP, SWITCH, IOT, MESH/device/{serialNumber}/logs
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.
/device/{serialNumber}/logs
0=any kind of logs (default) 1=normal logs only 2=crash logs only
No body
/device/{serialNumber}/healthchecks
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.
/device/{serialNumber}/statistics
Selecting this option means the LifetimeStatistics will be returned. All other parameters will be ignored.
Selecting this option means the LifetimeStatistics will be returned. All other parameters will be ignored.
Selecting this option means the newest record will be returned. Use limit to select how many.
/device/{serialNumber}/statistics
No body
/device/{serialNumber}/leds
only applies to the blink pattern
on, off, blinkNo body
/device/{serialNumber}/trace
No body
/device/{serialNumber}/telemetry
0 - means to stop streaming, values 1-120 in seconds.only valid when terminating a streamNo body
Get a list of blacklisted devices.
/blacklist
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
/blacklist/{serialNumber}
Pagination start (starts at 1. If not specified, 1 is assumed)
/blacklist/{serialNumber}
Pagination start (starts at 1. If not specified, 1 is assumed)
/entity/{uuid}
When creating the root entity, the uuid 0000-0000-0000 must be entered. When creating a non-root entity, uuid must be 1If 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
off, on, inheritNo body
/entity/{uuid}
When modifying the root entity, the uuid 0000-0000-0000 must be entered.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
off, on, inheritNo body
/contact
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,uuid3return the number of contacts
return only the UUIDs of contacts
/contact/{uuid}
SUBSCRIBER, USER, INSTALLER, CSR, MANAGER, BUSINESSOWNER, TECHNICIAN, CORPORATENo body
/contact/{uuid}
SUBSCRIBER, USER, INSTALLER, CSR, MANAGER, BUSINESSOWNER, TECHNICIAN, CORPORATENo body
/location
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,uuid3return the number of Locations
return only the UUIDs of Locations
/location/{uuid}
SERVICE, EQUIPMENT, AUTO, MANUAL, SPECIAL, UNKNOWN, CORPORATEeach uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/location/{uuid}
SERVICE, EQUIPMENT, AUTO, MANUAL, SPECIAL, UNKNOWN, CORPORATEeach uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/inventory
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,serial3only serial numbers of full device details
return the number of devices
return extended information
return extended information
serialNumber:a,created:dreturn the list of devices under RRM
return the list of devices under RRM
/inventory/{serialNumber}
/inventory/{serialNumber}
off, on, inheritany, venue, entity, subscriberNo body
/inventory/{serialNumber}
off, on, inheritany, venue, entity, subscriber/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 Venues comma separated
serial1,serial2,serial3only serial numbers of full device details
return the number of devices
/venue/{uuid}
off, on, inheritThe 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
No body
/venue/{uuid}
off, on, inheritThe 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
No body
/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
Return only maps I created
Return only maps shared with Me
/map/{uuid}
private, public, selectNo body
/map/{uuid}
private, public, selectNo body
/managementPolicy
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,serial3return the number of policies
/managementPolicy/{uuid}
each uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/managementPolicy/{uuid}
each uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/managementRole
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,serial3return the number of roles
/managementRole/{uuid}
during creation, must be set to 1. The real uuid will be returned in the created objecteach uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/managementRole/{uuid}
each uuid is preceded by ent, or ven to say that the elemenet is entity or venueNo body
/configurations
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,serial3return the number of devices
/configurations/{uuid}
When looking for the root entity, the uuid 0000-0000-0000 must be entered./configurations/{uuid}
When creating the root entity, the uuid 0000-0000-0000 must be entered. When creating a non-root entity, uuid must be 1off, on, inheritauto or a time string of the format DOW-HH:MMNo body
/configurations/{uuid}
When modifying the root entity, the uuid 0000-0000-0000 must be entered.off, on, inheritauto or a time string of the format DOW-HH:MMNo body
/signup
/signup
cancel, emailVerified, deviceVerifiedNo body
/signup
/variables
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,serial3return the number of devices
No body