diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 12 | ||||
| -rw-r--r-- | doc/altos.xsl | 543 | ||||
| -rw-r--r-- | doc/altusmetrum.xsl | 373 | ||||
| -rw-r--r-- | doc/micropeak.xsl | 581 | ||||
| -rw-r--r-- | doc/release-notes-1.2.xsl | 94 | ||||
| -rw-r--r-- | doc/telemega-outline.pdf (renamed from doc/megametrum-outline.pdf) | bin | 4349 -> 4349 bytes | |||
| -rw-r--r-- | doc/telemega-outline.svg (renamed from doc/megametrum-outline.svg) | 0 | ||||
| -rw-r--r-- | doc/telemetrum.svg | 33 | ||||
| -rw-r--r-- | doc/telemini.svg | 31 |
9 files changed, 1493 insertions, 174 deletions
diff --git a/doc/Makefile b/doc/Makefile index 3e1626f0..7c4da29e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -8,16 +8,18 @@ RELNOTES=\ release-notes-0.9.html \ release-notes-0.9.2.html \ release-notes-1.0.1.html \ + release-notes-1.1.html \ release-notes-1.1.1.html \ - release-notes-1.1.html + release-notes-1.2.html RELNOTES_XSL=$(RELNOTES:.html=.xsl) -HTML=altusmetrum.html altos.html telemetry.html companion.html $(RELNOTES) -PDF=altusmetrum.pdf altos.pdf telemetry.pdf companion.pdf +HTML=altusmetrum.html altos.html telemetry.html companion.html micropeak.html $(RELNOTES) +PDF=altusmetrum.pdf altos.pdf telemetry.pdf companion.pdf micropeak.pdf DOC=$(HTML) $(PDF) HTMLSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl FOSTYLE=/usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl PDFSTYLE= +IMAGES=telemetrum.svg telemini.svg .SUFFIXES: .xsl .html .fo .pdf @@ -50,8 +52,8 @@ clean: distclean: rm -f $(HTML) $(PDF) *.fo -altusmetrum.html: $(RELNOTES_XSL) -altusmetrum.fo: $(RELNOTES_XSL) +altusmetrum.html: $(RELNOTES_XSL) $(IMAGES) +altusmetrum.fo: $(RELNOTES_XSL) $(IMAGES) indent: altusmetrum.xsl xmlindent -i 2 < altusmetrum.xsl > altusmetrum.new diff --git a/doc/altos.xsl b/doc/altos.xsl index 37bb58da..5af94725 100644 --- a/doc/altos.xsl +++ b/doc/altos.xsl @@ -25,6 +25,11 @@ </legalnotice> <revhistory> <revision> + <revnumber>1.1</revnumber> + <date>05 November 2012</date> + <revremark>Portable version</revremark> + </revision> + <revision> <revnumber>0.1</revnumber> <date>22 November 2010</date> <revremark>Initial content</revremark> @@ -34,15 +39,48 @@ <chapter> <title>Overview</title> <para> - AltOS is a operating system built for the 8051-compatible - processor found in the TI cc1111 microcontroller. It's designed - to be small and easy to program with. The main features are: + AltOS is a operating system built for a variety of + microcontrollers used in Altus Metrum devices. It has a simple + porting layer for each CPU while providing a convenient + operating enviroment for the developer. AltOS currently + supports three different CPUs: <itemizedlist> <listitem> - <para>Multi-tasking. While the 8051 doesn't provide separate - address spaces, it's often easier to write code that operates - in separate threads instead of tying everything into one giant - event loop. + <para> + STM32L series from ST Microelectronics. This ARM Cortex-M3 + based microcontroller offers low power consumption and a + wide variety of built-in peripherals. Altus Metrum uses + this in the TeleMega, MegaDongle and TeleLCO projects. + </para> + </listitem> + <listitem> + <para> + CC1111 from Texas Instruments. This device includes a + fabulous 10mW digital RF transceiver along with an + 8051-compatible processor core and a range of + peripherals. This is used in the TeleMetrum, TeleMini, + TeleDongle and TeleFire projects which share the need for + a small microcontroller and an RF interface. + </para> + </listitem> + <listitem> + <para> + ATmega32U4 from Atmel. This 8-bit AVR microcontroller is + one of the many used to create Arduino boards. The 32U4 + includes a USB interface, making it easy to connect to + other computers. Altus Metrum used this in prototypes of + the TeleScience and TelePyro boards; those have been + switched to the STM32L which is more capable and cheaper. + </para> + </listitem> + </itemizedlist> + Among the features of AltOS are: + <itemizedlist> + <listitem> + <para>Multi-tasking. While microcontrollers often don't + provide separate address spaces, it's often easier to write + code that operates in separate threads instead of tying + everything into one giant event loop. </para> </listitem> <listitem> @@ -110,6 +148,166 @@ </para> </chapter> <chapter> + <title>AltOS Porting Layer</title> + <para> + AltOS provides a CPU-independent interface to various common + microcontroller subsystems, including GPIO pins, interrupts, + SPI, I2C, USB and asynchronous serial interfaces. By making + these CPU-independent, device drivers, generic OS and + application code can all be written that work on any supported + CPU. Many of the architecture abstraction interfaces are + prefixed with ao_arch. + </para> + <section> + <title>Low-level CPU operations</title> + <para> + These primitive operations provide the abstraction needed to + run the multi-tasking framework while providing reliable + interrupt delivery. + </para> + <section> + <title>ao_arch_block_interrupts/ao_arch_release_interrupts</title> + <programlisting> + static inline void + ao_arch_block_interrupts(void); + + static inline void + ao_arch_release_interrupts(void); + </programlisting> + <para> + These disable/enable interrupt delivery, they may not + discard any interrupts. Use these for sections of code that + must be atomic with respect to any code run from an + interrupt handler. + </para> + </section> + <section> + <title>ao_arch_save_regs, ao_arch_save_stack, + ao_arch_restore_stack</title> + <programlisting> + static inline void + ao_arch_save_regs(void); + + static inline void + ao_arch_save_stack(void); + + static inline void + ao_arch_restore_stack(void); + </programlisting> + <para> + These provide all of the support needed to switch between + tasks.. ao_arch_save_regs must save all CPU registers to the + current stack, including the interrupt enable + state. ao_arch_save_stack records the current stack location + in the current ao_task structure. ao_arch_restore_stack + switches back to the saved stack, restores all registers and + branches to the saved return address. + </para> + </section> + <section> + <title>ao_arch_wait_interupt</title> + <programlisting> + #define ao_arch_wait_interrupt() + </programlisting> + <para> + This stops the CPU, leaving clocks and interrupts + enabled. When an interrupt is received, this must wake up + and handle the interrupt. ao_arch_wait_interrupt is entered + with interrupts disabled to ensure that there is no gap + between determining that no task wants to run and idling the + CPU. It must sleep the CPU, process interrupts and then + disable interrupts again. If the CPU doesn't have any + reduced power mode, this must at the least allow pending + interrupts to be processed. + </para> + </section> + </section> + <section> + <title>GPIO operations</title> + <para> + These functions provide an abstract interface to configure and + manipulate GPIO pins. + </para> + <section> + <title>GPIO setup</title> + <para> + These macros may be invoked at system initialization time to + configure pins as needed for system operation. One tricky + aspect is that some chips provide direct access to specific + GPIO pins while others only provide access to a whole + register full of pins. To support this, the GPIO macros + provide both port+bit and pin arguments. Simply define the + arguments needed for the target platform and leave the + others undefined. + </para> + <section> + <title>ao_enable_output</title> + <programlisting> + #define ao_enable_output(port, bit, pin, value) + </programlisting> + <para> + Set the specified port+bit (also called 'pin') for output, + initializing to the specified value. The macro must avoid + driving the pin with the opposite value if at all + possible. + </para> + </section> + <section> + <title>ao_enable_input</title> + <programlisting> + #define ao_enable_input(port, bit, mode) + </programlisting> + <para> + Sets the specified port/bit to be an input pin. 'mode' is + a combination of one or more of the following. Note that + some platforms may not support the desired mode. In that + case, the value will not be defined so that the program + will fail to compile. + <itemizedlist> + <listitem> + AO_EXTI_MODE_PULL_UP. Apply a pull-up to the pin; a + disconnected pin will read as 1. + </listitem> + <listitem> + AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to the pin; + a disconnected pin will read as 0. + </listitem> + <listitem> + 0. Don't apply either a pull-up or pull-down. A + disconnected pin will read an undetermined value. + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section> + <title>Reading and writing GPIO pins</title> + <para> + These macros read and write individual GPIO pins. + </para> + <section> + <title>ao_gpio_set</title> + <programlisting> + #define ao_gpio_set(port, bit, pin, value) + </programlisting> + <para> + Sets the specified port/bit or pin to the indicated value + </para> + </section> + <section> + <title>ao_gpio_get</title> + <programlisting> + #define ao_gpio_get(port, bit, pin) + </programlisting> + <para> + Returns either 1 or 0 depending on whether the input to + the pin is high or low. + </para> + </section> + </section> + </section> + </chapter> + <chapter> <title>Programming the 8051 with SDCC</title> <para> The 8051 is a primitive 8-bit processor, designed in the mists @@ -120,6 +318,10 @@ instruction set, it is not completely able to hide the memory architecture from the application designer. </para> + <para> + When built on other architectures, the various SDCC-specific + symbols are #defined as empty strings so they don't affect the compiler. + </para> <section> <title>8051 memory spaces</title> <para> @@ -278,7 +480,9 @@ __critical which blocks interrupts during the execution of that statement. Keeping critical sections as short as possible is key to ensuring that interrupts are handled as - quickly as possible. + quickly as possible. AltOS doesn't use this form in shared + code as other compilers wouldn't know what to do. Use + ao_arch_block_interrupts and ao_arch_release_interrupts instead. </para> </section> </section> @@ -328,15 +532,17 @@ </para> <para> Because ao_wakeup wakes every task waiting on a particular - location, ao_sleep should be used in a loop that first - checks the desired condition, blocks in ao_sleep and then - rechecks until the condition is satisfied. If the - location may be signaled from an interrupt handler, the - code will need to block interrupts by using the __critical - label around the block of code. Here's a complete example: + location, ao_sleep should be used in a loop that first checks + the desired condition, blocks in ao_sleep and then rechecks + until the condition is satisfied. If the location may be + signaled from an interrupt handler, the code will need to + block interrupts around the block of code. Here's a complete + example: <programlisting> - __critical while (!ao_radio_done) + ao_arch_block_interrupts(); + while (!ao_radio_done) ao_sleep(&ao_radio_done); + ao_arch_release_interrupts(); </programlisting> </para> </section> @@ -357,27 +563,34 @@ RFIF &= ~RFIF_IM_DONE; } </programlisting> - Note that this need not be enclosed in __critical as the - ao_sleep block can only be run from normal mode, and so - this sequence can never be interrupted with execution of - the other sequence. + Note that this need not block interrupts as the ao_sleep block + can only be run from normal mode, and so this sequence can + never be interrupted with execution of the other sequence. </para> </section> <section> <title>ao_alarm</title> <programlisting> void - ao_alarm(uint16_t delay) + ao_alarm(uint16_t delay); + + void + ao_clear_alarm(void); </programlisting> <para> - Schedules an alarm to fire in at least 'delay' ticks. If - the task is asleep when the alarm fires, it will wakeup - and ao_sleep will return 1. + Schedules an alarm to fire in at least 'delay' ticks. If the + task is asleep when the alarm fires, it will wakeup and + ao_sleep will return 1. ao_clear_alarm resets any pending + alarm so that it doesn't fire at some arbitrary point in the + future. <programlisting> ao_alarm(ao_packet_master_delay); - __critical while (!ao_radio_dma_done) + ao_arch_block_interrupts(); + while (!ao_radio_dma_done) if (ao_sleep(&ao_radio_dma_done) != 0) ao_radio_abort(); + ao_arch_release_interrupts(); + ao_clear_alarm(); </programlisting> In this example, a timeout is set before waiting for incoming radio data. If no data is received before the @@ -389,7 +602,7 @@ <title>ao_start_scheduler</title> <programlisting> void - ao_start_scheduler(void) + ao_start_scheduler(void); </programlisting> <para> This is called from 'main' when the system is all @@ -400,26 +613,22 @@ <title>ao_clock_init</title> <programlisting> void - ao_clock_init(void) + ao_clock_init(void); </programlisting> <para> - This turns on the external 48MHz clock then switches the - hardware to using it. This is required by many of the - internal devices like USB. It should be called by the - 'main' function first, before initializing any of the - other devices in the system. + This initializes the main CPU clock and switches to it. </para> </section> </chapter> <chapter> <title>Timer Functions</title> <para> - AltOS sets up one of the cc1111 timers to run at 100Hz and + AltOS sets up one of the CPU timers to run at 100Hz and exposes this tick as the fundemental unit of time. At each interrupt, AltOS increments the counter, and schedules any tasks - waiting for that time to pass, then fires off the ADC system to + waiting for that time to pass, then fires off the sensors to collect current data readings. Doing this from the ISR ensures - that the ADC values are sampled at a regular rate, independent + that the values are sampled at a regular rate, independent of any scheduling jitter. </para> <section> @@ -462,9 +671,9 @@ ao_timer_init(void) </programlisting> <para> - This turns on the 100Hz tick using the CC1111 timer 1. It - is required for any of the time-based functions to - work. It should be called by 'main' before ao_start_scheduler. + This turns on the 100Hz tick. It is required for any of the + time-based functions to work. It should be called by 'main' + before ao_start_scheduler. </para> </section> </chapter> @@ -502,13 +711,20 @@ </section> </chapter> <chapter> - <title>CC1111 DMA engine</title> + <title>DMA engine</title> + <para> + The CC1111 and STM32L both contain a useful bit of extra + hardware in the form of a number of programmable DMA + engines. They can be configured to copy data in memory, or + between memory and devices (or even between two devices). AltOS + exposes a general interface to this hardware and uses it to + handle both internal and external devices. + </para> <para> - The CC1111 contains a useful bit of extra hardware in the form - of five programmable DMA engines. They can be configured to copy - data in memory, or between memory and devices (or even between - two devices). AltOS exposes a general interface to this hardware - and uses it to handle radio and SPI data. + Because the CC1111 and STM32L DMA engines are different, the + interface to them is also different. As the DMA engines are + currently used to implement platform-specific drivers, this + isn't yet a problem. </para> <para> Code using a DMA engine should allocate one at startup @@ -524,83 +740,170 @@ transfer is usually initiated by software. </para> <section> - <title>ao_dma_alloc</title> - <programlisting> - uint8_t - ao_dma_alloc(__xdata uint8_t *done) - </programlisting> - <para> - Allocates a DMA engine, returning the identifier. Whenever - this DMA engine completes a transfer. 'done' is cleared - when the DMA is started, and then receives the - AO_DMA_DONE bit on a successful transfer or the - AO_DMA_ABORTED bit if ao_dma_abort was called. Note that - it is possible to get both bits if the transfer was - aborted after it had finished. - </para> - </section> - <section> - <title>ao_dma_set_transfer</title> - <programlisting> - void - ao_dma_set_transfer(uint8_t id, - void __xdata *srcaddr, - void __xdata *dstaddr, - uint16_t count, - uint8_t cfg0, - uint8_t cfg1) - </programlisting> - <para> - Initializes the specified dma engine to copy data - from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and - cfg1 are values directly out of the CC1111 documentation - and tell the DMA engine what the transfer unit size, - direction and step are. - </para> - </section> - <section> - <title>ao_dma_start</title> - <programlisting> - void - ao_dma_start(uint8_t id); - </programlisting> - <para> - Arm the specified DMA engine and await a signal from - either hardware or software to start transferring data. - </para> - </section> - <section> - <title>ao_dma_trigger</title> - <programlisting> - void - ao_dma_trigger(uint8_t id) - </programlisting> - <para> - Trigger the specified DMA engine to start copying data. - </para> + <title>CC1111 DMA Engine</title> + <section> + <title>ao_dma_alloc</title> + <programlisting> + uint8_t + ao_dma_alloc(__xdata uint8_t *done) + </programlisting> + <para> + Allocate a DMA engine, returning the identifier. 'done' is + cleared when the DMA is started, and then receives the + AO_DMA_DONE bit on a successful transfer or the + AO_DMA_ABORTED bit if ao_dma_abort was called. Note that it + is possible to get both bits if the transfer was aborted + after it had finished. + </para> + </section> + <section> + <title>ao_dma_set_transfer</title> + <programlisting> + void + ao_dma_set_transfer(uint8_t id, + void __xdata *srcaddr, + void __xdata *dstaddr, + uint16_t count, + uint8_t cfg0, + uint8_t cfg1) + </programlisting> + <para> + Initializes the specified dma engine to copy data + from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and + cfg1 are values directly out of the CC1111 documentation + and tell the DMA engine what the transfer unit size, + direction and step are. + </para> + </section> + <section> + <title>ao_dma_start</title> + <programlisting> + void + ao_dma_start(uint8_t id); + </programlisting> + <para> + Arm the specified DMA engine and await a signal from + either hardware or software to start transferring data. + </para> + </section> + <section> + <title>ao_dma_trigger</title> + <programlisting> + void + ao_dma_trigger(uint8_t id) + </programlisting> + <para> + Trigger the specified DMA engine to start copying data. + </para> + </section> + <section> + <title>ao_dma_abort</title> + <programlisting> + void + ao_dma_abort(uint8_t id) + </programlisting> + <para> + Terminate any in-progress DMA transation, marking its + 'done' variable with the AO_DMA_ABORTED bit. + </para> + </section> </section> <section> - <title>ao_dma_abort</title> - <programlisting> - void - ao_dma_abort(uint8_t id) - </programlisting> - <para> - Terminate any in-progress DMA transation, marking its - 'done' variable with the AO_DMA_ABORTED bit. - </para> + <title>STM32L DMA Engine</title> + <section> + <title>ao_dma_alloc</title> + <programlisting> + uint8_t ao_dma_done[]; + + void + ao_dma_alloc(uint8_t index); + </programlisting> + <para> + Reserve a DMA engine for exclusive use by one + driver. + </para> + </section> + <section> + <title>ao_dma_set_transfer</title> + <programlisting> + void + ao_dma_set_transfer(uint8_t id, + void *peripheral, + void *memory, + uint16_t count, + uint32_t ccr); + </programlisting> + <para> + Initializes the specified dma engine to copy data between + 'peripheral' and 'memory' for 'count' units. 'ccr' is a + value directly out of the STM32L documentation and tells the + DMA engine what the transfer unit size, direction and step + are. + </para> + </section> + <section> + <title>ao_dma_set_isr</title> + <programlisting> + void + ao_dma_set_isr(uint8_t index, void (*isr)(int)) + </programlisting> + <para> + This sets a function to be called when the DMA transfer + completes in lieu of setting the ao_dma_done bits. Use this + when some work needs to be done when the DMA finishes that + cannot wait until user space resumes. + </para> + </section> + <section> + <title>ao_dma_start</title> + <programlisting> + void + ao_dma_start(uint8_t id); + </programlisting> + <para> + Arm the specified DMA engine and await a signal from either + hardware or software to start transferring data. + 'ao_dma_done[index]' is cleared when the DMA is started, and + then receives the AO_DMA_DONE bit on a successful transfer + or the AO_DMA_ABORTED bit if ao_dma_abort was called. Note + that it is possible to get both bits if the transfer was + aborted after it had finished. + </para> + </section> + <section> + <title>ao_dma_done_transfer</title> + <programlisting> + void + ao_dma_done_transfer(uint8_t id); + </programlisting> + <para> + Signals that a specific DMA engine is done being used. This + allows multiple drivers to use the same DMA engine safely. + </para> + </section> + <section> + <title>ao_dma_abort</title> + <programlisting> + void + ao_dma_abort(uint8_t id) + </programlisting> + <para> + Terminate any in-progress DMA transation, marking its + 'done' variable with the AO_DMA_ABORTED bit. + </para> + </section> </section> </chapter> <chapter> - <title>SDCC Stdio interface</title> + <title>Stdio interface</title> <para> - AltOS offers a stdio interface over both USB and the RF packet - link. This provides for control of the device localy or - remotely. This is hooked up to the stdio functions in SDCC by - providing the standard putchar/getchar/flush functions. These - automatically multiplex the two available communication - channels; output is always delivered to the channel which - provided the most recent input. + AltOS offers a stdio interface over USB, serial and the RF + packet link. This provides for control of the device localy or + remotely. This is hooked up to the stdio functions by providing + the standard putchar/getchar/flush functions. These + automatically multiplex the available communication channels; + output is always delivered to the channel which provided the + most recent input. </para> <section> <title>putchar</title> @@ -673,9 +976,9 @@ <para> AltOS includes a simple command line parser which is hooked up to the stdio interfaces permitting remote control of the device - over USB or the RF link as desired. Each command uses a single - character to invoke it, the remaining characters on the line are - available as parameters to the command. + over USB, serial or the RF link as desired. Each command uses a + single character to invoke it, the remaining characters on the + line are available as parameters to the command. </para> <section> <title>ao_cmd_register</title> @@ -828,9 +1131,9 @@ </section> </chapter> <chapter> - <title>CC1111 USB target device</title> + <title>USB target device</title> <para> - The CC1111 contains a full-speed USB target device. It can be + AltOS contains a full-speed USB target device driver. It can be programmed to offer any kind of USB target, but to simplify interactions with a variety of operating systems, AltOS provides only a single target device profile, that of a USB modem which @@ -945,7 +1248,7 @@ </section> </chapter> <chapter> - <title>CC1111 Serial peripheral</title> + <title>Serial peripherals</title> <para> The CC1111 provides two USART peripherals. AltOS uses one for asynch serial data, generally to communicate with a GPS device, diff --git a/doc/altusmetrum.xsl b/doc/altusmetrum.xsl index b2677a02..294f30ac 100644 --- a/doc/altusmetrum.xsl +++ b/doc/altusmetrum.xsl @@ -3,7 +3,7 @@ "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"> <book> <title>The Altus Metrum System</title> - <subtitle>An Owner's Manual for TeleMetrum, TeleMini and TeleDongle Devices</subtitle> + <subtitle>An Owner's Manual for TeleMetrum, TeleMini, TeleDongle and TeleBT Devices</subtitle> <bookinfo> <author> <firstname>Bdale</firstname> @@ -22,7 +22,7 @@ <surname>Towns</surname> </author> <copyright> - <year>2012</year> + <year>2013</year> <holder>Bdale Garbee and Keith Packard</holder> </copyright> <legalnotice> @@ -36,6 +36,15 @@ </legalnotice> <revhistory> <revision> + <revnumber>1.2</revnumber> + <date>14 April 2013</date> + <revremark> + Updated for software version 1.2. Version 1.2 adds support + for TeleBT and AltosDroid. It also adds a few minor features + and fixes a few minor bugs in AltosUI and the AltOS firmware. + </revremark> + </revision> + <revision> <revnumber>1.1.1</revnumber> <date>16 September 2012</date> <revremark> @@ -122,21 +131,28 @@ NAR #88757, TRA #12200 support optional capabilities in the future. </para> <para> - The newest device is TeleMini, a dual deploy altimeter with + Our second device was TeleMini, a dual deploy altimeter with radio telemetry and radio direction finding. This device is only 13mm by 38mm (½ inch by 1½ inches) and can fit easily in an 18mm air-frame. </para> <para> - Complementing TeleMetrum and TeleMini is TeleDongle, a USB to RF - interface for communicating with the altimeters. Combined with your - choice of antenna and - notebook computer, TeleDongle and our associated user interface software - form a complete ground station capable of logging and displaying in-flight - telemetry, aiding rocket recovery, then processing and archiving flight + TeleDongle was our first ground station, providing a USB to RF + interfaces for communicating with the altimeters. Combined with + your choice of antenna and notebook computer, TeleDongle and our + associated user interface software form a complete ground + station capable of logging and displaying in-flight telemetry, + aiding rocket recovery, then processing and archiving flight data for analysis and review. </para> <para> + For a slightly more portable ground station experience that also + provides direct rocket recovery support, TeleBT offers flight + monitoring and data logging using a Bluetooth connection between + the receiver and an Android device that has the Altos Droid + application installed from the Google Play store. + </para> + <para> More products will be added to the Altus Metrum family over time, and we currently envision that this will be a single, comprehensive manual for the entire product family. @@ -172,8 +188,9 @@ NAR #88757, TRA #12200 <para> The TeleMini battery can be charged by disconnecting it from the TeleMini board and plugging it into a standalone battery charger - board, and connecting that via a USB cable to a laptop or other USB - power source + such as the LipoCharger product included in TeleMini Starter Kits, + and connecting that via a USB cable to a laptop or other USB + power source. </para> <para> The other active device in the starter kit is the TeleDongle USB to @@ -196,6 +213,16 @@ NAR #88757, TRA #12200 The latest version may always be downloaded from <ulink url="http://altusmetrum.org/AltOS"/>. </para> + <para> + If you're using a TeleBT instead of the TeleDongle, you'll want + to go install the Altos Droid application from the Google Play + store. You don't need a data plan to use Altos Droid, but + without network access, the Map view will be less useful as it + won't contain any map data. You can also use TeleBT connected + over USB with your laptop computer; it acts exactly like a + TeleDongle. Anywhere this manual talks about TeleDongle, you can + also read that as 'and TeleBT when connected via USB'. + </para> </chapter> <chapter> <title>Handling Precautions</title> @@ -278,6 +305,19 @@ NAR #88757, TRA #12200 designed for use with single-cell batteries with 3.7 volts nominal. </para> <para> + The battery connectors are a standard 2-pin JST connector and + match batteries sold by Spark Fun. These batteries are + single-cell Lithium Polymer batteries that nominally provide 3.7 + volts. Other vendors sell similar batteries for RC aircraft + using mating connectors, however the polarity for those is + generally reversed from the batteries used by Altus Metrum + products. In particular, the Tenergy batteries supplied for use + in Featherweight flight computers are not compatible with Altus + Metrum flight computers or battery chargers. <emphasis>Check + polarity and voltage before connecting any battery not purchased + from Altus Metrum or Spark Fun.</emphasis> + </para> + <para> By default, we use the unregulated output of the Li-Po battery directly to fire ejection charges. This works marvelously with standard low-current e-matches like the J-Tek from MJG Technologies, and with @@ -350,15 +390,15 @@ NAR #88757, TRA #12200 flights, do what makes sense. </para> <para> - If idle mode is entered, you will hear an audible "di-dit" or see - two short flashes ("I" for idle), and the flight state machine is - disengaged, thus no ejection charges will fire. The altimeters also - listen for the radio link when in idle mode for requests sent via - TeleDongle. Commands can be issued to a TeleMetrum in idle mode - over either - USB or the radio link equivalently. TeleMini only has the radio link. - Idle mode is useful for configuring the altimeter, for extracting data - from the on-board storage chip after flight, and for ground testing + If idle mode is entered, you will hear an audible "di-dit" or + see two short flashes ("I" for idle), and the flight state + machine is disengaged, thus no ejection charges will fire. + The altimeters also listen for the radio link when in idle + mode for requests sent via TeleDongle. Commands can be issued + to a TeleMetrum in idle mode over either USB or the radio link + equivalently. TeleMini only has the radio link. Idle mode is + useful for configuring the altimeter, for extracting data from + the on-board storage chip after flight, and for ground testing pyro charges. </para> <para> @@ -372,6 +412,36 @@ NAR #88757, TRA #12200 tower with a screw-driver trying to turn on your avionics before installing igniters! </para> + <para> + TeleMini is configured via the radio link. Of course, that + means you need to know the TeleMini radio configuration values + or you won't be able to communicate with it. For situations + when you don't have the radio configuration values, TeleMini + offers an 'emergency recovery' mode. In this mode, TeleMini is + configured as follows: + <itemizedlist> + <listitem> + Sets the radio frequency to 434.550MHz + </listitem> + <listitem> + Sets the radio calibration back to the factory value. + </listitem> + <listitem> + Sets the callsign to N0CALL + </listitem> + <listitem> + Does not go to 'pad' mode after five seconds. + </listitem> + </itemizedlist> + </para> + <para> + To get into 'emergency recovery' mode, first find the row of + four small holes opposite the switch wiring. Using a short + piece of small gauge wire, connect the outer two holes + together, then power TeleMini up. Once the red LED is lit, + disconnect the wire and the board should signal that it's in + 'idle' mode after the initial five second startup period. + </para> </section> <section> <title>GPS </title> @@ -399,11 +469,12 @@ NAR #88757, TRA #12200 <section> <title>Controlling An Altimeter Over The Radio Link</title> <para> - One of the unique features of the Altus Metrum system is - the ability to create a two way command link between TeleDongle - and an altimeter using the digital radio transceivers built into - each device. This allows you to interact with the altimeter from - afar, as if it were directly connected to the computer. + One of the unique features of the Altus Metrum system is the + ability to create a two way command link between TeleDongle + and an altimeter using the digital radio transceivers + built into each device. This allows you to interact with the + altimeter from afar, as if it were directly connected to the + computer. </para> <para> Any operation which can be performed with TeleMetrum can @@ -481,7 +552,7 @@ NAR #88757, TRA #12200 <para> You can monitor the operation of the radio link by watching the lights on the devices. The red LED will flash each time a packet - is tramsitted, while the green LED will light up on TeleDongle when + is transmitted, while the green LED will light up on TeleDongle when it is waiting to receive a packet from the altimeter. </para> </section> @@ -756,6 +827,15 @@ NAR #88757, TRA #12200 incorrect data from being reported. </para> </listitem> + <listitem> + <para> + 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. + </para> + </listitem> </itemizedlist> <para> Finally, the largest portion of the window contains a set of @@ -1529,6 +1609,151 @@ NAR #88757, TRA #12200 </section> </chapter> <chapter> + <title>AltosDroid</title> + <para> + AltosDroid provides the same flight monitoring capabilities as + AltosUI, but runs on Android devices and is designed to connect + to a TeleBT receiver over Bluetooth™. Altos Droid monitors + telemetry data, logging it to internal storage in the Android + device, and presents that data in a UI the same way the 'Monitor + Flight' window does in AltosUI. + </para> + <para> + This manual will explain how to configure AltosDroid, connect + to TeleBT, operate the flight monitoring interface and describe + what the displayed data means. + </para> + <section> + <title>Installing AltosDroid</title> + <para> + AltosDroid is included in the Google Play store. To install + it on your Android device, open open the Google Play Store + application and search for "altosdroid". Make sure you don't + have a space between "altos" and "droid" or you probably won't + find what you want. That should bring you to the right page + from which you can download and install the application. + </para> + </section> + <section> + <title>Connecting to TeleBT</title> + <para> + Press the Android 'Menu' button or soft-key to see the + configuration options available. Select the 'Connect a device' + option and then the 'Scan for devices' entry at the bottom to + look for your TeleBT device. Select your device, and when it + asks for the code, enter '1234'. + </para> + <para> + Subsequent connections will not require you to enter that + code, and your 'paired' device will appear in the list without + scanning. + </para> + </section> + <section> + <title>Configuring AltosDroid</title> + <para> + The only configuration option available for AltosDroid is + which frequency to listen on. Press the Android 'Menu' button + or soft-key and pick the 'Select radio frequency' entry. That + brings up a menu of pre-set radio frequencies; pick the one + which matches your altimeter. + </para> + </section> + <section> + <title>Altos Droid Flight Monitoring</title> + <para> + Altos Droid is designed to mimic the AltosUI flight monitoring + display, providing separate tabs for each stage of your rocket + flight along with a tab containing a map of the local area + with icons marking the current location of the altimeter and + the Android device. + </para> + <section> + <title>Pad</title> + <para> + 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: + <itemizedlist> + <listitem> + <para> + Battery Voltage. This indicates whether the Li-Po battery + powering the TeleMetrum has sufficient charge to last for + the duration of the flight. A value of more than + 3.7V is required for a 'GO' status. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. TeleMetrum can store multiple flights, depending + on the configured maximum flight log size. TeleMini + 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. + </para> + </listitem> + <listitem> + <para> + GPS Locked. For a TeleMetrum 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. + </para> + </listitem> + <listitem> + <para> + GPS Ready. For a TeleMetrum 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. + </para> + </listitem> + </itemizedlist> + <para> + The Launchpad tab also shows the computed launch pad position + and altitude, averaging many reported positions to improve the + accuracy of the fix. + </para> + </para> + </section> + </section> + <section> + <title>Downloading Flight Logs</title> + <para> + Altos Droid always saves every bit of telemetry data it + receives. To download that to a computer for use with AltosUI, + simply remove the SD card from your Android device, or connect + your device to your computer's USB port and browse the files + on that device. You will find '.telem' files in the TeleMetrum + directory that will work with AltosUI directly. + </para> + </section> + </chapter> + <chapter> <title>Using Altus Metrum Products</title> <section> <title>Being Legal</title> @@ -1561,7 +1786,9 @@ NAR #88757, TRA #12200 <title>On the Ground</title> <para> To receive the data stream from the rocket, you need an antenna and short - feed-line connected to one of our <ulink url="http://www.altusmetrum.org/TeleDongle/">TeleDongle</ulink> units. The + feed-line connected to one of our <ulink url="http://www.altusmetrum.org/TeleDongle/">TeleDongle</ulink> 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. @@ -1598,7 +1825,7 @@ NAR #88757, TRA #12200 So, to recap, on the ground the hardware you'll need includes: <orderedlist inheritnum='inherit' numeration='arabic'> <listitem> - an antenna and feed-line + an antenna and feed-line or adapter </listitem> <listitem> a TeleDongle @@ -1621,7 +1848,9 @@ NAR #88757, TRA #12200 Arrow Antennas. </ulink> 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. + 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. </para> </section> <section> @@ -1647,22 +1876,36 @@ NAR #88757, TRA #12200 <section> <title>Future Plans</title> <para> - In the future, we intend to offer "companion boards" for the rocket that will - plug in to TeleMetrum to collect additional data, provide more pyro channels, - and so forth. + In the future, we intend to offer "companion boards" for the rocket + that will plug in to TeleMetrum to collect additional data, provide + more pyro channels, and so forth. + </para> + <para> + Also under design is a new flight computer with more sensors, more + pyro channels, and a more powerful radio system designed for use + in multi-stage, complex, and extreme altitude projects. + </para> + <para> + We are also working on alternatives to TeleDongle. One is a + a stand-alone, hand-held ground terminal that will allow monitoring + the rocket's status, collecting data during flight, and logging data + after flight without the need for a notebook computer on the + flight line. Particularly since it is so difficult to read most + notebook screens in direct sunlight, we think this will be a great + thing to have. We are also working on a TeleDongle variant with + Bluetooth that will work with Android phones and tablets. </para> <para> - We are also working on the design of a hand-held ground terminal that will - allow monitoring the rocket's status, collecting data during flight, and - logging data after flight without the need for a notebook computer on the - flight line. Particularly since it is so difficult to read most notebook - screens in direct sunlight, we think this will be a great thing to have. + 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... </para> <para> - 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 + <ulink url="http://altusmetrum.org/">web site</ulink> for more news + and information as our family of products evolves! </para> </section> </chapter> @@ -2199,7 +2442,7 @@ NAR #88757, TRA #12200 </listitem> <listitem> <para> - RF interface for battery charging, configuration, and data recovery. + RF interface for configuration, and data recovery. </para> </listitem> <listitem> @@ -2470,6 +2713,37 @@ NAR #88757, TRA #12200 </para> </appendix> <appendix> + <title>Drill Templates</title> + <para> + These images, when printed, provide precise templates for the + mounting holes in Altus Metrum flight computers + </para> + <section> + <title>TeleMetrum template</title> + <para> + TeleMetrum has overall dimensions of 1.000 x 2.750 inches, and the + mounting holes are sized for use with 4-40 or M3 screws. + </para> + <mediaobject id="TeleMetrumTemplate"> + <imageobject> + <imagedata format="SVG" fileref="telemetrum.svg"/> + </imageobject> + </mediaobject> + </section> + <section> + <title>TeleMini template</title> + <para> + TeleMini has overall dimensions of 0.500 x 1.500 inches, and the + mounting holes are sized for use with 2-56 or M2 screws. + </para> + <mediaobject id="TeleMiniTemplate"> + <imageobject> + <imagedata format="SVG" fileref="telemini.svg"/> + </imageobject> + </mediaobject> + </section> + </appendix> + <appendix> <title>Calibration</title> <para> There are only two calibrations required for a TeleMetrum board, and @@ -2577,13 +2851,14 @@ NAR #88757, TRA #12200 <appendix xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Release Notes</title> - <xi:include href="release-notes-1.1.1.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-1.1.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-1.0.1.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-0.9.2.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-0.9.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-0.8.xsl" xpointer="xpointer(/article/*)"/> - <xi:include href="release-notes-0.7.1.xsl" xpointer="xpointer(/article/*)"/> + <simplesect><title>Version 1.2</title><xi:include href="release-notes-1.2.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 1.1.1</title><xi:include href="release-notes-1.1.1.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 1.1</title><xi:include href="release-notes-1.1.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 1.0.1</title><xi:include href="release-notes-1.0.1.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 0.9.2</title><xi:include href="release-notes-0.9.2.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 0.9</title><xi:include href="release-notes-0.9.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 0.8</title><xi:include href="release-notes-0.8.xsl" xpointer="xpointer(/article/*)"/></simplesect> + <simplesect><title>Version 0.7.1</title><xi:include href="release-notes-0.7.1.xsl" xpointer="xpointer(/article/*)"/></simplesect> </appendix> </book> diff --git a/doc/micropeak.xsl b/doc/micropeak.xsl new file mode 100644 index 00000000..96179d01 --- /dev/null +++ b/doc/micropeak.xsl @@ -0,0 +1,581 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"> +<book> + <title>MicroPeak Owner's Manual</title> + <subtitle>A recording altimeter for hobby rocketry</subtitle> + <bookinfo> + <author> + <firstname>Keith</firstname> + <surname>Packard</surname> + </author> + <copyright> + <year>2012</year> + <holder>Bdale Garbee and Keith Packard</holder> + </copyright> + <legalnotice> + <para> + This document is released under the terms of the + <ulink url="http://creativecommons.org/licenses/by-sa/3.0/"> + Creative Commons ShareAlike 3.0 + </ulink> + license. + </para> + </legalnotice> + <revhistory> + <revision> + <revnumber>0.1</revnumber> + <date>29 October 2012</date> + <revremark> + Initial release with preliminary hardware. + </revremark> + </revision> + <revision> + <revnumber>1.0</revnumber> + <date>18 November 2012</date> + <revremark> + Updates for version 1.0 release. + </revremark> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>12 December 2012</date> + <revremark> + Add comments about EEPROM storage format and programming jig. + </revremark> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>20 January 2013</date> + <revremark> + Add documentation for the MicroPeak USB adapter board. Note + the switch to a Kalman filter for peak altitude + determination. + </revremark> + </revision> + </revhistory> + </bookinfo> + <acknowledgements> + <para> + Thanks to John Lyngdal for suggesting that we build something like this. + </para> + <para> + Have fun using these products, and we hope to meet all of you + out on the rocket flight line somewhere. + <literallayout> +Bdale Garbee, KB0G +NAR #87103, TRA #12201 + +Keith Packard, KD7SQG +NAR #88757, TRA #12200 + </literallayout> + </para> + </acknowledgements> + <chapter> + <title>Quick Start Guide</title> + <para> + MicroPeak is designed to be easy to use. Requiring no external + components, flying takes just a few steps + </para> + <itemizedlist> + <listitem> + <para> + Install the battery. Fit a CR1025 battery into the plastic + carrier. The positive (+) terminal should be towards the more + open side of the carrier. Slip the carrier into the battery + holder with the positive (+) terminal facing away from the + circuit board. + </para> + </listitem> + <listitem> + <para> + Install MicroPeak in your rocket. This can be as simple as + preparing a soft cushion of wadding inside a vented model payload + bay. Wherever you mount it, make sure you protect the + barometric sensor from corrosive ejection gasses as those + will damage the sensor, and shield it from light as that can + cause incorrect sensor readings. + </para> + </listitem> + <listitem> + <para> + Turn MicroPeak on. Slide the switch so that the actuator + covers the '1' printed on the board. MicroPeak will report + the maximum height of the last flight in decimeters using a + sequence of flashes on the LED. A sequence of short flashes + indicates one digit. A single long flash indicates zero. The + height is reported in decimeters, so the last digit will be + tenths of a meter. For example, if MicroPeak reports 5 4 4 + 3, then the maximum height of the last flight was 544.3m, or + 1786 feet. + </para> + </listitem> + <listitem> + <para> + Finish preparing the rocket for flight. After the + previous flight data have been reported, MicroPeak waits for + 30 seconds before starting to check for launch. This gives + you time to finish assembling the rocket. As those + activities might cause pressure changes inside the airframe, + MicroPeak might accidentally detect boost. If you need to do + anything to the airframe after the 30 second window passes, + make sure to be careful not to disturb the altimeter. The + LED will remain dark during the 30 second delay, but after + that, it will start blinking once every 3 seconds. + </para> + </listitem> + <listitem> + <para> + Fly the rocket. Once the rocket passes about 10m in height + (32 feet), the micro-controller will record the ground + pressure and track the pressure seen during the flight. In + this mode, the LED flickers rapidly. When the rocket lands, + and the pressure stabilizes, the micro-controller will record + the minimum pressure pressure experienced during the flight, + compute the height represented by the difference in air + pressure and blink that value out on the LED. After that, + MicroPeak powers down to conserve battery power. + </para> + </listitem> + <listitem> + <para> + Recover the data. Turn MicroPeak off and then back on. MicroPeak + will blink out the maximum height for the last flight. Turn + MicroPeak back off to conserve battery power. + </para> + </listitem> + </itemizedlist> + </chapter> + <chapter> + <title>Handling Precautions</title> + <para> + All Altus Metrum products are sophisticated electronic devices. + When handled gently and properly installed in an air-frame, they + will deliver impressive results. However, as with all electronic + devices, there are some precautions you must take. + </para> + <para> + The CR1025 Lithium batteries have an + extraordinary power density. This is great because we can fly with + much less battery mass... but if they are punctured + or their contacts are allowed to short, they can and will release their + energy very rapidly! + Thus we recommend that you take some care when handling MicroPeak + to keep conductive material from coming in contact with the exposed metal elements. + </para> + <para> + The barometric sensor used in MicroPeak is sensitive to + sunlight. Please consider this when designing an + installation. Many model rockets with payload bays use clear + plastic for the payload bay. Replacing these with an opaque + cardboard tube, painting them, or wrapping them with a layer of + masking tape are all reasonable approaches to keep the sensor + out of direct sunlight. + </para> + <para> + The barometric sensor sampling ports must be able to "breathe", + both by not being covered by foam or tape or other materials that might + directly block the hole on the top of the sensor, and also by having a + suitable static vent to outside air. + </para> + <para> + As with all other rocketry electronics, Altus Metrum altimeters must + be protected from exposure to corrosive motor exhaust and ejection + charge gasses. + </para> + </chapter> + <chapter> + <title>The MicroPeak USB adapter</title> + <para> + MicroPeak stores barometric pressure information for the first + 48 seconds of the flight in on-board non-volatile memory. The + contents of this memory can be downloaded to a computer using + the MicroPeak USB adapter. + </para> + <section> + <title>Installing the MicroPeak software</title> + <para> + The MicroPeak application runs on Linux, Mac OS X and + Windows. You can download the latest version from + <ulink url="http://altusmetrum.org/AltOS"/>. + </para> + <para> + On Mac OS X and Windows, the FTDI USB device driver needs to + be installed. A compatible version of this driver is included + with the MicroPeak application, but you may want to download a + newer version from <ulink + url="http://www.ftdichip.com/FTDrivers.htm"/>. + </para> + </section> + <section> + <title>Downloading Micro Peak data</title> + <itemizedlist> + <listitem> + <para> + Connect the MicroPeak USB adapter to a USB cable and plug it + in to your computer. + </para> + </listitem> + <listitem> + <para> + Start the MicroPeak application, locate the File menu and + select the Download entry. + </para> + </listitem> + <listitem> + <para> + The MicroPeak USB adapter has a small phototransistor on + the end of the board furthest from the USB + connector. Locate this and place the LED on the MicroPeak + directly in contact with it. The MicroPeak LED and the + MicroPeak USB adapter photo need to be touching—even a + millimeters of space between them will reduce the light + intensity from the LED enough that the phototransistor + will not sense it. Turn on the MicroPeak board and adjust + the position until the blue LED on the MicroPeak USB + adapter blinks in time with the orange LED on the + MicroPeak board. + </para> + </listitem> + <listitem> + <para> + After the maximum flight height is reported, MicroPeak will + pause for a few seconds, blink the LED four times rapidly + and then send the data in one long blur on the LED. The + MicroPeak application should receive the data. When it does, + it will present the data in a graph and offer to save the + data to a file. If not, you can power cycle the MicroPeak + board and try again. + </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Analyzing MicroPeak Data</title> + <para> + The MicroPeak application can present flight data in the form + of a graph, a collection of computed statistics or in tabular + form. + </para> + <para> + MicroPeak collects raw barometric pressure data which is + then used to compute the remaining data. Altitude is computed + through a standard atmospheric model. Absolute error in this + data will be affected by local atmospheric + conditions. Fortunately, these errors tend to mostly cancel + out, so the error in the height computation is much smaller + than the error in altitude would be. + </para> + <para> + Speed and acceleration are computed by first smoothing the + height data with a Gaussian window averaging filter. For speed + data, this average uses seven samples. For acceleration data, + eleven samples are used. These were chosen to provide + reasonably smooth speed and acceleration data, which would + otherwise be swamped with noise. + </para> + <para> + Under the Graph tab, the height, speed and acceleration values + are displayed together. You can zoom in on the graph by + clicking and dragging to sweep out an area of + interest. Right-click on the plot to bring up a menu that will + let you save, copy or print the graph. + </para> + <para> + The Statistics tab presents overall data from the flight. Note + that the Maximum height value is taken from the minumum + pressure captured in flight, and may be different from the + apparant apogee value as the on-board data are sampled twice + as fast as the recorded values, or because the true apogee + occurred after the on-board memory was full. Each value is + presented in several units as appropriate. + </para> + <para> + A table consisting of the both the raw barometric pressure + data and values computed from that for each recorded time. + </para> + <para> + The File menu has operations to open existing flight logs, + Download new data from MicroPeak, Save a copy of the flight + log to a new file, Export the tabular data (as seen in the Raw + Data tab) to a file, change the application Preferences, Close + the current window or close all windows and Exit the + application. + </para> + </section> + <section> + <title>Configuring the MicroPeak application</title> + <para> + The MicroPeak application has a few user settings which are + configured through the Preferences dialog, which can be + accessed from the File menu. + <itemizedlist> + <listitem> + <para> + The Log Directory is where flight data will be saved to + and loaded from by default. Of course, you can always + navigate to other directories in the file chooser windows, + this setting is just the starting point. + </para> + </listitem> + <listitem> + <para> + If you prefer to see your graph data in feet and + miles per hour instead of meters and meters per second, + you can select Imperial Units. + </para> + </listitem> + <listitem> + <para> + To see what data is actually arriving over the serial + port, start the MicroPeak application from a command + prompt and select the Serial Debug option. This can be + useful in debugging serial communication problems, but + most people need never choose this. + </para> + </listitem> + <listitem> + <para> + You can adjust the size of the text in the Statistics tab + by changing the Font size preference. There are three + settings, with luck one will both fit on your screen and + provide readable values. + </para> + </listitem> + <listitem> + <para> + The Look & feel menu shows a list of available + application appearance choices. By default, the MicroPeak + application tries to blend in with other applications, but + you may choose some other appearance if you like. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Note that MicroPeak shares a subset of the AltosUI + preferences, so if you use both of these applications, change + in one application will affect the other. + </para> + </section> + </chapter> + <chapter> + <title>Technical Information</title> + <section> + <title>Barometric Sensor</title> + <para> + MicroPeak uses the Measurement Specialties MS5607 sensor. This + has a range of 120kPa to 1kPa with an absolute accuracy of + 150Pa and a resolution of 2.4Pa. + </para> + <para> + The pressure range corresponds roughly to an altitude range of + -1500m (-4900 feet) to 31000m (102000 feet), while the + resolution is approximately 20cm (8 inches) near sea level and + 60cm (24in) at 10000m (33000 feet). + </para> + <para> + Ground pressure is computed from an average of 16 samples, + taken while the altimeter is at rest. Flight pressure is + computed from a Kalman filter designed to smooth out any minor + noise in the sensor values. + </para> + </section> + <section> + <title>Micro-controller</title> + <para> + MicroPeak uses an Atmel ATtiny85 micro-controller. This tiny + CPU contains 8kB of flash for the application, 512B of RAM for + temporary data storage and 512B of EEPROM for non-volatile + storage of previous flight data. + </para> + <para> + The ATtiny85 has a low-power mode which turns off all of the + clocks and powers down most of the internal components. In + this mode, the chip consumes only .1μA of power. MicroPeak + uses this mode once the flight has ended to preserve battery + power. + </para> + </section> + <section> + <title>Lithium Battery</title> + <para> + The CR1025 battery used by MicroPeak holes 30mAh of power, + which is sufficient to run for over 40 hours. Because + MicroPeak powers down on landing, run time includes only time + sitting on the launch pad or during flight. + </para> + <para> + The large positive terminal (+) is usually marked, while the + smaller negative terminal is not. Make sure you install the + battery with the positive terminal facing away from the + circuit board where it will be in contact with the metal + battery holder. A small pad on the circuit board makes contact + with the negative battery terminal. + </para> + <para> + Shipping restrictions may prevent us from including a CR1025 + battery with MicroPeak. If so, many stores carry CR1025 + batteries as they are commonly used in small electronic + devices such as flash lights. + </para> + </section> + <section> + <title>Atmospheric Model</title> + <para> + MicroPeak contains a fixed atmospheric model which is used to + convert barometric pressure into altitude. The model was + converted into a 469-element piece wise linear approximation + which is then used to compute the altitude of the ground and + apogee. The difference between these represents the maximum + height of the flight. + </para> + <para> + The model assumes a particular set of atmospheric conditions, + which while a reasonable average cannot represent the changing + nature of the real atmosphere. Fortunately, for flights + reasonably close to the ground, the effect of this global + inaccuracy are largely canceled out when the computed ground + altitude is subtracted from the computed apogee altitude, so + the resulting height is more accurate than either the ground + or apogee altitudes. + </para> + </section> + <section> + <title>Mechanical Considerations</title> + <para> + MicroPeak is designed to be rugged enough for typical rocketry + applications. It contains two moving parts, the battery holder + and the power switch, which were selected for their + ruggedness. + </para> + <para> + The MicroPeak battery holder is designed to withstand impact + up to 150g without breaking contact (or, worse yet, causing + the battery to fall out). That means it should stand up to + almost any launch you care to try, and should withstand fairly + rough landings. + </para> + <para> + The power switch is designed to withstand up to 50g forces in + any direction. Because it is a sliding switch, orienting the + switch perpendicular to the direction of rocket travel will + serve to further protect the switch from launch forces. + </para> + </section> + <section> + <title>On-board data storage</title> + <para> + The ATtiny85 has 512 bytes of non-volatile storage, separate + from the code storage memory. The MicroPeak firmware uses this + to store information about the last completed + flight. Barometric measurements from the ground before launch + and at apogee are stored, and used at power-on to compute the + height of the last flight. + </para> + <para> + In addition to the data used to present the height of the last + flight, MicroPeak also stores barometric information sampled + at regular intervals during the flight. This information can + be extracted from MicroPeak through any AVR programming + tool. + </para> + <table frame='all'> + <title>MicroPeak EEPROM Data Storage</title> + <tgroup cols='3' align='center' colsep='1' rowsep='1'> + <colspec align='center' colwidth='2*' colname='Address'/> + <colspec align='center' colwidth='*' colname='Size (bytes)'/> + <colspec align='left' colwidth='7*' colname='Description'/> + <thead> + <row> + <entry align='center'>Address</entry> + <entry align='center'>Size (bytes)</entry> + <entry align='center'>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>0x000</entry> + <entry>4</entry> + <entry>Average ground pressure (Pa)</entry> + </row> + <row> + <entry>0x004</entry> + <entry>4</entry> + <entry>Minimum flight pressure (Pa)</entry> + </row> + <row> + <entry>0x008</entry> + <entry>2</entry> + <entry>Number of in-flight samples</entry> + </row> + <row> + <entry>0x00a … 0x1fe</entry> + <entry>2</entry> + <entry>Instantaneous flight pressure (Pa) low 16 bits</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + All EEPROM data are stored least-significant byte first. The + instantaneous flight pressure data are stored without the + upper 16 bits of data. The upper bits can be reconstructed + from the previous sample, assuming that pressure doesn't + change by more more than 32kPa in a single sample + interval. Note that this pressure data is <emphasis>not</emphasis> + filtered in any way, while both the recorded ground and apogee + pressure values are, so you shouldn't expect the minimum + instantaneous pressure value to match the recorded minimum + pressure value exactly. + </para> + <para> + MicroPeak samples pressure every 96ms, but stores only every + other sample in the EEPROM. This provides for 251 pressure + samples at 192ms intervals, or 48.192s of storage. The clock + used for these samples is a factory calibrated RC circuit + built into the ATtiny85 and is accurate only to within ±10% at + 25°C. So, you can count on the pressure data being accurate, + but speed or acceleration data computed from this will be + limited by the accuracy of this clock. + </para> + </section> + <section> + <title>MicroPeak Programming Interface</title> + <para> + MicroPeak exposes a standard 6-pin AVR programming interface, + but not using the usual 2x3 array of pins on 0.1" + centers. Instead, there is a single row of tiny 0.60mm × + 0.85mm pads on 1.20mm centers exposed near the edge of the + circuit board. We couldn't find any connector that was + small enough to include on the circuit board. + </para> + <para> + In lieu of an actual connector, the easiest way to connect to + the bare pads is through a set of Pogo pins. These + spring-loaded contacts are designed to connect in precisely + this way. We've designed a programming jig, the MicroPeak + Pogo Pin board which provides a standard AVR interface on one + end and a recessed slot for MicroPeak to align the board with + the Pogo Pins. + </para> + <para> + The MicroPeak Pogo Pin board is not a complete AVR programmer, + it is an interface board that provides a 3.3V regulated power + supply to run the MicroPeak via USB and a standard 6-pin AVR + programming interface with the usual 2x3 grid of pins on 0.1" + centers. This can be connected to any AVR programming + dongle. + </para> + <para> + The AVR programming interface cannot run faster than ¼ of the + AVR CPU clock frequency. Because MicroPeak runs at 250kHz to + save power, you must configure your AVR programming system to + clock the AVR programming interface at no faster than + 62.5kHz, or a clock period of 32µS. + </para> + </section> + </chapter> +</book> +<!-- LocalWords: Altusmetrum MicroPeak +--> diff --git a/doc/release-notes-1.2.xsl b/doc/release-notes-1.2.xsl new file mode 100644 index 00000000..b254c7b5 --- /dev/null +++ b/doc/release-notes-1.2.xsl @@ -0,0 +1,94 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"> + +<article> + <para> + Version 1.2 is a minor release. It provides a few new features in AltosUI + and the AltOS firmware and fixes bugs. + </para> + <para> + AltOS Firmware Changes + <itemizedlist> + <listitem> + In TeleMini recovery mode (when booted with the outer two + debug pins connected together), the radio parameters are also + set back to defaults (434.550MHz, N0CALL, factory radio cal). + </listitem> + <listitem> + Add support for reflashing the SkyTraq GPS chips. This + requires special host-side code which currently only exists + for Linux. + </listitem> + <listitem> + Add MicroPeak support. This includes support for the ATtiny85 + processor and adaptations to the core code to allow for + devices too small to run the multi-tasking scheduler. + </listitem> + <listitem> + Correct Kalman filter model error covariance matrix. The + values used previously assumed continuous measurements instead + of discrete measurements. + </listitem> + </itemizedlist> + </para> + <para> + AltosUI Changes + <itemizedlist> + <listitem> + Handle missing GPS lock in 'Descent' tab. Previously, if the + GPS position of the pad was unknown, an exception would be + raised, breaking the Descent tab contents. + </listitem> + <listitem> + Add preliminary TeleMega support, including configuration, + data download and analysis. + </listitem> + <listitem> + Improve the graph, adding tool-tips to show values near the + cursor and making the displayed set of values configurable, + adding all of the flight data as options while leaving the + default settings alone so that the graph starts by showing + height, speed and acceleration. + </listitem> + <listitem> + Make the initial position of the AltosUI top level window + configurable. Along with this change, the other windows will + pop up at 'sensible' places now, instead of on top of one + another. + </listitem> + <listitem> + Add callsign to Monitor idle window and connecting + dialogs. This makes it clear which callsign is being used so + that the operator will be aware that it must match the flight + computer value or no communication will work. + </listitem> + <listitem> + When downloading flight data, display the block number so that + the user has some sense of progress. Unfortunately, we don't + know how many blocks will need to be downloaded, but at least + it isn't just sitting there doing nothing for a long time. + </listitem> + <listitem> + Add GPS data and a map to the graph window. This lets you see + a complete summary of the flight without needing to 'replay' + the whole thing. + </listitem> + </itemizedlist> + </para> + <para> + Distribution Changes + <itemizedlist> + <listitem> + Distribute Mac OS X packages in disk image ('.dmg') format to + greatly simplify installation. + </listitem> + <listitem> + Provide version numbers for the shared Java libraries to + ensure that upgrades work properly, and to allow for multiple + Altus Metrum software packages to be installed in the same + directory at the same time. + </listitem> + </itemizedlist> + </para> +</article> diff --git a/doc/megametrum-outline.pdf b/doc/telemega-outline.pdf Binary files differindex f8fc26e2..f8fc26e2 100644 --- a/doc/megametrum-outline.pdf +++ b/doc/telemega-outline.pdf diff --git a/doc/megametrum-outline.svg b/doc/telemega-outline.svg index e8d74d38..e8d74d38 100644 --- a/doc/megametrum-outline.svg +++ b/doc/telemega-outline.svg diff --git a/doc/telemetrum.svg b/doc/telemetrum.svg new file mode 100644 index 00000000..97c4e4a8 --- /dev/null +++ b/doc/telemetrum.svg @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + width="5in" + height="2.5in" + viewBox="0 0 500 250" + preserveaspectratio="none" + id="svg2" + version="1.1"> + <g transform="translate(112.5,75)" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linejoin:miter;font-family:Frutiger LT Std"> + <!-- outline --> + <rect width="275" height="100" x="0" y="0"/> + <!-- holes --> + <path d="M37.5,12.5 m-6.25,0 a6.25,6.25,0,1,0,12.5,0 a6.25,6.25,0,1,0,-12.5,0 l12.5,0 m-6.25,-6.25 l0,12.5"/> + <path d="M262.5,12.5 m-6.25,0 a6.25,6.25,0,1,0,12.5,0 a6.25,6.25,0,1,0,-12.5,0 l12.5,0 m-6.25,-6.25 l0,12.5"/> + <path d="M37.5,87.5 m-6.25,0 a6.25,6.25,0,1,0,12.5,0 a6.25,6.25,0,1,0,-12.5,0 l12.5,0 m-6.25,-6.25 l0,12.5"/> + <path d="M262.5,87.5 m-6.25,0 a6.25,6.25,0,1,0,12.5,0 a6.25,6.25,0,1,0,-12.5,0 l12.5,0 m-6.25,-6.25 l0,12.5"/> + <!-- arrow --> + <path d="M50,50 l165,0"/> + <path style="fill:#000000;stroke:none" d="M215,45 l10,5 l-10,5 z"/> + <!-- label --> + <text x="137.5" y="45" style="fill:#000000;stroke:none" text-anchor="middle">TeleMetrum</text> + <g transform="rotate(90)"> + <text x="50" y="-235" style="fill:#000000;stroke:none" text-anchor="middle">UP</text> + </g> + </g> +</svg>
\ No newline at end of file diff --git a/doc/telemini.svg b/doc/telemini.svg new file mode 100644 index 00000000..d07b4971 --- /dev/null +++ b/doc/telemini.svg @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + width="5in" + height="2in" + viewBox="0 0 500 200" + preserveaspectratio="none" + id="svg2" + version="1.1"> + <g transform="translate(175,75)" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linejoin:miter;font-family:Frutiger LT Std"> + <!-- outline --> + <rect width="150" height="50" x="0" y="0"/> + <!-- holes --> + <path d="M135,10 A5,5,0,1,0,145,10 A5,5,0,1,0,135,10 M135,10 l10,0 M140,5 l0,10"/> + <path d="M135,40 A5,5,0,1,0,145,40 A5,5,0,1,0,135,40 M135,40 l10,0 M140,35 l0,10"/> + <!-- arrow --> + <path d="M25,25 l90,0"/> + <path style="fill:#000000;stroke:none" d="M115,20 l10,5 l-10,5 z"/> + <!-- label --> + <text x="75" y="20" style="fill:#000000;stroke:none" text-anchor="middle">TeleMini</text> + <g transform="rotate(90)"> + <text x="25" y="-130" style="fill:#000000;stroke:none" text-anchor="middle">UP</text> + </g> + </g> +</svg>
\ No newline at end of file |
