What is OpenWiFi?

TIP OpenWiFi is an open source community project that believes in democratizing premium Wi-Fi experiences for multiple market use cases. The TIP approach to OpenWiFi creates an open source disaggregated technology stack without any vendor lock in. OpenWiFi offers premium managed Wi-Fi features, local break-out design, cloud native open source controller, and an open source AP firmware operating system tested nightly.

TIP OpenWiFi is the industry's first CI/CD open source Wi-Fi eco-system. Built nightly with a strong community of Wi-Fi leaders, new features are unit tested in automated RF chambers and checked from cloud to ground for Wi-Fi performance and conformance.

OpenWiFi 2.0 introduces management and telemetry based on uCentral offering expanded selection of managed devices including smaller APs and PoE access switches.

High Level Features

Each OpenWiFi AP offers:

• Multiple topologies including :

  • Bridging, Virtual LAN, VxLAN, NAT Gateway, Local Breakout, Overlay (PPPoE, L2oGRE, L2TP), Mesh, WDS

• Multiple authentications including WPA, WPA2, WPA3, Enterprise Radius models, M-PSK

Each OpenWiFi PoE Switch offers:

• IEEE802.1Q Virtual LAN

• VxLAN

• DHCP Snooping & Relay

Cloud SDK in OpenWiFi offers:

• Zero Touch Provisioning

• Firmware Management

• Integration Northbound Interface (NBI) RESTful

OpenWiFi AP Detail List:

• Wi-Fi 4 (n) Wi-Fi 5 (ac) Wi-Fi 6 (ax)

• Dual Bank Bootloader

• Multi-SSID per Radio

Cloud SDK additional features

• Provisioning

  • Device Identity (Model, MAC, Serial Number)

  • Device Software Upgrade

How to contribute

If you or your company are interested in contributing to TIP Open Wi-Fi, please join the Wi-Fi Product Group by visiting to become a member.

OpenWiFi services follow the OpenAPI 3.0 definition. The complete API is described here: OpenWiFi SDK OpenAPI

Devices

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.

Communication

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

Device Configuration

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.

SDK Gateway Communication

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.

API Basics

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.

Device 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 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

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.

Command Queue

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.

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.

The API is for an operator

This API is meant for an operator who would have to help a subscriber in configuring devices, reboot, manage firmware, etc.

Where is the OpenAPI?

This uses OpenAPI definition 3.0 and can be found here. All endpoints begin with /api/v1.

API Flow

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>.

Basic Entities

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

Relationships

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

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

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.

Dates

All dates should use the format defined in . All times are UTC based. Here is an example:

Command when parameter

Most 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.

Configuration UUID

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.

OpenWiFi supports Zero Touch Provisioning in a number of ways.

• Zero Touch Mesh

• Zero Touch WDS

• Zero Touch Provisioning ( Provisioning Services in upcoming 2.5/2.6 Release )

Onboarding

OpenWiFi makes use of TIP device certificates present on every access point as a secure identity from which to automate a number of Zero Touch operations.

Onboarding is a local EAP-TLS based authentication service available on any OpenWiFi device that works together with default OpenWiFi firstboot behavior to scan for "OpenWifi-onboarding" SSID, associate to that SSID, when challenged supply TIP root signed device certificate.

Onboarding Steps

1. Provision an Access Point for onboarding role as an SSID config { "purpose": "onboarding-ap", "bss-mode": "ap", "encryption": { "proto": "wpa2", "ieee80211w": "required" }, "certificates": { "use_local_certificates": true }, "radius": { "local": { "server-identity": "uCentral-EAP" } }, "name": "OpenWifi-onboarding", "wifi-bands": [ "2G" ] }

2. Ensure the SSID for onboarding use provides network connectivity for clients

Zero Touch Mesh

Deployment of Mesh may have multiple Mesh Client access points with no wired connectivity. These devices use IEEE802.11s Mesh participating interface(s) as transit for WAN / LAN connections.

In a Zero Touch Mesh deployment, the Gateway Access Point, sometimes termed the Root node, advertises mesh participating interfaces when "bss-mode": "mesh" is applied to an SSID. Please see for further details on initial setup.

Mesh Client Access Points needing to associate wirelessly for initial provisioning to join the mesh network, may be served using the onboarding feature of OpenWiFi.

Adding an SSID to the Mesh Gateway Access Point configuration to advertise "OpenWifi-onboarding" enables initial boot of any OpenWiFi Access Point to reach the OpenWiFi Gateway.

Upon connection to Onboarding, the Access Point obtains management network access from the upstream Access Point providing "onboarding-ap" service.

With management network access, reachability for the Mesh Client Access Point to the OpenWiFi Gateway should be possible, device provisioning stage will initiate with the production configuration being loaded to the client device.

Once processed, client Access Point will have receive provisioning to join the Mesh network as a Mesh Client Access Point.

Zero Touch WDS

Deployment of WDS links may have multiple WDS client devices with no wired WAN connectivity. WDS Access Points use the 4-tuple frame header with participating WDS Clients. Therefore WDS Clients must first receive provisioning from the OpenWiFi Gateway for their production state as a WDS link participant.

WDS Client Access Points needing to associate wirelessly for initial provisioning to join the WDS network, may be served using the onboarding feature of OpenWiFi from the WDS Root Access Point at the top of the topology with a "bss-mode": "ap" SSID for onboarding.

Adding an SSID to the WDS Root Access Point configuration to advertise "OpenWifi-onboarding" enables initial boot of any OpenWiFi Access Point to reach the OpenWiFi Gateway.

