Project

General

Profile

SignalScopePage » History » Version 13

matt, 10/26/2017 02:55 AM

1 3 matt
h1. Signal Scope
2 1 zecke
3 3 matt
h2. Installation
4 1 zecke
5 1 zecke
Before running the scope app, check that the following standard pre-requisite packages are also installed:
6 13 matt
7 1 zecke
 * GNU Radio
8 1 zecke
 * The op25 blocks
9 1 zecke
 * The op25 repeater block
10 1 zecke
11 1 zecke
The osmosdr http://sdr.osmocom.org/trac/wiki/GrOsmoSDR package is required when using USRP or HackRF (or other hardware supported by osmosdr)
12 1 zecke
13 1 zecke
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)
14 1 zecke
15 1 zecke
The Python Numeric package is also needed when using autocorrelation.  If you're running Debian or Ubuntu:
16 1 zecke
17 2 matt
>@apt-get install python-numeric@
18 2 matt
19 2 matt
20 1 zecke
Other than these pre-reqs, no special setup or installation is needed.
21 1 zecke
22 3 matt
h2. Targets
23 2 matt
24 1 zecke
 * Choice of osmosdr(uhd / hackrf, etc), discriminator-tap, or "audio-IF" hardware modes
25 1 zecke
 * Supports either GL or non-GL display mode
26 1 zecke
 * Both FSK4 and CQPSK demodulation modes supported
27 1 zecke
 * Lower and middle range PC hardware, not just the latest (optional features require more CPU)
28 1 zecke
29 2 matt
h2. Running the Program
30 1 zecke
31 1 zecke
There are four overall options or modes depending on your hardware; these are
32 13 matt
33 1 zecke
 * Osmosdr
34 1 zecke
 * Hamlib
35 1 zecke
 * External receiver with discriminator tap connected to sound card
36 1 zecke
 * External receiver with IF in the audio sound card range (e.g., 24 KHz), referred to as "audio IF"
37 1 zecke
38 2 matt
h3. Running with the disc-tap option
39 1 zecke
40 1 zecke
The signal scope does not require the USRP.  If you have a discriminator-tapped receiver, use the "-a" option:
41 1 zecke
42 2 matt
>@./scope.py -a -v 10 -g 50@
43 1 zecke
44 1 zecke
45 2 matt
h3. UHD example
46 1 zecke
47 2 matt
48 2 matt
>@./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'@
49 2 matt
50 2 matt
51 2 matt
h3. HackRF example
52 2 matt
53 2 matt
>@./scope.py --args 'hackrf'  -g 65 -f 412.34e6 -N  'RF:14,IF:32,BB:26' -o 50e3 -T trunk.tsv  -V -v 0@
54 2 matt
55 2 matt
56 2 matt
h3. Hamlib example
57 2 matt
58 1 zecke
Two receivers in cascade (USRP with LFRX connected to the 455 KHz IF output terminal of hamlib-controlled receiver)
59 1 zecke
60 2 matt
>@./scope.py --args 'uhd,nchan=1,subdev=A:A' -g 65 -f 455e3 -o 50e3 -V -v 0 -H 1234  -T trunk.tsv@
61 1 zecke
62 2 matt
h3. RTL-SDR Example
63 2 matt
64 2 matt
>@./scope.py --args 'rtl'  -g 65 -f 123.45e6 -N 'LNA:49' -V -v 0 -S 1000000 -q 39 -T trunk.tsv@
65 2 matt
66 2 matt
67 2 matt
h3. File Playback Example
68 2 matt
69 1 zecke
Selects input from a file instead of RF capture device.  The file must be in standard complex (I/Q) format at a sampling rate of 96,000 Hz.  Playback should automatically restart from the beginning whenever EOF is reached.
70 1 zecke
71 2 matt
>@./scope.py -F ~/gr/capture-96k.dat -g 10@
72 1 zecke
73 2 matt
74 2 matt
h3. Running in the Audio IF mode
75 2 matt
76 1 zecke
Receivers equipped with an IF output in the sound card range can be used.  This is known as "audio IF" mode.
77 1 zecke
A soundcard sampling rate of 96K is used and the IF frequency (typically 24 KHz) is given using the {{{--calibration}}} parameter:
78 1 zecke
79 2 matt
>@./scope.py -A -c 24e3 -g 50 -v 10@
80 1 zecke
81 1 zecke
82 2 matt
h2. Feature overview
83 2 matt
84 1 zecke
 * Spectrum plot
