Tech Note 32: Using the NSBiQueGPS Shared Library

June 6, 2004

 

Copyright 2004 Ron Glowka

Contents:

    Introduction
    Function Index and Quick Reference
    Function Reference

Introduction:

This library provides a wrapper for the Garmin iQue 3600 shared library for it's GPS functions.

In order to use the NSBiQueGPS Shared Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "NQG" for this reference name. Example:

Program's Startup code:

	Sub main()
	    LoadLibrary "NSBiQueGPS", "NQG"
	End Sub

Also, in order to use the NSBiQueGPS Shared Library, the NSBiQueGPS.INF file must be present in your "nsbasic\lib" directory and the NSBiQueGPS.prc file must be downloaded to your device.

Please be sure that your function return variables are dimensioned as the correct variable type. This library will return variable types of "Integer", "Double", or "String".

Function Index and Quick Reference:

    Version                   version = Version()
    CompileInfo               compileDateTime = CompileInfo()
    GPSLibLoaded              loaded = GPSLibLoaded()
    GPSGetLibAPIVersion       version = GPSGetLibAPIVersion()
    GPSClose                  GPSClose()
    GPSOpen                   status = GPSOpen()
    GPSGetMaxSatellites       maxSatellites = GPSGetMaxSatellites()
    GPSGetPosition            status = GPSGetPosition(lat, lon, altMSL, altWGS84)
    GPSGetPVT                 status = GPSGetPVT(mode, fix, epe, eph, epv, lat, lon, altMSL, altWGS84, east, north, up, track, speed, seconds, fracSeconds)
    GPSGetStatus              status = GPSGetStatus(mode, fix, epe, eph, epv)
    GPSGetTime                status = GPSGetTime(seconds, fracSeconds)
    GPSGetVelocity            status = GPSGetVelocity(east, north, up, track, speed)
    GPSGetSatellites          status = GPSGetSatellites(satellite, svid, statusBits, snr, azimuth, elevation)
    GetLatLonSemicircles      GetLatLonSemicircles lat, lon
    GetLatLonDegMin           GetLatLonDegMin lat, lon
    GetLatLonDegMinSec        GetLatLonDegMinSec lat, lon
    GetErrString              errString = GetErrString(status)
    GetModeString             modeString = GetModeString(mode)
    GetFixString              fixString = GetFixString(fix)
    GetSatStatusValues        GetSatStatusValues statusBits, ephemeris, differential, used, rising
    ConvertDouble             convertedValue = ConvertDouble(originalValue, conversionType)
    LatLonToUTM               zone = LatLonToUTM(datumID, lat, lon, easting, northing)
    UTMToLatLon               UTMToLatLon datumID, zone, easting, northing, lat, lon
    UTMDistance               distance = UTMDistance(zone1, easting1, northing1, zone2, easting2, northing2, ewDir, ewDist, nsDir, nsDist)
    PwrSetLowPowerMode        status = PwrSetLowPowerMode(creatorID, enabled)
    RegisterNotifyEvents      RegisterNotifyEvents locationChange, statusChange, lostFix, satDataChange, modeChange, displayResized
    WinGetDisplayExtent       WinGetDisplayExtent x, y
    WinSetDisplayExtent       WinSetDisplayExtent size
    FrmGetDIAPolicy           value = FrmGetDIAPolicy()
    FrmSetDIAPolicy           FrmSetDIAPolicy value
    PINGetDIAState            value = PINGetDIAState()
    PINSetDIAState            PINSetDIAState value
    PINGetInputTriggerState   value = PINGetInputTriggerState()
    PINSetInputTriggerState   PINSetInputTriggerState value

NSBiQueGPS Function Reference:

Version

	version = NSBiQueGPS.Version()
Returns the version number of the NSBiQueGPS Shared Library.
Returns:
	version as Double
Example:
	Dim version as Double
	
	version = NQG.Version()

CompileInfo

	compileDateTime = NSBiQueGPS.CompileInfo()
Returns the date and time that the NSBiQueGPS was compiled.
Returns:
	compileDateTime as String
Example:
	Dim compileDateTime as String
	
	compileDateTime = NQG.CompileInfo()

GPSLibLoaded

	loaded = NSBiQueGPS.GPSLibLoaded()
Check to see if the Garmin iQue GPS shared library is loaded and open.
Returns:
	loaded as Integer
	       1 - the library is loaded and open and is ready to use.
	       0 - the library is not loaded and no GPS functions should
	           be called except for the GPSOpen() function.