Upon connection to Onboarding, the WDS Client Access Point obtains management network access from the upstream WDS Root Access Point providing "onboarding-ap" service.

With management network access, reachability for the WDS Client Access Point to the OpenWiFi Gateway should be possible, device provisioning stage will initiate with the production configuration being loaded to the client device. For more information on WDS configuration please consult .

Once processed, WDS Client Access Point will have receive provisioning to join the WDS link as a Client WDS node.

TIP Wi-Fi members may contact the ODM manufacturers in the TIP OpenWiFi eco-system using the information posted within Community Confluence page.

If your organization is not already a TIP Open Converged Wireless Project Group (OCW PG) member, consider signing up. Joining the OCW PG is free as a Software Participation Tier in TIP.

For more information please visit: Becoming a Member

TIP OpenWiFi enables integration by commercial controllers to the OpenWiFi Software Development Kit (SDK).

The OpenWiFi SDK is designed to enable cloud partners to consume basic southbound device management and device discovery at a minimum. This is similar to augmenting a southbound device adapter for many orchestration or automation systems.

The OpenWiFi SDK also offers numerous micro services of incremental functionality for cloud partners to optionally consume including:

• Firmware Management

• Device Provisioning

• Subscriber Portal

• Analytics

• User Interface

This independent micro service approach has numerous advantages including ease of integration, ability to leverage more of the stack to accelerate product availability or support only device communication and discovery for partners who seek to maintain more functionality within their own application.

Step 1 : Join

If your organization is not already a TIP Open Converged Wireless Project Group (OCW PG) member, consider signing up. Joining the OCW PG is free as a Software Participation Tier in TIP.

For more information please visit:

Step 2 : Slack, Keys & Atlassian Tools

Introduce your organization to the Community on Slack. All Community members have access to Telecom Infra Project Slack. Send a message to "general" and "open-wifi-ucentral" channels.

Send an email to licensekeys@telecominfraproject.com to request onboarding as a supplier for OpenWiFi Cloud. All OpenWiFi Gateway services in the SDK require a signed key to terminate incoming device connections in the southbound interface.

Ensure your GitHub account was linked in your Telecom Infra Project user profile, this will enable write access to OpenWiFi repositories. Also confirm Atlassian link is also present in user profile.

Step 3 : Integration

OpenWiFi SDK uses OpenAPI 3.0 compliant northbound Rest API and Kafka for message bus topics. Typical CRUD actions occur via the Rest API, Kafka will present topics for device discovery and all telemetry captured from the network edge.

Please consult the to begin with integration work.

Summary

Integrations that use the published interfaces are the easiest approach to starting with OpenWiFi SDK.

If a cloud partner seeks to contribute a new SDK micro service, please announce the idea on "general" and "open-wifi-ucentral" slack channels for the Community to help further. There is a skeleton micro service example to help developers build new services that inherit SDK service discovery and security design.

Please find skeleton service .

All TIP OpenWiFi devices use the same cloud discovery mechanism on initial boot.

OpenWiFi devices ship from factory with a unique device certificate signed by the Telecom Infra Project Certificate Authority.

When a device boots for the first time, or is factory reset, a 'first-boot' process occurs within the device. First-boot initiates a connection over HTTPs to the Certificate Authority requesting the unique device record information. All connections to the Certificate Authority occur over mTLS encrypted session. Devices use their unique certificate identity to authenticate and retrieve the location of the assigned cloud.

Once the cloud location has been learned from first-boot, the device no longer depends on this cloud discovery and will return to the assigned cloud learned from first-boot.

OpenWiFi 2.0 Minimum Viable Product at the end of July, 2021 enables a cloud native and cloud agnostic Software Development Kit (SDK) with management and deployment support for a wide range of Access Point and PoE network switch platforms.

Initial release 2.0 SDK includes:

• Zero Touch Cloud Discovery

• Firmware Management

• User Interface

  • Device List

  • Device Reboot

Upcoming sprint for August includes Dynamic Provisioning service support for template based device configuration.

OpenWiFi 2.0 SDK is deployable as both a Docker Compose or a Helm on Kubernetes model. See section for installation instructions.

New in this Release

• Firmware

  • Basic Features for OpenWiFi Switching

  • Passpoint

Release 2.0 SDK offers a number of ways to consume OpenWiFi. Available as a single Docker for just the uCentralGW or as a set of micro services offering increasing value to consume helps multiple eco-system partners use as much or as little as desired to integrate with or build a commercial product on the TIP OpenWiFi SDK.

Features of the 2.0 SDK at July MVP include:

• RBAC based security framework

• OpenAPI compliant Northbound

• Kafka Message Bus

• PGSql HA Cluster

• Firmware Manager

• Central Logging Dashboard

• User Interface

• Docker Compose & Helm DevOps Deployment Automation

TIP OpenWiFi enables a turnkey from factory experience for the managed Wi-Fi ecosystem. When an ODM or an OEM join TIP it is for the purpose of supplying a TIP SKU to market direct from factory.

This has numerous advantages including scale of supply, ease of distribution, partner branding, use of standard software including device certificates direct from factory.

Step 1 : Join

If your organization is not already a TIP Open Converged Wireless Project Group (OCW PG) member, consider signing up. Joining the OCW PG is free as a Software Participation Tier in TIP.

OpenWiFi 2.0 makes it possible for integrators of the SDK to implement commercial products leveraging OpenWiFi Gateway service with vendor supplied provisioning above OpenWiFi SDK. As a minimum, the OpenWiFi 2.0 SDK framework offers a Security service which handles all OpenAPI authentication northbound, and the Gateway service which provides all uCentral websocket interface functionality southbound.

