path: root/doc/telegps-application.inc

== TeleGPS Application

	The TeleGPS application provides a graphical user interface for
	interacting with the Altus Metrum product family. TeleGPS can
	monitor telemetry data, configure devices and many other
	tasks. The primary interface window is for displaying data
	received over the telemetry link. There are additional
	tasks available from the main window menu bar.

	=== Telemetry Monitoring

		This is the window brought up when you start the
		application. If you have a TeleDongle device connected
		to the computer, it will automatically be selected for
		telemetry monitoring

		All telemetry data received are automatically recorded
		in suitable log files. The name of the files includes
		the current date and TeleGPS serial and flight
		numbers.

		The radio frequency being monitored by the TeleDongle
		device is displayed at the top of the window. You can
		configure the frequency by clicking on the frequency
		box and selecting the desired frequency. The TeleGPS
		application remembers the last frequency selected for
		each TeleDongle and selects that automatically the
		next time you use that device.

		Below the TeleDongle frequency selector, the window
		contains a few significant pieces of information about
		the altimeter providing the telemetry data stream:

		* The configured call-sign

		* The device serial number

		* The flight number. TeleGPS remembers how many times
                  it has flown.

		* The Received Signal Strength Indicator value. This
		  lets you know how strong a signal TeleDongle is
		  receiving. The radio inside TeleDongle operates down
		  to about -100dBm; weaker signals may not be
		  receivable. The packet link uses error detection and
		  correction techniques which prevent incorrect data
		  from being reported.

		* The age of the displayed data, in seconds since the
		  last successfully received telemetry packet.  In
		  normal operation this will stay in the low single
		  digits.  If the number starts counting up, then you
		  are no longer receiving data over the radio link
		  from the flight computer.

		Finally, the largest portion of the window contains a set of
		tabs, each of which contain some information about the TeleGPS
		board. The final 'table' tab displays many of the raw telemetry
		values in one place in a spreadsheet-like format.
      
		==== Map

			The Map tab shows the TeleGPS track over time
			on top of map data making it easy to locate
			the device.
        
			.TeleGPS Map View
			image::telegps-map.png[width="5.5in"]

			The map's default scale is approximately 3m
			(10ft) per pixel. The map can be dragged using
			the left mouse button. The map will attempt to
			keep the rocket roughly centered while data is
			being received.
        
			You can adjust the style of map and the zoom
			level with buttons on the right side of the
			map window. You can draw a line on the map by
			moving the mouse over the map with a button
			other than the left one pressed, or by
			pressing the left button while also holding
			down the shift key. The length of the line in
			real-world units will be shown at the start of
			the line.
	
			Images are fetched automatically via the
			Google Maps Static API, and cached on disk for
			reuse. If map images cannot be downloaded, the
			rocket's path will be traced on a dark gray
			background instead.
        
			You can pre-load images for your favorite
			launch sites before you leave home; check out
			the 'Preload Maps' section below.
	
		==== Location

			The Location tab shows the raw GPS data
			received from TeleGPS.
	
			.TeleGPS Location View
			image::telegps-location.png[width="5.5in"]

		==== Status

			The Status tab shows data relative to the
			location of TeleGPS when the application first
			received telemetry from it.
	
			.TeleGPS Status View
			image::telegps-status.png[width="5.5in"]

		==== Table

			The Table tab shows detailed information about
			the GPS receiver
	
			.TeleGPS Information Table
			image::telegps-table.png[width="5.5in"]

	=== TeleGPS Menus

		TeleGPS has three or four menus at the top of
		the window:

		File::

		New Window, Graph Data, Export Data, Load Maps,
		Preferences, Close and Exit
	      
		Monitor::

		Connect Device, Disconnect and Scan Channels

		Device::

		Download Data, Configure Device and Flash Device
	      
		Frequency::

		This shows the current monitoring frequency with a
		drop-down menu listing other configured
		frequencies. You can change the set of frequencies
		shown here from the Preferences dialog. This menu is
		only shown when the TeleGPS application is connected
		to a TeleDongle or TeleBT device.
	      
      
		==== New Window

			This creates another telemetry monitoring window, in case
			you have multiple TeleDongle devices connected to the
			computer.
	
	=== Graph Data

		The Graph tab shows a plot of the the GPS data
		collected. The X axis is time in seconds; there are a
		variety of Y axes available for different kinds of
		data. This window also allows you to see some
		statistics computed from the data, and an overall map
		of the entire data record.
	  
		==== Data Graph

			.TeleGPS Graph
			image::telegps-graph-graph.png[width="5.5in"]

		==== Graph Configuration

			.TeleGPS Graph Configuration
			image::telegps-graph-configure.png[width="5.5in"]

			This selects which graph elements to show, and, at the
			bottom, lets you switch between metric and imperial
			units

		==== Statistics

			.TeleGPS Statistics
			image::telegps-graph-stats.png[width="5.5in"]

			Shows overall data computed from the flight.
		
		==== Map

			.TeleGPS Map
			image::telegps-graph-map.png[width="6in"]

			Shows a map of the area overlaid with the GPS track. As with
			the telemetry monitoring window, you can select the style
			of map and zoom level using buttons along the side;
			you can scroll the map by dragging within the map pressing
			the left button and you can draw a line to measure
			distances using either the left button with the shift key,
			or any other button.

	=== Export Data

		This tool takes the raw data files and makes them
		available for external analysis. When you select this
		button, you are prompted to select a data file, which
		can be either a .eeprom or .telem.  The .eeprom files
		contain higher resolution and more continuous data,
		while .telem files contain receiver signal strength
		information.  Next, a second dialog appears which is
		used to select where to write the resulting file. It
		has a selector to choose between CSV and KML file
		formats.
	
		==== Comma Separated Value Format

			This is a text file containing the data in a
			form suitable for import into a spreadsheet or
			other external data analysis tool. The first
			few lines of the file contain the version and
			configuration information from TeleGPS, then
			there is a single header line which labels all
			of the fields. All of these lines start with a
			'#' character which many tools can be
			configured to skip over.

			The remaining lines of the file contain the
			data, with each field separated by a comma and
			at least one space. All of the sensor values
			are converted to standard units, with the
			barometric data reported in both pressure,
			altitude and height above pad units.

		==== Keyhole Markup Language (for Google Earth)

			This is the format used by Google Earth to provide an overlay
			within that application. With this, you can use Google Earth to
			see the whole path in 3D.

	=== Load Maps

		.Load Maps Window
		image::load-maps.png[width="5.2in"]

		Before using TeleGPS, you can use Load Maps to load
		map data in case you don't have access to the internet
		while receiving telemetry.

		There's a drop-down menu of rocket launch sites we
		know about; if your favorites aren't there, please let
		us know the lat/lon and name of the site. The contents
		of this list are actually downloaded from our server
		at run-time, so as new sites are sent in, they'll get
		automatically added to this list.  If the launch site
		isn't in the list, you can manually enter the lat/lon
		values

		There are four different kinds of maps you can view;
		you can select which to download by selecting as many
		as you like from the available types:

		Hybrid::
		A combination of satellite imagery and road data. This
		is the default view.

		Satellite::
		Just the satellite imagery without any annotation.

		Roadmap::
		Roads, political boundaries and a few geographic
		features.

		Terrain::
		Contour intervals and shading that show hills and
		valleys.

		You can specify the range of zoom levels to download;
		smaller numbers show more area with less
		resolution. The default level, 0, shows about
		3m/pixel. One zoom level change doubles or halves that
		number. Larger zoom levels show more detail, smaller
		zoom levels less.

		The Map Radius value sets how large an area around the
		center point to download. Select a value large enough
		to cover any plausible flight from that site. Be aware
		that loading a large area with a high maximum zoom
		level can attempt to download a lot of data. Loading
		hybrid maps with a 10km radius at a minimum zoom of -2
		and a maximum zoom of 2 consumes about 120MB of
		space. Terrain and road maps consume about 1/10 as
		much space as satellite or hybrid maps.

		Clicking the 'Load Map' button will fetch images from
		Google Maps; note that Google limits how many images
		you can fetch at once, so if you load more than one
		launch site, you may get some gray areas in the map
		which indicate that Google is tired of sending data to
		you. Try again later.

	=== Preferences

		.TeleGPS Preferences Window
		image::telegps-preferences.png[width="2.4in"]

			AltosUI provides voice announcements during
			flight so that you can keep your eyes on the
			sky and still get information about the
			current flight status. However, sometimes you
			don't want to hear them.

			Enable::
			Turns all voice announcements on and off

			Test Voice::
			Plays a short message allowing you to verify
			that the audio system is working and the volume settings
			are reasonable

      		==== Log Directory

			AltosUI logs all telemetry data and saves all
			TeleMetrum flash data to this directory. This
			directory is also used as the staring point
			when selecting data files for display or
			export.

			Click on the directory name to bring up a
			directory choosing dialog, select a new
			directory and click 'Select Directory' to
			change where AltosUI reads and writes data
			files.

      		==== Callsign

			This value is transmitted in each command
			packet sent from TeleDongle and received from
			an altimeter.  It is not used in telemetry
			mode, as the callsign configured in the
			altimeter board is included in all telemetry
			packets.  Configure this with the AltosUI
			operators call sign as needed to comply with
			your local radio regulations.

			Note that to successfully command a flight
			computer over the radio (to configure the
			altimeter, monitor idle, or fire pyro
			charges), the callsign configured here must
			exactly match the callsign configured in the
			flight computer.  This matching is case
			sensitive.

		==== Imperial Units

			This switches between metric units (meters)
			and imperial units (feet and miles). This
			affects the display of values use during
			flight monitoring, configuration, data
			graphing and all of the voice
			announcements. It does not change the units
			used when exporting to CSV files, those are
			always produced in metric units.

		==== Font Size

			Selects the set of fonts used in the flight
			monitor window. Choose between the small,
			medium and large sets.

      		==== Serial Debug

			This causes all communication with a connected
			device to be dumped to the console from which
			AltosUI was started. If you've started it from
			an icon or menu entry, the output will simply
			be discarded. This mode can be useful to debug
			various serial communication issues.

		==== Manage Frequencies

			This brings up a dialog where you can
			configure the set of frequencies shown in the
			various frequency menus. You can add as many
			as you like, or even reconfigure the default
			set. Changing this list does not affect the
			frequency settings of any devices, it only
			changes the set of frequencies shown in the
			menus.

	=== Close

		This closes the current window, leaving any other windows
		open and the application running.
	
	=== Exit

		This closes all TeleGPS windows and terminates the
		application.
	
	=== Connect Device

		Selecting this item brings up a dialog box listing all
		of the connected TeleDongle devices. When you choose
		one of these, AltosUI will display telemetry data as
		received by the selected TeleDongle device.
	
		.Device Selection Dialog
		image::device-selection.png[width="3.1in"]

	=== Disconnect

		Disconnects the currently connected TeleDongle or
		TeleBT

	=== Scan Channels

		.Radio Scanning Dialog
		image::telegps-scan.png[width="3.1in"]

		Scans the configured set of frequencies looking for
		telemetry signals. A list of all of the discovered
		signals is show; selecting one of those and clicking
		on 'Monitor' will select that frequency in the
		associated TeleGPS application window.

	=== Download Data

		TeleGPS records data to its internal flash memory.
		On-board data is recorded at the same rate as
		telemetry but is not subject to radio drop-outs. As
		such, it generally provides a more complete and
		precise record.  The 'Download Data' menu entry allows
		you to read the flash memory and write it to disk.

		Select the 'Download Data' menu entry to bring up a
		list of connected TeleGPS devices. After the device
		has been selected, a dialog showing the data stored in
		the device will be shown allowing you to select which
		entries to download and which to delete. You must
		erase flights in order for the space they consume to
		be reused by another track. This prevents accidentally
		losing data if you neglect to download data before
		starting TeleGPS again. Note that if there is no more
		space available in the device, then no data will be
		recorded.

		The file name for each data log is computed
		automatically from the recorded date, altimeter serial
		number and flight number information.
	
	=== Configure Device

		.TeleGPS Configuration Dialog
		image::telegps-configure.png[width="3.6in"]

		Select this button and then select any connected TeleGPS
		device from the list provided.

		The first few lines of the dialog provide information
		about the connected device, including the product
		name, software version and hardware serial
		number. Below that are the individual configuration
		entries.

		At the bottom of the dialog, there are four buttons:
	
		Save::
		This writes any changes to the configuration parameter
		block in flash memory. If you don't press this button,
		any changes you make will be lost.

		Reset::
		This resets the dialog to the most recently saved
		values, erasing any changes you have made.

		Reboot::

		This reboots the device. Use this to switch from idle
		to pad mode by rebooting once the rocket is oriented
		for flight, or to confirm changes you think you saved
		are really saved.

		Close::

		This closes the dialog. Any unsaved changes will be
		lost.

	        The rest of the dialog contains the parameters to be configured.

          The rest of the dialog contains the parameters to be configured.
	
		==== Frequency

			This configures which of the frequencies to use for
			both telemetry and packet command mode. Note that if
			you set this value via packet command mode, the
			TeleDongle frequency will also be automatically
			reconfigured to match so that communication will
			continue afterwards.

		==== RF Calibration

			The radios in every Altus Metrum device are calibrated
			at the factory to ensure that they transmit and
			receive on the specified frequency.  If you need to
			you can adjust the calibration by changing this value.
			Do not do this without understanding what the value
			means, read the appendix on calibration and/or the
			source code for more information.  To change a
			TeleDongle's calibration, you must reprogram the unit
			completely.

      		==== Telemetry/RDF/APRS Enable

			Enables the radio for transmission during
			flight. When disabled, the radio will not
			transmit anything during flight at all.

      		==== Telemetry baud rate

			This sets the modulation bit rate for data
			transmission for both telemetry and packet
			link mode. Lower bit rates will increase range
			while reducing the amount of data that can be
			sent and increasing battery consumption. All
			telemetry is done using a rate 1/2 constraint
			4 convolution code, so the actual data
			transmission rate is 1/2 of the modulation bit
			rate specified here.

      		==== APRS Interval

			How often to transmit GPS information via APRS
			(in seconds). When set to zero, APRS
			transmission is disabled. This option is
			available on TeleMetrum v2 and TeleMega
			boards. TeleMetrum v1 boards cannot transmit
			APRS packets. Note that a single APRS packet
			takes nearly a full second to transmit, so
			enabling this option will prevent sending any
			other telemetry during that time.

      		==== APRS SSID

			Which SSID to report in APRS packets. By
			default, this is set to the last digit of the
			serial number, but can be configured to any
			value from 0 to 9.

		==== Callsign

			This sets the call sign included in each
			telemetry packet. Set this as needed to
			conform to your local radio regulations.

		==== Logging Trigger Motion

			If TeleGPS moves less than this distance over
			a long period of time, it will not log that
			location, saving storage space.

		==== Position Reporting Interval

			This sets how often TeleGPS reports position
			information via telemetry and to the on-board
			log. Reducing this value will save power and
			logging memory consumption.

	=== Flash Device

		This reprograms TeleGPS devices with new
		firmware. Please read the directions for flashing
		devices in the Updating Device Firmware chapter below.