====== Introduction ====== This is a description of the XML format used to save GPS device preferences. The format is an extension of early work done by George Wang on the desktop with additions to support needs by the AGTEK Android technology platform (AGTEK_Lib/Location Manager). Typically the items stored in these preferences are parameters used by applications to initialize GPS devices. These parameters are those values which seldom change and are specific to a device. This file also contains information about the last used device, allowing applications to automatically choose the correct device upon startup. The structure needs to accommodate the following: * Uniquely identify a device instance, typically via Bluetooth mac address * Support non Bluetooth devices (Android has a few, e.g. "builtin") * Support human friendly naming for a device (e.g. "Bob's G-Ray") * Keep the type associated with the device (e.g. "Topcon") * Be portable between applications (i.e. XML) ===== Example Format ===== The following example illustrates a simple device preference file.




	
		00:10:C6:2F:07
	

	
		00:03:7A:69:43:4C
	

	
		
		13

		
		
			*99***1#
			ISPDA@CINGULAR.COM
			CINGULAR1
			tps
			0000
			isp.cingular
		

		
		
		
			dev/tcp/a

12.107.178.211
			8008
			EricI
			EricI

			
			NETWORK_RTK_CMR+_GG

			
			10
		

		
                
		
                   cmr

===== Device Types ===== The following device types are recognized by this format. Device types match those values used in the [[GPX Extensions]] spec. Valid provider names are: * AltusAPS3 * AltusAPS3Cell * Leica * LeicaCell * Topcon * TopconCell * NMEA (non RTK quality). * Builtin (functionally equivalent to an NMEA device, not RTK quality, supplied natively on some mobile platforms). * Playback - AKA Simulation for playing back GPX files. * Unknown - Placeholder type allowing unconfigured devices to be remembered. Applications are free to ignore these, or present them to the user so they can be configured. ===== Device Entries ===== Each entry for a device is tagged by the type of the device. In the example shown earlier, the only device is a TOPCON device. A device entry must contain the type tag and "id" attribute. The id is required, and must be unique within the file and associated with the device. For Bluetooth devices the id must be Bluetooth mac address. The name is optional, and may be supplied from a variety of sources, but is intended to be used for UI presentation to the user. The name, in most cases, comes from a human. If the name is not present, the application should compose a reasonable name dynamically. An example of a device listing tag for the Topcon looks like:

Here the unique id and name are evident. Device specific parameters are enclosed between and tags. In this example they are enclosed by and . Some devices may have no parameters at all and they would have an empty list between the tags (e.g. "Built-in"). Each of the following exception lists the device parameters, if any. ==== AltusAPS3 ==== * RADIO * - Boolean, if true configure the UHF radio, otherwise do not configure the radio * - The radio channel to use (if the radio is configured) * USE * - Boolean, if true use GLONASS satellites for solutions, otherwise only use GPS ==== AltusAPS3Cell ==== * GPRS - PPP/Internet connection parameters * - User id to establish connection * - User password to establish connection * - E.g. isp.congular * NTRIP Caster parameters *

- IP Address of NTRIP server, e.g. 12.107.178.211, or [[FQDN]] * - TCP port, e.g. 8008 * - NTRIP user ID for authentication * - NTRIP password for authentication * - NTRIP defined mount point * - List of mount points. Each MP is a pair of "display string"/"mount name" * E.G: RTCM3_MAX/RTCM3_MAX,RTCM3_IMAX/RTCM3_IMAX,RTCM3_NEAR/RTCM3_NEAR,RTCM3_ViRS/RTCM3_ViRS * - Integer period of NTRIP NMEA updates ==== Leica ==== ==== LeicaCell ==== NB: (mja) I've not analyzed these parameters yet to bring them into compliance with Topcon * * * * * * * * * * * * * * * ==== NMEA ==== Reference NMEA 0183 standard. This device type has no additional parameters. ==== Built-In ==== There are no additional parameters for this device type. ==== Playback ==== This represents a GPX read which will provide location updates in lieu of an actual RTK device. See format for more information on the structure of the GPX files. The file parameter is a path to the file and is saved so the user can select this device without needed to specify a file again. A configuration file may contain more than one Playback device but it is common to see no more than one. NB: Open question: Path is relative to a specific application directory. May be platform dependent, so it's reasonable to assume than an application may strip this entry from configuration when downloading, or at least be able to default to reasonable behavior when the path is not resolvable. * - The path to the GPX file for this device. * - A 32 bit integer indicating how many times to replay the file. Use 2**32-1 as the value for "forever", it's close enough. ===== Application ===== The application tag allows each application to save the last known device. The Application tag has one required attribuite, "name", which is the applications unique name. The only tag currently supported is: * - The unique ID (macAddress|Builtin|Playback) of the last used device. ===== Changes from pre-existing version ===== Changes between the previous XML examples and this spec: * TOPCON_GPS is named TOPCON * LEICA_GPS is named LEICA * Each device support "name" and "id" attributes. * There may be more than one instance of any type of device in the file, but they must be unique by "id" value * Some parameter names are changed to be consistent between types, e.g. NTRIP parameters. More work needed here. * Parameter groups for things like GPRS and NTRIP are now set aside in their own tag groups instead of partitioning based on individual parameter names. For instance: * becomes\\


          
             blagh

Other GPRS parameters are also in the GPRS block. Similar for NTRIP.