GPS Function

It is possible to take advantage of the functionality of a Global Positioning System (GPS) receiver when designing an application for use on either a laptop or tablet with a GPS receiver. Manipulating the GPS receiver is done from within the program's logic or by using one of the interactive GPS modes.

Basic Example

gps(open); // Android

gps(open, 3, 4800); // Windows (COM3, 4800 baud)

if gps(read, 15) then // attempt to read for up to 15 seconds
errmsg("Latitude is %f, longitude is %f", gps(latitude), gps(longitude));

else
errmsg("GPS signal could not be acquired");

endif;

gps(close);

Opening and Closing the GPS Receiver

b = gps(open);
b = gps(close);

Before using the device's GPS receiver, it is necessary to open a connection to the GPS unit. After making all necessary GPS readings, close the connection. The function returns 1 if successful, 0 otherwise. If using CSPro on a Windows laptop or tablet, it is necessary to specify the hardware settings of the GPS unit, specifically the number of the COM port and the baud rate (see the above example).

Obtaining the Last Successful GPS Reading

b = gps(readlast);

The readlast command obtains the last successful GPS reading, a reading that might be very old. If the GPS unit has been turned on for some time and the device is being used outdoors, it is likely that the reading is very fresh (recent), but if, for example, an enumerator walks inside a building to conduct an interview, the reading may be minutes or hours old, from the last time that the enumerator was outside. The function returns 1 if there was a successful previous reading, 0 otherwise.

Obtaining a New GPS Reading

b = gps(read);
b = gps(read, duration_in_seconds);
i = gps(read, duration_in_seconds, message);

The read command obtains a new GPS reading in a specified time period. The time period can be provided by supplying a numeric expression duration_in_seconds. If no time period is specified, the program will pause for up to three seconds to obtain a reading. A reading time of up to ten minutes (600 seconds) may be specified. An optional third argument, the string expression message, displays a message while the program attempts to obtain a GPS reading. The message box has a cancel button and if the user cancels the operation, the function returns -1. Otherwise the function returns 1 if a reading was successful, 0 otherwise. Unlike the readlast command, a successful function call with read guarantees a fresh GPS reading.

It is possible on Android devices to specify a desired level of accuracy for the reading. When specified, the function will continue to take GPS readings until a reading at or below the level of accuracy is achieved. The function will still return 1 if, though timing out, a successful reading at an accuracy level greater than specified was achieved during the allotted time period. This ensures that a GPS reading will be as accurate as possible, but with the assumption that any reading is better than no reading. Use a second numeric expression to specify the level of the accuracy.

b = gps(read, duration_in_seconds, accuracy);
i = gps(read, duration_in_seconds, message, accuracy);

Querying a Successful GPS Read

If the readlast or read commands returned successfully, the GPS system has valid values for latitude and longitude. Further attributes of the reading can be queried, though they are not guaranteed to be valid.

d = gps(latitude);
d = gps(longitude);
d = gps(altitude);
d = gps(satellites);
d = gps(accuracy);
d = gps(readtime);

Latitude and longitude return coordinates in degrees. Altitude returns the number of meters above sea level of the reading. Satellites returns the number of satellites used to calculate the values in the last reading. Generally, the greater number of satellites, the better the quality of the reading. Accuracy is a calculation of the precision of the last reading. On Windows devices, an accuracy value of 1 is the most accurate and 50 is the least accurate reading. On Android devices, the value signifies the accuracy of the reading, measured in meters. Readtime returns, in local time, the time of the last successful reading. If the queried value (other than latitude and longitude) is not available, or if the last GPS read was unsuccessful, the function will return default.

Calculating Distances

The gps function can also calculate great-circle distances between two sets of GPS coordinates. Great-circle calculations give a rough approximation of the distance between two points. The function returns the distance as measured in meters.

d = gps(distance, latitude1, longitude1, latitude2, longitude2);

For example:

numeric meters_to_census_bureau = gps(distance, 38.846261, -76.929445, gps(latitude), gps(longitude));

See also: Interactive GPS Modes