Break out common pieces from TeleGPS and AltusMetrum
[fw/altos] / doc / system-operation.inc
index d7c56eaaa00c1113a105cbc347f810bbcebdadd4..dd8d7d02041793e6b913a7553702034574edcce6 100644 (file)
                completes initialization and self test, and decides which mode
                to enter next.
 
                completes initialization and self test, and decides which mode
                to enter next.
 
-               Here's a short summary of all of the modes and the beeping (or
-               flashing, in the case of TeleMini v1) that accompanies each
-               mode. In the description of the beeping pattern, “dit” means a
-               short beep while "dah" means a long beep (three times as
-               long). “Brap” means a long dissonant tone.
-
-               .AltOS Modes
-               [options="border",cols="1,1,2,2"]
-               |====
-               |Mode Name
-               |Abbreviation
-               |Beeps
-               |Description
-
-               |Startup
-               |S
-               |battery voltage in decivolts
-               |Calibrating sensors, detecting orientation.
-
-               |Idle
-               |I
-               |dit dit
-               |Ready to accept commands over USB or radio link.
-
-               |Pad
-               |P
-               |dit dah dah dit
-               |Waiting for launch. Not listening for commands.
-
-               |Boost
-               |B
-               |dah dit dit dit
-               |Accelerating upwards.
-
-               |Fast
-               |F
-               |dit dit dah dit
-               |Decelerating, but moving faster than 200m/s.
-
-               |Coast
-               |C
-               |dah dit dah dit
-               |Decelerating, moving slower than 200m/s
-
-               |Drogue
-               |D
-               |dah dit dit
-               |Descending after apogee. Above main height.
-
-               |Main
-               |M
-               |dah dah
-               |Descending. Below main height.
-
-               |Landed
-               |L
-               |dit dah dit dit
-               |Stable altitude for at least ten seconds.
-
-
-               |Sensor error
-               |X
-               |dah dit dit dah
-               |Error detected during sensor calibration.
-               |====
-
                In flight or “pad” mode, the altimeter engages the flight
                state machine, goes into transmit-only mode to send telemetry,
                and waits for launch to be detected.  Flight mode is indicated
                In flight or “pad” mode, the altimeter engages the flight
                state machine, goes into transmit-only mode to send telemetry,
                and waits for launch to be detected.  Flight mode is indicated
 
        === Radio Link
 
 
        === Radio Link
 
-               TeleMetrum, TeleMini and TeleMega all incorporate an RF transceiver, but
-               it's not a full duplex system... each end can only be transmitting or
-               receiving at any given moment.  So we had to decide how to manage the
+               TeleMetrum, TeleMini and TeleMega all incorporate an
+               RF transceiver, but it's not a full duplex system;
+               each end can only be transmitting or receiving at any
+               given moment. So we had to decide how to manage the
                link.
 
                link.
 
