April, 2017
===========
This file contains notes on the new version OP25 receiver (rx.py) which
replaces the prior version scope.py. The primary differences are:
* The dependency on WX is completely removed. By default OP25 runs in
a console window in text-only mode.
* An optional real-time plot can be selected when launching rx.py:
contellation, datascope (eye pattern), or symbol trace.
* cqpsk versus fsk4 mode is now selected as a command line parameter.
* most rx.py command-line parameters are compatible with scope.py.
* reduced CPU consumption, as the frame assembler block now runs as a
sink-only GR block.
* dependency on 14.04 is completely removed. Should now run in later
ubuntu and fedora versions with only minor changes (not yet tested).
ADDITIONAL REQUIRED PACKAGES
============================
sudo apt-get install gnuplot-x11
EXAMPLE COMMAND LINE
====================
./rx.py --args 'rtl' --gains 'lna:49' -f 456.7e6 -T tsys.tsv -q -1 -S 1000000 -P symbol -o 50000 -w 2> stderr.2
Running stderr to a file (e.g., "2> stderr.2") is recommended to avoid
screen misprinting.
NOTE: For phase1 voice the "-V" option is not used. Instead the
"-w" option is used (see AUDIO SERVER section, below). For P25 phase 2/TDMA,
the "-2" option is required in addition to the "-w" option.
TERMINAL OPERATION
==================
After starting rx.py if plotting is in use a separate gnuplot window
should open. You must click on the terminal window to restore it to
focus, otherwise all keystrokes are consumed by gnuplot. Once in the
terminal window there are several keyboard commands:
h - hold
l - lockout
s - skip
q - quit program
There are also two experimental commands (should not be used in -T mode)
f - manually change frequencies
t - if currently tuned to a CC, autostart scanning talkgroups
The "t" command allows trunk tracking without setting up a trunking TSV
file. However running with the -T <filename> command line option is
preferred as that allows use of white/black lists and talkgroup tags files.
If the terminal window freezes there may have been a crash. Press Ctrl-Z
to suspend the program and examine stderr.2 for error messages. If there
is a traceback please report the full traceback (and the command line) to
the mail list.
EXTERNAL UDP AUDIO SERVER
=========================
Starting rx.py with the "-w -W host" options directs udp audio data to
be sent over the network to the specified remote host. It can then be
received and played back with either of the following methods:
1. Execute ./audio.sh on a remote machine equipped with python2.7,
libasound.so.2 and the sockaudio.py file.
-or-
2. Execute the command:
nc -kluvw 1 127.0.0.1 23456 | aplay -c1 -f S16_LE -r 8000
NOTE: audio underruns are to be expected when using nc | aplay as the
pcm stream is interrupted every time a radio transmission ends. The
sockaudio player is designed to handle this more gracefully, and generally
only underruns due to high cpu utilization or reception/decoding errors.
INTERNAL AUDIO SERVER
=====================
Starting rx.py with the "-U" command line option enables an internal udp
audio server which will play received audio through the default ALSA
device. Optionally you may specify which ALSA device to use by setting
the "-O audio_out" option along with "-U".
As of this writing (Aug 2017) it is still necessary to specify the "-w"
(wireshark) option if using either the internal or external audio server.
PLOT MODES
==========
Three types of plotting are currently implemented, via the -P parameter:
* constellation
* datascope
* symbol
The symbol mode is allowed both in fsk4 and cqpsk modes. The datascope
mode works only with fsk4 demod mode (-D fsk4). The constellation mode
only works when the cqpsk demod mode is selected (or defaulted).
A couple of notes specific to plot mode:
1. At program startup time the gnuplot window is given the focus after
it opens. Before you can enter terminal commands you need to click on
the terminal window once to make it the active window.
2. In some cases the gnuplot window is displayed on top of the terminal
window used by OP25. If so it may be necessary to move one or the other
of the two windows.
COMMAND LINE OPTIONS
====================
Usage: rx.py [options]
Options:
-h, --help show this help message and exit
--args=ARGS device args
--antenna=ANTENNA select antenna
-a, --audio use direct audio input
-A, --audio-if soundcard IF mode (use --calibration to set IF freq)
-I AUDIO_INPUT, --audio-input=AUDIO_INPUT
pcm input device name. E.g., hw:0,0 or /dev/dsp
-i INPUT, --input=INPUT
input file name
-b Hz, --excess-bw=Hz
for RRC filter
-c Hz, --calibration=Hz
USRP offset or audio IF frequency
-C Hz, --costas-alpha=Hz
value of alpha for Costas loop
-D DEMOD_TYPE, --demod-type=DEMOD_TYPE
cqpsk | fsk4
-P PLOT_MODE, --plot-mode=PLOT_MODE
constellation | symbol | datascope
-f Hz, --frequency=Hz
USRP center frequency
-F IFILE, --ifile=IFILE
read input from complex capture file
-H HAMLIB_MODEL, --hamlib-model=HAMLIB_MODEL
specify model for hamlib
-s SEEK, --seek=SEEK ifile seek in K
-L LOGFILE_WORKERS, --logfile-workers=LOGFILE_WORKERS
number of demodulators to instantiate
-S SAMPLE_RATE, --sample-rate=SAMPLE_RATE
source samp rate
-t, --tone-detect use experimental tone detect algorithm
-T TRUNK_CONF_FILE, --trunk-conf-file=TRUNK_CONF_FILE
trunking config file name
-v VERBOSITY, --verbosity=VERBOSITY
message debug level
-V, --vocoder voice codec
-o Hz, --offset=Hz tuning offset frequency [to circumvent DC offset]
-p, --pause block on startup
-w, --wireshark output data to Wireshark
-W WIRESHARK_HOST, --wireshark-host=WIRESHARK_HOST
Wireshark host
-r RAW_SYMBOLS, --raw-symbols=RAW_SYMBOLS
dump decoded symbols to file
-R RX_SUBDEV_SPEC, --rx-subdev-spec=RX_SUBDEV_SPEC
select USRP Rx side A or B (default=A)
-g GAIN, --gain=GAIN set USRP gain in dB (default is midpoint) or set audio
gain
-G GAIN_MU, --gain-mu=GAIN_MU
gardner gain
-N GAINS, --gains=GAINS
gain settings
-O AUDIO_OUTPUT, --audio-output=AUDIO_OUTPUT
audio output device name
-q FREQ_CORR, --freq-corr=FREQ_CORR
frequency correction
-2, --phase2-tdma enable phase2 tdma decode
-Z DECIM_AMT, --decim-amt=DECIM_AMT
spectrum decimation
Max
8fc1995181