4-Sep-2020 : We are currently updating this plugin to support Solar 2D build
This plugin is intended to be used with Corona. Currently it only supports Android platform. View it here on Corona.
This plugin has 2 categories; GPS & WiFi. It exposes more control over them.
Getting Started
All the methods used will be described below. Note : you will need to view the results in the logs using adb logcat Corona:v *:s
command
Start off by adding the plugin to your project. Activate the plugin in Corona Plugin page, then in your build.settings file, add this line to include the plugin
plugins = { ["plugin.wirelessAndLocation"] = {publisherId = 'com.bricatta'}, },
Then, call the plugin in your lua file with this line
local library = require "plugin.wirelessAndLocation"
Please ensure you include permissions needed in build.config file in your project.
settings = { android = { usesPermissions = { "android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION", "android.permission.ACCESS_WIFI_STATE", "android.permission.CHANGE_WIFI_STATE", "android.permission.ACCESS_NETWORK_STATE", -- If needed "android.permission.BLUETOOTH", "android.permission.BLUETOOTH_ADMIN", }, }, }
Here is a sample project, which is based on Corona’s “Clock Sample Project”. All the calls are made in main.lua file. Download it here.
GPS Related
1) Turn On GPS
- This is similar to how Google Maps app request and automatically turns on the GPS on the device. Language will be based on device.
- Listener Function Output is a table containing :
- gpsAccessGiven : true if Gps is enabled
- Settings.Secure.LOCATION_PROVIDERS_ALLOWED : the permission
local result = library.requestTurnOnGps( ) print( json.encode(result) )
2) Open GPS Device Settings Page
- This will open the device settings page using an intent ( new Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS) )
library.openGpsSettings()
3) Get GPS data
- This uses a listener which will be called whenever a GPS intent/activity is called.
- This is similar to
Runtime:addEventListener( "location", locationHandler )
in Corona, but this plugin will give slightly more data (see screen shot below) - Input Parameters “
- listener (callback) function
- A table (see this Google document for more info ) :
- gpsMinTime : minimum time interval between updates, in milliseconds
- gpsMinDistance : minimum distance between updates, in meters
- Gps status values will correspond to this Google document
- Listener Output is a table containing :
- name : name of the provider (gps)
- locationListenerType (see this Google document for more info) :
- 1 = onProviderEnabled (e.g. when GPS is turned on/enabled)
- 2 = onProviderDisabled (e.g. when GPS is turned off/disabled)
- 3 = onStatusChange
- 4 = onLocationChanged
- locationListenerData : the location data (if any)
local function listenerFunction( event ) print( "Received gps event (" .. event.name .. "): ") -- 1 = onProviderEnabled (e.g. when GPS is turned on/enabled) -- 2 = onProviderDisabled (e.g. when GPS is turned off/disabled) -- 3 = onStatusChange -- 4 = onLocationChanged print( json.encode( event.locationListenerType )) print( json.encode( event.locationListenerData ) ) end local results = library.startGpsListener( listenerFunction , {gpsMinTime = "500", gpsMinDistance = "2" })
4) Get Available Providers
- This will get the available providers on the device
local results = library.getLocationProviders() print( json.encode( results ) ) -- Sample Output : -- {"isGPSProviderEnabled":true,"isPassiveProviderEnabled":true,"isNetworkProviderEnabled":true,"allProviders":"[passive, gps, network]"}
5) Get Last Known Location (Fused)*
- This feature is coming soon.
- Get last known location using Android’s Fused Location API. The location obtained is a coarse and accuracy is usually within a few hundred meters or a few kilometers.
- This feature is good to quickly get last known location without a GPS lock (as it may take a few minutes for GPS-lock)
- Read more here.
WiFi Related
1) Open the WiFi Settings Page
- This will open the device settings page using an intent ( new Intent(Settings.ACTION_WIFI_SETTINGS) )
library.openWifiSettings()
2) Add a WiFi
- This will manually add a WiFi connection to the device
- In this example, a WiFi network called ‘test’ is added
- After adding the WiFi, you can see it added in Device->Settings->WiFi->Manage Networks (it will be different on devices)
- Table Input Parameters :
- SSID : SSID of the WiFi
- password : the WiFi password. It is your responsibility to ensure the password length and other criterias are correct.
local result = library.setupNewWifi( { ssid = 'test' , password = 'ssidpassword' } )
3) Scan WiFi
IMPORTANT : Access to location (GPS) is required. Please read this Google document. There are also throttling limitations on how many scans can be performed
- This will scan the available WiFi signals
- Input Parameters :
- listener (callback) function
- Output table :
- wifiState : Values will correspond to this Google document
- isScanSuccessful : true if scan is successful. False : if scan is unsuccessful. The listener/callback function will not be called. Most likely location (GPS) is not turned on.
- wifiScanResults : the string of data
- Listener Output is a table containing :
- A json string. See example below
-- Return the results of the latest access point scan. -- An app must need ACCESS_FINE_LOCATION & others (depending on API LEVEL) permission in order to get valid results. See https://developer.android.com/guide/topics/connectivity/wifi-scan local function listenerFunction(event) print( "Received wifi-scan results event (" .. event.name .. "): ", json.encode(event.isScanSuccessful), json.encode(event.scanResults) ) -- Sample Output (some info are masked with XX) -- "[SSID: , BSSID: 76:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -56, frequency: 2442, timestamp: 95592030136, distance: ?(cm), distanceSd: ?(cm), passpoint: no, ChannelBandwidth: 1, centerFreq0: 2432, centerFreq1: 0, 80211mcResponder: is not supported, Carrier AP: no, Carrier AP EAP Type: -1, Carrier name: null, Radio Chain Infos: null, semVendorSpecificInfo: null, semBssLoadElement: null, semKtVendorSpecificInfo: null, SSID: , BSSID: 74:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -57, frequency: 2442, timestamp: 95592030233, distance: ?(cm), distanceSd: ?(cm), passpoint: no, ChannelBandwidth: 1, centerFreq0: 2432, centerFreq1: 0, 80211mcResponder: is not supported, Carrier AP: no, Carrier AP EAP Type: -1, Carrier name: null, Radio Chain Infos: null, semVendorSpecificInfo: null, semBssLoadElement: null, semKtVendorSpecificInfo: null, SSID: , BSSID: 76:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -57, frequency: 2442, timestamp: 95592030242, distance: ?(cm), distanceSd: ?(cm), passpoint: no, ChannelBandwidth: 1, centerFreq0: 2432, centerFreq1: 0, 80211mcResponder: is not supported, Carrier AP: no, Carrier AP EAP Type: -1, Carrier name: null, Radio Chain Infos: null, semVendorSpecificInfo: null, semBssLoadElement: null, semKtVendorSpecificInfo: null, SSID: XX, BSSID: 76:XX:28:b5:XX:XX, ... end local wifiScanResults = library.getWifiScanInfo( listenerFunction ) print( json.encode(wifiScanResults) ) -- Sample Output (some info are masked with XX) -- {"wifiState":3,"isScanSuccessful":true,"wifiScanResults":"[SSID: , BSSID: 76:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -57, frequency: 2442, timestamp: 96568726938, distance: ?(cm), distanceSd: ?(cm), passpoint: no, ChannelBandwidth: 1, centerFreq0: 2432, centerFreq1: 0, 80211mcResponder: is not supported, Carrier AP: no, Carrier AP EAP Type: -1, Carrier name: null, Radio Chain Infos: null, semVendorSpecificInfo: null, semBssLoadElement: null, semKtVendorSpecificInfo: null, SSID: XX, BSSID: 76:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -57, frequency: 2442, timestamp: 96568727004, distance: ?(cm), distanceSd: ?(cm), passpoint: no, ChannelBandwidth: 1, centerFreq0: 2432, centerFreq1: 0, 80211mcResponder: is not supported, Carrier AP: no, Carrier AP EAP Type: -1, Carrier name: null, Radio Chain Infos: null, semVendorSpecificInfo: null, semBssLoadElement: null, semKtVendorSpecificInfo: null, SSID: , BSSID: 76:XX:28:b5:XX:XX, capabilities: [WPA2-PSK-CCMP][ESS], level: -58, frequency: 2442, timestamp: 96568726996, distance: ?(cm), d....
4) WiFi Connection Info
- Will get WiFi connection info
- Output table :
- wifiState : Values will correspond to this Google document
- wifiConnectionInfo : the data is in here
-- Will get the info of getConnectionInfo. Return dynamic information about the current Wi-Fi connection, if any is active. local result = library.getWifiConnectionInfo() print( json.encode(result) ) -- Sample Output (some info are masked with XX) -- {"wifiState":3,"wifiConnectionInfo":"SSID: , BSSID: , MAC: 02:XX:00:00:XX:XX, Supplicant state: SCANNING, RSSI: -127, Link speed: -1Mbps, Frequency: -1MHz, Net ID: -1, Metered hint: false, GigaAp: false, VenueName: null, score: 0"}
5) DHCP Info
- Will get WiFi related info, such as if 5GHz support is available on the device.
- Note that there is a minimum Android API (>21) for this to function properly.
-- Will get getDhcpInfo, getConfiguredNetworks, and 5Ghz is-supported (only for API 21 Lollipop and above) local result = library.getWifiDhcpAndConfiguredNetworksInfo() print( json.encode(result) ) -- Sample Output (some info are masked with XX) -- {"wifi5GhzSupport":true,"wifiState":3,"wifiConfiguredNetworks":"[ID: 0 SSID: \"XX\" PROVIDER-NAME: null BSSID: null FQDN: null PRIO: 0 HIDDEN: true PMF: false\n NetworkSelectionStatus NETWORK_SELECTION_ENABLED\n connect choice: \"XX\"WPA_PSK connect choice set time: 09-23 20:53:07.486 hasEverConnected: true\n numAssociation 31\nupdate millis:1569490936412\ncreation millis:1569220127972\n validatedInternetAccess\n KeyMgmt: WPA_PSK Protocols: WPA RSN\n AuthAlgorithms: OPEN\n PairwiseCiphers: TKIP CCMP\n GroupCiphers: WEP40 WEP104 TKIP CCMP\n PSK: *\nEnterprise config:\neap NULL\nphase2\"auth=NULL\"\nIP config:\nIP assignment: DHCP\nProxy settings: NONE\n cuid=1000 cname=android.uid.system:1000 luid=1000 lname=android.uid.system:1000 lcuid=1000 userApproved=USER_UNSPECIFIED noInternetAccessExpected=false \nrecentFailure:Association Rejection code: 0\n\nsamsungSpecificFlags:\nsemAutoWifiScore: 4\nisVendorAp : false\nrecoverableRSSI: -200\ninRecoverArea: false\ndisabledTime: 0\nnotInRangeTime: 0\nisUsableInternet: false\nskipInternetCheck: 0\nnotAskAgainCheck: false\nnextTargetRssi: 0\nisCaptivePortal: false\nisAuthenticated: false\nloginUrl: null\nautoReconnect: 1\nisRecommended: false\nisHomeProviderNetwork: false\n WapiCertIndex: 0\n WapiPskType: 0\nisWeChatAp : false\nentryRssi24GHz : -78\nentryRssi5GHz : -75, ID: 1 SSID: \"XX\" PROVIDER-NAME: null BSSID: null FQDN: null PRIO: 0 HIDDEN: true PMF: false\n NetworkSelectionStatus NETWORK_SELECT....
Others
1) Open Bluetooth Settings
- Will just open device bluetooth settings page
library.openBluetoothSettings( )
* feature coming soon