KeplerNetworkManagerTM - A KeplerScript Library

KeplerNetworkManagerTM is a library to provide APIs for managing network interfaces.

Using APIs in KeplerNetworkManagerTM, a KeplerScript application can:

• Enable or disable network interfaces
• Query network status
• Monitor network connections and events
• Manage Wi-Fi access point information and connections
• Monitor Wi-Fi events

KeplerNetworkManagerTM includes support for React Native Network Info, allowing KeplerScript applications to use the same APIs available in React Native Network Info."

Getting Started

A KeplerScript application can consume KeplerNetworkManagerTM for network support.

Setup

To use the KeplerNetworkManagerTM, follow the instructions below:

1. Update Config Go to the Config file in your package and add KeplerNetworkManagerTM with 1.0 version.

    dependencies = {
        1.0 = {
            ...
            KeplerNetworkManagerTM = 1.0;
        };
    };

2. Update package.json Open package.json file and add "@amazon-devices/keplerscript-netmgr-lib" with the version of "~2.0.0".

     "dependencies": {
       ...
       "@amazon-devices/keplerscript-netmgr-lib": "~2.0.0"
     },

3. Add com.amazon.network.service to [wants.service] in your KeplerScript application's manifest.toml:

	[[wants.service]]
	id = "com.amazon.network.service"

4. Add API privileges to [wants.privilege] in your KeplerScript application's manifest.toml:

Each API requires different privileges. Add the required privileges to [wants.privilege]. Invoke the requestPrivilege() for run-time privileges. This prompts the operating system to launch its Privilege Request Handler that handles user consent. Some APIs requires your applications to be signed.

    [[wants.privilege]]
    id="com.amazon.wifi.privilege.wifi-scan"
    [[wants.privilege]]
    id="com.amazon.network.privilege.net-info"

API

NetworkManager

NetworkManager provides primary APIs for managing network interfaces in the system. Specifically, it provides APIs for:

• Enabling or disabling network interfaces
• Monitoring network status, captive portal status, and IP configurations
• Notifying applications of network connection changes"

In NetworkManager, most of APIs require a network interface id. The network inteface id is defined in NetworkInterface. NetworkInterface can be obtained from calling getNetworkInterfaces() or getActiveNetworkInterface(). getNetworkInterfaces() returns the list of NetworkInterface on the given network interface type and getActiveNetworkInterface() returns NetworkInterface for the current active network interface.

Use of some APIs in NetworkManager requires declaring network information or network administrator permission in your manifest file. Calling the API without proper permission results in getting Status.PERMISSION_DENIED as the return of the API.

| API | Description | Permission | | -----------| ----------- | ----------- | |getNetworkInterfaces()|return the array of NetworkInterface provided in the system| -| |getActiveNetworkInterface()|return the default active NetworkInterface| -| |enableNetworkInterface()|enable or disable NetworkInterface|com.amazon.network.privilege.net-admin| |isNetworkInterfaceEnabled()|return whether NetworkInterface is enabled|-| |getIpConfig()|return IP configuration on the NetworkInterface|-| |setIpConfig()|set IP configuration| com.amazon.network.privilege.net-admin| |getNetworkState()|return the current network state|-| |getMacAddress()|return the MAC address of the NetworkInterface|com.amazon.network.privilege.restricted-net-info*| |evaluateCaptivePortal()|evaluate captive portal|com.amazon.network.privilege.net-admin| |getCaptivePortalState()|return the captive portal state |-| |getNetworkCapabilities()|return the network capabilities |-| |getLinkSpeed()|return the link speed |-| |setNetworkProxy()|set network proxy|com.amazon.network.privilege.net-admin| |getNetworkProxy()|return network proxy|-| |registerNetworkEventCallback()|register callback to receive network events|-| |unregisterNetworkEventCallback()|unregister callback to receive network events|-|

*. com.amazon.network.privilege.restricted-net-info is only allowed to signed applications.

WifiInterface

WifiInterface is a class that offers APIs for managing Wi-Fi connectivity. Using APIs in WifiInterface, you scan Wi-Fi access points, connect the Wi-Fi access point, disconnect the currently connected access point.

