OP25

OP25 WINDOWS 10 VIRTUAL MACHINE SETUP GUIDE ***IN-DEVELOPMENT***

JULY 10, 2022

INTRODUCTION

OP25 is a free software program to decode and listen to digital radio frequencies such as DMR and P25, including P25 Phase I & II trunking systems. It runs in the Linux operating system and utilizes a website called GitHub which is used by software programmers to share and update software code. There are two different versions of OP25, Osmocom and Boatbod:

https://github.com/osmocom/op25
https://github.com/boatbod/op25

There are numerous different versions of Linux such as Mint, Ubuntu, or Debian, which are called distributions or “distros”. To make OP25 run in Windows 10, you can use a software program such as VMWare or Virtualbox that emulates a virtual computer inside of Windows using a different operating system such as any of the Linux distros.

This guide will demonstrate how to setup both versions of OP25 in Windows 10 using VMWare and Ubuntu, which are all free, to monitor a P25 trunking system.

INSTALL VMWARE AND UBUNTU

Download and install VMware Workstation Player (currently version 16):

https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html

Then download Ubuntu LTS version 20.04 (use the 64-bit Desktop image):

https://releases.ubuntu.com/20.04/

This will download a large .iso file onto your PC which you will use to create a virtual machine with VMWare. The Boatbod and Osmocom versions each have their own benefits. To install both versions on the same Linux computer may be slightly confusing because they have similar file and folder names but will each need to have separate folders. Therefore, it may be easier to create 2 separate virtual Linux computers, one for each version, which we will do here, starting with Boatbod.

Open VMWare and click the green plus + sign to create a new virtual machine:

At the pop-up prompt, use the following settings and click Browse to select the Ubuntu .iso file:

At the next prompt, enter the following and click next (you need to select a password that you can remember):

Create an empty folder in Windows called C:\Ubuntu Boatbod and at the next prompt, enter the following, change the default location to C:\Ubuntu Boatbod, and click Next:

Leave the following defaults as-is on the next 2 prompts and click Next and Finish like so:

Wait For VMWare to finish creating your virtual Linux machine and Ubuntu will install itself (this will take a while). This will basically function like a Linux PC that you run inside of VMWare in order to run OP25. Click through any introductory screens and let the Software Updater do any updates. Poke around and familiarize yourself with Ubuntu. Then repeat these steps to create another separate virtual machine for the Osmocom version. When finished, your VMWare launcher should look something like this:

To use an AirSpy, there’s a line of code that must be entered into a file on your Windows 10 C:\ drive (this is not needed for RTL-SDR dongles). Power down Ubuntu and close VMWare. Go to the C:\Ubuntu Boatbod folder and find the file called Boatbod.vmx. Right-click on it and open it with Notepad. Scroll down and add the following to a blank line on the bottom:

usb.quirks.device0 = "0x1d50:0x60a1 skip-reset, skip-refresh, skip-setconfig"

For the Osmocom version, go to C:\Ubuntu Osmocom and do the same thing with Ubuntu Osmocom.vmx.

DOWNLOAD AND INSTALL OP25

To perform tasks and install software in Linux, you can use commands in a terminal window. To install the Boatbod version, open/play your Boatbod virtual machine in VMWare to boot up Ubuntu (we will install the Osmocom version next). Open a terminal window in Ubuntu and run the following commands, one-by-one in this order (you will be asked for your password). When prompted about additional disk space, type y to continue. Give each command time to finish running before running the next command. This is for the Boatbod version:

1. sudo apt-get install git 2. sudo apt install build-essential 3. cd ~ 4. git clone https://github.com/boatbod/op25 5. cd op25 6. ./install.sh

The first command installs the ability for Ubuntu to access the GitHub website and download files using terminal commands. The second command installs essential Linux tools that give you the ability to do more tasks in a terminal window, such as running sudo make commands that are needed to install software. The third command makes sure you’re in your home folder where the OP25 files will be downloaded to. The fourth command accesses the GitHub website and downloads the OP25 files and installer (you will now have a folder called op25). The fifth command navigates you to the op25 folder where the installer file install.sh was downloaded. The sixth command runs the install.sh installer file to install OP25 and will take a while to finish.

After the Boatbod version finishes installing, shut down Ubuntu, re-open VMWare, and now open/play the Osmocom virtual machine. To install the Osmocom version, run the following commands one-by-one in a terminal window:

1. sudo apt-get install git 2. sudo apt install build-essential 3. git clone https://git.osmocom.org/op25 4. cd op25 5. cat gr3.8.patch | patch -p1 6. ./install.sh 7. sudo apt-get install gnuplot-x11