85 1 zecke
 * Baseband oscilloscope
86 1 zecke
 * Eye Pattern Diagram (Datascope) display supporting several standard symbol rates
87 1 zecke
 * Constellation Diagrams
88 1 zecke
 * Demodulated Symbol Output
89 1 zecke
 * Correlation (including Fast Auto-Correlation)
90 1 zecke
 * Direct-frequency entry, signal gain and fine-tuning controls
91 1 zecke
 * User-selectable demodulator (FSK4 or QPSK)
92 2 matt
 * Multi-system trunked receiver with IMBE voice support using the @-V@ command line option (requires frequency-agile SDR receiver)
93 1 zecke
94 11 matt
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.
95 1 zecke
96 2 matt
In all modes, the wireshark option is used to write received P25 packet data to Wireshark.
97 1 zecke
98 2 matt
h2. Program Options
99 1 zecke
100 1 zecke
Here is a full list of program options:
101 1 zecke
102 4 matt
<pre>Usage: scope.py [options]
103 2 matt
104 1 zecke
Options:
105 1 zecke
  -h, --help            show this help message and exit
106 1 zecke
  --args=ARGS           device args
107 1 zecke
  --antenna=ANTENNA     select antenna
108 1 zecke
  -a, --audio           use direct audio input
109 1 zecke
  -A, --audio-if        soundcard IF mode (use --calibration to set IF freq)
110 1 zecke
  -I AUDIO_INPUT, --audio-input=AUDIO_INPUT
111 1 zecke
                        pcm input device name.  E.g., hw:0,0 or /dev/dsp
112 1 zecke
  -i INPUT, --input=INPUT
113 1 zecke
                        input file name
114 1 zecke
  -b Hz, --excess-bw=Hz
115 1 zecke
                        for RRC filter
116 1 zecke
  -c Hz, --calibration=Hz
117 1 zecke
                        USRP offset or audio IF frequency
118 1 zecke
  -C Hz, --costas-alpha=Hz
119 1 zecke
                        value of alpha for Costas loop
120 1 zecke
  -f Hz, --frequency=Hz
121 1 zecke
                        USRP center frequency
122 1 zecke
  -F IFILE, --ifile=IFILE
123 1 zecke
                        read input from complex capture file
124 1 zecke
  -H HAMLIB_MODEL, --hamlib-model=HAMLIB_MODEL
125 1 zecke
                        specify model for hamlib
126 1 zecke
  -s SEEK, --seek=SEEK  ifile seek in K
127 1 zecke
  -S SAMPLE_RATE, --sample-rate=SAMPLE_RATE
128 1 zecke
                        source samp rate
129 1 zecke
  -t, --tone-detect     use experimental tone detect algorithm
130 1 zecke
  -T TRUNK_CONF_FILE, --trunk-conf-file=TRUNK_CONF_FILE
131 1 zecke
                        trunking config file name
132 1 zecke
  -v VERBOSITY, --verbosity=VERBOSITY
133 1 zecke
                        message debug level
134 1 zecke
  -V, --vocoder         voice codec
135 1 zecke
  -o Hz, --offset=Hz    tuning offset frequency [to circumvent DC offset]
136 1 zecke
  -p, --pause           block on startup
137 1 zecke
  -w, --wireshark       output data to Wireshark
138 1 zecke
  -W WIRESHARK_HOST, --wireshark-host=WIRESHARK_HOST
139 1 zecke
                        Wireshark host
140 1 zecke
  -r RAW_SYMBOLS, --raw-symbols=RAW_SYMBOLS
141 1 zecke
                        dump decoded symbols to file
142 1 zecke
  -R RX_SUBDEV_SPEC, --rx-subdev-spec=RX_SUBDEV_SPEC
143 1 zecke
                        select USRP Rx side A or B (default=A)
144 1 zecke
  -g GAIN, --gain=GAIN  set USRP gain in dB (default is midpoint) or set audio
