The iOS and Android engine can track the location, heading, acceleration and rotation of a device, if GPS, accelerometer and digital compass hardware are available. LiveCode commands can start, stop and capture relevant position and heading information that can then be used in your application.

From time to time, an iOS device may request to calibrate the compass hardware. LiveCode provides a feature to set the timeout for the calibration request or probe the current timeout value.

Note: This lesson assumes that your device has GPS, accelerometer and digital compass hardware.

Download the sample stack from this url: https://tinyurl.com/yc2uq5mm

Create a simple application interface, as is show in the figure of this section. The interface consists of eight buttons and a text field. The buttons control the activation of tracking location, heading, acceleration, rotation rate and the timeout settings. The text field displays the location, heading, acceleration, rotation rate and error information from the device.

You can select which sensor you would like to access by selecting the sensor option from the button that displays the label "Location". Selecting this button opens a combo box that provides a selection of sensors that can be accessed.

The stack card contains the following five message handlers that update the text field:

on rotationRateChanged
	put the params & return before field "log"
end rotationRateChanged

on locationChanged
	put the params & return before field "log"
end locationChanged

on headingChanged
	put the params & return before field "log"
end headingChanged

on accelerationChanged
	put the params & return before field "log"
end accelerationChanged

on trackingError
	put the params & return before field "log"
end trackingError

Button "Test for Support" tests whether or not the device provides support for the sensor selected by the top right button. The code on the button script is as follows:

on mouseUp
	if mobileSensorAvailable (the label of button "sensor") is true then
		answer the label of button "sensor" && "Tracking is Supported." with "Okay"
	else
		answer the label of button "sensor" && "Tracking is not Supported." with "Okay"
	end if
end mouseUp

This calls function mobileSensorAvailable() that returns either true or false. Depending on the name of the sensor type passed in to this function, the result may vary. Not all devices support all sensors that are accessible via LiveCode.

Button "Start Tracking" informs LiveCode that the selected sensor should start to collect data. The code of that button is as follows:

on mouseUp
	mobileStartTrackingSensor the label of button "sensor", the hilited of button "Loosely"
end mouseUp

Note: mobileStartTrackingSensor may request permission from the user to access the GPS hardware, depending on how the system preferences have been set up.

If location tracking cannot be started, either because device support is not available or because the user denied access to GPS information then a trackingError message is sent.

In this example, once the location is being tracked, LiveCode sends locationChanged messages to your stack, each time a change in location is detected.

Sensor tracking can be halted by selecting button "Stop Tracking", which has the following code:

on mouseUp
	mobileStopTrackingSensor the label of button "sensor"
end mouseUp

You can request sensor information directly, without having to process the changed messages. This is implemented under button "Get Current Reading" with the following code:

on mouseUp
	get mobileSensorReading(the label of button "sensor", true) 
	if it is an array then
		combine it using return and "="
	end if
	put "Current Reading" && it & return before field "log"
end mouseUp

mobileSensorReading ("location", true) returns an array with the following information:

• horizontal accuracy – The maximum error in meters of the position indicated by longitude and latitude.
• latitude – The latitude of the current location, measured in degrees relative to the equator. Positive values indicate positions in the Northern Hemisphere, negative values indicate positions in the Southern Hemisphere.
• longitude – The longitude of the current location, measured in degrees relative to the zero meridian. Positive values extend east of the meridian, negative values extend west of the meridian.
• vertical accuracy – The maximum error in meters of the altitude value.
• altitude – The distance in meters of the height of the device relative to sea-level. Positive values extend upward of sea-level, negative values downward.
• timestamp – the time at which the measurement was taken, in seconds since 1970.

Note: If the latitude and longitude could not be measured, then those keys, together with the horizontal accuracy key are not present. If the altitude could not be measured, then that key together with the vertical accuracy are not be present.

Select "Heading" from the top right button and then press button "Test for Support". This test whether your device supports heading data. Similarly, by selecting acceleration and rotation rate, you can test for the availability of the other sensor types.

Note: Digital compass support is only available in iOS 4.0 and later.

Button "Start Tracking", in conjunction with the selection of "Heading" informs LiveCode that heading information should be collected. The code of that button is as follows:

If heading tracking cannot be started, then the headingError message is sent.

Once the heading is being tracked, LiveCode sends headingChanged messages to your stack, each time a change in heading is detected.

Heading tracking can be halted by selecting button "Stop Tracking", that has the following code:

You can request heading information outside of the headingChanged messages that are sent when heading changes are detected. This is implemented under button "Get Current Reading".

mobileSensorReading ("heading", true) returns an array with the following information:

• accuracy – The maximum deviation (measured in degrees) between the reported heading and true geomagnetic heading. The lower the value, the more accurate the reading.
• magnetic heading – The heading (measured in degrees) relative to magnetic north.
• true heading – The heading (measured in degrees) relative to true north. If the true heading could not be calculated (usually due to location tracking not being enabled, or lack of calibration), then this key is not present.
• heading – The true heading, if available, otherwise the magnetic heading.
• x, y, z – The geomagnetic data (measured in microtesla) for each of the x, y, and z axes.
• timestamp – the time at which the measurement was taken, in seconds since 1970.

Note: In order to calculate the true heading, location tracking must be enabled simultaneously with heading tracking.

In addition to location and heading, LiveCode also supports acceleration and rotation rate.

The detailed reading for these sensors returns the following information:

mobileSensorReading ("acceleration", true) returns an array with the following information:

• x, y, z – The acceleration in for each of the x, y, and z axes.
• timestamp – the time at which the measurement was taken, in seconds since 1970.

mobileSensorReading ("rotation rate", true) returns an array with the following information:

• x, y, z – The change in rotation for each of the x, y, and z axes.
• timestamp – the time at which the measurement was taken, in seconds since 1970.

An iOS device may sometimes prompt the user to calibrate the magnetometer in order to provide reliable heading information. This feature is turned off by default and will not allow the user to be prompted, if a calibration may be required.

A timeout delay in seconds can be set using iphoneSetHeadingCalibrationTimeout. This allows the device to prompt the user to perform a calibration, should one be needed. If the timeout delay is set to 0, no calibration requests are permitted. Values greater than 0 specify the duration for which the calibration request prompt is displayed. The message is automatically dismissed, if the user does not respond to the message in the time set by the timeout.

The following code allows the user to set the timeout delay:

on mouseUp
	ask question "What Timeout do You want?" with "10" titled "Heading Calibration Timeout"
	if it is an integer then
		iphoneSetHeadingCalibrationTimeout it
	end if
end mouseUp

The value of the timeout delay can be returned using iphoneHeadingCalibrationTimeout().

on mouseUp
	local tResult
	put iphoneHeadingCalibrationTimeout() into tResult
	if tResult is a number then
		answer "Heading Calibration Timeout is set to:" && tResult with "Okay"
	else
		answer "No Heading Calibration Timeout available." with "Okay"
	end if
end mouseUp