cordova-plugin-wifiwizard2
Advanced tools
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
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.
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
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
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 12 and later, enable the Access WiFi Information capability for your app in Xcode. When you enable this capability, Xcode automatically adds the Access WiFi Information entitlement to your entitlements file and App ID.
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;
These are functions that can be used by both Android and iOS applications
WifiWizard2.getConnectedSSID()
WifiWizard2.getConnectedBSSID()
WifiWizard2.timeout(delay)
delay should be time in milliseconds to delaydelay is optional, default is 2000ms = 2 secondsExample 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
TIMEOUT_WAITING_FOR_SCAN on timeout waiting for scan 10 seconds +SCAN_FAILED if unable to start scanFor functionality, you need to note the following:
ssidPassword or call with falseWifiWizard2.iOSConnectNetwork(ssid, ssidPassword)
WifiWizard2.iOSDisconnectNetwork(ssid)
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)
ssid should be the SSID to connect to requiredbindAll should be set to true to tell Android to route all connections from your Android app, through the wifi connection (default is false) optional
WifiWizard2.enable for more details regarding bindAll featurealgorithm and password is not required if connecting to an open networkWPA and WEP are only supported algorithmsWPA2 just pass WPA as the algorithmisHiddenSSID to true if the network you're connecting to is hiddenformatWifiConfigformatWifiConfig then add then enableThrown Errors
CONNECT_FAILED_TIMEOUT unable to verify connection, timed out after 60 secondsINVALID_NETWORK_ID_TO_CONNECT Unable to connect based on generated wifi configINTERPUT_EXCEPT_WHILE_CONNECTING Interupt exception while waiting for connectionSame 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)
ssid can either be an SSID (string) or a network ID (integer)ssid is OPTIONAL .. if not passed, will disconnect current WiFi (almost all Android versions now will just automatically reconnect to last wifi after disconnecting)ssid is provided, this method will first attempt to disable and then remove the networkdisable insteadThrown Errors
DISCONNECT_NET_REMOVE_ERROR Android returned error when removing wifi configurationDISCONNECT_NET_DISABLE_ERROR Unable to connect based on generated wifi configDISCONNECT_NET_ID_NOT_FOUND Unable to determine network ID to disconnect/remove (from passed SSID)ERROR_DISCONNECT - Android error disconnecting wifi (only when SSID is not passed)WifiWizard2.formatWifiConfig(ssid, password, algorithm, isHiddenSSID)
algorithm and password is not required if connecting to an open networkWPA and WEP are only supported algorithmsWPA2 just pass WPA as the algorithmisHiddenSSID to true if the network you're connecting to is hiddenWifiWizard2.formatWPAConfig(ssid, password, isHiddenSSID)
WifiWizard2.formatWifiConfig( ssid, password, 'WPA', isHiddenSSID );WifiWizard2.add(wifi)
wifi must be an object formatted by formatWifiConfig, this must be done before calling enableThrown Errors
AUTH_TYPE_NOT_SUPPORTED - Invalid auth type specifiedERROR_ADDING_NETWORK - Android returned -1 specifying error adding networkERROR_UPDATING_NETWORK - Same as above, except an existing network ID was found, and unable to update itWifiWizard2.remove(ssid)
ssid can either be an SSID (string) or a network ID (integer)Thrown Errors
UNABLE_TO_REMOVE Android returned failure in removing networkREMOVE_NETWORK_NOT_FOUND Unable to determine network ID from passed SSIDWifiWizard2.listNetworks()
WifiWizard2.scan([options])
startScan and then getScanResults, except this method will only resolve the promise after the scan completes and returns the results.WifiWizard2.startScan()
scan method instead of startScanThrown Errors
STARTSCAN_FAILED Android returned failure in starting scanWifiWizard2.getScanResults([options])
getScanResults should only be called after calling startScan (it is recommended to use scan instead as this starts the scan, then returns the results)[options] is optional, if you do not want to specify, just pass success callback as first parameter, and fail callback as second parameternetworks = [
{ "level": signal_level, // raw RSSI value
"SSID": ssid, // SSID as string, with escaped double quotes: "\"ssid name\""
"BSSID": bssid // MAC address of WiFi router as string
"frequency": frequency of the access point channel in MHz
"capabilities": capabilities // Describes the authentication, key management, and encryption schemes supported by the access point.
"timestamp": timestamp // timestamp of when the scan was completed
"channelWidth":
"centerFreq0":
"centerFreq1":
}
]
channelWidth centerFreq0 and centerFreq1 are only supported on API > 23 (Marshmallow), any older API will return null for these valuesAn options object may be passed. Currently, the only supported option is numLevels, and it has the following behavior:
(n == true || n < 2), *.getScanResults({numLevels: n}) will return data as before, split in 5 levels;(n > 1), *.getScanResults({numLevels: n}) will calculate the signal level, split in n levels;(n == false), *.getScanResults({numLevels: n}) will use the raw signal level;WifiWizard2.isWifiEnabled()
WifiWizard2.setWifiEnabled(enabled)
true for enabled parameter to set Wifi enabledThrown Errors
ERROR_SETWIFIENABLED wifi state does not match call (enable or disable)WifiWizard2.getConnectedNetworkID()
Thrown Errors
GET_CONNECTED_NET_ID_ERROR Unable to determine currently connected network ID (may not be connected)WifiWizard2.resetBindAll()
WifiWizard2.setBindAll()
WifiWizard2.canConnectToInternet()
connect or enable and passed true for bindAll, your application will force the ping through wifi connection.true (or passed false) for bindAll, and the wifi does not have internet connection, Android Lollipop+ (API 21+) will use cell connection to ping (due to Android using cell connection when wifi does not have internet) More DetailsWifiWizard2.canConnectToRouter()
canPingWifiRouter is notoriously unreliable, this method uses HTTP connection to test if able to connect to router (as most routers should have web server running on port 80)bindAll feature to support issues with Android Lollipop+ (API 21+) not routing calls through WiFi if WiFi does not have internet connection See Android Bloghttp://192.168.0.1/ where 192.168.0.1 is the automatically detected IP address)WifiWizard2.isConnectedToInternet()
connect or enable and passed true for bindAll, your application will force the ping through wifi connection.true (or passed false) for bindAll, and the wifi does not have internet connection, Android Lollipop+ (API 21+) will use cell connection to ping (due to Android using cell connection when wifi does not have internet) More DetailsWifiWizard2.canPingWifiRouter()
bindAll feature to support issues with Android Lollipop+ (API 21+) not routing calls through WiFi if WiFi does not have internet connection See Android BlogWifiWizard2.enableWifi()
WifiWizard2.disableWifi()
WifiWizard2.getWifiIP()
WifiWizard2.getWifiRouterIP()
Thrown Errors
NO_VALID_IP_IDENTIFIED if unable to determine a valid IP (ip returned from device is 0.0.0.0)WifiWizard2.getWifiIPInfo()
Returns a JSON object with IPv4 address and subnet {"ip": "192.168.1.2", "subnet": "255.255.255.0" } or rejected promise if not found or not connected
Thrown Errors
NO_VALID_IP_IDENTIFIED if unable to determine a valid IP (ip returned from device is 0.0.0.0)
WifiWizard2.reconnect()
Thrown Errors
ERROR_RECONNECT Android returned error when reconnectingWifiWizard2.reassociate()
Thrown Errors
ERROR_REASSOCIATE Android returned error when reassociatingWifiWizard2.getSSIDNetworkID(ssid)
WifiWizard2.disable(ssid)
ssid can either be an SSID (string) or a network ID (integer)Thrown Errors
UNABLE_TO_DISABLE Android returned failure in disabling networkDISABLE_NETWORK_NOT_FOUND Unable to determine network ID from passed SSID to disableWifiWizard2.requestPermission()
ACCESS_FINE_LOCATION permssionscan, startStart and getScanResultsThrown Errors
PERMISSION_DENIED user denied permission on deviceWifiWizard2.enable(ssid, bindAll, waitForConnection)
ssid can either be an SSID (string) or a network ID (integer)bindAll should be set to true to tell Android to route all connections from your Android app, through the wifi connection
true to bindAll will force Android to route connections from your Android app through Wifi, regardless of internet connection.bindAll and this should fix the problem.bindAll is enabled, ALL connections from your app will be routed through WiFi, until you call disconnect or disablebindall will be ignored (as API older than 21 does this by default)WifiWizard2.add(wifi) before calling enable as the wifi configuration must exist before you can enable it (or previously used connect without calling disconnect)true to waitForConnection to only return promise once connection is verified in COMPLETED state to specific ssidThrown Errors
UNABLE_TO_ENABLE - Android returned -1 signifying failure enabling
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.
Run cordova plugin add cordova-plugin-wifiwizard2
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
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.
WIFI_NOT_ENABLED
Please see demo Meteor project for code examples: https://github.com/tripflex/WifiWizard2Demo
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
3.1.1 - April 4, 2019
canConnectToRouter() and canConnectToInternet() to use HTTP to test connection (since ping is notoriously unreliable)canConnectToRouter(), canConnectToInternet(), canPingWifiRouter(), isConnectedToInternet() to iOS fn return not supportedresetBindAll() and setBindAll() for Android (props @saoron PR #74)JSONObject.NULL instead of just null when scan results Android older than Marshmallow (props @seanyang1984) Issue #513.1.0 - August 28, 2018
jdk.nashorn.internal.codegen.CompilerConstants import (props @jack828)Object cannot be converted to int in Android code (props @xLarry)3.0.0 - April 12, 2018
getWifiIP and getWifiIPInfo functionsgetWifiRouterIP functionconnect instead of androidConnectNetwork, etc)requestPermission and automatic request permission when call method that requires themisConnectedToInternet to ping 8.8.8.8 and verify if wifi has internet connectioncanPingWifiRouter to ping wifi router IP obtained through DHCP informationbindAll feature to use bindProcessToNetwork for Marshmallow (API 23+) and setProcessDefaultNetwork for Lollipop (API 21-22) More Detailsconnect to helper method that calls formatWifiConfig then add then enabledisconnect to helper method that calls disable then removeadd method to set priority of added wifi to highest priority (locates max priority on existing networks and sets to +1)ping Android Java code for possible new methods to ping custom IP/URL (in upcoming releases)2.1.1 - 1/9/2018
2.1.0 - 1/8/2018
fail callback when error detected in JS (before calling Cordova)exec actions (before actions called that require wifi enabled)es6-promise-plugin cordova dependency to plugin.xmlfalse in Cordova Android execute when invalid action is called
Issue #12.0.0 - 1/5/2018
disconnect() before and reconnect() after disable/enable network on connect callgetConnectedNetworkID to return currently connected network IDverifyWiFiEnabled to automatically enable WiFi for methods that require WiFi to be enabledscan method to return networks in callback @props jeffcharlesChangelog 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
isWifiEnabled, setWifiEnabledv0.2.5
getConnectedSSID error handlersv0.2.4
getConnectedSSID methodv0.2.3
disconnect that does disconnection on current WiFiv0.2.2
startScan and getScanResultsv0.2.1
formatWPAConfigv0.2.0
v0.1.1
addNetwork will now update the network if the SSID already exists.v0.1.0
v0.0.3
v0.0.2
v0.0.1
FAQs
Cordova WiFi Manager for Android and iOS
The npm package cordova-plugin-wifiwizard2 receives a total of 419 weekly downloads. As such, cordova-plugin-wifiwizard2 popularity was classified as not popular.
We found that cordova-plugin-wifiwizard2 demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.