145 1 zecke
                        gain
146 1 zecke
  -G GAIN_MU, --gain-mu=GAIN_MU
147 1 zecke
                        gardner gain
148 1 zecke
  -N GAINS, --gains=GAINS
149 1 zecke
                        gain settings
150 1 zecke
  -O AUDIO_OUTPUT, --audio-output=AUDIO_OUTPUT
151 1 zecke
                        audio output device name
152 1 zecke
  -q FREQ_CORR, --freq-corr=FREQ_CORR
153 1 zecke
                        frequency correction
154 1 zecke
  -2, --phase2-tdma     enable phase2 tdma decode
155 1 zecke
  -L LOGFILE_WORKERS, --logfile-workers=LOGFILE_WORKERS
156 4 matt
                        number of demodulators to instantiate</pre>
157 1 zecke
158 3 matt
h2. Spectrum Display
159 1 zecke
160 9 matt
!a.png!
161 1 zecke
162 1 zecke
The controls arranged along the bottom of the page are:
163 13 matt
164 1 zecke
 * Frequency: to retune, type the new frequency here and press ENTER
165 1 zecke
 * Signal Gain: adjusts the baseband (demodulated) signal level
166 1 zecke
 * Fine Tune: adjusts tuning frequency over +/- 3000 Hz range
167 1 zecke
 * Demod: Selects demodulator (currently used in Demodulated Symbols only)
168 1 zecke
Except for the signal gain control, these controls are only available in USRP RX mode.
169 1 zecke
170 3 matt
h2. Eye Pattern Diagrams
171 1 zecke
172 1 zecke
The scope input source can be connected either before or after the symbol filter using the Viewpoint toggle.
173 1 zecke
174 1 zecke
Also the proper speed must be selected from the available options.
175 1 zecke
176 10 matt
!b.png!
177 1 zecke
178 3 matt
h2. Constellation Diagram
179 1 zecke
180 10 matt
!f.png!
181 1 zecke
182 1 zecke
The signal scope also features an angular population graph (shown above) in addition to the traditional constellation display.
183 1 zecke
In this mode the symbol magnitude (distance from center) is discarded.  Instead the circle is sliced into segments and a count
184 1 zecke
of symbols found in each segment is plotted.  This is similar to a histogram except that a straight line is drawn between each
185 1 zecke
result, and that the results are arranged in polar form instead of rectangular form.
186 1 zecke
187 1 zecke
With this display, the zone at the exact center of the plot can be used precisely to measure the degree of separation or margin
188 1 zecke
between the demodulated symbols.  The plots below illustrate the difference, with poor separation showing on the left image as 
189 1 zecke
revealed by the failure to converge at the center and by the clear territorial violations:
190 1 zecke
191 10 matt
!mhp7a.png! !c.png!
192 1 zecke
193 1 zecke
The two-color mode is used in these images, providing natural relief to highlight the distinctive feature of &pi;/4 DQPSK in which 
194 1 zecke
successive symbols are chosen from two distinct constellations (each containing four possible symbol values) separated by 45&deg;
195 1 zecke
196 3 matt
h2. Demodulated Symbols
197 1 zecke
198 10 matt
!d.png!
199 1 zecke
200 3 matt
h2. Correlation
201 1 zecke
202 1 zecke
!e.png!
203 10 matt
204 11 matt
Cross correlation allows rapid identification of signals with known characteristics.  Frame Sync (FS) signatures of several commonly used radio systems are included.
205 11 matt
 
206 11 matt
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:
207 1 zecke
208 1 zecke
 * If the hardware polarity is inverted 
209 1 zecke
 * When the FS symbols are purposely inverted as an integral part of protocol processing (commonly used in certain protocols but not used in P25)