Use of some APIs in WifiInterface requires declaring network information, network administrator, or Wi-Fi scan permission in your manifest file. Calling the API without proper permission results in getting Status.PERMISSION_DENIED as the return of the API.

| API | Description | Permission | | -----------| ----------- | ----------- | |startScan()|start a scan to discovery Wi-Fi access points|com.amazon.wifi.privilege.wifi-scan| |getScanResults()|return discovered Wi-Fi access points from the result of the latest scan|com.amazon.wifi.privilege.wifi-scan| |getProfiles()|return the array of Wi-Fi profiles|com.amazon.network.privilege.net-info| |addProfile()|add a new Wi-Fi profile|com.amazon.network.privilege.net-admin| |removeProfile()|remove a Wi-Fi profile| com.amazon.network.privilege.net-admin| |saveProfiles()|save the current Wi-Fi profiles in the system| com.amazon.network.privilege.net-admin| |enableAllProfiles()|return the current network state|com.amazon.network.privilege.net-admin| |connect()|connect to the access point stored in Wi-Fi profiles|com.amazon.network.privilege.net-admin| |disconnect()|disconnect the connected access point|com.amazon.network.privilege.net-admin| |getConnectionInfo()|return the connection information|com.amazon.network.privilege.net-info| |calculateSignalLevel()|return the level of the signal strength |-| |getLinkSpeed()|return the link speed |-| |getStandard()|return the supported Wi-Fi standard|-| |getStatisticsInfo()|return the statistics information from the current connection|-| |registerEventCallback()|register callback to receive Wi-Fi events|-| |unregisterEventCallback()|unregister callback to receive Wi-Fi events|-|

Usage

Query Network Status

The following code snippet shows how to query network status.

import {NetworkManager, NetworkState, IpType} from "@amazon-devices/keplerscript-netmgr-lib";
const networkManager = new NetworkManager();
// Get Wi-Fi network interface information including network interface id
networkManager.getNetworkInterfaces(NetworkInterfaceType.WIFI, nis);
// Get network state with the network id from getNetworkInterfaces() or getActiveNetworkInterface()
const [status, state] = networkManager.getNetworkState(networkInterfaceId, IpType.IPV4);

Monitor Network Events

In order to receive network events from network interfaces, you must implement NetworkEventCallback and register the NetworkEventCallback using registerNetworkEventCallback. For example, this code snippet shows how to implement and register NetworkEventCallback.

const callback: NetworkEventCallback = {
      onNetworkStateChanged: (networkInterfaceId, type, oldState, newState) => {
      },
      onCaptivePortalEvaluated: (networkInterfaceId, result) => {
      },
    };
networkManager.registerNetworkEventCallback(callback);

Wi-Fi Scan

In order to scan Wi-Fi access points, you can call startScan() and wait onScanDone() for the completion.

const wifiEventCallback: WifiEventCallback = {
    onScanDone: () => {
    }
...
}
wifiInterface.registerEventCallback(wifiEventCallback);
wifiInterface.startScan();

Once your onScanDone() is called back, you can get the result by calling getScanResults().

let results: ScanResultItem[] = [];
res = wifiInterface.getScanResults(results);

Connect an Wi-Fi access point

A Profile represents an Wi-Fi access point to connect. For different security modes, different parameter sets in the Wi-Fi Profile are required. ssid and authMode are required for every Wi-Fi Profiles. WPA1/WPA2 and WPA3 networks require psk and saePassword respectively.

// If you need Open access point
const profile:Profile = {
    ssid: "My AP's SSID",
    authMode: AuthMode.OPEN
};
// If you need WPA2 access point
const profile:Profile = {
    ssid: "My AP's SSID",
    psk: "MY AP's Pre-Shared Key",
    authMode: AuthMode.WPA2
};
// If you need WPA3 access point
 const profile:Profile = {
    ssid: "My AP's SSID",
    saePassword: "MY AP's SAE password",
    authMode: AuthMode.WPA3
};
// Add the profile and connect
wifiInterface.addProfile(profile);
wifiInterface.connect( "My AP's SSID", AuthMode.WPA2);