You now have both versions installed in separate virtual machines. Both versions are periodically updated. To install updates in the future for either version, open a terminal window and run:

cd op25 git pull ./rebuild.sh

At this point, stay in the Osmocom machine and proceed to create your .tsv files next.

CREATE .TSV FILES

To monitor a P25 trunking system, you need to tell OP25 the control channel frequency, the system ID, and the Network Access Code (NAC) by creating a .tsv file and entering the details. A .tsv file in Linux is similar to a .csv or .txt file in Windows. Ubuntu includes a spreadsheet application called LibreOffice Calc which is similar to Microsoft Excel and can be used to edit .tsv files. OP25 includes trunk.tsv as an example which you can use as a guide to follow to create a new .tsv file for a local P25 system in your area.

Navigate to the op25/op25/gr-op25_repeater/apps folder and find the file called trunk.tsv:

Make a copy of the trunk.tsv file and re-name it to the name of a local P25 system in your area. Double-click on it to open the file. You will get an initial prompt. Set it to these values and then click OK:

Delete all the rows of systems except for the header row. Then enter just one (1) local P25 trunking system like so:

Column A – This is the name of the system as it will appear on the screen when you run OP25. Type whatever you want here. Column B – These are the control channel frequencies separated by a comma with no spaces. It is recommended to only enter the control channel frequencies and not every frequency on the whole system. This will speed up the time that OP25 takes to find the current active control channel for decoding. Column C – Offset, leave as zero 0 for now. Column D – Enter the NAC in hexadecimal, starting with 0x. For example, if the NAC is 9D1, enter 0x9D1. (0x before a number is an indicator that tells you the number after it is in hexadecimal.) The Osmocom version requires you to enter the proper NAC code. For Boatbod, it is optional and you may enter 0x0. Column E – If the system is simulcast (also known as Linear Simulcast Modulation [LSM]), enter CQPSK. If it’s not simulcast, enter C4FM. Column F – This is another optional separate .tsv file that you can create to list talk group (TG) names/aliases to be displayed (described further down). Enter the filename here, or leave it blank. Column G – Enter talk group IDs separated by commas with no spaces that you only want to hear exclusively without hearing anything else. If you enter any IDs here at all, OP25 will only stop on those TGs and nothing else. Or, leave it blank to hear all TGs. Column H – Blacklist basically means permanently locking out TG IDs. Enter talk group IDs separated by commas with no spaces that you want OP25 to never stop on (such as encrypted TGs, for example). Column I – Center Frequency, leave blank for now.

After making your changes, save the .tsv file by clicking the red down arrow button in the upper-left. At the next prompt, use the following settings and click the “Use Text CSV Format” button:

For your TG names/aliases (also called tags), you may create another .tsv file that should follow this format (no header row is needed):

Column A – The TGID in decimal Column B – The TG name/alias. Type whatever you want. Column C – This is optional in the Osmocom version only (leave column C blank for Boatbod). Enter a color code number from 0-99. This will tell OP25 what color to make the TG and name/alias appear on the screen (there is a color numbering scheme you can see later in OP25 while it’s running). You also have the option of making this a 3-digit number with the first number being a scanning priority and the next 2 digits the color. For example, entering 500 means a priority of 5 and a color code of 00.

Save the .tsv file and make sure the filename matches Column F in your trunk.tsv file (above).

CONNECT YOUR DONGLE(S)

Plug your dongle(s) into your PC. You can use just 1 dongle. AirSpy or RTL-SDR dongles will work as well as other brands. After you’ve physically plugged them in, you need to virtually connect them in VMWare. In the upper-left, click on Player > Removable Devices > whatever the name of your dongle(s) shows as > Connect (Disconnect from host) like so:

In this example, there are 2 AirSpy dongles and they both need to be connected. This basically takes the dongle(s) away from Windows 10 and makes them available to be run in Ubuntu by OP25. You will need to remember to do this every time you open VMWare and open/play a virtual machine. All dongle(s) should now be checked:

RTL-SDR dongles should look something like this:

RUNNING OP25 WITH ONE (1) DONGLE USING rx.py

Navigate to Home/op25/op25/gr-op25_repeater/apps and notice a file called rx.py:

rx.py is an executable file that you run in order to startup OP25 using one (1) dongle. However, you cannot simply double-click on the icon because you need to tell it some parameters using command line arguments in a terminal window. Open a terminal window and go to the op25/op25/gr-op25_repeater/apps/ folder by entering the following command:

cd op25/op25/gr-op25_repeater/apps

The syntax ./ is used in the terminal window to tell Linux to run an executable file. Here is an example of what to run in the terminal window for an RTL-SDR dongle (Osmocom version):