OpenWiFi also provides options to receive telemetry and events over both OpenAPI interface as well as Kafka message bus. When using Kafka, OpenWiFi Gateway directly publishes telemetry and event topics to the bus.

In future sprints of OpenWiFi dynamic device provisioning will be available as an added micro service.

Gateway

OpenWiFi 2.0 Gateway implements the uCentral device management interface. uCentral specifies the data model and interface for management and telemetry of OpenWrt based devices. Gateway uCentral interface is a websocket JSON-RPC based design between OpenWiFi Gateway and the device running uCentral agent.

All communications from Gateway to Device are secured using mutual Transport Layer Security (mTLS). In mTLS systems each endpoint is a unique device sharing the same signed root or intermediate trust. In OpenWiFi each device has a signed certificate, key and device identifier. These are validated by the uCentral-Gateway to establish mTLS session.

Upon successful connection the device exchanges its capabilities with the OpenWiFi SDK. OpenWIFi SDK, via the Gateway micro service will send the entire device provisioning data as a JSON payload. Within OpenWiFi devices, the uCentral agent has a reader and renderer process providing serialization and validation of data sent from cloud. If any data presented can not be processed by the local agent, this is returned within an ERROR message using the same websocket connection.

If the device agrees with provisioning information presented, the render process builds calls into the operating system configuration sub-system known as UCI. The Unified Configuration Interface ensures OpenWrt compliant syntax is persisted within the device.

Configuration source of truth is the OpenWiFi SDK. Consistency of device configuration is handled with an applied hash compared by the Gateway for each device. If the value differs on device from that of the stored information in cloud, the device will be immediately resent its configuration from the OpenWiFi SDK Gateway service.

Once present, all configuration data is preserved on device restart.

It is possible to generate device configurations outside of the OpenWiFi 2.0 SDK as shown in the minimum SDK image at the start of this page. This may occur for some integrations or may occur when the OpenWiFi Provisioning micro service is not present. In this way, integrators of commercial products are welcome to build device provisioning outside of OpenWiFi and use the OpenWiFi cloud to manage the scale, state, security and validation of device websocket communications.

Access Point Network OS (APNOS)

License: BSD-3-Clause

• Openwrt based APNOS: https://github.com/Telecominfraproject/wlan-ap/tree/release/v2.4.0

Controller SDK

License: BSD-3-Clause

• Gateway Service:

• Gateway UI:

• Security Service:

• Firmware Service:

• Provisioning Service:

• Provisioning UI:

Testing

License: BSD-3-Clause

• Open Test Harness and Test cases:

SDK Load Simulator

License: BSD-3-Clause

• OpenWiFi Load Simulator (OWLS):

Deployment

License: BSD-3-Clause

• Helm and Docker Compose Deployments:

There could be reasons cloud discovery does not complete. These include:

• Lack of Internet Connectivity

  • Device may require additional WAN settings

  • Network may not be connected to Internet

• No Configuration of Cloud in Certificate Authority

  • Manufacturer may have left this value blank in the device record stored in Certificate Authority

When the cloud can not be automatically discovered, OpenWiFi devices will turn on a local admin web UI made available via SSID "Maverick".

The Maverick UI will support configuring WAN interface parameters, including DHCP, Static, PPPoE, and LTE/5G settings. Please see for details on using Maverick. Additionally the Maverick UI supports direct entry of the cloud for cases when the cloud value has not been supplied during manufacture.

For non-Wi-Fi devices such as PoE access switches, the same cloud location information may be configured using local management interface.

To introduce the Community to the uCentral data model structure, the below illustrates a basic Access Point configuration that assumes a typical enterprise Wi-Fi scenario of a ceiling mount or wall mount device presenting a single WAN interface with a private management network and separate Wi-Fi network on a virtual local area network.

Start with Location and Radios

We will set the unit location and timezone, then proceed to configure radios.

In this example, a two radio device that indicates it is Wi-Fi 6 as the channel-mode values for both radios is "HE" which defines 802.11ax operation. Valid values are "HT" -High Throughput 802.11n mode, "VHT" - Very High Throughput 802.11ac mode, "HE" - High Efficiency 802.11ax mode.

Channel defines the specific channel number the radio shall operate on as an integer from 1 - 171 and may also be set to a string for "auto" mode. Channel width permits configuring the amount of RF channel the radio will operator over from 20-40-80-160 including 8080 mode (also known as 80+80) .

OpenWiFi radios may be set to require UE clients to associate to a minimum standard such as excluding any 802.11b associations depicted above with "require-mode" set to "HT" meaning 802.11n or higher clients may associate.

Control of beacon interval and multicast rates is possible per radio as shown in the "rates" section.

Interfaces

OpenWiFi 2.0 offers a highly flexible model for arranging network interfaces. Multi-port devices may be easily provisioned for numerous types of network segmentation and logical network configuration. We will start with a simple WAN that has a management IP and also a VLAN sub-interface for a logical SSID in a subsequent step.

In the above configuration block we have a WAN interface, its role is "upstream" meaning it faces the upstream in terms of service it provides (WAN). This has a direct alignment to how the device interprets a physical or logical port participates in bridge forwarding domains.

Note we want this port to have an IP address for its management, therefore the "ipv4" configuration is associated as a child of any Ethernet WAN ports and set to DHCP.

Common Config - VLAN on WAN for SSID

Imagine the OpenWiFi device is an enterprise Access Point mounted on a ceiling. These devices do not always have a LAN port. Also in an enterprise, it is likely the Wi-Fi services are in their own network segments and not subject to Network Address Translation (NAT). Since the enterprise would also not want Wi-Fi on the same network as Management, an 802.1Q Virtual LAN is used.

