Documentation for Corona GPS Wireless Plugin

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.

Sample Code

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

First. 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 main.lua file. Download it here.


GPS Related

1) Turn On GPS

  1. This is similar to how Google Maps app request and automatically turns on the GPS on the device
  2. Input Parameters :
    • listener (callback) function
  3. Listener Function Output is a table containing :
    • gpsAccessGiven : true if Gps is enabled
    • Settings.Secure.LOCATION_PROVIDERS_ALLOWED : the permission
local function  listenerFunction(event)
  print( 'gpsAccessGiven' , event.gpsAccessGiven )

  -- Sample Output
  -- {"Settings.Secure.LOCATION_PROVIDERS_ALLOWED":3,"isGpsProviderEnabled":true}

end
local result = library.requestTurnOnGps( listenerFunction )
print( json.encode(result) )

2) Open GPS Device Settings Page

  1. This will open the device settings page using an intent ( new Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS) )
library.openGpsSettings()

3) Get GPS data

  1. This uses a listener which will be called whenever a GPS intent/activity is called.
  2. This is similar to Runtime:addEventListener( "location", locationHandler ) in Corona, but this plugin will give slightly more data (see screen shot below)
  3. 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
  4. Gps status values will correspond to this Google document
  5. 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

  1. 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]"}

WiFi Related

1) Open the WiFi Settings Page

  1. This will open the device settings page using an intent ( new Intent(Settings.ACTION_WIFI_SETTINGS) )
library.openWifiSettings()

2) Add a WiFi 

  1. This will manually add a WiFi connection to the device
  2. Table Input Parameters  :
    • SSID : SSID of the WiFi
    • password : the WiFi password
local result = library.setupNewWifi( { ssid = 'ssidName' , 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

  1. This will scan the available WiFi signals
  2. Input Parameters :
    • listener (callback) function
  3. 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
  4. Listener Output is a table containing :
-- 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

  1. Will get WiFi connection info
  2. 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

  1. Will get WiFi related info, such as if 5GHz support is available on the device.
  2. Note that there is a minimum Android API 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

  1. Will just open device bluetooth settings page
library.openBluetoothSettings( )