Example:
	Dim loaded as Integer
	
	loaded = NQG.GPSLibLoaded()
This function should always be called and the value returned should always be 1 before any other functions, except Version () or CompileInfo(), in this library are called.

GPSGetLibAPIVersion

	version = NSBiQueGPS.GPSGetLibAPIVersion()
Returns the Garmin iQue Shared Library API Version number. If the Garmin iQue Shared Library is not loaded, the return value will be -1.
Returns:
	version as Integer
Example:
	Dim version as Integer
	
	version = NQG.GPSGetLibAPIVersion()

GPSClose

	NSBiQueGPS.GPSClose()
Explicity close the GPS library. (See Notes)
Example:
	
	NQG.GPSClose()
Normally, the GPS library is automatically closed when the NSBasic program gets terminated. The GPSOpen() function must be called before any other GPS library functions are called after the GPS library has been closed.

GPSOpen

	status = NSBiQueGPS.GPSOpen()
Explicity open the GPS library. (See Notes)
Returns:
	status as Integer
	       1 if the library was opened succussfully.
	       0 if the library could not be loaded or opened.
Example:
	Dim status as Integer
	
	status = NQG.GPSOpen()
Normally, the GPS library is automatically opened when the NSBasic program loads this library. This function function must be called before any other GPS library functions are called after the GPS library has been closed.

GPSGetMaxSatellites

	maxSatellites = NSBiQueGPS.GPSGetMaxSatellites()
Get the maximum number of satellites that are currently supported.
Returns:
	maxSatellites as Integer
	       -1 if the Garmin iQue shared libary is not loaded and open.
	       nbr, the maximum number of satellites currently supported.
Example:
	Dim maxSatellites as Integer
	
	maxSatellites = NQG.GPSGetMaxSatellites()

GPSGetPosition

	status = NSBiQueGPS.GPSGetPosition(lat, lon, altMSL, altWGS84)
Get current position data.
Parameters:
	lat as Double (output parameter)
	        lat - latitude in degrees

	lon as Double (output parameter)
	        lon - longitude in degrees

	altMSL as Double (output parameter)
	        altMSL - altitude above mean sea level (meters)

	altWGS84 as Double (output parameter)
	        altWGS84 - altitude above WGS84 ellipsoid (meters)
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
Example:
	Dim status as Integer
	Dim lat as Double
	Dim lon as Double
	Dim altMSL as Double
	Dim altWGS84 as Double
	Dim errString as String
	
	status = NQG.GPSGetPosition(lat, lon, altMSL, altWGS84)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetPosition error = " + errString
	End If

GPSGetPVT

	status = NSBiQueGPS.GPSGetPVT(mode, fix, epe, eph, epv, lat, lon, altMSL, altWGS84, east, north, up, track, speed, seconds, fracSeconds)
Get current position, velocity, and time data.
Parameters:
	mode as Integer (output parameter)
	       mode - mode type.  Values returned are:
	           0 = gpsModeOff - GPS is off
	           1 = gpsModeNormal - continuous satellite tracking
	           2 = gpsModeBatSaver - periodic satellite tracking
	           3 = gpsModeSim - simulated GPS information
	           4 = gpsModeExternal - external source of GPS information

	fix as Integer (output parameter)
	       fix - fix type.  Values returned are:
	           0 = gpsFixUnusable - failed integrity check
	           1 = gpsFixInvalid - invalid or unavailable
	           2 = gpsFix2D - 2 dimension
	           3 = gpsFix3D - 3 dimension
	           4 = gpsFix2DDiff - 2 dimension differential
	           5 = gpsFix3DDiff - 3 dimension differential

	epe as Double (output parameter)
	       epe - estimated position error, 1-sigma (meters)

	eph as Double (output parameter)
	       eph - epe, horizontal only (meters)

	epv as Double (output parameter)
	       epv - epe, vertical only (meters)

	lat as Double (output parameter)
	       lat - latitude in degrees

	lon as Double (output parameter)
	       lon - longitude in degrees

	altMSL as Double (output parameter)
	       altMSL - altitude above mean sea level (meters)

	altWGS84 as Double (output parameter)
	       altWGS84 - altitude above WGS84 ellipsoid (meters)

	east as Double (output parameter)
	       east - east (m/s)

	north as Double (output parameter)
	       north - north (m/s)

	up as Double (output parameter)
	       up - upwards (m/s)

	track as Double (output parameter)
	       track - track (radians)

	speed as Double (output parameter)
	       speed - speed, horizontal only (m/s)

	seconds as Integer (output parameter)
	       seconds - seconds since midnight (UTC)

	fracSeconds as Integer (output parameter)
	       fracSeconds - 0..1 second *2^32
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
Example:
	Dim status as Integer
	Dim mode as Integer
	Dim fix as Integer
	Dim epe as Double
	Dim eph as Double
	Dim epv as Double
	Dim lat as Double
	Dim lon as Double
	Dim altMSL as Double
	Dim altWGS84 as Double
	Dim east as Double
	Dim north as Double
	Dim up as Double
	Dim track as Double
	Dim speed as Double
	Dim seconds as Integer
	Dim fracSeconds as Integer
	Dim errString as String
	
	status = NQG.GPSGetPVT(mode, fix, epe, eph, epv, lat, lon, altMSL, altWGS84, east, north, up, track, speed, seconds, fracSeconds)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetPVT error = " + errString
	End If

