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 Local Device Settings 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.

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

  • Device LED Blink

  • Device Remote Packet Capture

  • Device Configuration

  • Device Factory Reset

  • Device Remote TTY shell

  • Remote Wi-Fi Scan

  • Associations

    • UE (Wi-Fi Clients)

    • Mesh and WDS Clients

    • MCS, NSS, RSSI, Channel, SSID, Tx/Rx

  • Device Health Check

  • Interface Statistics

  • Device Command History

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 Release 2.0 SDK section for installation instructions.

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.

Devices may periodically initiate connection to the Certificate Authority to validate their unique certificate status. This is a normal process involved in mutual TLS security models.

When an operator or end customer seeks to change the cloud associated with their device(s), the value of the cloud stored in the Certificate Authority device record is updated. A factory reset of the device will cause first-boot to re-occur which will then discover the new cloud.

TIP OpenWiFi ODM partners are able to manage device records directly using the Certificate Authority portal. All other users should send an email to licensekeys@telecominfraproject.com to request update of cloud discovery.

OpenWi-Fi 2.0 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:

Installation

There are multiple ways you can install OpenWiFi SDK with assembly charts:

1. One way is by installing directly from the assembly chart’s repository. For that, you’ll need to install and extra Helm plugin that is used to pull the latest charts code from all the referenced micro services: .

2. Another way, which is considered more stable, is by installing from a prepackaged bundle that is published to on every official uCentral release. For this approach to work, you don’t need to install any additional plugins or dependencies, just to make sure you’ve got Helm installed on your local system.

Directly from the Assembly repository

1. Install the helm-git pluging according to the official documentation

2. Run helm upgrade --install tip-ucentral git+

3. You can also reference any other open branch from the deployment repository. For example, if you want to deploy using the assembly code from the v2.0.0-rc1 branch, you can just run helm upgrade --install tip-ucentral git+

Using the pre-built Helm package

1. This method doesn’t require to install anything locally other than Helm

2. Start by adding the wlan-cloud-ucentral Helm repository to your local list of repositories by running helm repo add tip-ucentral

3. helm upgrade --install tip-ucentral wlan-cloud-ucentral to install the latest version, or specify the release you want to install by adding the --version x.y.z flag.

Chart configuration using the Values file

The configuration of OpenWiFi SDK using Helm chart may be separated into layers:

During deployment all values are merged as maps with priority to the level of deployment (so Environment-specific values will override any overrides from Assembly chart values and so on).

Example: Let’s pass environment-specific ucentralgw.properties configuration parameter (which is probably quite common thing to test). For example, we have an environment that requires to set parameter ucentral.websocket.host.0.backlog to 1000. For that we would need to run following command, extending our base command:

Automated community deployment

The configuration is dynamic, and new namespaces (a.k.a environments) may be created by adjusting the json configuration in the workflow.

The json format allows to deploy or upgrade and existing environment using the latest Docker images or to specify a specific version of each micro service.

To deploy specific version to the specific environment a list of things must be done:

1. First, you need to make sure that the Docker image with the correct version exists in Artifactory, otherwise, the Helm upgrade will fail.

2. Update the json configuration in the workflow to reference the require version for the require micro service (examples are attached in the json file itself)

3. Re-run the deployment in Github actions. You can also make all the above changes in a separate branch, and re-run the workflow from that branch (using a drop-down in the top left corner in Github’s UI).

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.

Using Maverick

After association to the Maverick SSID, open a web browser to http://192.168.1.1 Log into the OpenWiFi device with username: root and password: openwifi

When the page above is displayed, begin to configure Uplink based on the WAN requirements of the deployment.

If connection uses Point to Point over Ethernet (PPPoE) username and password credentials, enter those values and save.

If the OpenWiFi device has a Cellular connection which is possible on device models with 4G and 5G radios, the network Access Point Name (APN) and PIN will be required. These values are supplied by your mobile network provider.

When dynamic address allocation is not available, static IP address assignment may be required. IPv4 and IPv6 are supported, enter these values with DNS address and save.

Otherwise leave the Uplink configuration to DHCP or cloud defaults.

Manual Redirector and Certificate Upload

If under rare circumstances it is not possible to discover the OpenWiFi cloud associated with the device or there is a need to replace device certificates, this may be configured in Settings.

System

It is possible to reset the device to defaults, or locally update firmware using the commands available from System.

****

The wlan-cloud-ucentral-deploy repository contains a Compose file and the related files and directories to set up a local uCentral instance with Docker Compose. You'll find all related data under the docker-compose/ directory.

Volumes

The deployment creates local volumes to persist mostly application and database data. In addition to that several bind mounts are created:

docker-compose/certs/ directory used by multiple services

Service specific data directories and configuration files located under docker-compose/ mounted into the appropriate containers.

Configuration

Changing image tags used in the deployments may be performed in docker-compose/.env.

