https://etwiki.sys.comcast.net/display/CE/%5bShared%5d+WiFi

https://etwiki.sys.comcast.net/display/APPS/WIFI+Manager+API

RDK Wi-Fi Sub-system overview

...

WiFi is a new features that is added in RDK video community devices. Recently Wi-Fi features is added to a Hardware Development (Raspberry Pi) video platform. As of now feature wise almost covered the client and access point related things, and we are continuing to work on remote management and diagnostics functionalities to be included into the Wi-Fi code.

Where does Raspberry-Pi Wi-Fi stand?

1.Basic Feature wise R-PI Wi-Fi is almost at the same level as that of other RDK platforms.Image Removed

Main difference that we can derive are:

...

In this section, we will  get the details on the architecture, layers, and how different RDK components interact with the wifi driver to enable Core wifi functionality.

Image Removed

Application:
      In top of the eco-system we have wide range of application which requires wireless network access. This may be a cloud based UI application, a diagnostics webpage or a console application such as test automation kit which will be required to verify readiness of a new RDK box with respect to different component features. This can be a HTML based webpage or a native console application requesting Wi-Fi functionalities.

...

Let us see in what types of network topology one wireless enabled RDK box can operate. We can see two use cases here,
In first case we will see a straight forward network where we will have an IP headend for TV channels, VOD,  etc.

Image Removed

• In the above picture, the data will be received by a RDK Broadband device which will be our entry point to the home network. This will act as a video gateway, an internet router as well as can be a home DVR also. The network connectivity from RDK broadband device to IP headend will be through a high speed network such as fiber optics, etc.
• From the RDK broadband device, all clients in a home network will receive internet and video data through the wireless network. The RDK broadband device will be the access point and video devices such as Raspberry Pi will act as wifi clients.

In second use case, we wanted to show how a legacy network can be extended to operate with wifi enable devices,
In the figure, we use a RDK Video gateway to receive data from Cable media and relay to a RDK broadband device through MoCA network. In this network topology,

Image Removed

RDK client devices will be able to access the QAM channel and DVR from the Video gateway and internet through the broadband device. Video and internet data will be received by the Broadband Device and sent to Wireless clients.

...

Some of major API details are provided which is available under the header include/services/wifimanagerservice.h. Generally in case of each service, there are two common API for registering and un-registering particular service. When we register a service, we are making it available to the other application. And when we un-register it will no longer be accessible to the upper layer application.

...

WifiManagerService()

...

Constructor, which will register for Wi-Fi service

...

WifiManagerService::registerForEvents()

...

Register events for Wi-Fi manager service.

...

WifiManagerService::unregisterEvents()

...

Unregister events for Wi-Fi manager service

...

WifiManagerService::notifyEvent()

...

Notify the events received from netSrvMgr.

...

WifiManagerService::getAvailableSSIDs()

...

Retrieves the array of strings representing SSIDs

...

WifiManagerService::getCurrentState()

...

Retrieves the current state

...

WifiManagerService::getPairedSSID()

...

Returns the paired SSIDs as string

...

WifiManagerService::connect()

...

Connect with given or saved SSID and passphrase

...

…….

...

…….

Refer to Wifi Manager APIs for a complete list of APIs provided by Wifi Service manager.

Wi-Fi Wi-Fi Network Manager

Wifi- network manager, which takes several responsibility for managing Wifi in Video device

• It dynamically detect the Network interfaces, send notifications to subscribers
• Supports diagnostics both local and cloud based applications
• Setup and update the network routes based on priorities, wifi connection status, availability, etc
• It also Listen to home networking updates to determine the routes for which communication to be established in outside world
• It provide Modular approach to add/remove new network interface types and also provide support for configuring routing rules

Lets see how network manager works when a RDK device boots up, On bootup, network service manager reads a configuration file to check what all network interfaces are supported on current set-top box and accordingly it initializes and bring-up the corresponding subsystems such as wifi, moca, or Ethernet. It also sets the telemetry parameters such as logging interval and decide what information need to be logged according to the configuration sets by the user.

The WIFI Manager API provides support to client applications that wish to enable WIFI communications on a STB.

• It Provide API to Initialize the wifi driver and runs the linux wireless daemon
• Provides API to configure WiFi SSID and password, it is required for video device to to connect to the Access Point.
• It provide facility to immediately try to connect to WiFi network with provided SSID and password when API is invoked.
• It also Provides response to caller to indicate whether or not WiFi network connection was successfully established.
• Provides API to clear previously configured SSID and password.
• Stores/Saves WiFi SSID and password in persistent memory, which will help in automatically connecting to the AP after box reboots. 
• Enumerates via API the available broadcasting SSIDs.
• Wifi Manager automatically tries to connect to paired Wifi network on startup

Another important feature of the network manager is to notify other application or other listeners when a major event occurs with the Wi-Fi sub-system
Here the event may of following types.

• Any state change that either the state changed from Connected to Disconnected or Vice Versa.
• when settop boots with WiFi capability.
• when WiFi network is successfully established.
• when connection to WiFi network is lost.
• when WiFi driver failure is detected.
• By notifying about all the discussed events, it helps the other application to do some decision making or display some information in the screen.
• For example, when a video is being played from internet and in-between wireless connection is lost.
• In this case the video player will receive a disconnection event from the network manager and can show on screen error message.

Wi-Fi Network Manager - IARM Event & Calls