-               By design, the altimeter firmware listens for the radio link when
-               it's in “idle mode”, which
-               allows us to use the radio link to configure the rocket, do things like
-               ejection tests, and extract data after a flight without having to
-               crack open the air-frame.  However, when the board is in “flight
-               mode”, the altimeter only
-               transmits and doesn't listen at all.  That's because we want to put
-               ultimate priority on event detection and getting telemetry out of
-               the rocket through
-               the radio in case the rocket crashes and we aren't able to extract
-               data later...
-
-               We don't generally use a 'normal packet radio' mode like APRS
-               because they're just too inefficient.  The GFSK modulation we
-               use is FSK with the base-band pulses passed through a Gaussian
-               filter before they go into the modulator to limit the
-               transmitted bandwidth.  When combined with forward error
-               correction and interleaving, this allows us to have a very
-               robust 19.2 kilobit data link with only 10-40 milliwatts of
-               transmit power, a whip antenna in the rocket, and a hand-held
-               Yagi on the ground.  We've had flights to above 21k feet AGL
-               with great reception, and calculations suggest we should be
-               good to well over 40k feet AGL with a 5-element yagi on the
-               ground with our 10mW units and over 100k feet AGL with the
-               40mW devices.  We hope to fly boards to higher altitudes over
-               time, and would of course appreciate customer feedback on
-               performance in higher altitude flights!
-
-       === APRS
-
-               TeleMetrum v2.0 and TeleMega can send APRS if desired, and the
-               interval between APRS packets can be configured. As each APRS
-               packet takes a full second to transmit, we recommend an
-               interval of at least 5 seconds to avoid consuming too much
-               battery power or radio channel bandwidth. You can configure
-               the APRS interval using AltosUI; that process is described in
-               the Configure Altimeter section of the AltosUI chapter.
-
-               AltOS uses the APRS compressed position report data format,
-               which provides for higher position precision and shorter
-               packets than the original APRS format. It also includes
-               altitude data, which is invaluable when tracking rockets. We
-               haven't found a receiver which doesn't handle compressed
-               positions, but it's just possible that you have one, so if you
-               have an older device that can receive the raw packets but
-               isn't displaying position information, it's possible that this
-               is the cause.
-
-               APRS packets include an SSID (Secondary Station Identifier)
-               field that allows one operator to have multiple
-               transmitters. AltOS allows you to set this to a single digit
-               from 0 to 9, allowing you to fly multiple transmitters at the
-               same time while keeping the identify of each one separate in
-               the receiver. By default, the SSID is set to the last digit of
-               the device serial number.
-
-               The APRS packet format includes a comment field that can have
-               arbitrary text in it. AltOS uses this to send status
-               information about the flight computer. It sends four fields as
-               shown in the following table.
-
-               .Altus Metrum APRS Comments
-               [options="header",cols="1,1,3"]
-               |====
-               |Field        |Example        |Description
-
-               |1
-               |L
-               |GPS Status U for unlocked, L for locked
-
-               |2
-               |6
-               |Number of Satellites in View
-
-               |3
-               |B4.0
-               |Altimeter Battery Voltage
-
-               |4
-               |A3.7
-               |Apogee Igniter Voltage
-
-               |5
-               |M3.7
-               |Main Igniter Voltage
-
-               |6
-               |1286
-               |Device Serial Number
-               |====
-
-               Here's an example of an APRS comment showing GPS lock with 6
-               satellites in view, a primary battery at 4.0V, and
-               apogee and main igniters both at 3.7V from device 1286.
-
-               ....
-               L6 B4.0 A3.7 M3.7 1286
-               ....
-
-               Make sure your primary battery is above 3.8V, any
-               connected igniters are above 3.5V and GPS is locked
-               with at least 5 or 6 satellites in view before
-               flying. If GPS is switching between L and U regularly,
-               then it doesn't have a good lock and you should wait
-               until it becomes stable.
-
-               If the GPS receiver loses lock, the APRS data
-               transmitted will contain the last position for which
-               GPS lock was available. You can tell that this has
-               happened by noticing that the GPS status character
-               switches from 'L' to 'U'. Before GPS has locked, APRS
-               will transmit zero for latitude, longitude and
-               altitude.
+               By design, the altimeter firmware listens for the
+               radio link when it's in “idle mode”, which allows us
+               to use the radio link to configure the rocket, do
+               things like ejection tests, and extract data after a
+               flight without having to crack open the air-frame.
+               However, when the board is in “flight mode”, the
+               altimeter only transmits and doesn't listen at all.
+               That's because we want to put ultimate priority on
+               event detection and getting telemetry out of the
+               rocket through the radio in case the rocket crashes
+               and we aren't able to extract data later.
+
+               We don't generally use a 'normal packet radio' mode
+               like APRS because they're just too inefficient.  The
+               GFSK modulation we use is FSK with the base-band
+               pulses passed through a Gaussian filter before they go
+               into the modulator to limit the transmitted bandwidth.
+               When combined with forward error correction and
+               interleaving, this allows us to have a very robust
+               19.2 kilobit data link with only 10-40 milliwatts of
+               transmit power, a whip antenna in the rocket, and a
+               hand-held Yagi on the ground.  We've had flights to
+               above 21k feet AGL with great reception, and
+               calculations suggest we should be good to well over
+               40k feet AGL with a 5-element yagi on the ground with
+               our 10mW units and over 100k feet AGL with the 40mW
+               devices.  We hope to fly boards to higher altitudes
+               over time, and would of course appreciate customer
+               feedback on performance in higher altitude flights!
+
+       :aprsdevices: TeleMetrum v2.0 and TeleMega
+       :configure_section: _configure_altimeter
+       include::aprs-operation.raw[]
 
        === Configurable Parameters
 
                Configuring an Altus Metrum altimeter for flight is
                very simple.  Even on our baro-only TeleMini and
                EasyMini boards, the use of a Kalman filter means
 
        === Configurable Parameters
 
                Configuring an Altus Metrum altimeter for flight is
                very simple.  Even on our baro-only TeleMini and
                EasyMini boards, the use of a Kalman filter means
