Page 1

OP25 WINDOWS 10 VIRTUAL MACHINE SETUP GUIDE

JULY 10, 2022

 Page 2

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:
 Page 3

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:
 Page 4

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:
 Page 5

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
 Page 6

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.
 Page 7

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:
 Page 8

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
 Page 9

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):
 Page 10

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:
 Page 11

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:

 Page 12

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).
 Page 13

 -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:

 Page 14

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.
 Page 15

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:
 Page 16

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:
 Page 17

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:

 Page 18

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:
 Page 19

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):
 Page 20

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.
 Page 21

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:
 Page 22

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:
 Page 23

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:
 Page 24

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.
 Page 25

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:
 Page 26

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:
 Page 27

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.
 Page 28

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:
 Page 29

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:
 Page 30

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.