./rx.py --args 'rtl' -S 1000000 -n --gains 'lna:28' -T trunk.tsv -P symbol,constellation -2 -U -l http:0.0.0.0:8080 2> stderr.2 -X

The command arguments are explained here:

• ./rx.py This tells Linux to run rx.py which starts OP25. • --args 'rtl' This tells OP25 which type (brand) of dongle you’re using. • -S 1000000 This tells OP25 what sampling rate to use for the dongle, where the number value is in Hz (1,000,000 Hz, or 1 MHz in this example). • -n Tells OP25 to mute encrypted voice calls so you don’t hear digital encryption noise (OP25 still stops on encrypted voice calls though, and there is no option to prevent this). • --gains 'lna:28' Tells OP25 what gain setting you want. RTL-SDR dongles have gain from 0-49. It is not recommended to set the gain too high to avoid bleedover from other frequencies or a high noise floor which will degrade decoding performance. • -T trunk.tsv Tells OP25 the name of your .tsv file that has the system ID, control channels, and NAC code, etc. (This needs to be your trunk system .tsv and not your TG name/alias .tsv.) • -P symbol,constellation (Osmocom only) Tells OP25 to display 2 live graphs (known as plots) called symbol and constellation, which indicates the quality of the decode (the Boatbod version shows plots without requiring -P). • -2 Enables decoding of Phase II P25 voice calls. • -U Tells OP25 to play the audio from voice calls to your default sound output device. • -l http:0.0.0.0:8080 Tells OP25 the URL address you want to use to display the Graphical User Interface (GUI) in a web browser. • 2> stderr.2 Creates a log file called stderr.2 which records diagnostic data that can be used to troubleshoot problems. • -X (Osmocom only) Enables auto fine-tuning to make sure your dongle is exactly on frequency. This is often necessary to get proper decode (the Boatbod version instead has fine tuning buttons you click on).

See the README file in the apps folder for a complete list of all the command arguments. If you’re using an AirSpy, here is an example command line:

./rx.py --args 'airspy' -S 3000000 -n -N 'LNA:10,MIX:10,IF:10' -T trunk.tsv -P symbol,constellation -2 -U -l http:0.0.0.0:8080 2> stderr.2 -X

Most of the parameters are the same for AirSpy, except for the gain. AirSpy dongles have 3 separate gain settings which each have a range of 1-15, and you do not need the "--gains" part in the syntax.

To run your command line, change the -T trunk.tsv argument to whatever the name of your file is (for example, -T anytown.tsv).

Then hit enter in the terminal window:

You should start hearing voice calls on the system. In Ubuntu, open your Firefox browser and go to the URL http://0.0.0.0:8080 (per your command argument above) and you should now see the GUI:

The top part is called the Main Display and the graphs below it are called plots. Plots with nice clean lines indicate a good high-quality decode. TSBK stands for Trunking Signal Block. With proper decode, TSBK should show numbers changing that continually increase. The LOCKOUT button temporarily locks out a TGID. There is no option to see what TGs you’ve locked out and unlock them. GO TO lets you enter a TGID that you want to hold on. The SCAN button is really like a Search button on a traditional scanner as there are no TG banks or scanlists. OP25 does not show patch information if TGs are patched. Click the buttons along the top header to see the different screens (the Logs button requires another setup step, described later). The Help button explains how to use the GUI. To stop running OP25, go back to the terminal window and press Ctrl + c.

CONTROL CHANNEL ACTIVITY

With rx.py, the dongle is tuned to either the control channel frequency or a voice frequency, but not both at the same time. While tuned to the control channel, live trunking activity is displayed such as the frequency activity, call history, and events. On the Osmocom version, the displaying of live trunking activity is temporarily interrupted whenever the dongle is tuned to a voice frequency to hear a voice call. During a voice call on Osmocom, the trunking activity will stop updating and the frequency activity window will go blank until the voice call is over and the dongle is tuned back to the control channel. Notice how the frequency activity is blank during a voice call:

On the Boatbod version, trunking activity data present on voice channels is decoded during voice calls so that live frequency activity continues to be displayed without interruption. In the screenshot below, the Boatbod version shows live frequency activity during a voice call:

Therefore, to get uninterrupted live trunking activity on Osmocom, two (2) dongles are needed. One stays tuned to the control channel frequency and the other is tuned to voice call frequencies. To use two (2) dongles, you must first identify the serial numbers of the 2 dongles, described next.

IDENTIFYING DONGLE SERIAL NUMBERS