GPSGetStatus

	status = NSBiQueGPS.GPSGetStatus(mode, fix, epe, eph, epv)
Get current status data.
Parameters:
	mode as Integer (output parameter)
	       mode - mode type.  Values returned are:
	           0 = gpsModeOff - GPS is off
	           1 = gpsModeNormal - continuous satellite tracking
	           2 = gpsModeBatSaver - periodic satellite tracking
	           3 = gpsModeSim - simulated GPS information
	           4 = gpsModeExternal - external source of GPS information

	fix as Integer (output parameter)
	       fix - fix type.  Values returned are:
	           0 = gpsFixUnusable - failed integrity check
	           1 = gpsFixInvalid - invalid or unavailable
	           2 = gpsFix2D - 2 dimension
	           3 = gpsFix3D - 3 dimension
	           4 = gpsFix2DDiff - 2 dimension differential
	           5 = gpsFix3DDiff - 3 dimension differential

	epe as Double (output parameter)
	       epe - estimated position error, 1-sigma (meters)

	eph as Double (output parameter)
	       eph - epe, horizontal only (meters)

	epv as Double (output parameter)
	       epv - epe, vertical only (meters)
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
Example:
	Dim status as Integer
	Dim mode as Integer
	Dim fix as Integer
	Dim epe as Double
	Dim eph as Double
	Dim epv as Double
	Dim errString as String
	
	status = NQG.GPSGetStatus(mode, fix, epe, eph, epv)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetStatus error = " + errString
	End If

GPSGetTime

	status = NSBiQueGPS.GPSGetTime(seconds, fracSeconds)
Get current time data.
Parameters:
	seconds as Integer (output parameter)
	       seconds - seconds since midnight (UTC)

	fracSeconds as Integer (output parameter)
	       fracSeconds - 0..1 second *2^32
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
Example:
	Dim status as Integer
	Dim seconds as Integer
	Dim fracSeconds as Integer
	Dim errString as String
	
	status = NQG.GPSGetTime(seconds, fracSeconds)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetTime error = " + errString
	End If

GPSGetVelocity

	status = NSBiQueGPS.GPSGetVelocity(east, north, up, track, speed)
Get current velocity data.
Parameters:
	east as Double (output parameter)
	       east - east (m/s)

	north as Double (output parameter)
	       north - north (m/s)

	up as Double (output parameter)
	       up - upwards (m/s)

	track as Double (output parameter)
	       track - track (radians)

	speed as Double (output parameter)
	       speed - speed, horizontal only (m/s)
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
Example:
	Dim status as Integer
	Dim east as Double
	Dim north as Double
	Dim up as Double
	Dim track as Double
	Dim speed as Double
	Dim errString as String
	
	status = NQG.GPSGetVelocity(east, north, up, track, speed)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetVelocity error = " + errString
	End If

GPSGetSatellites

	status = NSBiQueGPS.GPSGetSatellites(satellite, svid, statusBits, snr, azimuth, elevation)
Get current satellite data for the indicated satellite.
Parameters:
	satellite as Integer (input parameter)
	       satellite - (1..maxSatellites)

	svid as Integer (output parameter)
	       svid - space vehicle identifier

	statusBits as Integer (output parameter)
	       status bitfield
	           bit 0 (bitmask 1) = gpsSatEphMask (ephemeris mask)
	           bit 1 (bitmask 2) = gpsSatDifMask (differential mask)
	           bit 2 (bitmask 4) = gpsSatUsedMask (used in solution mask)
	           bit 3 (bitmask 8) = gpsSatRisingMask (rising mask)
	           Note:  The GetSatStatusValues() in this library can be
	                  used to retrieve these individual bit values.

	snr as Integer (output parameter)
	       snr - signal to noise ratio *100 (dB Hz)

	azimuth as Double (output parameter)
	       azimuth - azimuth (radians)

	elevation as Double (output parameter)
	       elevation - elevation (radians)
