OP25j

= Signal Scope =

== Installation ==

Before running the scope app, check that the following standard pre-requisite packages are also installed:

 * GNU Radio

 * The op25 blocks

 * The op25 repeater block

The osmosdr http://sdr.osmocom.org/trac/wiki/GrOsmoSDR package is required when using USRP or HackRF (or other hardware supported by osmosdr)

Additionally, hamlib http://sourceforge.net/apps/mediawiki/hamlib/index.php?title=Main_Page is (optionally) needed if using a frequency-agile receiver that is to be tuned using hamlib (see below)

The Python Numeric package is also needed when using autocorrelation.  If you're running Debian or Ubuntu:

{{{

apt-get install python-numeric

}}}

Other than these pre-reqs, no special setup or installation is needed.

== Targets ==

 * Choice of osmosdr(uhd / hackrf, etc), discriminator-tap, or "audio-IF" hardware modes

 * Supports either GL or non-GL display mode

 * Both FSK4 and CQPSK demodulation modes supported

 * Lower and middle range PC hardware, not just the latest (optional features require more CPU)

== Running the Program ==

There are four overall options or modes depending on your hardware; these are

 * Osmosdr

 * Hamlib

 * External receiver with discriminator tap connected to sound card

 * External receiver with IF in the audio sound card range (e.g., 24 KHz), referred to as "audio IF"

=== Running with the disc-tap option ===

The signal scope does not require the USRP.  If you have a discriminator-tapped receiver, use the "-a" option:

{{{

./scope.py -a -v 10 -g 50

}}}

=== UHD example ===

{{{

./scope.py --args 'uhd,nchan=1,subdev=B:0' -g 65 -f 412.34e6  -o 50e3 -V -v 0   -T trunk.tsv -N 'ADC-pga:10,PGA0:29'

}}}

=== HackRF example ===

{{{

./scope.py --args 'hackrf'  -g 65 -f 412.34e6 -N  'RF:14,IF:32,BB:26' -o 50e3 -T trunk.tsv  -V -v 0

}}}

=== Hamlib example ===

Two receivers in cascade (USRP with LFRX connected to the 455 KHz IF output terminal of hamlib-controlled receiver)

{{{

./scope.py --args 'uhd,nchan=1,subdev=A:A' -g 65 -f 455e3 -o 50e3 -V -v 0 -H 1234  -T trunk.tsv

}}}

=== RTL-SDR Example ===

{{{

./scope.py --args 'rtl'  -g 65 -f 123.45e6 -N 'LNA:49' -V -v 0 -S 1000000 -q 39 -T trunk.tsv

}}}

=== Running in the Audio IF mode ===

Receivers equipped with an IF output in the sound card range can be used.  This is known as "audio IF" mode.

A soundcard sampling rate of 96K is used and the IF frequency (typically 24 KHz) is given using the {{{--calibration}}} parameter:

{{{

./scope.py -A -c 24e3 -g 50 -v 10

}}}

== Feature overview ==

 * Spectrum plot

 * Baseband oscilloscope

 * Eye Pattern Diagram (Datascope) display supporting several standard symbol rates

 * Constellation Diagrams

 * Demodulated Symbol Output

 * Correlation (including Fast Auto-Correlation)

 * Direct-frequency entry, signal gain and fine-tuning controls

 * User-selectable demodulator (FSK4 or QPSK)

 * Multi-system trunked receiver with IMBE voice support using the {{{-V}}} command line option (requires frequency-agile SDR receiver)

In the baseband AF (disc. tap) mode, several program functions are disabled (spectrum FFT, constellation diagram, PSK demod, FAC and iDEN correlation)

because these functions require direct access to the signal with no demodulation.

In all modes, the {{{--wireshark}}} option is used to write received P25 packet data to Wireshark.

== Program Options ==

Here is a full list of program options:

{{{

Usage: scope.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

  -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

  -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

}}}

== Spectrum Display ==

[[Image(a.png)]]

The controls arranged along the bottom of the page are:

 * Frequency: to retune, type the new frequency here and press ENTER

 * Signal Gain: adjusts the baseband (demodulated) signal level

 * Fine Tune: adjusts tuning frequency over +/- 3000 Hz range

 * Demod: Selects demodulator (currently used in Demodulated Symbols only)

