AO40TLMVIEW(1) 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 pur-
poses: watching via the internet live telemetry being received else-
where, or connecting the ao40tlmview program to another program that
e.g. can demodulate the beacon's audio signal via the computer's sound-
card. 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 com-
mand 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 speci-
fied, 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 time-
out 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 demod-
ulator 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 lay-
out 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 follow-
ing colour conventions are used:
o 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).
o 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).
o red background in the 'RAW' window means the CRC failed.
o 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/trans-
mitter).
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 (hexadec-
imal) channel numbers; after typing 'g', these numbers are dis-
played instead of the received data. If DISPLAY is set and gnu-
plot 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)
