Read Me

dsctl - the Digital Scanner Control program

INTRODUCTION
(Original Author of Sctl)

  This program was written because I went up to freshmeat one day, and
wanted to find a program to control a Bearcat 895 XLT for linux.  No
dice.  So, I decided to write one myself.  That's where sctl came from
-- that and all the control programs I could find for Windows (a
barely acceptable alternative just to see how it worked) were either
broken, dorky, or cost upwards of 50 bucks.

  I wrote this program to make sense to the Unix frame of reference, so
it tends to mask the Bearcat/scanner frame of reference in some things.
This may or may not cause you problems.  The majority of the
documentation is built into the program, so run it without options to
see what you've got.

  Note please that this is a DEVELOPER RELEASE and should be considered
unstable, armed and dangerous.  I doubt it'll erase your hard drive or
melt your radio, but ya never know, and I provide no guarantees.  That
said, I've had good luck with it, and haven't seen any big problems
with it (unless you count semantic problems or UI problems, but that's
a different thing entirely).

(Current Development for Dsctl)
  
  Dsctl works using some of the orginal framework of Sctl with some minor
additions.  Dsctl's main focus are the BCD* models and the old BC* models
code was removed for easing the development process.


DOWNLOADING/UNPACKING/COMPILING

  Chances are, if you're reading this, you've already unpacked the tar
file into your favorite directory.  If not, go ahead and download the
source from the web page:

http://www.sourceforge.net/projects/dsctl/

  Unpack it using the tar command:

Linux/BSD/GNU tar: tar -jxvf dsctl.tar.bz2

  This program should ideally work with damn near any Unix-like OS, as
long as it uses files to represent serial ports.

  Note: Linux serial ports are named like /dev/ttyS0 /dev/ttyS1 etc.
        FreeBSD serial ports are /dev/cuaa0 /dev/cuaa1 and so on.
  Other unix systems will have similar naming conventions.

  For example, if you are on Linux, your first serial port (COM1 under
DOS) would be /dev/ttyS0

  Also make sure your login has permission to read and write to the
serial port device.  You can either chmod 666 the device (bad idea), or
just put your login in the appropriate group (on FreeBSD, this is
"dialer", on Debian Linux it is "dialout").  Remember that you have to
re-login before changes to /etc/group will take effect.

  So anyway, once you've got it unpacked into your directory, cd into
sctl directory and type:

make

  That's it.  If I've been industrious, there's an install target, but
if there isn't, all you need to do is move "dsctl" to your favorite
binary directory.  I would usually choose /usr/local/bin/  I don't get
any warnings or errors on my systems (Debian 1.2 and Redhat 6.2).  If
I've been *really* industrious, there's a man page to install as well,
but at that point there'll probably be an install target in the
Makefile, too.  Make sure that your serial port (as defined in
config.h) is read/writeable for whichever set of users will be
controlling the scanner.

  Now copy the dotdsctl.example file from the dsctl source code directory
to your home directory:

cp dotdsctl.example ~/.dsctl

and edit it with a text editor to change the values to their correct
settings.  Everything in this file must be in lowercase.  Please try not
to leave any extra spaces or tabs in the file -- although it shouldn't
cause any problems, it hasn't been tested thoroughly yet...

  If for some reason you don't have a dotdsctl.example, don't worry, a
.dsctl file will be created for you in your home directory the first
time you run the program.


RUNNING

(read docs/quickstart.txt for more information about how to setup your
scanner for computer control, etc)

  There is help text built into the program, and running it without any
options will print out a brief help message.  More extensive help is
available by doing "sctl help commandname".  Typical usage would look
something like this:

miranda:~/devel/dsctl$ ./dsctl status
Current status: ID (trunking) scan mode
Listening to ID memory C4, talkgroup ID 3696
Listening to 854.3625 MHz, at S 026

miranda:~/devel/dsctl$ ./dsctl help
<help contents>

miranda:~/devel/sctl$ ./sctl dump
<scanner should dump memory contents>

  Note that you can shorten the commands down to the minimum necessary
to uniquely identify them: ie, "status" can become "st" at its shortest
(as of this writing).

  Options typically include things like frequency, channel number, etc.
and vary with each command.  Run "sctl help commandname" to see a
detailed account of what all the command takes.


TODO

  Many things. :-)  Check out the sourceforge.net "Feature Requests"
section for more information.


A NOTE ON COMPATIBILITY

  This program has been designed to work with the following scanner
models:

	* Uniden Bearcat BCD996T
	* Uniden Bearcat BCD396T (I don't have one, but protocol is the same.)

  We also intend to support any new computer-controllable scanners
released by Uniden or (maybe) Radio Shack.

  At the time of this writing (Jun 26, 2007), the program has been tested
and is known to work on the BCD996T.  It *should* work on
the other scanner models as well, but since the developers don't have
those models, we can't be 100% certain.  The best way to find out is to
try it out yourself (and then tell us if it works!)


BUGREPORTS, FEATURE REQUESTS, ET AL.

  Please make submissions to the mailing list found at:
  
  http://www.sourceforge.net/projects/dsctl/

  We will take a look at them and may even be able to fix/implement
them. :-)

  That said, I do want to know what sort of features people find
useful.  If you don't see something here that you'd like to have (like,
CTCSS commands, fer instance), I'd like to know that.  I don't
personally give a rat's ass about CTCSS, but other people might (and
it'd be pretty easy to implement).  Likewise, if you find bugs, I do
want to know about them.  I just don't want to give any false
impressions -- I'm not sitting at my computer waiting to pounce on bug
reports.  I've got a life (I'm not really sure how it happened).

  I hope people find this software useful, but I naturally don't
warrant it for anything at all.  Use at your own risk, etc. etc.  Don't
sue me because you downloaded some random software off someone's
random website and it didn't do what you wanted it to.  You know the
drill.

  This software is placed under the GPL, and you can find a copy of
that document included in this tarfile.  Basically, I want this source
code to be freely available in perpetuity.


RANDOM WEBSITE PLUGS

  The latest version of Dsctl is available at:

http://www.sourceforge.net/projects/dsctl/

  The Dsctl developer's homepage is at:

http://www.eskimo.com/~roger

  The latest version of Sctl program will usually be available at:

http://www.sourceforge.net/projects/bc-sctl/

  The Sctl author's homepage (full of randomness) is at:

http://www.obairlann.net/~reaper/

  A scanner stream, playing live police, ambulance, fire and emergency
communications from the Seattle Metro area is available here:

http://www.obairlann.net/scanner.html

- Ian Johnston, Seattle, WA.

- Roger <roger@eskimo.com>
(Original Sctl author's comments left here for now and modified to show this is Dsctl and not Sctl.)