Returns:
	status as Integer
	       0 = gpsErrNone
	           If the return status is not gpsErrNone (0), the data
	           should be considered invalid.
	       32769 = gpsErrNotOpen
	       32770 = gpsErrStillOpen
	       32771 = gpsErrMemory
	       32772 = gpsErrNoData
	       -1 = GPSGetMaxSatellites() returned <= 0
Example:
	Dim status as Integer
	Dim satellite as Integer
	Dim svid as Integer
	Dim statusBits as Integer
	Dim snr as Integer
	Dim azimuth as Double
	Dim elevation as Double
	Dim errString as String
	
	status = NQG.GPSGetSatellites(satellite, svid, statusBits, snr, azimuth, elevation)
	If status <> 0 Then
	    errString = NQG.GetErrString(status)
	    MsgBox "GPSGetSatellites error = " + errString
	End If

GetLatLonSemicircles

	NSBiQueGPS.GetLatLonSemicircles lat, lon
Return the latitude and longitude as expressed in semicircles (not degrees). The return values from the Garmin library's GPSGetPosition() and GPSGetPVT() functions actually return latitude and longitude as expressed in semicircles - not degrees. Except for this function, the other functions in this library convert latitude and longitude to degrees. This function retrieves the raw values returned from the Garmin Library's GPSGetPosition() and GPSGetPVT() functions.

The Garmin iQue 3600 Shared Library .h files documents the following:

GPS Position Data Type

The GPSPositionDataType uses integers to indicate latitude and longitude in semicircles, where 2^31 semicircles equals 180 degrees. North latitudes and East longitudes are indicated with positive numbers; South latitudes and West longitudes are indicated with negative numbers. The following formulas show how to convert between degrees and semicircles:

degrees = semicircles * ( 180 / 2^31 )

This is the equation used by this library for converting from semicircles to degrees.
Parameters:
	lat as Integer (output parameter)
	       lat - latitude in semicircles

	lon as Integer (output parameter)
	       lon - longitude in semicircles
Example:
	Dim lat as Integer
	Dim lon as Integer

	NQG.GetLatLonSemicircles lat, lon

GetLatLonDegMin

	NSBiQueGPS.GetLatLonDegMin lat, lon
Return the last retrieved latitude and longitude as expressed in degrees and minutes (not decimal degrees).

Example: W097°08.957880'

Parameters:
	lat as String (output parameter)
	       lat - latitude in degrees and minutes

	lon as String (output parameter)
	       lon - longitude in degrees and minutes
Example:
	Dim lat as String
	Dim lon as String

	NQG.GetLatLonDegMin lat, lon

GetLatLonDegMinSec

	NSBiQueGPS.GetLatLonDegMinSec lat, lon
Return the last retrieved latitude and longitude as expressed in degrees, minutes, and seconds (not decimal degrees).

Example: W097°08'57.472844"

Parameters:
	lat as String (output parameter)
	       lat - latitude in degrees, minutes, and seconds

	lon as String (output parameter)
	       lon - longitude in degrees, minutes, and seconds
Example:
	Dim lat as String
	Dim lon as String

	NQG.GetLatLonDegMinSec lat, lon

GetErrString

	errString = NSBiQueGPS.GetErrString(status)
Returns a string interpretation of the passed status value.
Parameter:
	status as Integer (input parameter)
	       result status returned from a library call
Returns:
	errString as String
	       "badCreatorID" if status is -2
	       "failure" if status is -1
	       "success" if status is gpsErrNone (0)
	       "gpsErrNotOpen" if status is gpsErrNotOpen (32769)
	       "gpsErrStillOpen" if staus is gpsErrStillOpen (32770)
	       "gpsErrMemory" if status is gpsErrMemory (32771)
	       "gspErrNoData" if status is gpsErrNoData (32772)
Example:
	Dim errString as String
	Dim status as Integer

	errString = NQG.GetErrString(status)

GetModeString

	modeString = NSBiQueGPS.GetModeString(mode)
Returns a string interpretation of the passed status mode value.
Parameter:
	mode as Integer (input parameter)
	       mode value returned from GPSGetStatus() or GPSGetPVT()
