tripflex / WifiWizard2

A Cordova plugin for managing Wifi networks (new version of WiFiWizard) - Latest is version 3+
https://www.npmjs.com/package/cordova-plugin-wifiwizard2
Apache License 2.0
123 stars 146 forks source link
android cordova cordova-plugin ios wifi wifiwizard wifiwizard2

WiFiWizard2 - 3.1.1

Table of Contents

About

WifiWizard2 enables Wifi management for both Android and iOS applications within Cordova/Phonegap projects.

This project is a fork of the WifiWizard plugin with fixes and updates, as well as patches taken from the Cordova Network Manager plugin.

Version 3.0.0+ has undergone a TON of changes from the original fork (version 2.0), and the majority of method/functions have been changed. You can find the latest release of version 2 on the 2.1.x branch

The recommended version to use is the latest 3+ as that is the version that is actively maintained.

iOS has limited functionality as Apple's WifiManager equivalent is only available as a private API. Any app that used these features would not be allowed on the app store.

If you are an iOS developer, please consider helping us to resolve the open iOS issues

If you are an Android developer, please consider helping us to refactor the current code base

If you're a Cordova developer, please consider helping out this project, open a new issue, a PR, or contact me directly

Basics

This plugin creates the object WifiWizard2 and is accessible after deviceready has been fired, see Cordova deviceready Event Docs

document.addEventListener('deviceready', function () {
    // Call some WifiWizard2.method after deviceready fired
}, false);

This is really only necessary if you plan on immediately invoking one of this plugin's methods/functions, as the majority of the time you would probably just call the method/function on say, a button click to scan for networks, etc. Basically if you are going to call something immediately when a webview is shown, make sure to add the event listener for deviceready before making that call, otherwise you probably don't need to.

Async Handling

Because Cordova exec calls are made asynchronously, all methods/functions return async promises. These functions will return the results, or a JavaScript error. You should use await and try/catch blocks (or .then and .catch). See below for more details, and examples.

Callbacks are not longer supported in this plugin

Promises are handled by the Cordova PromisesPlugin as an ES6 polyfill if your application does not already define window.Promise

Demo Meteor Project

To test this plugin as well as provide some example code for others to work off of, I have created an example Meteor project you can find here:

https://github.com/tripflex/WifiWizard2Demo

This demo has examples of using both async functions (with async/await and try/catch blocks), as well as non async functions with .then and .catch

Android and IOS Permissions and Notes

In order to obtain scan results (to call scan or startScan then getScanResults) your application must have the ACCESS_FINE_LOCATION Android Permission. You can do this by calling the requestPermission method detailed below, or this plugin will automagically do this for you when you call scan or startScan functions.

Newer versions of Android will not allow you to remove, update existing configuration, or disable networks that were not created by your application. If you are having issues using this features, with your device connected to your computer, run adb logcat to view Android Logs for specific error.

IOS Notes

iOS 12 and later, enable the Access WiFi Information capability for your app in Xcode. If you also want to use the iOS specific connection functions the Hotspot Configuration capability. When you enable this capability, Xcode automatically adds the Access WiFi Information entitlement to your entitlements file and App ID.

Ionic/Angular Notes

This plugin does not have @ionic/native typings (yet), in order to use it add this to just below your import list on your service: declare var WifiWizard2: any;

Global Functions

These are functions that can be used by both Android and iOS applications

WifiWizard2.getConnectedSSID()
WifiWizard2.timeout(delay)

Example inside async function

async function example(){
    await WifiWizard2.timeout(4000);
    // do something after 4 seconds
}

Example inside standard non-async function

function example(){
    WifiWizard2.timeout(4000).then( function(){
        // do something after waiting 4 seconds
    }):
}

Thrown Errors

iOS Functions

For functionality, you need to note the following:

WifiWizard2.iOSConnectNetwork(ssid, ssidPassword)
WifiWizard2.iOSDisconnectNetwork(ssid)

Android Functions

Connect vs Enable

When writing Android Java code, there is no connect methods, you basically either enable or disable a network. In the original versions of WifiWizard the connect method would basically just call enable in Android. I have changed the way this works in WifiWizard2 version 3.0.0+, converting it to a helper method to eliminate having to call formatWifiConfig then add and then enable ... the connect method will now automatically call formatWifiConfig, then call add to either add or update the network configuration, and then call enable. If the connect method is unable to update existing network configuration (added by user or other apps), but there is a valid network ID, it will still attempt to enable that network ID.