Lets see how the event notification mechanism works. Basically all the event related activity are done through a D-Bus messaging extension known as IARM. In our case the network manager will register few event names and their corresponding event handler function. When an application is interested to receive that event, he will be register as a listen to that event. Whenever the event occurs all the register listener that are connected to IARM will be able to receive the notification.

...

IARM_BUS_WIFI_MGR_API_getAvailableSSIDs

...

Retrieves the List of available APs

...

IARM_BUS_WIFI_MGR_API_getConnectedSSID

...

Returns the properties of the currently connected SSID

...

IARM_BUS_WIFI_MGR_API_setEnabled

...

Enable the WIFI adapter on the box

...

IARM_BUS_WIFI_MGR_API_connect

...

Connect with given or saved SSID and passphrase

...

IARM_BUS_WIFI_MGR_API_getConnectionType

...

Retrieves the type based on active network interface

...

IARM_BUS_WIFI_MGR_API_getRadioStatsProps

...

Retrieve the get radio stats properties

...

Refer to netsrvmgr for more detail such as APIs, Events and Error codes.

Wi-Fi Communication Workflow

In the below sequence diagram, we will see how an HTML application will interact with Wifi manager through Service manager. We can see that for each functionality we have an uniform API name across different component, which enable simplicity in development and the set off APIs can be mapped easily. For example, If we take one API that is getConnectionType(), which we can use to get the active interface type which may be Wifi or LAN interface.

In first place, we will have Java Script functions registered with Service manager. Then Service manager will have an internal implementation for that API with error handling and managing result.
When the call is propagated, to the actual handler daemon (Wifi manager) through message bus, it will be translated to a IARM RPC call. 

On the receiving side, Wifi manager will invoke actual Wi-Fi HAL API to get the result.So, we have seen a similar set of API are presented by different components to achieve the task.

An example, we have an user interface application where we want to show an icon based on whether Wi-Fi network is up. In that case we can take the help of service manager API to get the current state. Here service manager will internally call an RPC call with the Wifi manager to invoke the specific function. Then the wifi manager will invoke the actual HAL API to retrieve all the details and returns to the caller in a JSON formatted string. This status string will be then return to the application for displaying the appropriate icon based on UP/DN status.

Use Case: AP Discovery & Establishing Wi-Fi connection with AP

Here we will walkthrough the different RDK component involved in the process and starting from Application which is the imitator, ending with Wi-Fi HAL which is the provider of the functionality. We will also see the messaging formats in which the RDK components communicate. 

Initiating the connection: Here application may need to enable the WiFi if required. In which case he has call the initialization routine and network manager will handle the further operation

Getting a list of connection: When the WiFi system is up, application can request for a scan operation and then the neighbor scan API will be called by network manager. Which intern calls a Wi-Fi HAL API and return the result in JSON formatted string.

Selecting a preferred network: User can select a network from the list of Available AP.

Providing credential for the preferred network: Application has to handle the prompts for passphrase, network security Key, etc. and initiate the connection process. 

Validation of the credential: Wifi manager will take the parameter and select the appropriate method to pass credential to WPA supplicant via an Wi-Fi HAL function. WPA supplicant will perform the actual sequence of operation to validate and establish the connection which will be an asynchronous process. i.e whenever the connection is established an appropriate event will be generated and notify to the caller.

Results: Application when receive the connection establish/failed event can show a visual confirmation.

Wi-Fi Integration Requirement

For integrating Wifi feature in a new RDK platform, following basic requirement can be kept in mind,

• First we need to have the OEM or SOC provider driver and firmware available with us so that we can integrate with our platform.
• There are Generic linux wireless packages need to be integrated with the platform.
• Most importantly, all the compatibility issues regarding Wifi driver and platform need to be addressed before hand, so that there is no issues regarding performance or connection glitches.
• We will need build support files for integration.
• A new HAL has to be written for the platform.

RDK Wifi Specification mentions, all communication from network manager to the Wifi Driver has to be through WPA supplicant. So the basic requirement is to add WPA supplicant and its related packages such as netlink library and wireless tools. When all the dependency are added to the platform, we have to write a Wi-Fi HAL customized in our platform. Then we have to add the Wifi support in build framework via adding appropriate packages in image recipe as well as machine configuration file.

Code Walk-through in RPI Platform

Code Walk-through: Folder structure

Image Added

Looking at the below folder structure of the wifi HAL code in reference wifi & device specific wifi, We can see both follow similar naming conventions. We have 2 common files: wifi_common_hal.c and wifi_client_hal.c

In wifi_common_hal.c:

• Here we have defined most of the diagnostic APIs and utility functions.

In wifi_client_hal.c:

• It Mainly defines the internal state management functions, threads for monitoring the events coming from wpa_supplicant and connection related functions.
• It also defines callback functions for sending back the state changes and error events to wifi manager
• In generic wifi HAL, we have 3 header functions for defining AP, client & common APIs.
• In Raspberry Pi, the device specific HAL has dependency of WPA client library and libnl.

Code Walk-through: Wi-Fi HAL Recipe

This is a simple recipe which defines build rules for WIFI HAL library code. Here we can see that after defining some common stuff, it defines 2 environment variables i.e. PROVIDES , RPROVIDES_PN, both of which are assigned to virtual/wifi-hal. We can also see that wpa_supplicant and wifi-hal-headers as dependencies in the below code.

Image Added

Code Walk-through: Network Manager

Image Added

Debugging and Log analysis

TODO

API Documentation

 To know more about SoC/Application level APIs details use in RDK, refer the link  WIFI API Documentation

Wi-Fi Integration requirement

Code Walk-through

Wi-Fi HAL APIs

...