Returns:
	modeString as String
	       "Off" when mode is gpsModeOff (0)
	       "Continuous" when mode is gpsModeNormal (1)
	       "Periodic" when mode is gpsModeBatSaver (2)
	       "Simulated" when mode is gpsModeSim (3)
	       "External" when mode is gpsModeExternal (4)
Example:
	Dim modeString as String
	Dim mode as Integer

	modeString = NQG.GetModeString(mode)

GetFixString

	fixString = NSBiQueGPS.GetFixString(fix)
Returns a string interpretation of the passed status fix value.
Parameter:
	fix as Integer (input parameter)
	       fix value returned from GPSGetStatus() or GPSGetPVT()
Returns:
	fixString as String
	       "Unusable" when fix is gpsFixUnusable (0)
	       "Invalid" when fix is gpsFixInvalid (1)
	       "2D" when fix is gpsFix2D (2)
	       "3D" when fix is gpsFix3D (3)
	       "2DDiff" when fix is gspFix2DDiff (4)
	       "3DDiff" when fix is gspFix3DDiff (5)
Example:
	Dim fixString as String
	Dim fix as Integer

	fixString = NQG.GetFixString(fix)

GetSatStatusValues

	NSBiQueGPS.GetSatStatusValues statusBits, ephemeris, differential, used, rising
Returns the value of each of the status bitfield bits returned by the GPSGetSatellites() function.
Parameters:
	statusBits as Integer (input parameter)

	ephemeris as Integer (output parameter)
	       returns 1 if the "ephemeris" bit is set, otherwise 0

	differential as Integer (output parameter)
	       returns 1 if the "differential" bit is set, otherwise 0

	used as Integer (output parameter)
	       returns 1 if the "used in solution bit" is set,
	           otherwise 0

	rising as Integer (output parameter)
	       returns 1 if the "rising" bit is set, otherwise 0
Example:
	Dim statusBits as Integer
	Dim ephemeris as Integer
	Dim differential as Integer
	Dim used as Integer
	Dim rising as Integer

	NQG.GetSatStatusValues statusBits, ephemeris, differential, used, rising

ConvertDouble

	convertedValue = NSBiQueGPS.ConvertDouble(originalValue, conversionType)
Returns a converted value based on the passed conversionType.
Parameters:
	originalValue as Double (input parameter)
	       original value

	conversionType as Integer (input parameter)
	        1 = meters to inches
	        2 = meters to feet
	        3 = meters to miles
	        4 = kilometers to miles
	        5 = meters per second to miles per hour
	        6 = meters per second to kilometers per hour
	        7 = inches to meters
	        8 = feet to meters
	        9 = miles to meters
	       10 = miles to kilometers
	       11 = miles per hour to meters per second
	       12 = kilometers per hour to meters per second
Returns:
	convertedValue as Double
	       converted value
Example:
	Dim convertedValue as Double
	Dim originalValue as Double
	Dim conversionType as Integer

	convertedValue = NQG.ConvertDouble(originalValue, conversionType)

LatLonToUTM

	zone = NSBiQueGPS.LatLonToUTM(datumID, lat, lon, easting, northing)
Converts latitude and longitude to UTM (Universal Transverse Mercator) coordinates. The accuracy of the conversion, when compared to another source such as a map, depends on the "datum" (set of parameters) used by the other source. The following table shows the ID and parameters that can be used for converting lat/lon to UTM coordinates. ID 0 is probably the best datum to use if you don't have a reference to another specific datum.

IDDatum Equatorial Radius, metersEccentricity Squared
0WGS-84, GRS 1980, NAD83 63781370.00669438
1Everest 63772760.006637847
2Modified Everest 63773040.006637847
3Modified Airy 63773400.00667054
4Bessel 1841 63773970.006674372
5Bessel 1841 (Nambia) 63774840.006674372
6Airy 63775630.00667054
7WGS-72 63781350.006694318
8WGS-84, GRS 1980, NAD83 63781370.00669438
9WGS 66 63781450.006694542
10Fischer 1968 63781500.006693422
11Modified Fischer 1960 63781550.006693422
12Australian National, South American 1969, GRS 1967 63781600.006694542
13WGS 60 63781650.006693422
14Fischer 1960 (Mercury) 63781660.006693422
15Helmert 1906 63782000.006693422
16Clarke 1866 63782060.006768658
17Krassovsky 63782450.006693422
18Clarke 1880 63782490.006803511
19Hough 63782700.00672267
20International 63783880.00672267
Parameters:
	datumID as Integer (input parameter)
	       see the description and datum table above

	lat as Double (input parameter)
	       latitude in decimal degrees

	lon as Double (input parameter)
	       longitude in decimal degrees

	easting as Double (output parameter)
	       UTM "easting" coordinate
	           -1 is returned if MathLib is not available.

	northing as Double (output parameter)
	       UTM "northing" coordinate
	           -1 is returned if MathLib is not available.