WifiWizard2.connect(ssid, bindAll, password, algorithm, isHiddenSSID)

Thrown Errors

Disconnect vs Disable

Same as above for Connect vs Enable, except in this situation, disconnect will first disable the network, and then attempt to remove it (if SSID is passed)

WifiWizard2.disconnect(ssid)

Thrown Errors

WifiWizard2.formatWifiConfig(ssid, password, algorithm, isHiddenSSID)
WifiWizard2.add(wifi)

Thrown Errors

WifiWizard2.remove(ssid)

Thrown Errors

WifiWizard2.listNetworks()
WifiWizard2.scan([options])
WifiWizard2.startScan()

Thrown Errors

WifiWizard2.getScanResults([options])

An options object may be passed. Currently, the only supported option is numLevels, and it has the following behavior:

WifiWizard2.isWifiEnabled()

Thrown Errors

WifiWizard2.getConnectedNetworkID()

Thrown Errors

New to 3.1.1+

WifiWizard2.resetBindAll()
WifiWizard2.setBindAll()
WifiWizard2.canConnectToInternet()
WifiWizard2.canConnectToRouter()

New to 3.0.0+

WifiWizard2.isConnectedToInternet()
WifiWizard2.canPingWifiRouter()
WifiWizard2.enableWifi()
WifiWizard2.disableWifi()
WifiWizard2.getWifiIP()
WifiWizard2.getWifiRouterIP()

Thrown Errors

WifiWizard2.getWifiIPInfo()
WifiWizard2.reconnect()

Thrown Errors

WifiWizard2.reassociate()

Thrown Errors

WifiWizard2.getSSIDNetworkID(ssid)
WifiWizard2.disable(ssid)

Thrown Errors

WifiWizard2.requestPermission()

Thrown Errors

WifiWizard2.enable(ssid, bindAll, waitForConnection)

Thrown Errors

UNABLE_TO_ENABLE - Android returned -1 signifying failure enabling

Installation

Master

Run cordova plugin add https://github.com/tripflex/wifiwizard2

To install from the master branch (latest on GitHub)

To install a specific branch (add #tag replacing tag with tag from this repo, example: cordova plugin add https://github.com/tripflex/wifiwizard2#v3.1.1

Find available tags here: https://github.com/tripflex/WifiWizard2/tags

If you are wanting to have the latest and greatest stable version, then run the 'Releases' command below.

Releases

Run cordova plugin add cordova-plugin-wifiwizard2

Meteor

To install and use this plugin in a Meteor project, you have to specify the exact version from NPM repository: https://www.npmjs.com/package/cordova-plugin-wifiwizard2

As of April 4th 2019, the latest version is 3.1.1:

meteor add cordova:cordova-plugin-wifiwizard2@3.1.1

Errors/Rejections

Methods now return formatted string errors as detailed below, instead of returning generic error messages. This allows you to check yourself what specific error was returned, and customize the error message. In an upcoming release I may add easy ways to override generic messages, or set your own, but for now, errors returned can be found below each method/function.

Generic Thrown Errors

WIFI_NOT_ENABLED

Examples

Please see demo Meteor project for code examples: https://github.com/tripflex/WifiWizard2Demo

Ionic/Angular Example (User Provided)

Props @13546777510 (Angelo Fan) has provided a basic Ionic/Angluar demo app: https://github.com/13546777510/WifiWizard2-Demo See issue #69 regarding this

I recommend using ES6 arrow functions to maintain this reference. This is especially useful if you're using Blaze and Meteor.

this.FirstName = 'John';

wifiConnection.then( result => {
   // Do something after connecting!
   // Using arrow functions, you still have access to `this`
   console.log( this.FirstName + ' connected to wifi!' );
});

License

Apache 2.0

Changelog:

3.1.1 - April 4, 2019

3.1.0 - August 28, 2018

3.0.0 - April 12, 2018

2.1.1 - 1/9/2018

2.1.0 - 1/8/2018

2.0.0 - 1/5/2018

Changelog below this line, is from original WifiWizard

v0.2.9

isWifiEnabled bug fixed. level in getScanResults object now refers to raw RSSI value. The function now accepts an options object, and by specifiying { numLevels: value } you can get the old behavior.

v0.2.8

getScanResults now returns the BSSID along with the SSID and strength of the network.

v0.2.7

v0.2.6

v0.2.5

v0.2.4

v0.2.3

v0.2.2

v0.2.1

v0.2.0

v0.1.1

v0.1.0

v0.0.3

v0.0.2

v0.0.1