#
# Copyright 2005, 2006 Free Software Foundation, Inc.
# 
# This file is part of GNU Radio
# 
# GNU Radio is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
# 
# GNU Radio is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with GNU Radio; see the file COPYING.  If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street,
# Boston, MA 02110-1301, USA.
# 

Welcome to gr-smartnet!
======================================================================
This package implements a trunk-tracking scanner for GNU Radio. It 
is a work-in-progress, but it is already possible to listen to 
and follow conversations on a Motorola Type II SmartNet trunked
network. See the Python source, as well as the exampleusage.sh,
for the gory details of how to operate it. User-friendly it is not,
and I haven't really looked into how to work the framework
into a GUI yet.

It also implements a trunk logger, which is capable of tracking up
to ~12 (depending on your computer) simultaneous conversations on
the trunk and logging these to disk as .wav files, with associated
timestamps in .txt files. This allows you to continuously log
timestamped conversations, with which you can, for instance,
reconstruct a complete incident response from all parties involved.

Please see http://github.com/bistromath/gr-smartnet and forks for
more infromation.  There is also additional description at the
end of this document.


How to Build gr-smartnet
======================================================================

  (1) Ensure that you have installed gnuradio-core 3.6.1 with the patch:
  https://github.com/brad-anton/gnuradio/blob/master/gnuradio_gri_wav-v0.1.patch
  

  (2) Building from cmake:

      $ mkdir $(builddir)
      $ cd $(builddir)
      $ cmake [OPTIONS] $(srcdir)
      $ make
      $ make test
      $ sudo make install


That's it!

Options:
Useful options include setting the install prefix and the build type:

  -DCMAKE_INSTALL_PREFIX=<directory to install to>
  -DCMAKE_BUILD_TYPE="<type>"
  -DPYTHON_LIBRARY=<Python framework directory>

Currently, gr-smartnet has a "Debug" type that builds with '-g -O2'
useful for debugging the software and a "Release" type that builds
with '-O3', which is the default.


Details
======================================================================

As it currently stands, the program cannot decode APCO P25 or other
encoded voice data. There is a separate project, OP25, to do this:
http://sedition.org.au/op25/wiki/WikiStart
My local repeater uses analog voice, so I don't have P25 data here. 
If your local repeater uses P25, please let me know at 
bistromat@hotmail.com so I can work with you to add P25 support.

The default values are reasonable for the USRP with the DBS RX
receiver. You will probably want to play with the squelch setting
as well as the talkgroup list. Using a talkgroup list gives you
pretty-printing of who you're listening to, instead of just a
talkgroup ID number. The included file sf_talkgroups.csv is the
RadioReference.com listing for San Francisco. There is also a frequency
list, which correlates channel assignments with frequencies. This is
a somewhat arcane subject, and Motorola has been known to use at least
four different channel assignment maps. The most common map is given
as a default, which gives reasonable results for most trunks.

You'll have to find out what frequency the control channel is on;
it's easy enough to listen for with usrp_nbfm_rx.py, or look it up
online. If you find yourself getting lots of CRC errors and poor
tracking, play with the -E option to find a frequency offset that
works for you. Usually the USRP is off a few kHz in the 800MHz band.
Again, usrp_nbfm_rx.py will help you find what the offset is using
the FFT display. The demodulator incorporates a carrier-tracking
PLL in order to allow some leeway in frequency error, but it doesn't
give you more than 5kHz leeway in either direction. This will
probably improve later on. In addition, sometimes the PLL appears to
get "lost", and upon starting the program you won't receive any output.
Just restart to fix.

This receiver tracks by sampling the entire band (requires decimation
of 20 or lower) and frequency-translating up and down in order to select
individual channels. This might seem like madness, but is required for
the logging receiver to work.

To use the logger, just execute smartnet2logger.py. For example:

./smartnet2logging.py -R A -g 35 -f 866.9625M -c 867.5M

This would execute the logger using RX subdev A, gain 35dB, control
channel at 866.9625MHz, and a band center of 867.5MHz. Choosing a band
center is best done by looking up the channel allocations, or using
usrp_fft.py to scan the band. Eventually I suppose I could calculate
band center from the frequency assignments being heard on the control
channel. I'm not there yet.

By default, log data is saved to src/python/log. If you want that
changed, feel free to change it using the -D option. The directory
must already exist.

This package requires that gnuradio-core is already installed.  It
also depends on some GNU Radio prerequisites, such as boost.