Returns:
	zone as String
	       UTM "zone" identifier
	           An empty string ("") if the datumID is invalid.
	       
	           The last character of the zone id is an indicator of the
	           coordinate's hemisphere.  With the exception of "Z", if
	           it is "N" or greater, the coordinate is in the northern
	           hemisphere.  Less than "N", the coordinate is in
	           the southern hemisphere.  If the last character is "Z",
	           the coordinate is outside the UTM limits of latitude
	           84°N and 80°S
Example:
	Dim zone as String
	Dim datumID as Integer
	Dim lat as Double
	Dim lon as Double
	Dim easting as Double
	Dim northing as Double

	zone = NQG.LatLonToUTM(datumID, lat, lon, easting, northing)

UTMToLatLon

	NSBiQueGPS.UTMToLatLon datumID, zone, easting, northing, lat, lon
Converts UTM (Universal Transverse Mercator) coordinates to latitude and longitude. The accuracy of the conversion, when compared to another source such as a map, depends on the "datum" (set of parameters) used by the other source. Please see the LatLonToUTM() function for a list and description of the datums supported. ID 0 is probably the best datum to use if you don't have a reference to another specific datum.

Parameters:
	datumID as Integer (input parameter)
	       see the description and datum table described for the
	           LatLonToUTM() function

	zone as String (input parameter)
	       UTM "zone" identifier

	easting as Double (input parameter)
	       UTM "easting" coordinate

	northing as Double (input parameter)
	       UTM "northing" coordinate

	lat as Double (output parameter)
	       latitude in decimal degrees
	           -1 is returned if MathLib is not available or the
	           datumID is invalid.

	lon as Double (output parameter)
	       longitude in decimal degrees
	           -1 is returned if MathLib is not available or the
	           datumID is invalid.
Example:
	Dim datumID as Integer
	Dim zone as String
	Dim easting as Double
	Dim northing as Double
	Dim lat as Double
	Dim lon as Double

	NQG.UTMToLatLon datumID, zone, easting, northing, lat, lon

UTMDistance

	distance = NSBiQueGPS.UTMDistance(zone1, easting1, northing1, zone2, easting2, northing2, ewDir, ewDist, nsDir, nsDist)
Returns the distances between two UTM coordinates.
Parameters:
	zone1 as String (input parameter)
	       UTM 1's zone

	easting1 as Double (input parameter)
	       UTM 1's easting coordinate

	northing1 as Double (input parameter)
	       UTM 1's northing coordinate

	zone2 as String (input parameter)
	       UTM 2's zone

	easting2 as Double (input parameter)
	       UTM 2's easting coordinate

	northing2 as Double (input parameter)
	       UTM 2's northing coordinate

	ewDir as String (output parameter)
	       returns "E" if UTM 2 is east of UTM 1, otherwise the
	           return value is "W"

	ewDist as Double (output parameter)
	       east/west distance in meters

	nsDir as String (output parameter)
	       returns "N" if UTM 2 is north of UTM 1, otherwise the
	           return value is "S"

	nsDist as Double (output parameter)
	       north/south distance in meters
Returns:
	distance as Double
	       straight line distance between UTM 1 and UTM 2 in meters
	          returns -1.0 if zone1 and zone2 are not equal.
Example:
	Dim distance as Double
	Dim zone1 as String
	Dim easting1 as Double
	Dim northing1 as Double
	Dim zone2 as String
	Dim easting2 as Double
	Dim northing2 as Double
	Dim ewDir as String
	Dim ewDist as Double
	Dim nsDir as String
	Dim nsDist as Double

	distance = NQG.UTMDistance(zone1, easting1, northing1, zone2, easting2, northing2, ewDir, ewDist, nsDir, nsDist)
This function can only calculate distances between UTM coordinates if they are in the same zone.

PwrSetLowPowerMode

	status = NSBiQueGPS.PwrSetLowPowerMode(creatorID, enabled)
Set or unset the LowPowerMode of the Garmin iQue 3600 device. The Garmin SDK has this to say about "LowPowerMode":

"Low Power Mode:

When the iQue 3600 enters low power mode, the display and backlight are turned off, while the processor, GPS, and audio continue to operate normally. Low power mode can be used to extend the battery life while continuing to allow the unit to execute applications, such as an audio player. If any application has enabled low power mode, while the auto-off time has expired the iQue 3600 will enter low power mode instead of powering off. Low power mode is indicated by the LED blinking briefly approximately every 10 seconds. Note that low power mode uses substantially more battery power than allowing the unit to power off.

If an application desires to have the iQue 3600 enter low power mode when the auto-off time has expired, the application should enable low power mode. Low power mode will stay enabled until your application disables it; therefore it is extremely important that your application disables low power mode when it no longer needs to be enabled. Note that if your application disables low power mode it does not guarantee that the unit will power off, as another application could also have low power mode enabled; however if your application enables low power mode, it does guarantee that the unit will enter low power mode and will not power off."


NOTE: Unless the enable parameter is 2, this library will automatically disable the Low Power Mode setting for the last creator ID specified when this library is closed (ie. when the NSBasic program exits). It is still important however, that the correct actual creator Id of the NSBasic program is used for this function.

This function only works on Palm OS software v.5.2.1r3 or higher. To update your Garmin device, visit https://www.garmin.com/support/download.jsp and choose the software updates for the iQue 3600.
Parameters:
	creatorID as String (input parameter)
	       4 character creator ID of the NSBasic program

	enabled as Integer (input parameter)
	       0 = disable
	       1 = enable
	       2 = enable, but don't disable when this library closes
Returns:
	status as Integer
	       -2 if the creator ID is less than 4 characters
	       -1 if the Power Manager library couldn't be loaded
	       0 if unsuccessful for some other reason
	       1 if successful
Example:
	Dim status as Integer
	Dim creatorID as String
	Dim enabled as Integer
	
	creatorID = "Nigt"    'NSBiQueGPS_Test creator ID
	enabled = 1
	status = NQG.PwrSetLowPowerMode(creatorID, enabled)

RegisterNotifyEvents

	NSBiQueGPS.RegisterNotifyEvents locationChange, statusChange, lostFix, satDataChange, modeChange, displayResized
Register with the Notification Manager to be notified when the sysNotifyGPSDataEvent or sysNotifyDisplayResizedEvent events occur. When they do occur, an event for the specific type of notification will be generated. The parameters for this function specify the event number to generate. A value of 0 disables event notification for that specific notification type. Parameter values should typically be in the custom event number range (24576 to 32767). These events can be "caught" with the NSBasic GetEventType() function.
Parameters:
	locationChange as Integer (input parameter)
	       event number for gpsLocationChange - The GPS position has changed.

	statusChange as Integer (input parameter)
	       event number for gpsStatusChange - The GPS status has changed.

	lostFix as Integer (input parameter)
	       event number for gpsLostFix  - The quality of the GPS position
	                                      computation has become less than
	                                      two dimensional.

	satDataChange as Integer (input parameter)
	       event number for gpsSatDataChange - The GPS satellite data has
	                                           changed.

	modeChange as Integer (input parameter)
	       event number for gpsModeChange - The GPS mode has changed.

	displayResized as Integer (input parameter)
	       event number for sysNotifyDisplayResizedEvent - The display has
	                                                       been resized.
Example:
	Sub Form1223_After()
	
	    'Register to have the following events generated:
	    '   event number 30001 - location change
	    '   event number 30002 - status change
	    '   event number 30003 - lost fix
	    '   event number 30004 - satellite data change
	    '   event number 30005 - mode change
	    '   event number 30006 - display was resized
	
	    NQG.RegisterNotifyEvents 30001, 30002, 30003, 30004, 30005, 30006
	End Sub
	
	
	Sub Form1239_Event()
	    Dim event as Integer
	
	    event = GetEventType()
	    Select Case event
	        Case 30001
	            fldLocationChange.text = str(val(fldLocationChange.text) + 1)
	        Case 30002
	            fldStatusChange.text = str(val(fldStatusChange.text) + 1)
	        Case 30003
	            fldLostFix.text = str(val(fldLostFix.text) + 1)
	        Case 30004
	            fldSatDataChange.text = str(val(fldSatDataChange.text) + 1)
	        Case 30005
	            fldModeChange.text = str(val(fldModeChange.text) + 1)
	        Case 30006
	            fldDisplayResized.text = str(val(fldDisplayResized.text) + 1)
	    End Select
	End Sub

WinGetDisplayExtent

	NSBiQueGPS.WinGetDisplayExtent x, y
