doc: Add updating firmware and using am products asciidoc bits

This finishes the asciidoc transition

Signed-off-by: Keith Packard <keithp@keithp.com>

diff --git a/doc/Makefile b/doc/Makefile
index 818bd574fe3b3b32ce8670ba597d7998c2cd27b0..82ece0d516312660b48fb3db33eace94b8a924ae 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -74,6 +74,8 @@ INC_FILES=\
        telemega.inc \
        easymega.inc \
        installation.inc \
        telemega.inc \
        easymega.inc \
        installation.inc \

+       using-am-products.inc \
+       updating-firmware.inc \

        altosui.inc \
        altosdroid.inc \
        system-operation.inc \
        altosui.inc \
        altosdroid.inc \
        system-operation.inc \

diff --git a/doc/altusmetrum.txt b/doc/altusmetrum.txt
index 9f1bbf2841bc2193d931226e4044024f204febf9..8dc183629a73ce3ca69356bcfae47b72a1102544 100644 (file)
--- a/doc/altusmetrum.txt
+++ b/doc/altusmetrum.txt
@@ -25,6 +25,8 @@
 
        include::installation.raw[]
 
 
        include::installation.raw[]
 

+       include::using-am-products.raw[]
+

        include::altosui.raw[]
 
        include::altosdroid.raw[]
        include::altosui.raw[]
 
        include::altosdroid.raw[]


@@ -33,6 +35,8 @@
 
        include::handling.raw[]
 
 
        include::handling.raw[]
 

+       include::updating-firmware.raw[]
+

        include::flight-data-recording.raw[]
 
        include::specs.raw[]
        include::flight-data-recording.raw[]
 
        include::specs.raw[]

diff --git a/doc/pyro-channels.inc b/doc/pyro-channels.inc
index 0da7db25eae136316664445b56582ba7e2f1c397..3b9185445c40e910651a03fe70a5a29b2386e668 100644 (file)
--- a/doc/pyro-channels.inc
+++ b/doc/pyro-channels.inc
@@ -47,30 +47,23 @@ pad and initialize the system.
   of less than that value.
   ====
 
   of less than that value.
   ====
 

-Flight Time:: Time since boost was
-detected. Select a value and choose whether to
-activate the pyro channel before or after that
-amount of time.
-
-Ascending:: A simple test saying whether the
-rocket is going up or not. This is exactly
-equivalent to testing whether the speed is
-> 0.
-
-Descending:: A simple test saying whether the
-rocket is going down or not. This is exactly
-equivalent to testing whether the speed is
-< 0.
-
-After Motor:: The flight software counts each
-time the rocket starts accelerating and then
-decelerating (presumably due to a motor or
-motors burning). Use this value for
-multi-staged or multi-airstart launches.
-
-Delay:: This value doesn't perform any checks,
-instead it inserts a delay between the time
-when the other parameters become true and when
+Flight Time:: Time since boost was detected. Select a value and choose
+whether to activate the pyro channel before or after that amount of
+time.
+
+Ascending:: A simple test saying whether the rocket is going up or
+not. This is exactly equivalent to testing whether the speed is > 0.
+
+Descending:: A simple test saying whether the rocket is going down or
+not. This is exactly equivalent to testing whether the speed is < 0.
+
+After Motor:: The flight software counts each time the rocket starts
+accelerating and then decelerating (presumably due to a motor or
+motors burning). Use this value for multi-staged or multi-airstart
+launches.
+
+Delay:: This value doesn't perform any checks, instead it inserts a
+delay between the time when the other parameters become true and when

 the pyro channel is activated.
 
 Flight State:: The flight software tracks the flight
 the pyro channel is activated.
 
 Flight State:: The flight software tracks the flight


@@ -96,15 +89,11 @@ through a sequence of states:
 
  * Landed. The rocket is no longer moving.
 
 
  * Landed. The rocket is no longer moving.
 