To use more than 1 dongle with OP25, you need to know the serial number of each dongle to tell OP25 which dongle is used for what purpose (voice calls or control channel). To see the serial numbers, plug in both dongles, make sure they’re enabled in VMWare, and enter the following command in a terminal window:

lsusb -v | grep -i iserial

This is an example of 2 RTL-SDR dongles with serial numbers of 00000002 and 00000001:

RTL-SDR dongles may have 00000001 as the standard default serial number. You cannot use multiple dongles that have the same serial number. If both RTL-SDRs are 00000001, you will need to change the serial number of one of them. There is a file called rtl_eeprom.exe that you can use to change the serial number, which can be downloaded here:

https://ftp.osmocom.org/binaries/windows/rtl-sdr/

Scroll to the bottom of the list and download the most recent 64-bit version onto your C:\ drive in Windows 10. Create a new folder on your C:\ drive in Windows 10 and unzip all the files into the folder, including the .dll’s. Disable both dongles in VMWare and physically unplug one of the dongles. Now you should have just one dongle physically plugged in and disabled in VMWare. Open a command prompt in Windows 10 and navigate to the folder where you unzipped the files. Then run the following command to change the serial number from the default of 00000001 to 00000002:

rtl_eeprom.exe -s 00000002

Review the configuration information and enter y to make the change:

Now you must unplug the dongle and re-plug it back in for the change to take effect. Plug in the other dongle so that they’re now both plugged in and run rtl_test.exe at the command prompt to ensure the dongles are now 00000001 and 00000002:

Terminate the .exe from running by pressing Ctrl + c. AirSpy dongles typically have long, unique serial numbers and therefore don’t need to be changed:

However, make a note of the serial numbers because you’ll need to enter them in your .json files, described next.

CREATING .json FILES

Using one (1) dongle with rx.py has some command line arguments which may be somewhat lengthy. However, to use multiple dongles, the arguments will become much lengthier. Therefore, OP25 uses a file in the apps folder where parameters can be entered and saved rather than having to type out lots of command arguments everytime. This file is called a .json file and there are several examples included in OP25, such as cfg.json, cfg-trunk.json, cfg-trunk2.json, and cfg-trunkx.json (see the file called README-July-2021 in the Osmocom version).

Make a copy of the cfg-trunk2.json file and re-name it to rtlsdr.json:

Open rtlsdr.json and change the parameters to the following (some will be left at the original defaults):

Save the file and close it. If you’re using AirSpy dongles, re-name your copy of cfg-trunk2.json to airspy.json. Open airspy.json and change the parameters to the following (except use your own AirSpy dongle’s serial numbers):

The abbreviation vc means voice channel and cc means control channel. Save the file and close it. To run multiple dongles in OP25, you will now use multi_rx.py instead of rx.py, described next.

USING multi_rx.py TO RUN TWO (2) DONGLES

Make sure both dongles are physically plugged in and enabled in VMWare. Open a terminal window in the Osmocom version and enter the following command:

./multi_rx.py -c rtlsdr.json -T trunk.tsv -U -l http:0.0.0.0:8080 2> stderr.2 -X

Replace -T trunk.tsv with the name of your particular .tsv file. If you’re using an airspy, replace -c rtlsdr.json with -c airspy.json instead.

You should start hearing voice calls. Point your web browser to http://0.0.0.0:8080 to view the GUI:

You should now be able to listen to voice calls with no interruption in the trunking activity:

To end an multi_rx.py session, simply press enter in the terminal window instead of Ctrl + c. (To end rx.py sessions, use Ctrl + c.)

USING A BROWSER IN WINDOWS 10 OUTSIDE OF VMWARE

Instead of using Firefox inside of VMWare, you can use a web browser in Windows 10 outside of VMWare. In Ubuntu, enter the command “ip a” in a terminal window and take note of the IP address:

Then take that IP address (whatever it is on your end) and create a URL like so (add :8080 to the end):

http://192.168.133.134:8080

Open a web browser in Windows 10 and go to that URL. Now you can run the GUI and use OP25 outside of VMWare to get a larger viewing area:

SETUP SQL LOGGING (OSMOCOM ONLY)

The Osmocom version includes a logging feature called SQL logging that records and saves detailed control channel data that can be searched or queried on. This is accessed by pressing the Logs button over the Main Display, however SQL logging has to be set up first.

Make sure OP25 is not running and go to the apps folder at Home/op25/op25/gr-op25_repeater/apps. Create a new .tsv file named sysid-tags.tsv. Open the sysid-tags.tsv file and enter the system ID in Column A (in decimal) and the name of the system in Column B like so (with no header row):

Save the file and close it. Open a terminal window and make sure you’re in the apps folder:

cd op25/op25/gr-op25_repeater/apps

Then run the following command (nothing is returned in the terminal window when you run this):

python3 sql_dbi.py reset_db

Run the following, but replace tags.tsv with the name of your TG name/alias file and replace 813 with your system ID in decimal (the terminal window returns nothing):

python3 sql_dbi.py import_tgid tags.tsv 813

Then run (the terminal window returns nothing):

python3 sql_dbi.py import_sysid sysid-tags.tsv 0

Run OP25 for a few minutes to collect some data and then quit OP25. Then run:

sh install-sql.sh

Enter your password when prompted and when prompted about additional disk space, type y to continue. When the install finishes, you will need to access a file called .bashrc in the Home folder. Go to the Home folder, click the 3 lines icon in the upper-right (the hamburger menu) and make sure Show Hidden Files is checked. Now the .bashrc file should be visible.

Double-click on .bashrc to open it and enter the following line at the bottom: export PATH=/home/osmocom/.local/bin:$PATH

Save it and close the .bashrc file. Log out of Ubunto and then log back in again. Open a terminal window and go to the oplog folder:

cd op25/op25/gr-op25_repeater/apps/oplog

Then run the following two (2) commands:

export FLASK_APP=op25 FLASK_DEBUG=1 flask run

Then press Ctrl + c to quit:

SQL logging should be set up now. In order to run SQL logging, you will first need to run OP25 in a terminal window as usual:

While OP25 is running, open a separate new terminal window and go to the oplog folder:

cd op25/op25/gr-op25_repeater/apps/oplog

Then run ./oplog.sh:

Now that oplog.sh is running, you may access the logging application by clicking the Logs button above the Main Display:

A new browser window/tab will open and you may click around and use all the features:

As control channel data is being saved, the op25-data.db file in the apps folder can become quite large over time and may slow down oplog.sh. Therefore, it is recommended to periodically clear the data by clicking on OP25 – Logs in the upper left and scrolling down and selecting Purge Database:

Then follow the instructions and make your selections on the next screen.

ADJUSTING THE DELAY TIME

OP25 has a default delay time of 2.0 seconds. When a voice call ends, OP25 remains monitoring the TG and will resume scanning (searching) after 2 seconds of inactivity. During the delay, the TG information disappears from the Main Display, but OP25 still holds on it for 2 seconds (there is no option to make the TG information stay visible during the delay time). To change the delay time, open the file in the apps folder called trunking.py and find the following line:

self.TGID_HOLD_TIME = 2.0 # TODO: make more configurable

Change the value from 2.0 to whatever you want, in seconds. Save the file and close it. NOTE: When you periodically update OP25 to a new version, you must go back in and change this back to the 2.0 default or the update won’t work.

MORE ABOUT THE BOATBOD VERSION

Run the Boatbod version using rx.py and observe the following:

The Plot button opens a new screen with a list of plots you can choose from. For example, clicking the Con button shows the plot called constellation. A good high-quality decode will have four (4) neat clusters on the graph:

Explanation of the buttons on the Home screen:

SKIP – This is not a lockout. It is basically functions like a search button on a traditional scanner where you tell OP25 to get off the current TG and search on to the next one.

HOLD – This holds on whatever the current TG is that is on the Main Display.

GOTO – This gives you a pop-up box that lets you type a TGID that you want to listen to. Then it will hold on that TG.

B/LIST – Blacklist, this is a temporary lockout. The TG will no longer be stopped on during your current session. After you close OP25 and re-start it again, any TGs you blacklisted (temporarily locked out) are restored and will be stopped on. You must click the B/LIST during an actual voice call, not during the scan/search hold time. Otherwise, you’ll get a pop-up box asking what TGID to blacklist. There is no option to see what TGs you’ve blacklisted out and unlock them.

W/LIST – Whitelist, gives you a pop-up box to enter the TGID. If you whitelist even just 1 TG, OP25 will only stop for that one TG. All other TGs will be ignored. This is temporary until the next time you run OP25, after which the TGs are no longer whitelisted and OP25 will stop on whatever it finds.

LOG/V – This gives you a pop-up prompt where you can enter a number telling OP25 how much or little verbosity of logging data you want saved in the stderr.2 file. Values range from 1-11. The higher the number, the more detailed data that will be saved in stderr.2.

< > – Single side arrows allow for fine-tuning of the dongle. Clicking < lowers the tuned frequency by 100 Hz and > increases it by 100 Hz. You can use the frequency error shown further down on the display as a guide.

<< >> – Double side arrows function the same as the < > single side arrows, except that the increment is 1,200 Hz instead of 100 Hz.