Documentation for Solar2D (Corona) GPS Wireless Plugin

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 :
1. wifiState : Values will correspond to this Google document
2. 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