op25
/
op25
4
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity
op25/op25/gr-op25_repeater/apps/README

244 lines
10 KiB
Plaintext
Raw Blame History

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
H - hold/goto the specified tgid
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.
REMOTE TERMINAL
===============
Adding (for example) "-l 56111" to the rx.py command starts rx.py but does
not attach a curses terminal. Instead the program runs as normal in the
foreground (hit CTRL-C to end rx.py as desired). To connect to a running
instance of rx.py, (in this example)
./terminal.py 127.0.0.1 56111
NOTE: rx.py and terminal.py need not run on the same machine. The machine
where terminal.py is running need not have an SDR device directly attached;
but GNU Radio (and OP25) must be available.
WARNING: there is no security or encryption on the UDP port.
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 TERMINAL_TYPE, --terminal-type=TERMINAL_TYPE
'curses' or udp port or 'http:host:port'
-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
HTTP CONSOLE
============
New as of Jan. 2018, the OP25 dashboard is accessible to any Web browser over
HTTP. Include the option "-l http:<host>:<port>" when starting the rx.py app,
where <host> is either "127.0.0.1" to limit access from only this host, or
"0.0.0.0" if HTTP access from anywhere is to be allowed*. After rx.py has
started it begins listening on the specified port for incoming connections.
Once connected the status page should automatically update to show trunking
system status, frequency list, adjacent sites, and other data.
Example: you have started rx.py with the option "-l http:127.0.0.1:8080".
To connect, set your web browser URL to "http://127.0.0.1:8080".
If one or more plot modes has been selected using the "-P" option you may
view them by clicking the "PLOT" button. The plots are updated approx.
every five seconds. Click "STATUS" to return to the main status page.
*WARNING*: there is no security or encryption. Be careful when using "0.0.0.0"
as the listening address since anyone with access to the network can connect.
NOTE: the python-pyramid package is required when using this option. It can
be installed by running
sudo apt-get install python-pyramid
MULTI-RECEIVER
==============
The multi_rx.py app allows an arbitrary number of SDR devices and channels
to be defined. Each channel may have one or more plot windows attached.
Configuration is achieved via a json file (see cfg.json for an example).
In this version, channels are automatically assigned to the first device
found whose frequency span includes the selected frequency.
As of this writing (winter, 2017), neither trunking nor P25 P2/TDMA are
supported in multi_rx.py. The rx.py app should be used for P25 trunking,
for either P1/FDMA or P2/TDMA.
Below is a summary of the major config file keys:
demod_type: 'cqpsk' for qpsk p25 only; 'fsk4' for ysf/dstar/dmr/fsk4 p25
filter_type: 'rc' for p25; 'rrc' for dmr and ysf; 'gmsk' for d-star
plot: 'fft', 'constellation', 'datascope', 'symbol'
[if more than one plot desired, provide a comma-separated list]
destination: 'udp://host:port' or 'file://<filename>'
name: arbitrary string used to identify channels and devices
bug: 'fft' and 'constellation' currently mutually exclusive
bug: 'gmsk' needs work
Note: DMR audio for the second time slot is sent on the specified port number
plus two. In the example 'udp://127.0.0.1:56122', audio for the first slot
would use 56122; and 56124 for the second.
The command line options for multi_rx:
Usage: multi_rx.py [options]
Options:
-h, --help show this help message and exit
-c CONFIG_FILE, --config-file=CONFIG_FILE
specify config file name
-v VERBOSITY, --verbosity=VERBOSITY
message debug level
-p, --pause block on startup
View Git Blame Copy Permalink