210 1 zecke
211 1 zecke
The first case commonly happens when using the disc-tap method of hardware connection, because the actual polarity of the signal seems to vary 
212 1 zecke
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.
213 1 zecke
214 1 zecke
The P25 software framer automatically detects the proper polarity and issues a message if negative polarity data is received:
215 1 zecke
216 2 matt
>@Reversed FS polarity detected - autocorrecting@
217 2 matt
218 2 matt
219 1 zecke
The automatic correction applies only to software framing and doesn't help with correlation.  For correct results for both software framing and
220 1 zecke
correlation, you should correct the polarity reversal problem at its source; this is done using negative values for the {{{--gain}}} parameter at 
221 1 zecke
program start time:
222 1 zecke
223 1 zecke
224 2 matt
>@./scope.py -a -v 10 -g -50@
225 2 matt
226 2 matt
227 1 zecke
The second cause of negative correlation peaks is that some protocols (although not P25) make use of both normal- and inverted-polarity FS 
228 1 zecke
sequences as a standard part of their processing.   Instead of clogging the GUI menu with several choices that are merely inverses of others,
229 1 zecke
just for the sake of always having positive-peaked correlations, we allow the correlation graph to reflect the natural polarity of the data.
230 1 zecke
Thus both + and - peaks are shown, allowing quick diagnosis of incorrect hardware polarity (see above), and allowing identification of the
231 1 zecke
particular family and sub-protocol in use.
232 1 zecke
233 2 matt
h2. Auto Correlation
234 1 zecke
235 1 zecke
Also included is Frank's Fast Auto Correlation (fac):
236 1 zecke
237 10 matt
!g.png!
238 1 zecke
239 1 zecke
For further details about Fast Auto Correlation refer to Frank's page at http://sites.google.com/site/radiorausch/
240 1 zecke
241 3 matt
h3. TRUNKING
242 1 zecke
243 1 zecke
New in late 2013, trunk following for multiple trunked P25 systems was added, supporting the following feature set:
244 12 matt
245 1 zecke
  * Any number of separate trunked systems may be scanned
246 1 zecke
  * P25 Phase I (IMBE) voice channel decoding and audio output
247 1 zecke
  * Supports LSM/CQPSK systems that require CQPSK (not C4FM) demodulation in addition to C4FM systems
248 1 zecke
  * Since CQPSK demodulation is used, LSM simulcast distortion is suppressed (contrary to all current scanners)
249 1 zecke
  * In this release, systems and voice channels are scanned sequentially (like trunk tracking scanners)
250 1 zecke
  * Alpha tagging for talkgroup ID's
251 1 zecke
  * Per-system whitelist (closed group) support: only those talkgroups in the list are scanned
252 1 zecke
  * Per-system blacklist support: all talkgroups are scanned, except those listed
253 1 zecke
  * Configuration files are TSV (tab-separated); may be edited using spreadsheet software such as Libre office
254 1 zecke
  * Talkgroup ID hold: momentary delay after each voice transmission to allow following conversations
255 1 zecke
  * Manual talkgroup ID hold: click to pause, remains on current talkgroup until resumed
256 1 zecke
  * Manual lockout: click to lock out current talkgroup
257 1 zecke
  * All of the signal scope functions (see above) are live and may be selected in real time
258 1 zecke
  * Traffic history including list of active voice channels, key trunk control channel data, etc.
259 1 zecke
  * 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.
260 12 matt
261 1 zecke
The trunking code has not yet been merged into the master branch.  In the meantime after cloning the
262 1 zecke
repository you can issue this command to switch to the proper code branch:
263 1 zecke
264 2 matt
265 2 matt
>@git checkout max-trunking-update2@
266 2 matt
267 5 matt
(you must first @cd@ to the top level op25 project directory)
268 1 zecke
269 3 matt
h2. Trunking Configuration
270 2 matt
271 7 matt
The primary configuration file @trunk.tsv@ contains one line (or spreadsheet row) per trunked system
272 7 matt
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:
273 13 matt
274 1 zecke
 * NAC: This is used as the "primary key" to tell different systems apart. 
275 1 zecke
 * Sysname: The name of the system (for display purposes)
276 1 zecke
 * Control Channel List: comma-separated list of trunk control channels.
277 1 zecke
 * 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).
278 1 zecke
 * Modulation: C4FM or CQPSK
279 1 zecke
 * TGID Tags File: specifies the name of a TSV file for this system, containing alpha talkgroup ID tags
280 1 zecke
 * Whitelist: if set, the system is a "closed" system; only listed TGID's will be included
281 1 zecke
 * Blacklist: excludes listed TGID's
282 1 zecke
 * 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