By default this file specifies the micro service image tags according to the release branch you have checked out.

Additional configuration changes such as database settings or passwords are found in the various other service specific .env files.

The rest of the configuration is done through the config files located in the appropriate subdirectories of the Compose project directory.

Ports

Exposed port dependencies by application are listed below:

127.0.0.1:80/tcp - OpenWiFi-UI 127.0.0.1:5912/tcp - rttys dev 127.0.0.1:5913/tcp - rttys user 0.0.0.0:15002/tcp - OpenWiFi-uCentralGW websocket 127.0.0.1:16002/tcp - OpenWiFi-uCentralGW REST API public 0.0.0.0:16003/tcp - OpenWiFi-uCentralGW fileupload 127.0.0.1:16102/tcp - OpenWiFi-uCentralGW alivecheck 127.0.0.1:16001/tcp - OpenWiFi-uCentralSec REST API public 127.0.0.1:16101/tcp - OpenWiFi-uCentralSec alivecheck

Certificates

The repository includes a TIP Root CA Digicert-signed (for the Gateway websocket to devices) and a self-signed certificate (for the REST API northbound and other components), which you can use to create a local deployment out of the box.

The certificates are valid for the *.wlan.local domain.

How to

1. First you'll have to install Docker Compose according to your platform specific instructions. After that clone the repository with git clone https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy.

2. The Docker Compose uCentral micro service configs use ucentral.wlan.local as a hostname, so make sure you add an entry in your hosts file (or in your local DNS solution) which points to 127.0.0.1 or whatever the IP of the host running the deployment is.

3. Switch to the Compose project directory with cd docker-compose/.

4. Spin up the deployment with docker-compose up -d. If your deployment was successfully created, you should see the following output with docker-compose ps:

              Name                             Command               State                                                             Ports
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ucentral_kafka_1                    /opt/bitnami/scripts/kafka ...   Up      9092/tcp
ucentral_rttys_1                    /rttys/rttys                     Up      127.0.0.1:5912->5912/tcp, 127.0.0.1:5913->5913/tcp
ucentral_ucentralgw-ui_1            /docker-entrypoint.sh ngin ...   Up      127.0.0.1:80->80/tcp
ucentral_ucentralgw.wlan.local_1    /bin/sh -c /ucentral/ucent ...   Up      0.0.0.0:15002->15002/tcp, 127.0.0.1:16002->16002/tcp, 0.0.0.0:16003->16003/tcp, 127.0.0.1:16102->16102/tcp, 17002/tcp
ucentral_ucentralsec.wlan.local_1   /bin/sh -c /ucentral/ucent ...   Up      127.0.0.1:16001->16001/tcp, 127.0.0.1:16101->16101/tcp, 17001/tcp
ucentral_zookeeper_1                /docker-entrypoint.sh zkSe ...   Up      2181/tcp, 2888/tcp, 3888/tcp, 8080/tcp

1. Since the certificate for the REST API and other components is self-signed, you have to add it to the system trust store of the containers communicating together internally via TLS. The add-ca-cert.sh script located in the Compose project directory does the work for you.

   You also have to trust the self-signed REST API certificate on your local machine. To achieve that you either have to add certs/restapi-ca.pem to your trusted browser certificates or add certificate exceptions in your browser by visiting https://ucentral.wlan.local:16001 and https://ucentral.wlan.local:16002 and accepting the self-signed SSL certificate warnings (make sure to visit both and add the exceptions).

2. Connect to your AP via SSH and add a static hosts entry in /etc/hosts for ucentral.wlan.local which points to the address of the host the Compose deployment runs on.

3. While staying in the SSH session, copy the content of certs/restapi-ca.pem on your local machine to your clipboard and append it to the file /etc/ssl/cert.pem on the AP. This way your AP will also trust the self-signed certificate.

4. Go to http://ucentral.wlan.local to visit the UI and login with username tip@ucentral.com and password openwifi if you didn't change the default credentials in the uCentralSec configuration.

5. To use the curl test scripts which are included in the micro service repositories make sure to set the following environment variables before issuing a request:

export UCENTRALSEC="ucentral.wlan.local:16001"
export FLAGS="-s --cacert <your-wlan-cloud-ucentral-deploy-location>/docker-compose/certs/restapi-ca.pem"

Upgrading Compose Deployments

Stop the running containers with docker-compose down

Check out the new branch by repeating Step 1 from How to above for the given release and docker-compose up -d. Don’t forget to re-add the self-signed certificates to the containers with the provided script. Also be aware that you may have to change back some file permissions. To obtain the most recent changes as the files are under version control, you may have to change the ownership to your user again before pulling changes.

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

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

"results": { 
  "serial": "aabbcc00120a",  
       "status": {    
          "error": 0,  
                "rejected": [   
                             "[W] ("A Reason will be given"
                             ],