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 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::" when starting the rx.py app, where 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://' 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