283 1 zecke
284 1 zecke
Note: the first line of the file containing the field names must not be changed.
285 1 zecke
286 3 matt
h3. Software Tuning Mode
287 1 zecke
288 2 matt
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.
289 2 matt
290 1 zecke
To use this mode
291 13 matt
292 1 zecke
 * find the lowest (F1) and highest frequencies (F2) in the system
293 1 zecke
 * You will have to adjust F1 and F2 such that (F2-F1) is less than the selected sample rate
294 1 zecke
 * RTL SDR apparently supports rates higher than 2.56 MHz but there are reported problems
295 1 zecke
 * Find the center frequency = F1 plus one-half of (F2-F1)
296 1 zecke
 * 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
297 1 zecke
 * The higher the sample rate, the more CPU is used
298 1 zecke
 * 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
299 1 zecke
 * The "Center Frequency" is defined as a new column in the trunking TSV file (added to the right of the Blacklist column after the example shown below was created).
300 1 zecke
301 10 matt
!t2.png!
302 1 zecke
303 3 matt
h2. TSV Files
304 1 zecke
305 1 zecke
Use the following command to open a TSV file for editing:
306 1 zecke
307 2 matt
@oocalc trunk.tsv@
308 1 zecke
309 1 zecke
Here are the options used when opening the file
310 1 zecke
311 10 matt
!t1.png!
312 1 zecke
313 3 matt
h2. Talkgroup ID Alpha Tags
314 1 zecke
315 1 zecke
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).
316 1 zecke
317 10 matt
!t3.png!
318 1 zecke
319 3 matt
h2. Trunked Traffic
320 1 zecke
321 10 matt
!t4.png!
322 1 zecke
323 3 matt
h2. P25 PHASE 2 TDMA
324 1 zecke
325 6 matt
Use the @-2@ command line option to enable Phase 2 TDMA.  Unlike in P25 Phase 1 FDMA, TDMA voice channels cannot be tuned manually.  TDMA voice channels are always operated under control of a trunked system having a 9,600 FDMA trunking control channel.  Accordingly you must establish a trunking definition for your system as detailed above; no other special setup is required.
326 1 zecke
327 3 matt
h2. TALKGROUP LOGGING
328 1 zecke
329 1 zecke
This records in parallel all talkgroup activity to .WAV files (except talkgroups excluded via the white list and black lists system). The band of frequencies that can be spanned is equal to the SDR sampling rate, e.g., 2.4 MHz or so if using an RTL, wider in other devices (8 MHz in HackRF, for example). Only one SDR is needed though, no matter how many talkgroups are to be logged (as long as these frequency limits are observed). The option is enabled via the "-L n" command line parameter (where n is an int specifying the number of logfile workers - one plus the number of concurrent talkgroups to be logged).   Note that in TDMA one worker is required per active frequency (not per talkgroup). The wider the spectrum, and the more workers defined, the higher the CPU usage ...
330 1 zecke
331 1 zecke
The logging option must be used with the -T option, and (in this version of scope.py) only the first data row of the trunking TSV file is utilized - subsequent rows are not used.
332 1 zecke
333 3 matt
h2. BUGS
334 1 zecke
335 1 zecke
Possibly bugs exist, here are a few of the known ones as of this writing
336 13 matt
337 1 zecke
 * Symbol filters totally brain damaged (need separate filters for each speed)
338 1 zecke
 * When switching modes using the notebook tabs, leftover data from before may appear momentarily
339 1 zecke
 * Highest and lowest speeds are not well tuned resulting either in sluggish updates or CPU exhaustion
340 1 zecke
 * Currently ignores all except first frequency in list of trunk control frequencies
341 1 zecke
 * The selected tab may override the mode (C4FM vs. CQPSK); be sure to select "constellation" to enable CQPSK mode
342 2 matt
343 3 matt
h2. CREDITS
344 1 zecke
345 1 zecke
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.
346 1 zecke
347 1 zecke
The Fast Auto Correlation (fac) code came from Radiorausch.
348 1 zecke
349 1 zecke
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.
350 1 zecke
351 1 zecke
Special thanks also to GPL(v3), for encouraging these mashups.
Add picture from clipboard (Maximum size: 48.8 MB)