ao40tlmview

AO40TLMVIEW(1)              General Commands Manual             AO40TLMVIEW(1)



NAME
       ao40tlmview - decode and view AO-40 telemetry

SYNOPSIS
       ao40tlmview [-f filename] [-t hostname:port] [-u hostname:port]


DESCRIPTION
       ao40tlmview decodes the binary telemetry data transmitted by the AMSAT-
       OSCAR 40 amateur-radio satellite, and provides an ncurses-based display
       with facilities for easy browsing archived telemetry blocks.


   Sources of telemetry data
       ao40tlmview can get the telemetry to be decoded from three different
       sources.


       Local file

       The filename of a file containing archived telemetry can be specified
       on the commandline using the -f filename option, or it can be given
       after typing f while ao40tlmview is running.

       The file should contain the raw telemetry blocks of 512 bytes each
       (i.e., without sync vector, CRC bytes or padding).  This is the same
       file format as used in the AO-40 telemetry archive at
       http://www.amsat.org/amsat/ftp/telemetry/ao40/ ⟨⟩
       Note: if the most-significant bit of the first byte is 1, the block is
       assumed to have been received with bit errors (according to the CRC);
       this is a convention that ao40tlmview shares with other AO40 telemetry
       programs.


       TCP connection

       Receiving telemetry over a TCP connection can be useful for two
       purposes: watching via the internet live telemetry being received
       elsewhere, or connecting the ao40tlmview program to another program
       that e.g. can demodulate the beacon's audio signal via the computer's
       soundcard.  In order to use this, you need to tell ao40tlmview to what
       machine and to what portnumber on that machine it should connect.  This
       can be done on the commandline, using the -t hostname:portnumber
       option, or in the .ao40tlmviewrc file; see below.  The keystroke
       command t only switches to the server given on the commandline; if not
       specified otherwise (through the -t option or the .ao40tlmviewrc file)
       this defaults to garc9.gsfc.nasa.gov:1024, which is the server through
       which several amateurs often send their live telemetry feeds.

       The data format expected by ao40tlmview for telemetry via TCP is the
       same as the one used by several other (MS-Windows) programs, such as
       P3T and ao40rcv, and used over the garc server.  In this format, for
       every block an 8 byte sync vector (hex 2f,8f,6e,4d,28,86,75,60) is
       transmitted first, folllowed by the block's 512 data bytes and its 2
       CRC bytes.


       UDP packets

       Receiving telemetry over UDP is quite similar to receiving over TCP.
       Again, it can be configured either on the command line, using the -u
       hostname:portnumber option, or in a .ao40tlmviewrc file (note that
       portnumber is now the portnumber to which the remote host is sending
       the packets, not its source port number).  If no UDP source is
       specified, the u keystroke defaults to localhost:2222.

       The data format ao40tlmview expects over UDP, is Phil Karn's Satellite
       Telemetry Protocol
       http://people.qualcomm.com/karn/papers/telem.txt ⟨⟩
       Some soundcard telemetry demodulation software supports this.


   Some notes about live telemetry reception
       When live reception, either over TCP or UDP, is activated, all received
       blocks are written to a file with a name Tyymmdd.RAW in the current
       directory, where yy , mm and dd are year, month and day.  If a callsign
       has been defined in a .ao40tlmviewrc file (see below), this callsign
       will be included in the filename: Tyymmdd@callsign.RAW
       After the computer's clock passes midnight UTC, the file is closed, and
       a new file (with the new date in its name) is opened.  However, in
       order not to split up data belonging to one pass, this is by default
       postponed until no telemetry has been received for an hour.  This
       timeout can be changed in the .ao40tlmviewrc file, see below.
       The log file serves two purposes: it enables you to browse through the
       received telemetry blocks (although this could also have been achieved
       by storing the blocks in memory), and archival for later use and/or for
       submission to the telemetry archive, see
       http://www.amsat.org/amsat/ftp/telemetry/ao40/ ⟨⟩ ; ao40tlmview writes
       the files in the recommended format for the archive.

       If you are demodulating the telemetry using one of the soundcard
       demodulator programs, you may want to choose TCP rather than UDP for
       the connection: with UDP a block is sent as one packet after it has
       been completely received, while with TCP each byte can be sent
       immediately after reception so you can see the block come in byte-by-
       byte.

       Ao40tlmview does not (yet) support direct connection of a hardware
       modem to a serial port. The reason is simple: I don't have such a
       modem, so can't test it; if you have a modem and would be willing to
       test, please contact me.




   The display; colour and abbreviations
       ao40tlmview's display consists of several windows, each displaying a
       part of the received telemetry. The 'RAW' window shows every received
       block; the other windows decode the binary telemetry data transmitted
       in 'A'- and 'E'-type blocks, and don't change when other block types
       are received.

       ao40tlmview has two layouts for the windows: one requiring a screen of
       at least 118x37 (columns x rows), the other requiring 80x60.  The
       layout which fits best to your terminal size will automatically be
       chosen; if your screen is too small, the TAB key can be used to select
       which part is displayed.

       In the interest of using the screen as efficiently as possible, the
       display is rather terse, using colours and abbreviations.  The
       following colour conventions are used:


       ·      numerical data: labels in normal white; values in bright white;
              values of non-functional sensors in dark gray (or dark blue on
              terminals (like xterm) that don't support the 'dim' attribute).


       ·      on/off settings: ON reverse video; OFF dark gray (or dark blue
              on some terminals), or normal white if the text also serves as a
              label (e.g. in the matrix display).


       ·      red background in the 'RAW' window means the CRC failed.


       ·      colours in the matrix diagram don't mean anything special, they
              only serve to help identify what is connected to what.


       Some possibly non-trivial abbreviations :

       o      omni-directional antenna (with V, U, L1 and L2
              receiver/transmitter).

       bth    both antennas (L1 and L2 receiver).  If it says just "L1" or
              "L2", the high-gain antenna is connected.

       GB+    general beacon with the FSK bit activated.

       N J I S
              For LEILA: Notch, Jam, IHU control, Scan

       SunS.  Sun Sensor

       See also the 'Glossary' section of the telemetry specification.



   Keystroke commands
       Source selection:

       f      open file

       t      open TCP connection

       u      start listening for UDP packets

       Navigation:

       left, up
              go to previous block

       right, down
              go to next block

       page-up
              go back 16 blocks

       page-down
              go forward 16 blocks

       home   go to first block

       end    go to last (most recent) block

       <      go to previous block of same class (i.e., 'A'-type, 'E'-type, or
              other)

       >      go to next block of same class (i.e., 'A'-type, 'E'-type, or
              other)

       q      quit

       View:

       a      Toggle decoding of 'A'-type blocks (which contain current
              telemetry).

       e      Toggle decoding of 'E'-type blocks (which contain data from past
              events).

       c      Toggle decoding blocks with incorrect CRC.

       g      Display a graph of one or two telemetry channels as a function
              of time.  The channel(s) is/are chosen by typing their
              (hexadecimal) channel numbers; after typing 'g', these numbers
              are displayed instead of the received data.  If DISPLAY is set
              and gnuplot is available, gnuplot is used for showing the graph
              in a separate X11 window; otherwise, a crude ASCII-graph is
              shown.

       G      If the current block is a Whole Orbit Data block, display a
              graph of its contents.

       r      Toggle display of 'raw' data vs. data converted to engineering
              units.

       R      Toggle display of (hexadecimal) channel numbers instead of
              received data.

       x      Toggle hexadecimal display of entire block.

       TAB    Change which part of display in viewable, if screen is too small
              to view all at once.



   The .ao40tlmviewrc file
       Upon startup, ao40tlmview searches the user's home directory and the
       current working directory for a file called .ao40tlmviewrc This file
       can be used to change some of the default settings, using the following
       format:

       callsign ab1cde
              specifies the callsign to be included in the telemetry capture
              file names (default: none).

       logfiledelay 300
              sets the timeout for switching to a new log file after midnight
              UTC to 300 seconds (default: 3600 seconds).
              Note: even if you set this timeout to 0, you should not count on
              the previous file being closed exactly at midnight, since
              ao40tlmview only checks the time once a minute.

       tcp hostname:port
              sets the hostname and port for TCP connections, just like the -t
              commandline option does.

       udp hostname:port
              sets the hostname and port for UDP connections, just like the -u
              commandline option does.






AUTHOR
       Pieter-Tjerk de Boer; internet e-mail: pa3fwm@amsat.org, amateur
       packet-radio: PA3FWM@PI8DAZ.#TWE.NLD.EU.






                                 23 April 2002                  AO40TLMVIEW(1)