-You can select a state to limit when the pyro
-channel may activate; note that the check is
-based on when the rocket transitions *into*
-the state, and so checking for “greater than
-Boost” means that the rocket is currently in
-boost or some later state.
-
-When a motor burns out, the rocket enters
-either Fast or Coast state (depending on how
-fast it is moving). If the computer detects
-upwards acceleration again, it will move back
-to Boost state.
+You can select a state to limit when the pyro channel may activate;
+note that the check is based on when the rocket transitions *into* the
+state, and so checking for “greater than Boost” means that the rocket
+is currently in boost or some later state.
+
+When a motor burns out, the rocket enters either Fast or Coast state
+(depending on how fast it is moving). If the computer detects upwards
+acceleration again, it will move back to Boost state.

diff --git a/doc/updating-firmware.inc b/doc/updating-firmware.inc
new file mode 100644 (file)
index 0000000..8b29558
--- /dev/null
+++ b/doc/updating-firmware.inc
@@ -0,0 +1,342 @@
+[appendix]
+== Updating Device Firmware
+
+       TeleMega, TeleMetrum v2, EasyMega, EasyMini and TeleDongle v3
+       are all programmed directly over their USB connectors (self
+       programming). TeleMetrum v1, TeleMini and TeleDongle v0.2 are
+       all programmed by using another device as a programmer (pair
+       programming). It's important to recognize which kind of devices
+       you have before trying to reprogram them.
+
+       You may wish to begin by ensuring you have current firmware
+       images.  These are distributed as part of the AltOS software
+       bundle that also includes the AltosUI ground station program.
+       Newer ground station versions typically work fine with older
+       firmware versions, so you don't need to update your devices
+       just to try out new software features.  You can always
+       download the most recent version from
+       http://www.altusmetrum.org/AltOS/
+
+       If you need to update the firmware on a TeleDongle v0.2, we
+       recommend updating the altimeter first, before updating
+       TeleDongle.  However, note that TeleDongle rarely need to be
+       updated.  Any firmware version 1.0.1 or later will work,
+       version 1.2.1 may have improved receiver performance slightly.
+
+       Self-programmable devices (TeleMega, TeleMetrum v2, EasyMega
+       and EasyMini) are reprogrammed by connecting them to your
+       computer over USB
+
+       === Updating TeleMega, TeleMetrum v2, EasyMega, EasyMini or TeleDongle v3 Firmware
+
+               . Attach a battery if necessary and power switch to
+                 the target device. Power up the device.
+
+               . Using a Micro USB cable, connect the target device to your
+                 computer's USB socket.
+
+               . Run AltosUI, and select 'Flash Image' from the File menu.
+
+               . Select the target device in the Device Selection dialog.
+
+               . Select the image you want to flash to the device,
+                 which should have a name in the form
+                 <product>-v<product-version>-<software-version>.ihx,
+                 such as TeleMega-v1.0-1.3.0.ihx.
+
+               . Make sure the configuration parameters are
+                 reasonable looking. If the serial number and/or RF
+                 configuration values aren't right, you'll need to
+                 change them.
+
+               . Hit the 'OK' button and the software should proceed
+                 to flash the device with new firmware, showing a
+                 progress bar.
+
+               . Verify that the device is working by using the
+                 'Configure Altimeter' or 'Configure Groundstation'
+                 item to check over the configuration.
+
+               ==== Recovering From Self-Flashing Failure
+
+                       If the firmware loading fails, it can leave the device
+                       unable to boot. Not to worry, you can force the device to
+                       start the boot loader instead, which will let you try to
+                       flash the device again.
+
+                       On each device, connecting two pins from one of the exposed
+                       connectors will force the boot loader to start, even if the
+                       regular operating system has been corrupted in some way.
+
+                       TeleMega::
+
+                       Connect pin 6 and pin 1 of the companion
+                       connector. Pin 1 can be identified by the square pad
+                       around it, and then the pins could sequentially across
+                       the board. Be very careful to *not* short pin 8 to
+                       anything as that is connected directly to the
+                       battery. Pin 7 carries 3.3V and the board will crash
+                       if that is connected to pin 1, but shouldn't damage
+                       the board.
+
+                       EasyMega::
+
+                       Connect pin 6 and pin 1 of the companion
+                       connector. Pin 1 can be identified by the square pad
+                       around it, and then the pins could sequentially across
+                       the board. Be very careful to *not* short pin 8 to
+                       anything as that is connected directly to the
+                       battery. Pin 7 carries 3.3V and the board will crash
+                       if that is connected to pin 1, but shouldn't damage
+                       the board.
+
+                       TeleMetrum v2::
+
+                       Connect pin 6 and pin 1 of the companion
+                       connector. Pin 1 can be identified by the square pad
+                       around it, and then the pins could sequentially across
+                       the board. Be very careful to *not* short pin 8 to
+                       anything as that is connected directly to the
+                       battery. Pin 7 carries 3.3V and the board will crash
+                       if that is connected to pin 1, but shouldn't damage
+                       the board.
+
+                       EasyMini::
+
+                       Connect pin 6 and pin 1 of the debug connector, which
+                       is the six holes next to the beeper. Pin 1 can be
+                       identified by the square pad around it, and then the
+                       pins could sequentially across the board, making Pin 6
+                       the one on the other end of the row.
+
+                       TeleDongle v3::
+
+                       Connect pin 32 on the CPU to ground. Pin 32 is closest
+                       to the USB wires on the row of pins towards the center
+                       of the board. Ground is available on the capacitor
+                       next to it, on the end towards the USB wires.
+
+                       Once you've located the right pins:
+
+                       . Turn the altimeter power off.
+
+                       . Connect a battery.
+
+                       . Connect the indicated terminals together with a
+                         short piece of wire. Take care not to accidentally
+                         connect anything else.
+
+                       . Connect USB
+
+                       . Turn the board power on.
+
+                       The board should now be visible over USB as
+                       'AltosFlash' and be ready to receive firmware.  Once
+                       the board has been powered up, you can remove the
+                       piece of wire.
+
+       === Pair Programming
+
+               The big concept to understand is that you have to use
+               a TeleMetrum v1.0, TeleBT v1.0 or TeleDongle v0.2 as a
+               programmer to update a pair programmed device. Due to
+               limited memory resources in the cc1111, we don't
+               support programming directly over USB for these
+               devices.
+
+               ==== Updating TeleMetrum v1.x Firmware
+
+                       . Find the 'programming cable' that you got as
+                         part of the starter kit, that has a red
+                         8-pin MicroMaTch connector on one end and a
+                         red 4-pin MicroMaTch connector on the other
+                         end.
+
+                       . Take the 2 screws out of the TeleDongle v0.2
+                         or TeleBT v1.0 case to get access to the
+                         circuit board.
+
+                       . Plug the 8-pin end of the programming cable
+                         to the matching connector on the TeleDongle
+                         v0.2 or TeleBT v1.0, and the 4-pin end to
+                         the matching connector on the TeleMetrum.
+                         Note that each MicroMaTch connector has an
+                         alignment pin that goes through a hole in
+                         the PC board when you have the cable
+                         oriented correctly.
+
+                       . Attach a battery to the TeleMetrum board.
+
+                       . Plug the TeleDongle v0.2 or TeleBT v1.0 into
+                         your computer's USB port, and power up the
+                         TeleMetrum.
+
+                       . Run AltosUI, and select 'Flash Image' from
+                         the File menu.
+
+                       . Pick the TeleDongle v0.2 or TeleBT v1.0
+                         device from the list, identifying it as the
+                         programming device.
+
+                       . Select the image you want put on the
+                         TeleMetrum, which should have a name in the
+                         form telemetrum-v1.2-1.0.0.ihx.  It should
+                         be visible in the default directory, if not
+                         you may have to poke around your system to
+                         find it.
+
+                       . Make sure the configuration parameters are
+                         reasonable looking. If the serial number
+                         and/or RF configuration values aren't right,
+                         you'll need to change them.
+
+                       . Hit the 'OK' button and the software should
+                         proceed to flash the TeleMetrum with new
+                         firmware, showing a progress bar.
+
+                       . Confirm that the TeleMetrum board seems to
+                         have updated OK, which you can do by
+                         plugging in to it over USB and using a
+                         terminal program to connect to the board and
+                         issue the 'v' command to check the version,
+                         etc.
+
+                       If something goes wrong, give it another try.
+
+               ==== Updating TeleMini Firmware
+
+                       You'll need a special 'programming cable' to
+                       reprogram the TeleMini.  You can make your own
+                       using an 8-pin MicroMaTch connector on one end
+                       and a set of four pins on the other.
+
+                       . Take the 2 screws out of the TeleDongle v0.2
+                         or TeleBT v1.0 case to get access to the
+                         circuit board.
+
+                       . Plug the 8-pin end of the programming cable
+                         to the matching connector on the TeleDongle
+                         v0.2 or TeleBT v1.0, and the 4-pins into the
+                         holes in the TeleMini circuit board.  Note
+                         that the MicroMaTch connector has an
+                         alignment pin that goes through a hole in
+                         the PC board when you have the cable
+                         oriented correctly, and that pin 1 on the
+                         TeleMini board is marked with a square pad
+                         while the other pins have round pads.
+
+                       . Attach a battery to the TeleMini board.
+
+                       . Plug the TeleDongle v0.2 or TeleBT v1.0 into
+                         your computer's USB port, and power up the
+                         TeleMini
+
+                       . Run AltosUI, and select 'Flash Image' from
+                         the File menu.
+
+                       . Pick the TeleDongle v0.2 or TeleBT v1.0
+                         device from the list, identifying it as the
+                         programming device.
+
+                       . Select the image you want put on the
+                         TeleMini, which should have a name in the
+                         form telemini-v1.0-1.0.0.ihx.  It should be
+                         visible in the default directory, if not you
+                         may have to poke around your system to find
+                         it.
+
+                       . Make sure the configuration parameters are
+                         reasonable looking. If the serial number
+                         and/or RF configuration values aren't right,
+                         you'll need to change them.
+
+                       . Hit the 'OK' button and the software should
+                         proceed to flash the TeleMini with new
+                         firmware, showing a progress bar.
+
+                       . Confirm that the TeleMini board seems to
+                         have updated OK, which you can do by
+                         configuring it over the radio link through
+                         the TeleDongle, or letting it come up in
+                         “flight” mode and listening for telemetry.
+
+                       If something goes wrong, give it another try.
+
+               ==== Updating TeleDongle v0.2 Firmware
+
+               Updating TeleDongle v0.2 firmware is just like
+               updating TeleMetrum v1.x or TeleMini firmware, but you
+               use either a TeleMetrum v1.x, TeleDongle v0.2 or
+               TeleBT v1.0 as the programmer.
+
+               . Find the 'programming cable' that you got as part of
+                 the starter kit, that has a red 8-pin MicroMaTch
+                 connector on one end and a red 4-pin MicroMaTch
+                 connector on the other end.
+
+               . Find the USB cable that you got as part of the
+                 starter kit, and plug the “mini” end in to the
+                 mating connector on TeleMetrum v1.x, TeleDongle v0.2
+                 or TeleBT v1.0.
+
+               . Take the 2 screws out of the TeleDongle v0.2 or
+                 TeleBT v1.0 case to get access to the circuit board.
+
+               . Plug the 8-pin end of the programming cable to the
+                 matching connector on the programmer, and the 4-pin
+                 end to the matching connector on the TeleDongle
+                 v0.2.  Note that each MicroMaTch connector has an
+                 alignment pin that goes through a hole in the PC
+                 board when you have the cable oriented correctly.
+
+               . Attach a battery to the TeleMetrum v1.x board if
+                 you're using one.
+
+               . Plug both the programmer and the TeleDongle into
+                 your computer's USB ports, and power up the
+                 programmer.
+
+               . Run AltosUI, and select 'Flash Image' from the File
+                 menu.
+
+               . Pick the programmer device from the list,
+                 identifying it as the programming device.
+
+
+               . Select the image you want put on the TeleDongle
+                 v0.2, which should have a name in the form
+                 teledongle-v0.2-1.0.0.ihx.  It should be visible in
+                 the default directory, if not you may have to poke
+                 around your system to find it.
+
+               . Make sure the configuration parameters are
+                 reasonable looking. If the serial number and/or RF
+                 configuration values aren't right, you'll need to
+                 change them.  The TeleDongle v0.2 serial number is
+                 on the “bottom” of the circuit board, and can
+                 usually be read through the translucent blue plastic
+                 case without needing to remove the board from the
+                 case.
+
+               . Hit the 'OK' button and the software should proceed
+                 to flash the TeleDongle v0.2 with new firmware,
+                 showing a progress bar.
+
+               . Confirm that the TeleDongle v0.2 board seems to have
+                 updated OK, which you can do by plugging in to it
+                 over USB and using a terminal program to connect to
+                 the board and issue the 'v' command to check the
+                 version, etc.  Once you're happy, remove the
+                 programming cable and put the cover back on the
+                 TeleDongle v0.2.
+
+               If something goes wrong, give it another try.
+
+               Be careful removing the programming cable from the
+               locking 8-pin connector on TeleMetrum.  You'll need a
+               fingernail or perhaps a thin screwdriver or knife
+               blade to gently pry the locking ears out slightly to
+               extract the connector.  We used a locking connector on
+               TeleMetrum to help ensure that the cabling to
+               companion boards used in a rocket don't ever come
+               loose accidentally in flight.

