From 7ef958cbb51a04079e2a4833917ccef57ae5a2ee Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Thu, 29 Oct 2015 20:32:58 -0700 Subject: [PATCH] doc: Add updating firmware and using am products asciidoc bits This finishes the asciidoc transition Signed-off-by: Keith Packard --- doc/Makefile | 2 + doc/altusmetrum.txt | 4 + doc/pyro-channels.inc | 61 +++---- doc/updating-firmware.inc | 342 ++++++++++++++++++++++++++++++++++++++ doc/using-am-products.inc | 148 +++++++++++++++++ 5 files changed, 521 insertions(+), 36 deletions(-) create mode 100644 doc/updating-firmware.inc create mode 100644 doc/using-am-products.inc diff --git a/doc/Makefile b/doc/Makefile index 818bd574..82ece0d5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -74,6 +74,8 @@ INC_FILES=\ telemega.inc \ easymega.inc \ installation.inc \ + using-am-products.inc \ + updating-firmware.inc \ altosui.inc \ altosdroid.inc \ system-operation.inc \ diff --git a/doc/altusmetrum.txt b/doc/altusmetrum.txt index 9f1bbf28..8dc18362 100644 --- a/doc/altusmetrum.txt +++ b/doc/altusmetrum.txt @@ -25,6 +25,8 @@ include::installation.raw[] + include::using-am-products.raw[] + include::altosui.raw[] include::altosdroid.raw[] @@ -33,6 +35,8 @@ include::handling.raw[] + include::updating-firmware.raw[] + include::flight-data-recording.raw[] include::specs.raw[] diff --git a/doc/pyro-channels.inc b/doc/pyro-channels.inc index 0da7db25..3b918544 100644 --- a/doc/pyro-channels.inc +++ b/doc/pyro-channels.inc @@ -47,30 +47,23 @@ pad and initialize the system. 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 @@ -96,15 +89,11 @@ through a sequence of states: * 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 index 00000000..8b29558c --- /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 + -v-.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 index 00000000..8d7d005a --- /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! -- 2.30.2