In this next section of configuration, an additional logical interface associated to the WAN ports for the VLAN id of "100" is shown. Note there is no IP address associated to this interface, it is a layer 2 interface that will emit on any and all WAN ports with VLAN id 100.

To associate the Wi-Fi with the VLAN interface define, we continue within the WAN100 interface adding SSID services.

Within the "ssids" configuration block we can process an array of SSIDs. Often there may be separate "2G" and "5G" configurations. We have grouped them in this introductory example for simplicity however "2G", "5G", "5G-lower", "5G-upper", "6G" are all valid options.

The "name" value is the advertised SSID clients will discover for this access point. Hidden is supported by setting the "hidden-ssid" to true. Which operating mode is determined by "bss-mode". The "bss-mode" is a highly flexible operating parameter to determine "ap", "sta", mesh", "wds-ap", "wds-sta", "wds-repeater" radio modes of operation.

Security of the SSID is determined using the "encryption" section. Many options are possible, in this initial example, a WPA-PSK2 shared key encryption is shown. Lastly, for devices that support, 802.11w protected management frames are defined as optional for this SSID. This may also be disabled or required.

Metrics for wifi-frames will be described next.

Sending Data

Add metrics to our configuration that will help expose state of the Wi-Fi network and its services to the cloud.

Within metrics it is possible to define the interval for sending information to the cloud. Additionally the type of information sent is defined here. In this example configuration there are associated services to interfaces along the way. This included LLDP and dhcp-snooping and wifi-frames.

Within each uCentral device, the agent has a global health check feature that includes memory, cpu, temperature operating states in addition to performing various network and service health tests. The interval at which these reports are sent to the cloud is configured within health.

For all SSIDs that have wifi-frames associated as a service, the listed management frame types will be gathered and sent to the cloud, on each interval.

To assist with fingerprinting and client troubleshooting, dhcp-snooping sends the cloud all current client DHCP and DHCPv6 state.

Global Services

The final section of the simple configuration example turns on LLDP and SSH where those services were associated to interfaces listed above.

The complete simple configuration file as described in this page may be downloaded here:

Initial Minimum Viable Product Release 2.0 does not include template driven device provisioning, this will be available in the next sprint.

Given many cloud and ODM partners wish to consume the 2.0 reference stack early, some with their own device provisioning logic as part of commercial cloud controllers, the following describes uCentral based management and telemetry, interactions with the OpenWiFi SDK processing provisioning and telemetry data.

Device Interactions with SDK

OpenWiFi 2.0 follows the uCentral system. Complete data model is available . Upon discovery of the cloud, a device default or specific configuration is transferred.

All devices are known to the cloud by their unique id and provisioned based on advertised capabilities. Each configuration generates a new unique hash value to ensure as devices report back to the cloud, their configuration state is guaranteed.

If the cloud sends invalid configuration data or the device has insufficient ability to complete the provisioning commands, the error handling process will send this response back to the cloud.

For example results returned to SDK from a device configuration error:

OpenWiFi 2.0 data model for device management is based on uCentral.

uCentral is set to become a leading component of OpenWrt, as such will have a diverse, and worldwide developer and support base in open source.

Within the model it is possible to provision or return state for all aspects of an OpenWiFi based device easily structured as a JSON payload.

The complete data model may be found here : https://ucentral.io/docs/ucentral-schema.html

Organization

Each device has a Universally Unique Identifier (UUID). For each device, the configuration presented either manually, via the future Provisioning service from OpenWifi or via a commercial controller generation of provisioning data, the high level relationships of the schema may be understood as follows.

The unique device record has a set of top level configurations. A device is referred to as a 'unit' that may have a Description, Location, TimeZone as example. Each unit may have globals for IPv4 and IPv6 networks that are derived to lower lever interfaces in later generation.

Services and Metrics are associated with logical and physical interfaces. Services enable configuration of features such as LLDP or SSH, rTTY, IGMP, 802.1x, RADIUS Proxy, WiFi-Steering, or NTP and are then associated with Interfaces as desired.

Interfaces define upstream and downstream configuration over both Wi-Fi logical (SSID) and wired physical ports.

Metrics enable visibility to the cloud for numerous states of the device. These are associated per interface and may be sent in 60 second or greater intervals and include Statistics of SSID, LLDP, Clients. Also include Health check reports of device load, network reachability, temperature. To assist with fingerprinting DHCP-Snooping exposes numerous interactions of IP binding to clients. Additionally wifi-frames expose all 802.11 management frames to the SDK Gateway.

It is also possible to configure config-raw elements that will parse direct UCI commands once the device provisioning has been completed by the uCentral agent.

Within the devices view, the Commands tile offers a number of features and administrative actions. Each of these represent API calls exposed on the OpenAPI northbound interface from the SDK.

Reboot

Selecting the Reboot action will prompt the below dialog. Options presented permit an immediate reboot or a scheduled reboot based on date and time.

Multiple events are recorded in the Command History tile. Each line item will have a Result, Details, and Delete action.

When an rTTY session is executed, this is a displayed command history. Selecting the Result icons will display the Success or Fail of the command.

Each provisioning event is reflected as a configure command history. To see the entire JSON payload and the result, including success or error with message, simply select Details to expand the dialog below with this data. A date and time in the third column indicates when the configure command was executed successfully.

If a provisioning event has failed to complete, its command history for configure will show as pending.

When OpenWiFi devices are unable to connect to the cloud during their initial power on from factory, this may be a result of Internet connectivity issues.