-               there is no need to set a “mach delay”.  The few
-               configurable parameters can all be set using AltosUI
-               over USB or or radio link via TeleDongle. Read the
-               Configure Altimeter section in the AltosUI chapter
-               below for more information.
-
-               ==== Radio Frequency
-
-                       Altus Metrum boards support radio frequencies
-                       in the 70cm band. By default, the
-                       configuration interface provides a list of 10
-                       “standard” frequencies in 100kHz channels
-                       starting at 434.550MHz.  However, the firmware
-                       supports use of any 50kHz multiple within the
-                       70cm band. At any given launch, we highly
-                       recommend coordinating when and by whom each
-                       frequency will be used to avoid interference.
-                       And of course, both altimeter and TeleDongle
-                       must be configured to the same frequency to
-                       successfully communicate with each other.
-
-               ==== Callsign
-
-                       This sets the callsign used for telemetry,
-                       APRS and the packet link. For telemetry and
-                       APRS, this is used to identify the device. For
-                       the packet link, the callsign must match that
-                       configured in AltosUI or the link will not
-                       work. This is to prevent accidental
-                       configuration of another Altus Metrum flight
-                       computer operating on the same frequency
-                       nearby.
-
-               ==== Telemetry/RDF/APRS Enable
-
-                       You can completely disable the radio while in
-                       flight, if necessary. This doesn't disable the
-                       packet link in idle mode.
-
-               ==== 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
-
-                       This selects how often APRS packets are
-                       transmitted. Set this to zero to disable APRS
-                       without also disabling the regular telemetry
-                       and RDF transmissions. As APRS takes a full
-                       second to transmit a single position report,
-                       we recommend sending packets no more than once
-                       every 5 seconds.
-
-               ==== APRS SSID
-
-                       This selects the SSID reported in APRS
-                       packets. By default, it is set to the last
-                       digit of the serial number, but you can change
-                       this to any value from 0 to 9.
-
-               ==== Apogee Delay
-
-                       Apogee delay is the number of seconds after
-                       the altimeter detects flight apogee that the
-                       drogue charge should be fired.  In most cases,
-                       this should be left at the default of 0.
-                       However, if you are flying redundant
-                       electronics such as for an L3 certification,
-                       you may wish to set one of your altimeters to
-                       a positive delay so that both primary and
-                       backup pyrotechnic charges do not fire
-                       simultaneously.
-
-                       The Altus Metrum apogee detection algorithm
-                       fires exactly at apogee.  If you are also
-                       flying an altimeter like the PerfectFlite
-                       MAWD, which only supports selecting 0 or 1
-                       seconds of apogee delay, you may wish to set
-                       the MAWD to 0 seconds delay and set the
-                       TeleMetrum to fire your backup 2 or 3 seconds
-                       later to avoid any chance of both charges
-                       firing simultaneously.  We've flown several
-                       air-frames this way quite happily, including
-                       Keith's successful L3 cert.
-
-               ==== Apogee Lockout
-
-                       Apogee lockout is the number of seconds after
-                       boost where the flight computer will not fire
-                       the apogee charge, even if the rocket appears
-                       to be at apogee. This is often called 'Mach
-                       Delay', as it is intended to prevent a flight
-                       computer from unintentionally firing apogee
-                       charges due to the pressure spike that occurrs
-                       across a mach transition. Altus Metrum flight
-                       computers include a Kalman filter which is not
-                       fooled by this sharp pressure increase, and so
-                       this setting should be left at the default
-                       value of zero to disable it.
-
-               ==== Main Deployment Altitude
-
-                       By default, the altimeter will fire the main
-                       deployment charge at an elevation of 250
-                       meters (about 820 feet) above ground.  We
-                       think this is a good elevation for most
-                       air-frames, but feel free to change this to
-                       suit.  In particular, if you are flying two
-                       altimeters, you may wish to set the deployment
-                       elevation for the backup altimeter to be
-                       something lower than the primary so that both
-                       pyrotechnic charges don't fire simultaneously.
-
-               ==== Maximum Flight Log
-
-                       Changing this value will set the maximum
-                       amount of flight log storage that an
-                       individual flight will use. The available
-                       storage is divided into as many flights of the
-                       specified size as can fit in the available
-                       space. You can download and erase individual
-                       flight logs. If you fill up the available
-                       storage, future flights will not get logged
-                       until you erase some of the stored ones.
-
-                       Even though our flight computers (except TeleMini v1.0) can store
-                       multiple flights, we strongly recommend downloading and saving
-                       flight data after each flight.
-
-               ==== Ignite Mode
-
-                       Instead of firing one charge at apogee and
-                       another charge at a fixed height above the
-                       ground, you can configure the altimeter to
-                       fire both at apogee or both during
-                       descent. This was added to support an airframe
-                       Bdale designed that had two altimeters, one in
-                       the fin can and one in the nose.
-
-                       Providing the ability to use both igniters for
-                       apogee or main allows some level of redundancy
-                       without needing two flight computers.  In
-                       Redundant Apogee or Redundant Main mode, the
-                       two charges will be fired two seconds apart.
-
-               ==== Pad Orientation
-
-                       TeleMetrum, TeleMega and EasyMega measure
-                       acceleration along the axis of the
-                       board. Which way the board is oriented affects
-                       the sign of the acceleration value. Instead of
-                       trying to guess which way the board is mounted
-                       in the air frame, the altimeter must be
-                       explicitly configured for either Antenna Up or
-                       Antenna Down. The default, Antenna Up, expects
-                       the end of the board connected to the 70cm
-                       antenna to be nearest the nose of the rocket,
-                       with the end containing the screw terminals
-                       nearest the tail.
-
-               ==== Configurable Pyro Channels
-
-                       In addition to the usual Apogee and Main pyro
-                       channels, TeleMega and EasyMega have four
-                       additional channels that can be configured to
-                       activate when various flight conditions are
-                       satisfied. You can select as many conditions
-                       as necessary; all of them must be met in order
-                       to activate the channel. The conditions
-                       available are:
-
-                       include::pyro-channels.raw[]
-
+               there is no need to set a “mach delay”.  All of the
+               configurable parameters can be set using AltosUI
+               over USB or or radio link via TeleDongle. Read
+               <<_configure_altimeter>> for more information.