diff --git a/doc/using-am-products.inc b/doc/using-am-products.inc
new file mode 100644 (file)
index 0000000..8d7d005
--- /dev/null
+++ b/doc/using-am-products.inc
@@ -0,0 +1,148 @@
+== Using Altus Metrum Products
+
+       === Being Legal
+
+        First off, in the US, you need an
+        link:http://www.altusmetrum.org/Radio/[amateur radio license]
+        or other authorization to legally operate the radio
+        transmitters that are part of our products.
+
+
+       === In the Rocket
+
+               In the rocket itself, you just need a flight computer
+               and a single-cell, 3.7 volt nominal Li-Po rechargeable
+               battery.  An 850mAh battery weighs less than a 9V
+               alkaline battery, and will run a TeleMetrum, TeleMega
+               or EasyMega for hours.  A 110mAh battery weighs less
+               than a triple A battery and is a good choice for use
+               with TeleMini or EasyMini.
+
+               By default, we ship TeleMini, TeleMetrum and TeleMega
+               flight computers with a simple wire antenna.  If your
+               electronics bay or the air-frame it resides within is
+               made of carbon fiber, which is opaque to RF signals,
+               you may prefer to install an SMA connector so that you
+               can run a coaxial cable to an antenna mounted
+               elsewhere in the rocket.  However, note that the GPS
+               antenna is fixed on all current products, so you
+               really want to install the flight computer in a bay
+               made of RF-transparent materials if at all possible.
+
+       === On the Ground
+
+               To receive the data stream from the rocket, you need
+               an antenna and short feed-line connected to one of our
+               link:http://www.altusmetrum.org/TeleDongle/[TeleDongle]
+               units.  If possible, use an SMA to BNC adapter instead
+               of feedline between the antenna feedpoint and
+               TeleDongle, as this will give you the best
+               performance.  The TeleDongle in turn plugs directly
+               into the USB port on a notebook computer.  Because
+               TeleDongle looks like a simple serial port, your
+               computer does not require special device
+               drivers... just plug it in.
+
+               The GUI tool, AltosUI, is written in Java and runs
+               across Linux, Mac OS and Windows. There's also a suite
+               of C tools for Linux which can perform most of the
+               same tasks.
+
+               Alternatively, a TeleBT attached with an SMA to BNC
+               adapter at the feed point of a hand-held yagi used in
+               conjunction with an Android device running AltosDroid
+               makes an outstanding ground station.
+
+               After the flight, you can use the radio link to
+               extract the more detailed data logged in either
+               TeleMetrum or TeleMini devices, or you can use a mini
+               USB cable to plug into the TeleMetrum board directly.
+               Pulling out the data without having to open up the
+               rocket is pretty cool!  A USB cable is also how you
+               charge the Li-Po battery, so you'll want one of those
+               anyway... the same cable used by lots of digital
+               cameras and other modern electronic stuff will work
+               fine.
+
+               If your rocket lands out of sight, you may enjoy
+               having a hand-held GPS receiver, so that you can put
+               in a way-point for the last reported rocket position
+               before touch-down.  This makes looking for your rocket
+               a lot like Geo-Caching... just go to the way-point and
+               look around starting from there.  AltosDroid on an
+               Android device with GPS receiver works great for this,
+               too!
+
+               You may also enjoy having a ham radio “HT” that covers
+               the 70cm band... you can use that with your antenna to
+               direction-find the rocket on the ground the same way
+               you can use a Walston or Beeline tracker.  This can be
+               handy if the rocket is hiding in sage brush or a tree,
+               or if the last GPS position doesn't get you close
+               enough because the rocket dropped into a canyon, or
+               the wind is blowing it across a dry lake bed, or
+               something like that...  Keith currently uses a Yaesu
+               FT1D, Bdale has a Yaesu VX-7R, which is a nicer radio
+               in most ways but doesn't support APRS.
+
+               So, to recap, on the ground the hardware you'll need includes:
+
+               . an antenna and feed-line or adapter
+               . a TeleDongle
+               . a notebook computer
+               . optionally, a hand-held GPS receiver
+               . optionally, an HT or receiver covering 435 MHz
+
+               The best hand-held commercial directional antennas we've found for radio
+               direction finding rockets are from
+               link:http://www.arrowantennas.com/[Arrow Antennas].
+
+               The 440-3 and 440-5 are both good choices for finding
+               a TeleMetrum- or TeleMini- equipped rocket when used
+               with a suitable 70cm HT.  TeleDongle and an SMA to BNC
+               adapter fit perfectly between the driven element and
+               reflector of Arrow antennas.
+
+       === Data Analysis
+
+               Our software makes it easy to log the data from each
+               flight, both the telemetry received during the flight
+               itself, and the more complete data log recorded in the
+               flash memory on the altimeter board.  Once this data
+               is on your computer, our post-flight tools make it
+               easy to quickly get to the numbers everyone wants,
+               like apogee altitude, max acceleration, and max
+               velocity.  You can also generate and view a standard
+               set of plots showing the altitude, acceleration, and
+               velocity of the rocket during flight.  And you can
+               even export a TeleMetrum data file usable with Google
+               Maps and Google Earth for visualizing the flight path
+               in two or three dimensions!
+
+               Our ultimate goal is to emit a set of files for each
+               flight that can be published as a web page per flight,
+               or just viewed on your local disk with a web browser.
+
+       === Future Plans
+
+               We have designed and prototyped several “companion
+               boards” that can attach to the companion connector on
+               TeleMetrum, TeleMega and EasyMega flight computers to
+               collect more data, provide more pyro channels, and so
+               forth.  We do not yet know if or when any of these
+               boards will be produced in enough quantity to sell.
+               If you have specific interests for data collection or
+               control of events in your rockets beyond the
+               capabilities of our existing productions, please let
+               us know!
+
+               Because all of our work is open, both the hardware
+               designs and the software, if you have some great idea
+               for an addition to the current Altus Metrum family,
+               feel free to dive in and help!  Or let us know what
+               you'd like to see that we aren't already working on,
+               and maybe we'll get excited about it too...
+
+               Watch our link:http://altusmetrum.org/[web site] for
+               more news and information as our family of products
+               evolves!