Return the current width and height of the display.
Parameters:
	x as Integer (output parameter)

	y as Integer (output parameter)
Example:
	Dim x as Integer
	Dim y as Integer

	NQG.WinGetDisplayExtent x, y

WinSetDisplayExtent

	NSBiQueGPS.WinSetDisplayExtent size
Sets the display width and height to either normal or large. If the size is large, the form's Dynamic Input Area (DIA) Policy, Input Trigger, and Dynamic Input Area values will be set to custom, enabled, and closed respectively.
Parameter:
	size as Integer (input parameter)
	       0 = normal - 160 pixels wide x 160 pixels high
	       1 = large - 160 pixels wide x 225 pixels high
Example:
	Dim size as Integer

	NQG.WinSetDisplayExtent size

FrmGetDIAPolicy

	value = NSBiQueGPS.FrmGetDIAPolicy()
Returns the form's current Dynamic Input Area (DIA) Policy. The DIA Policy controls whether the graffiti input area may be collapsed or not.
Returns:
	value as Integer
	       0 - frmDIAPolicyStayOpen.  The graffiti input area
	                                  is always open.  It cannot
	                                  be collapsed.
	       1 - frmDIAPolicyCustom.  The graffiti input area is
	                                collapsable.
	       -1 - error.  The Pen Input Manager is not present on device.
Example:
	Dim value as Integer

	value = NQG.FrmGetDIAPolicy()

FrmSetDIAPolicy

	NSBiQueGPS.FrmSetDIAPolicy value
Sets the form's Dynamic Input Area (DIA) Policy. The DIA Policy controls whether the graffiti input area may be collapsed or not.
Parameter:
	value as Integer (input parameter)
	       0 - frmDIAPolicyStayOpen.  The graffiti input area
	                                  is always open.  It cannot
	                                  be collapsed.
	       1 - frmDIAPolicyCustom.  The graffiti input area is
	                                collapsable.
Example:
	Dim value as Integer

	NQG.FrmSetDIAPolicy value

PINGetDIAState

	value = NSBiQueGPS.PINGetDIAState()
Returns the current Dynamic Input Area (DIA) state.
Returns:
	value as Integer
	       0 - pinInputAreaOpen.  The Dynamic Input Area is displayed.
	       1 - pinInputAreaClosed.  The Dynamic Input Area is not
	                                being displayed.
	       2 - pinInputAreaNone.  There is no Dynamic Input Area.
	       -1 - error.  The Pen Input Manager is not present on device.
Example:
	Dim value as Integer

	value = NQG.PINGetDIAState()

PINSetDIAState

	NSBiQueGPS.PINSetDIAState value
Sets the current Dynamic Input Area (DIA) state.
Parameter:
	value as Integer (input parameter)
	       0 - pinInputAreaOpen.  The Dynamic Input Area will be displayed.
	       1 - pinInputAreaClosed.  The Dynamic Input Area will not
	                                be displayed.
	       2 - pinInputAreaNone.  There is no Dynamic Input Area.
Example:
	Dim value as Integer

	NQG.PINSetDIAState value

PINGetInputTriggerState

	value = NSBiQueGPS.PINGetInputTriggerState()
Returns the current Input Trigger state.
Returns:
	value as Integer
	       0 - pinInputTriggerEnabled.   The status bar icon is enabled,
	                                     meaning that the user is allowed
	                                     to open and close the Dynamic
	                                     Input Area.
	       1 - pinInputTriggerDisabled.  The status bar icon is disabled,
	                                     meaning that the user is not
	                                     allowed to open and close the
	                                     Dynamic Input Area.
	       2 - pinInputTriggerNone.   There is no Dynamic Input Area.
	       -1 - error.  The Pen Input Manager is not present on device.
Example:
	Dim value as Integer

	value = NQG.PINGetInputTriggerState()

PINSetInputTriggerState

	NSBiQueGPS.PINSetInputTriggerState value
Sets the current Input Trigger state.
Parameter:
	value as Integer (input parameter)
	       0 - pinInputTriggerEnabled.   Enable the status bar icon,
	                                     meaning that the user is allowed
	                                     to open and close the Dynamic
	                                     Input Area.
	       1 - pinInputTriggerDisabled.  Disable the status bar icon,
	                                     meaning that the user is not
	                                     allowed to open and close the
	                                     Dynamic Input Area.
	       2 - pinInputTriggerNone.   There is no Dynamic Input Area.
Example:
	Dim value as Integer

	NQG.PINSetInputTriggerState value