diff options
Diffstat (limited to 'doc/altosui.inc')
| -rw-r--r-- | doc/altosui.inc | 682 |
1 files changed, 682 insertions, 0 deletions
diff --git a/doc/altosui.inc b/doc/altosui.inc new file mode 100644 index 00000000..76a24d91 --- /dev/null +++ b/doc/altosui.inc @@ -0,0 +1,682 @@ +== AltosUI + + .AltosUI Main Window + image::altosui.png[width="4.6in"] + + The AltosUI program provides a graphical user interface for + interacting with the Altus Metrum product family. AltosUI can + monitor telemetry data, configure devices and many other + tasks. The primary interface window provides a selection of + buttons, one for each major activity in the system. This + chapter is split into sections, each of which documents one of + the tasks provided from the top-level toolbar. + + ifdef::radio[] + === Monitor Flight + //// + <subtitle>Receive, Record and Display Telemetry Data</subtitle> + //// + + Selecting this item brings up a dialog box listing all + of the connected TeleDongle devices. When you choose + one of these, AltosUI will create a window to display + telemetry data as received by the selected TeleDongle + device. + + .Device Selection Dialog + image::device-selection.png[width="3.1in"] + + All telemetry data received are automatically recorded + in suitable log files. The name of the files includes + the current date and rocket 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. AltosUI + 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. Each altimeter remembers how + many times it has flown. + + * The rocket flight state. Each flight passes through + several states including Pad, Boost, Fast, Coast, + Drogue, Main and Landed. + + * The Received Signal Strength Indicator value. This + lets you know how strong a signal TeleDongle is + receiving. At the default data rate, 38400 bps, in + bench testing, the radio inside TeleDongle v0.2 + operates down to about -106dBm, while the v3 radio + works down to about -111dBm. Weaker signals, or an + environment with radio noise may cause the data to + not be received. 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 rocket. They're arranged in 'flight order' + so that as the flight progresses, the selected tab + automatically switches to display data relevant to the + current state of the flight. You can select other tabs + at any time. The final 'table' tab displays all of the + raw telemetry values in one place in a + spreadsheet-like format. + + ==== Launch Pad + + .Monitor Flight Launch Pad View + image::launch-pad.png[width="5.5in"] + + The 'Launch Pad' tab shows information used to decide when the + rocket is ready for flight. The first elements include red/green + indicators, if any of these is red, you'll want to evaluate + whether the rocket is ready to launch: + + Battery Voltage:: + This indicates whether the Li-Po battery powering the + flight computer has sufficient charge to last for + the duration of the flight. A value of more than + 3.8V is required for a 'GO' status. + + Apogee Igniter Voltage:: + This indicates whether the apogee + igniter has continuity. If the igniter has a low + resistance, then the voltage measured here will be close + to the Li-Po battery voltage. A value greater than 3.2V is + required for a 'GO' status. + + Main Igniter Voltage:: + This indicates whether the main + igniter has continuity. If the igniter has a low + resistance, then the voltage measured here will be close + to the Li-Po battery voltage. A value greater than 3.2V is + required for a 'GO' status. + + On-board Data Logging:: + This indicates whether there is space remaining + on-board to store flight data for the upcoming + flight. If you've downloaded data, but failed to erase + flights, there may not be any space left. Most of our + flight computers can store multiple flights, depending + on the configured maximum flight log size. TeleMini + v1.0 stores only a single flight, so it will need to + be downloaded and erased after each flight to capture + data. This only affects on-board flight logging; the + altimeter will still transmit telemetry and fire + ejection charges at the proper times even if the + flight data storage is full. + + GPS Locked:: + For a TeleMetrum or TeleMega device, this indicates + whether the GPS receiver is currently able to compute + position information. GPS requires at least 4 + satellites to compute an accurate position. + + GPS Ready:: + + For a TeleMetrum or TeleMega device, this indicates + whether GPS has reported at least 10 consecutive + positions without losing lock. This ensures that the + GPS receiver has reliable reception from the + satellites. + + The Launchpad tab also shows the computed launch pad + position and altitude, averaging many reported + positions to improve the accuracy of the fix. + + ==== Ascent + + .Monitor Flight Ascent View + image::ascent.png[width="5.5in"] + + This tab is shown during Boost, Fast and Coast + phases. The information displayed here helps monitor the + rocket as it heads towards apogee. + + The height, speed, acceleration and tilt are shown along + with the maximum values for each of them. This allows you to + quickly answer the most commonly asked questions you'll hear + during flight. + + The current latitude and longitude reported by the GPS are + also shown. Note that under high acceleration, these values + may not get updated as the GPS receiver loses position + fix. Once the rocket starts coasting, the receiver should + start reporting position again. + + Finally, the current igniter voltages are reported as in the + Launch Pad tab. This can help diagnose deployment failures + caused by wiring which comes loose under high acceleration. + + ==== Descent + + .Monitor Flight Descent View + image::descent.png[width="5.5in"] + + Once the rocket has reached apogee and (we hope) + activated the apogee charge, attention switches to + tracking the rocket on the way back to the ground, and + for dual-deploy flights, waiting for the main charge + to fire. + + To monitor whether the apogee charge operated + correctly, the current descent rate is reported along + with the current height. Good descent rates vary based + on the choice of recovery components, but generally + range from 15-30m/s on drogue and should be below + 10m/s when under the main parachute in a dual-deploy + flight. + + With GPS-equipped flight computers, you can locate the + rocket in the sky using the elevation and bearing + information to figure out where to look. Elevation is + in degrees above the horizon. Bearing is reported in + degrees relative to true north. Range can help figure + out how big the rocket will appear. Ground Distance + shows how far it is to a point directly under the + rocket and can help figure out where the rocket is + likely to land. Note that all of these values are + relative to the pad location. If the elevation is near + 90°, the rocket is over the pad, not over you. + + Finally, the igniter voltages are reported in this tab + as well, both to monitor the main charge as well as to + see what the status of the apogee charge is. Note + that some commercial e-matches are designed to retain + continuity even after being fired, and will continue + to show as green or return from red to green after + firing. + + ==== Landed + + .Monitor Flight Landed View + image::landed.png[width="5.5in"] + + Once the rocket is on the ground, attention switches + to recovery. While the radio signal is often lost once + the rocket is on the ground, the last reported GPS + position is generally within a short distance of the + actual landing location. + + The last reported GPS position is reported both by + latitude and longitude as well as a bearing and + distance from the launch pad. The distance should give + you a good idea of whether to walk or hitch a ride. + Take the reported latitude and longitude and enter + them into your hand-held GPS unit and have that + compute a track to the landing location. + + Our flight computers will continue to transmit RDF + tones after landing, allowing you to locate the rocket + by following the radio signal if necessary. You may + need to get away from the clutter of the flight line, + or even get up on a hill (or your neighbor's RV roof) + to receive the RDF signal. + + The maximum height, speed and acceleration reported + during the flight are displayed for your admiring + observers. The accuracy of these immediate values + depends on the quality of your radio link and how many + packets were received. Recovering the on-board data + after flight may yield more precise results. + + To get more detailed information about the flight, you + can click on the 'Graph Flight' button which will + bring up a graph window for the current flight. + + ==== Table + + .Monitor Flight Table View + image::table.png[width="5.5in"] + + The table view shows all of the data available from the + flight computer. Probably the most useful data on + this tab is the detailed GPS information, which includes + horizontal dilution of precision information, and + information about the signal being received from the satellites. + + ==== Site Map + + .Monitor Flight Site Map View + image::site-map.png[width="5.5in"] + + When the TeleMetrum has a GPS fix, the Site Map tab + will map the rocket's position to make it easier for + you to locate the rocket, both while it is in the air, + and when it has landed. The rocket's state is + indicated by color: white for pad, red for boost, pink + for fast, yellow for coast, light blue for drogue, + dark blue for main, and black for landed. + + 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 <<_load_maps>>. + + ==== Igniter + + .Monitor Flight Additional Igniter View + image::ignitor.png[width="5.5in"] + + TeleMega includes four additional programmable pyro + channels. The Ignitor tab shows whether each of them has + continuity. If an ignitor has a low resistance, then the + voltage measured here will be close to the pyro battery + voltage. A value greater than 3.2V is required for a 'GO' + status. + endif::radio[] + + + === Save Flight Data + + The altimeter records flight data to its internal + flash memory. + ifdef::radio[] + Data logged on board is recorded at a much + higher rate than the telemetry system can handle, and + is not subject to radio drop-outs. As such, it + provides a more complete and precise record of the + flight. + endif::radio[] + The 'Save Flight Data' button allows you to + read the flash memory and write it to disk. + + Clicking on the 'Save Flight Data' button brings up a + list of connected flight computers and TeleDongle + devices. If you select a flight computer, the flight + data will be downloaded from that device directly. + ifdef::radio[] + If you select a TeleDongle device, flight data will be + downloaded from a flight computer over radio link via + the specified TeleDongle. See + <<_controlling_an_altimeter_over_the_radio_link>> for + more information. + endif::radio[] + + After the device has been selected, a dialog showing + the flight data saved in the device will be shown + allowing you to select which flights to download and + which to delete. With version 0.9 or newer firmware, + you must erase flights in order for the space they + consume to be reused by another flight. This prevents + accidentally losing flight data if you neglect to + download data before flying again. Note that if there + is no more space available in the device, then no data + will be recorded during the next flight. + + The file name for each flight log is computed + automatically from the recorded flight date, altimeter + serial number and flight number information. + + === Replay Flight + + Select this button and you are prompted to select a flight + record file, either a .telem file recording telemetry data or a + .eeprom file containing flight data saved from the altimeter + flash memory. + + Once a flight record is selected, the flight monitor interface + is displayed and the flight is re-enacted in real + time. + ifdef::radio[] + Check + <<_monitor_flight>> to learn how this window operates. + endif::radio[] + + === Graph Data + + Select this button and you are prompted to select a flight + record file, either a .telem file recording telemetry data or a + .eeprom file containing flight data saved from + flash memory. + + Note that telemetry files will generally produce poor graphs + due to the lower sampling rate and missed telemetry packets. + Use saved flight data in .eeprom files for graphing where possible. + + Once a flight record is selected, a window with multiple tabs is + opened. + + ==== Flight Graph + + .Flight Data Graph + image::graph.png[width="5.5in"] + + By default, the graph contains acceleration (blue), + velocity (green) and altitude (red). + + The graph can be zoomed into a particular area by + clicking and dragging down and to the right. Once + zoomed, the graph can be reset by clicking and + dragging up and to the left. Holding down control and + clicking and dragging allows the graph to be panned. + The right mouse button causes a pop-up menu to be + displayed, giving you the option save or print the + plot. + + ==== Configure Graph + + .Flight Graph Configuration + image::graph-configure.png[width="5.5in"] + + This selects which graph elements to show, and, at the + very bottom, lets you switch between metric and + imperial units + + ==== Flight Statistics + + .Flight Statistics + image::graph-stats.png[width="5.5in"] + + Shows overall data computed from the flight. + + ifdef::gps[] + ==== Map + + .Flight Map + image::graph-map.png[width="5.5in"] + + Shows a satellite image of the flight area overlaid + with the path of the flight. The red concentric + circles mark the launch pad, the black concentric + circles mark the landing location. + endif::gps[] + + === 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 flight 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. + ifdef::gps[] + It has a selector to choose between CSV and KML + file formats. + endif::gps[] + + ==== 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 the altimeter, 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. + + ifdef::gps[] + ==== 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 flight path + in 3D. + endif::gps[] + + === Configure Altimeter + + .Altimeter Configuration + image::configure-altimeter.png[width="3.6in"] + + ifdef::radio[] + Select this button and then select either an altimeter or + TeleDongle Device from the list provided. Selecting a TeleDongle + device will use the radio link to configure a remote + altimeter. + endif::radio[] + ifndef::radio[] + Select this button and then select an altimeter. + endif::radio[] + + 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. + + include::config-device.raw[] + + + === Configure AltosUI + + .Configure AltosUI Dialog + image::configure-altosui.png[width="2.4in"] + + This button presents a dialog so that you can + configure the AltosUI global settings. + + include::config-ui.raw[] + + ifdef::radio[] + === Configure Groundstation + + .Configure Groundstation Dialog + image::configure-groundstation.png[width="3.1in"] + + Select this button and then select a TeleDongle or + TeleBT 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. + + Note that TeleDongle and TeleBT don't save any + configuration data, the settings here are recorded on + the local machine in the Java preferences + database. Moving the device to another machine, or + using a different user account on the same machine + will cause settings made here to have no effect. + + At the bottom of the dialog, there are three + buttons: + + Save:: + This writes any changes to the local Java + preferences file. 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. + + Close:: + This closes the dialog. Any unsaved changes + will be lost. + + The rest of the dialog contains the parameters + to be configured. + + ==== Frequency + + This configures the frequency to use for both + telemetry and packet command mode. Set this + before starting any operation involving packet + command mode so that it will use the right + frequency. Telemetry monitoring mode also + provides a menu to change the frequency, and + that menu also sets the same Java preference + value used here. + + ==== 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. To change a TeleDongle or TeleBT's + calibration, you must reprogram the unit + completely, so this entry simply shows the + current value and doesn't allow any changes. + + ==== Telemetry Rate + + This lets you match the telemetry and packet + link rate from the transmitter. If they don't + match, the device won't receive any data. + endif::radio[] + + === Flash Image + + This reprograms Altus Metrum devices with new + firmware. + ifdef::telemetrum,telemini[] + TeleMetrum v1.x, TeleDongle v0.2, TeleMini + and TeleBT are all reprogrammed by using another + similar unit as a programming dongle (pair + programming). + endif::telemetrum,telemini[] + ifdef::telemega,easymega,telemetrum[] + TeleMega, EasyMega, TeleMetrum v2, + EasyMini and TeleDongle v3 are all + endif::telemega,easymega,telemetrum[] + ifndef::telemega,easymega,telemetrum[] + EasyMini is + endif::telemega,easymega,telemetrum[] + programmed directly + over USB (self programming). Please read + the directions for flashing devices in + <<_updating_device_firmware>>. + + === Fire Igniter + + .Fire Igniter Window + image::fire-igniter.png[width="1.2in"] + + This activates the igniter circuits in the flight + computer to help test recovery systems + deployment. + ifdef::radio[] + Because this command can operate over the + Packet Command Link, you can prepare the rocket as for + flight and then test the recovery system without + needing to snake wires inside the air-frame. + endif::radio[] + + Selecting the 'Fire Igniter' button brings up the + usual device selection dialog. Pick the desired + device. This brings up another window which shows the + current continuity test status for all of the pyro + channels. + + Next, select the desired igniter to fire. This will + enable the 'Arm' button. + + Select the 'Arm' button. This enables the 'Fire' + button. The word 'Arm' is replaced by a countdown + timer indicating that you have 10 seconds to press the + 'Fire' button or the system will deactivate, at which + point you start over again at selecting the desired + igniter. + + ifdef::radio[] + === Scan Channels + + .Scan Channels Window + image::scan-channels.png[width="3.2in"] + + This listens for telemetry packets on all of the + configured frequencies, displaying information about + each device it receives a packet from. You can select + which of the baud rates and telemetry formats should + be tried; by default, it only listens at 38400 baud + with the standard telemetry format used in v1.0 and + later firmware. + endif::radio[] + + ifdef::gps[] + include::load-maps.raw[] + endif::gps[] + + ifdef::radio[] + === Monitor Idle + + .Monitor Idle Window + image::monitor-idle.png[width="5.2in"] + + This brings up a dialog similar to the Monitor Flight + UI, except it works with the altimeter in “idle” mode + by sending query commands to discover the current + state rather than listening for telemetry + packets. Because this uses command mode, it needs to + have the TeleDongle and flight computer callsigns + match exactly. If you can receive telemetry, but + cannot manage to run Monitor Idle, then it's very + likely that your callsigns are different in some way. + + You can change the frequency and callsign used to + communicate with the flight computer; they must both + match the configuration in the flight computer + exactly. + endif::radio[] |