Except for the signal gain control, these controls are only available in USRP RX mode.

== Eye Pattern Diagrams ==

The scope input source can be connected either before or after the symbol filter using the Viewpoint toggle.

Also the proper speed must be selected from the available options.

[[Image(b.png)]]

== Constellation Diagram ==

[[Image(f.png)]]

The signal scope also features an angular population graph (shown above) in addition to the traditional constellation display.

In this mode the symbol magnitude (distance from center) is discarded.  Instead the circle is sliced into segments and a count

of symbols found in each segment is plotted.  This is similar to a histogram except that a straight line is drawn between each

result, and that the results are arranged in polar form instead of rectangular form.

With this display, the zone at the exact center of the plot can be used precisely to measure the degree of separation or margin

between the demodulated symbols.  The plots below illustrate the difference, with poor separation showing on the left image as 

revealed by the failure to converge at the center and by the clear territorial violations:

[[Image(mhp7a.png)]][[Image(c.png)]]

The two-color mode is used in these images, providing natural relief to highlight the distinctive feature of π/4 DQPSK in which 

successive symbols are chosen from two distinct constellations (each containing four possible symbol values) separated by 45°

== Demodulated Symbols ==

[[Image(d.png)]]

== Correlation ==

[[Image(e.png)]]

Cross correlation allows rapid identification of signals with known characteristics.  Frame Sync (FS) signatures of several commonly

used radio systems are included.

By convention correlation results are usually displayed using positive correlation peaks only.  In this system

however it is possible (and legal) for negative correlation products to be produced.  This can occur for two wholly separate reasons:

 * If the hardware polarity is inverted 

 * When the FS symbols are purposely inverted as an integral part of protocol processing (commonly used in certain protocols but not used in P25)

The first case commonly happens when using the disc-tap method of hardware connection, because the actual polarity of the signal seems to vary 

randomly among different sound cards and receivers.  In one actual case, two PC's of the same PC brand bought from the same store had opposite polarity.

The P25 software framer automatically detects the proper polarity and issues a message if negative polarity data is received:

{{{

Reversed FS polarity detected - autocorrecting

}}}

The automatic correction applies only to software framing and doesn't help with correlation.  For correct results for both software framing and

correlation, you should correct the polarity reversal problem at its source; this is done using negative values for the {{{--gain}}} parameter at 

program start time:

{{{

./scope.py -a -v 10 -g -50

}}}

The second cause of negative correlation peaks is that some protocols (although not P25) make use of both normal- and inverted-polarity FS 

sequences as a standard part of their processing.   Instead of clogging the GUI menu with several choices that are merely inverses of others,

just for the sake of always having positive-peaked correlations, we allow the correlation graph to reflect the natural polarity of the data.

Thus both + and - peaks are shown, allowing quick diagnosis of incorrect hardware polarity (see above), and allowing identification of the

particular family and sub-protocol in use.

== Auto Correlation ==

Also included is Frank's Fast Auto Correlation (fac):

[[Image(g.png)]]

For further details about Fast Auto Correlation refer to Frank's page at http://sites.google.com/site/radiorausch/

=== TRUNKING ===

New in late 2013, trunk following for multiple trunked P25 systems was added, supporting the following feature set:

  * Any number of separate trunked systems may be scanned

  * P25 Phase I (IMBE) voice channel decoding and audio output

  * Supports LSM/CQPSK systems that require CQPSK (not C4FM) demodulation in addition to C4FM systems

  * Since CQPSK demodulation is used, LSM simulcast distortion is suppressed (contrary to all current scanners)

  * In this release, systems and voice channels are scanned sequentially (like trunk tracking scanners)

  * Alpha tagging for talkgroup ID's

  * Per-system whitelist (closed group) support: only those talkgroups in the list are scanned

  * Per-system blacklist support: all talkgroups are scanned, except those listed

  * Configuration files are TSV (tab-separated); may be edited using spreadsheet software such as Libre office

  * Talkgroup ID hold: momentary delay after each voice transmission to allow following conversations

  * Manual talkgroup ID hold: click to pause, remains on current talkgroup until resumed

  * Manual lockout: click to lock out current talkgroup

  * All of the signal scope functions (see above) are live and may be selected in real time

  * Traffic history including list of active voice channels, key trunk control channel data, etc.

  * Hardware support provided by gr-osmosdr http://sdr.osmocom.org/trac/wiki/GrOsmoSDR including usrp/uhd, hackrf, and (in theory) RTL DVB-T based sticks etc.