Certain WAN connections may require credentials such as a username and password or a mobile configuration or simply static address assignment instead of dynamic.

OpenWiFi 2.0 supports these scenarios. When a device does not have an existing configuration and is unable to contact the cloud for provisioning it enters "Maverick" mode.

For all Wi-Fi devices this means a Wi-Fi network with the SSID 'Maverick' will become available. Association with and logging in to the device will permit initial WAN connectivity to be entered.

Firmware management service integrates across all OpenWiFi Gateways deployed in a cluster enabling updates to running firmware either from the latest published version, or any other released version.

Dashboard

Firmware dashboard provides a single view for overall health of deployed device firmware. Latest firmware charts, device firmware version distribution, distribution of device by type and current connected devices.

Each device page presents statistics in traffic terms per interface as a line graph of bandwidth over time.

The generated image may be downloaded for offline use.

Accessing Wi-Fi Analysis and Last Statistics may be found at the top right of Statistics tile.

Each device presents Metrics and Health check data to the Gateway. Devices view displays this information in the following organization:

• Status

• Configuration

Release 2.0 uses a Single-Page Application (SPA) as an example user interface built using React to demonstrate several interactions using the northbound OpenAPI.

Login to OpenWiFi SDK

Default username is: tip@ucentral.com and password is:

The following pipeline is used to leverage Kafka messages being emitted from OpenWiFi 2.0 for ELK (Elastic Logstash Kibana) stack integration :

TIP OpenWiFi project has deployed an ELK stack for community members to access .

The key for this integration is to use a plugin that enables Kafka to be used as an input for Logstash. This plugin can be found . Once installed then Logstash can be configured to listen to the input source of the Kafka broker that is deployed as part of OpenWiFi SDK 2.0 release and its appropriate topics. Here is a Logstash configuration.

It is important to note that Logstash provides the ability to transform messages which then can be pushed to Elasticsearch for storage with effective indexing. Finally Kibana is used to create visualization such as this:

TIP OpenWiFi software stack is envisioned to have a rich telemetry data that can be extracted, transformed and stored for analytics purposes. This section will outline various integration using the current capabilities of the OpenWiFi release. These integrations will provide examples for the community to enrich, adopt and productize.

The current release of OpenWiFi utilizes both a rich open API and Kafka for retrieving telemetry information from Access Points and SDK services. For the purpose of this section and Release 2.0 we will be showcasing Kafka integration with third party monitoring subsystems.

Kafka Data Source

The docker-compose within the deploy repository contains all the relevant files for various modes of SDK.

Modes

The following two modes are currently supported by docker-compose:

The wlan-cloud-ucentral-deploy repository contains two packaging options:

• Docker Compose

• Helm

The repository is managed using branches where:

• main branch: contains references to the latest development SDK images

• release/v* branch: contains image references specific to the release artifacts. For example: release/v2.4.0 branch will contain references to SDK images related to 2.4.0 release candidates (RC) and GA.

OpenWiFi devices have a number of features that may be configured.

The following pages guide the user to understanding each of these features individually including example configuration information.