The trunking code has not yet been merged into the master branch.  In the meantime after cloning the

repository you can issue this command to switch to the proper code branch:

{{{

git checkout max-trunking-update2

}}}

(you must first {{{cd}}} to the top level op25 project directory)

== Trunking Configuration ==

The primary configuration file {{{trunk.tsv}}} contains one line (or spreadsheet row) per trunked system

to be monitored. The file need not be named {{{trunk.tsv}}}; any name of your choice may be used, and is specified using the {{{-T}}} option.  The file contains the following information:

 * NAC: This is used as the "primary key" to tell different systems apart. 

 * Sysname: The name of the system (for display purposes)

 * Control Channel List: comma-separated list of trunk control channels.

 * Offset: if using a SDR with GPSDO, this value is not needed and should be set to zero.  Used for frequency drift correction.  The values shown are almost certainly incorrect for your system; the frequency error (drift) is different for every oscillator and is also almost always temperature dependent.  You can use the other functions of scope.py such as the eye diagram to determine the error (difference between nominal frequency and received frequency).

 * Modulation: C4FM or CQPSK

 * TGID Tags File: specifies the name of a TSV file for this system, containing alpha talkgroup ID tags

 * Whitelist: if set, the system is a "closed" system; only listed TGID's will be included

 * Blacklist: excludes listed TGID's

 * Center Frequency: set this to (Highest-Frequency-Channel - Lowest-Frequency-Channel) / 2 - and make sure it's at least (say) 50 KHz away from any active channel

Note: the first line of the file containing the field names must not be changed.

=== Software Tuning Mode ===

A new feature which helps to workaround a current problem with the RTL-SDR, the software Local Oscillator allows software tuning within the passband whose width is equal to the current sampling rate ({{{--sample-rate}}}) parameter.  Currently this seems to be limited to 2.56 MHz.

To use this mode

 * find the lowest (F1) and highest frequencies (F2) in the system

 * You will have to adjust F1 and F2 such that (F2-F1) is less than the selected sample rate

 * RTL SDR apparently supports rates higher than 2.56 MHz but there are reported problems

 * Find the center frequency = F1 plus one-half of (F2-F1)

 * Adjust the center frequency by a few tens of KHz if necessary to ensure it does not coincide with any of the system channel frequencies, to avoid DC offset

 * The higher the sample rate, the more CPU is used

 * If the system contains frequencies outside of the band from F1 to F2, tuning error messages will be issued but the remaining channels should still work

[[Image(t2.png)]]

== TSV Files ==

Use the following command to open a TSV file for editing:

{{{oocalc trunk.tsv}}}

Here are the options used when opening the file

[[Image(t1.png)]]

== Talkgroup ID Alpha Tags ==

There is usually a separate tags file for each system, although sometimes multiple systems can share a common set of tags.  The talkgroup ID (first column in each row) is in decimal (base 10).

[[Image(t3.png)]]

== Trunked Traffic ==

[[Image(t4.png)]]

== BUGS ==

Possibly bugs exist, here are a few of the known ones as of this writing

 * Symbol filters totally brain damaged (need separate filters for each speed)

 * When switching modes using the notebook tabs, leftover data from before may appear momentarily

 * Highest and lowest speeds are not well tuned resulting either in sluggish updates or CPU exhaustion

 * Currently ignores all except first frequency in list of trunk control frequencies

 * The selected tab may override the mode (C4FM vs. CQPSK); be sure to select "constellation" to enable CQPSK mode

== CREDITS ==

I ripped off the "tabbed notebook" theme (and code) from Stevie; it already had the spectrum, baseband, and decoded symbol displays. I added the data scope, constellation scope, cross correlation, and trunk tracking features.

The Fast Auto Correlation (fac) code came from Radiorausch.

Special thanks to Mossmann for leaving one commented-out "print" statement in c4fm-decode.py. Of course it was tempting to wonder "what would happen" if that statement were un-commented. The final result? The cross-correlation feature.

Special thanks also to GPL(v3), for encouraging these mashups.