Creating logical bridges may be done through association to named "interfaces". To associate a logical SSID interface directly to the WAN, place SSID configuration within the interface have a "role" of upstream.

    "interfaces": [
        {
            "name": "WAN",
            "role": "upstream",
            "services": [ "lldp" ],
            "ethernet": [
                {
                    "select-ports": [
                        "WAN*"
                    ]
                }
            ],
            "ipv4": {
                "addressing": "dynamic"

SDK can be deployed to Kubernetes using a Helm package. The Helm package code is located at repository.

Each micro service in the OpenWiFi SDK system has its own Helm chart that is managed in the micro service’s own repository. The assembly chart collects all the relevant micro service charts and other external dependencies like kafka, rtty, etc. and deploys them together as one cohesive release.

You can review the full list of all the assembled micro services and related dependencies here:

Creating a NAT Gateway is easily done via association to an interface having a role of "downstream".

Based on the above Dual SSID NAT configuration, a unique 2GHz and 5GHz SSID are created and logically bound to the same NAT LAN side network.

The NAT service is inherited by the downstream role with DHCP addressing defined according to the range set within the downstream "ipv4" configuration.

One of the benefits of the new data plane in OpenWiFi 2.0 is the flexibility of physical port to logical forwarding that is easily conveyed through configuration structures.

New protocol support is both easily added to the system as well as associated with interfaces by their role in the device.

The following sections offer feature configuration examples.

For complete reference to the device data model please refer

The most common use case for VLANs and Wi-Fi is likely the service provider, venue, enterprise where Wi-Fi traffic is not subject to address translation. This is the example that will be shown, however it is entirely possible to create multiple downstream VLANs with SSIDs as well. Simply replace the logic of upstream to downstream where desired.

In all cases the WAN port without VLAN id is using DHCP to obtain a management IP address. Each additional "upstream" role interface with an SSID associated have no IP configuration.

Layer 2 Tunneling Protocol may be associated to any interface using the "tunnel" configuration option.

This makes it possible to configure L2TP for multiple types of deployments as any interface may be encapsulated by the "tunnel" parameter.

For example, to send all content of a specific SSID over an L2TP tunnel, the following configuration would apply.

        {
            "name": "LAN",
            "role": "downstream",
            "services": [ "ssh" ],
            "ethernet": [
                {
                    "select-ports": [
                        "LAN*"
                    ]
                }
            ],
            "ipv4": {
                "addressing": "static",
                "subnet": "192.168.1.1/24",
                "dhcp": {
                    "lease-first": 10,
                    "lease-count": 100,
                    "lease-time": "6h"
                }
            }
        },
        {
            "name": "L2TP",
            "role": "downstream",
            "tunnel": {
                "proto": "l2tp",
                "server": " far end IP address ",
                "user-name": "secret-l2tp-username",
                "password": "secrectPassword"
            },
            "ipv4": {
                "addressing": "static",
                "subnet": "192.168.10.1/24",
                "dhcp": {
                    "lease-first": 10,
                    "lease-count": 100,
                    "lease-time": "6h"
                }
            },
            "ssids": [
                {
                    "name": "Tunneled SSID",
                    "wifi-bands": [
                        "5G", "2G"
                    ],
                    "bss-mode": "ap"
                }
            ]
        }
    ],

When operators of enterprise or service provider networks seek to influence or control the allocation of dynamically assigned IP address, typically the network edge has been provisioned to encode information in DHCP Relay packets that help identify the access device through which a subscriber is attached, the logical sub-interface of that network edge or the subscriber directly.

TIP OpenWiFi supports DHCP Relay with encoding of client Circuit-Id information containing any of:

• Interface

• VLAN-Id

• SSID

• Encryption Mode

• Device Name

• Device Model

• Device Location

• Access Point MAC Address

• Access Point MAC in Hex

• Client MAC Address

• Client MAC Address in Hex

TIP OpenWiFi Relay-Agent remote-id may be configured to contain any of the following:

• VLAN-Id

• SSID

• AP-MAC

The remote-id originates from a configured IPv4 interface address.

In the above example, when the IPv4 downstream interface 192.168.1.1 has DHCP enabled for relay-server a DHCP relay process associates to the IP interface of the subnet. When DHCP DISCOVER packets arrive as broadcasts, they will be copied to a unicast packet from the 192.168.1.1 interface as the relay-id source address and unicast forwarded to the defined relay-server address. Additional parameters are encoded for inspection at the DHCP server as present in circuit-id-format and remote-id-format options.

OpenWiFi devices have global services that operate either independently system wide or as an association to a physical or logical interface.

Within the "services" configuration block, define the operating mode for each service, then associate a service with an interface.

SSH

Secure shell may optionally be enabled on OpenWiFi devices, associated to specific interface(s), and optionally support operator defined keys or password authentication.

Associate Service to Interface

Operator Key Management

For production deployments, it is recommended to assign operator SSH key from the OpenWiFi Provisioning configuration of the Venue or Entity which the device associates.

In this way, an operator may ensure their standard SSH key is delivered to all devices on a network operating region basis. All keys remain base64 encoded when added to the device.

NTP

Network time protocol for OpenWiFi devices may be configured to listen for time synchronization from NTP sources and may also be configured to supply NTP source.

Associate to an Interface

LLDP

Link Layer Discovery Protocol describes interfaces and capabilities between directly attached neighbors over Layer 2.

Associate "lldp" as a services attribute to any interface.

MDNS

To assist in device or service discovery over smaller networks, multicast DNS (mDNS) protocol if often used. In an mDNS environment there is no local name server for resources to leverage. mDNS zero-configuration service effectively behaves as unicast Domain Name Service (DNS).

Associate "mdns" as a services attribute to any interface.

Syslog

Remote syslog systems may be configured to receive device logs in a central location. This content is standard device log and not related to telemetry for metrics and service information received by the OpenWiFi Gateway. Valid port range is from 100 - 65535 with operation over UDP or TCP.

Associate "log" as a services attribute to appropriate interface.

IGMP

When enabled the OpenWiFi device will process IGMP Proxy.

Associate "igmp" as a services attribute to any interface participating in IGMP Proxy.

VXLAN’s goal is allowing dynamic large scale isolated virtual L2 networks to be created for virtualized and multi-tenant environments. It does this by encapsulating Ethernet frames in VXLAN packets which when deployed in Wi-Fi topologies can create highly extensible Layer 2 inter-network domains over large campus, MDU, venue service networks.

VxLAN header uses a 24-bit VNID as a unique layer 2 forwarding domain value. VxLAN maintains layer 2 isolation between the forwarding domains and does not leak MAC addresses into upstream switches. Through the use of 24 bits in VNID VxLAN scales up to 16 million unique LAN forwarding domains.

The VXLAN encapsulation method is IP based and provides for a virtual L2 network. With VXLAN the full Ethernet Frame (with the exception of the Frame Check Sequence: FCS) is carried as the payload of a UDP packet. VXLAN utilizes a 24-bit VXLAN header, to identify virtual networks. This header provides for up to 16 million virtual L2 networks.

Frame encapsulation is done by an entity known as a VxLAN Tunnel Endpoint (VTEP.) A VTEP has two logical interfaces: an uplink and a downlink. The uplink is responsible for receiving VxLAN frames and acts as a tunnel endpoint with an IP address used for routing VxLAN encapsulated frames.

Metrics

Several metrics are reported during intervals to the OpenWiFi Gateway. In general metrics contain traffic counters, neighbor tables, discovered clients.

Each OpenWiFi device is capable of sending statistics on SSID, LLDP, and associated Clients learned by the device.

Additionally, OpenWiFi devices expose all 802.11 management data within wifi-frames and to assist network troubleshooting and client fingerprinting solutions OpenWiFi provides dhcp-snooping for all possible client exchanges over DHCP and DHCPv6.

OpenWiFi Mesh has been designed to eliminate configuration complexity while also remaining capable of advanced topology designs including Multi-Gateway, Multi-SSID, VLAN, and Zero Touch Mesh onboarding.

The physical wired interface(s) to participate in the mesh topology egress are defined with the protocol "mesh".

The logical wireless interface(s) to participate in mesh topology are defined by their bss-mode set to "mesh".

In this basic mesh, dual SSIDs are configured for clients while an SSID for mesh transit is configured for IEEE802.11s client associations. Additional mesh clients simply use the same approach, no other configuration is required for the client to participate in this mesh.

Advanced examples with VLANs and roaming are all possible by adding additional configuration steps.

OpenWiFi 2.0 supports Generic Routing Encapsulation as an available "tunnel" protocol type.

This makes it possible to configure GRE for multiple types of deployments as any interface may be encapsulated by the "tunnel" parameter.

For example, to send all content of a specific SSID over an GRE tunnel, the following configuration would apply.

In the above example, the WAN untagged port will request DHCP in addition to present a VLAN interface with id 20 that both initiates the GRE tunnel as well as passes SSID traffic over that tunnel. Optionally the GRE tunnel itself may also carry a VLAN encapsulated payload. In the above example a WAN presentation of VLAN interface 20 has GRE tunnel. Within the GRE tunnel on WAN interface of VLAN 20 is a GRE payload with VLAN 30 in the payload header.

OpenWiFi supports multiple models for Captive Portal. A built-in captive portal is described below. With multiple overlay tunnel services such as GRE and L2TP in addition to VLAN features, OpenWiFi is also easily deployed with any number of Captive Portal appliance solutions in either in-band or out-of-band style deployments.

Local Captive Portal

Creating a local captive portal involves associating the "captive" service with an interface. In the example below, "captive" is enabled on a downstream role interface. Any associated SSID on LAN side of this Access Point will be subject to configuration of the local captive portal. This would also apply to LAN interfaces if also associated with "captive".

        {
            "name": "captive",
            "role": "downstream",
            "captive": {
                "max-clients": 32,
                "gateway-name": "Lobby Wi-Fi Welcome",
                "upload-rate": 10,
                "download-rate": 20,
                "upload-quota": 300,
                "download-quota": 300
            },
            "ipv4": {
                "addressing": "static",
                "subnet": "192.168.2.1/24",
                "dhcp": {
                    "lease-first": 10,
                    "lease-count": 100,
                    "lease-time": "6h"
                }
            },
            "ssids": [
                {
                    "name": "Office Lobby Wi-Fi",
                    "wifi-bands": [
                        "5G",
                        "2G"
                    ],
                    "bss-mode": "ap",
                    "encryption": {
                        "proto": "none",
                        "ieee80211w": "optional"
                    },
                    "roaming": {
                        "message-exchange": "ds",
                        "generate-psk": true
                    }
                }
            ]
        }
    ],

Local captive portal will redirect to a default landing page and display the name as configured in "gateway-name". Per associated user bandwidth and usage quota limits and total association limits may all be defined.

When an external access controller, such as a captive portal appliance or a Universal Access Method (UAM) redirector is required to handle subscriber login, OpenWiFi optionally supports builds that include use of CoovaChili. This would be found in build profile chilli-redirect.yml.

To configure a CoovaChilli service, OpenWiFi supports the "third-party" schema definition.

Through the use of third-party, many configurations are possible, for external captive portal, third-party will process a services lookup of "chilli-redirect" applied to an interface.

Within "third-party" will be the necessary CoovaChilli configuration parameters.

"third-party": {
                "chilli-redirect": {
                        "uamport": 3990,
                        "radiusauthport": 1812,
                        "radiusacctport": 1813,
                        "radiusserver1": "radiusServerIP",
                        "radiusserver2": "radiusServerIP",
                        "radiusnasid": "nasID",
                        "uamallowed": "allowed.example.com,10.0.0.1,192.168.10.1",
                        "uamdomain": "exampleUAMdomain.com,otherExampleUAMdomain.com",
                        "defidletimeout": 900,
                        "definteriminterval": 600,
                        "acctupdate": 1,
                        "uamserver": "https://portal.example.com/portal/default/index.php?n=NAME&c=3&l=181",
                        "radiussecret": "radiusSecret",
                        "nasmac": "00:01:02:03:04:AA"
                }
        }

NAT Mode

Associate to an interface:

Bridge Mode

In the above example, captive portal redirection occurs via a NAT interface on LAN side or "downstream" role.

When a direct to WAN presentation, or bridge mode operation is desired, associate the service to the "upstream" interface.

Associate to an interface:

Wireless Distribution System (WDS) supports an Access Point, Station and Repeater mode of operation. OpenWiFi 2.0 supports all three.

In the below example, the LAN side of the Access Point at the top of the topology will be wirelessly bridged to the LAN side of the Access Point Station at the bottom of the topology.

    "interfaces": [
        {
            "name": "WAN",
            "role": "upstream",
            "services": [ "lldp" ],
            "ethernet": [
                {
                    "select-ports": [
                        "WAN*"
                    ]
                }
            ],
            "ipv4": {
                "addressing": "dynamic"

In this configuration, LAN clients of the WDS Station AP receive IP addresses from the WDS Access Point AP from its LAN side DHCP service, via WDS link at 5GHz.

Multiple Pre Shared Key is a popular configuration option in Multi Dwelling Unit, dormitory or similar environment where it is costly to implement complex 802.1x security however that same level of per-client security is highly desired.

A SSID when configured for multi-psk can have multiple PSK/VID mappings. Each one of them can be bound to a specific MAC or be a wildcard.

In many deployment scenarios, user authentication is centralized with RADIUS systems. In addition, users may have association to their own networks or private networks. A common approach for this is to dynamically assign VLANs to Wi-Fi subscribers as they join the OpenWiFi network.

To configure Dynamic VLANs with RADIUS, associate an SSID with RADIUS authentication, and associate the interface to "upstream" role as dynamic VLANs are most likely to be applicable across the service provider, venue, enterprise network.

RADIUS Access-Accept

OpenWiFi devices will determine a VLAN is associated to the authentication of a subscriber when the access-accept message returns the following attribute value pairs:

• Tunnel-Type = 13

• Tunnel-Medium-Type = 6

• Tunnel-Private-Group-Id = VLAN Id Number

Upon return of an access-accept from RADIUS, based on any method chosen for security, OpenWiFi will dynamically create a VLAN Id as described in Tunnel-Private-Group-Id, associated to the interface role, in this example upstream.

Dynamic Air-Time Policy is a service to influence underlying co-ordination function of the Wi-Fi MAC domain per associated UE in terms of priority to use the air interface.

It is possible to govern certain application use cases such as streaming media or real time communications based on the resolution of those services through DNS.

This results in the UE, by its IP address having matched a specific fully qualified domain name or a wildcard therein, to having its air-time weighted priority to the value set in the weight parameter.

            "services": {     
                "airtime-policies": {
                    "dns-match": ["*.example.com", "host.example2.com" ],
                    "dns-weight": 256
                }
            }

Possible Uses

Any application a user may commonly use the OpenWiFi administrator seeks to prioritize air-time for may be triggered via the airtime-policies.

For example:

Any number of services may interest the administrator for airtime-policies. Simply determine the FQDN or wildcard FQDN applicable and update the OpenWiFi device configuration.

Radio Resource Management and Self Organizing Network features in OpenWiFi 2.0 operate by default in local mode from the Access Point device without dependency on the cloud. Data and state related to client steering and roaming is also possible in co-operation with the cloud when so configured.

Metrics and telemetry are sent to the cloud as desired based on configuration however operation of 802.11k/v/r behavior and autonomous channel control are built in features of all OpenWiFi 2.0 Access Points.

Steering

OpenWiFi services feature "wifi-steering" determines the operating parameters of RRM on the Access Point.

When mode is set to local, the Access Point handles steering decisions autonomously with the surrounding OpenWifi devices. Which network association, in this case "upstream" will steering be operating on. Note in prior examples most service provider, venue, enterprise services operate on the WAN side upstream network of the Access Point.

Apply Wi-Fi Steering to enable 802.11r Fast Roaming SSIDs

Each SSID to participate in roaming must have "services" : [ "wifi-steering" ] associated.

Additional fast roaming configuration is possible including setting message-exchange either to "air" or "ds" to determine pre authenticated message exchange occurs over the air or distribution system.

The generate-psk option generates FT response locally for PSK networks. This avoids use of PMK-R1 push/pull from other APs with FT-PSK networks.

Configuring domain-identifier sets Mobility Domain identifier (dot11FTMobilityDomainID, MDID) permitting segmentation of fast roaming RF topologies.

When pmk-r0-key-holder and pmk-r1-key-holder are left un-configured, the pairwise master key R0 and R1 will generate a deterministic key automatically for fast mobility domain exchange over the air.

RRM 802.11k

To enable 80211k parameters, associate these on a participating SSID basis.

In addition to 802.11k features for neighbor reporting, fine timing measurement responder and stationary ap indication, OpenWiFi also supports LCI measurement, Civic Location subelement as well.

Automatic Channel Balancing

As part of "wifi-steering" feature, autonomous channel management algorithm may be enabled to establish a self organizing Wi-Fi network.

The auto-channel setting operates in co-ordination with other OpenWiFi Access Points by enumerating the newest AP in the network, then running neighbor and RF scans to determine the best channel of operation. Once the newest AP completes this process, the next AP is sequence will run the same algorithm for channel balancing until all APs in the network complete. The entire process may take up to 5 minutes the first time a network is powered on. The algorithm will re-run every 12 hours.

When authenticating clients with back office RADIUS systems, the configuration of OpenWiFi permits this on a per SSID basis.

    "interfaces": [
        {
            "name": "WAN",
            "role": "upstream",
            "ethernet": [
                {
                    "select-ports": [
                        "WAN*"
                    ]
                }
            ],
            "ipv4": {
                "addressing": "dynamic"
            },
            "ssids": [

Many parameters are possible with RADIUS authentications given the many methods in use worldwide. Many of the EAP methods have configuration options described below.

At home, in a cafe, or on the go, Express Wi-Fi gives you access to fast, affordable, and reliable internet so you can make connections that matter.

Express Wi-Fi partners with service providers to deliver great wi-fi to people when and where it's needed.

For information about becoming an expressWIFI partner please visit their site.

Configuration

ExpressWiFi builds a captive portal experience using a control plane protocol called OpenFlow. Configuring OpenWiFi for use with expressWiFi is as simple as defining a downstream interface and associating with an SSID and the open-flow service.

TIP OpenWiFi devices implement support for both the air interface and systems interfaces necessary to support Passpoint® Release 2 and above. Once also termed Hotspot 2.0, IEEE 802.11u specified added air interface fields exposing Access Network Query Protocol interactions for clients to discovery Access Point capabilities.

Wi-Fi Alliance expanded ANQP to include Online Signup (OSU) concepts to leverage seamless onboarding and client security for Passpoint® networks. Following on from these efforts, Wireless Broadband Alliance has provided the necessary system interfaces for identity, security, mobile offload within a common federated operator solution known as OpenRoaming.

TIP OpenWiFi enables operators to deploy the full range of Passpoint® and OpenRoaming solutions.