Usage manual for Btscanner
==========================

Starting Btscanner
------------------
btscanner [--cfg=<config file>] [--no-reset]

Btscanner only accepts two command line arguments. The first one is --cfg
which can inform Btscanner of a new configuration file. The file is parsed
and validated against the configuration DTD. If the default or user
supplied configuration files fails to validate, Btscanner will not start.

The second command line option is to prevent Btscanner from resetting the
Bluetooth dongle before starting a scan. Some dongles will not reset
properly and will therefore prevent Btscanner from working correctly. The
dongle can be hard reset by removing and re-inserting it. I normal mode,
Btscanner tries to reset the dongle before starting each scan. It has been
found that sever common dongles appear to crash when performing lots of
consecutive scans.


Btscanner commands
------------------

When Btscanner starts up, it does not start scanning. Scanning must be
initiated by selecting an inquiry scan or a brute force scan. This can be
done by pressing the 'i' or 'b' keys respectively.

Scan results are displayed on the main screen and by default the first in
the list is highlighted (selected). The list can be scrolled through by
using the up and down arrow keys. Pressing enter will display all the
available information regarding the devices. Pressing 'q' on the
informational screen will return to the device listing.

The device list can be sorted according to several parameters. This can be
achieved by pressing 's' on the device listing screen. A prompt will
appear which asks for the sorting parameters. Three main sort methods
exist:

1) Bluetooth address ('b'). This sorts the devices into ascending numerical
   order. The Bluetooth address is taken as a single hexadecimal number
   ranging from 0x0 to 0xffffffffffff.
2) First Seen ('f'). This compares the time and date of when each device was
   first scanned. For instance, if each device was only scanned once,
   Btscanner would append each new device found to the bottom of the list.
3) Last seen ('l'). This compares the time and date of when each device was
   last scanned. For instance, if each device was scanned only once,
   Btscanner would prepend each new device to the bottom of the displayed list.

To determine the nature of these sorting methods, it should be remembered
that each device stores two timestamps. The first time it was seen, which
once stored does not change, and the last time it was seen, which is
updated each time the device is re-scanned.

There is also a reversing function which can be applied to any of the
sorting methods. This is activated by prefixing the sort method with 'r'.

A scan can be interrupted by pressing 'a' (abort scan). This shuts down all
scanning threads and returns Btscanner to an idle state.

Btscanner is capable of saving a summary of device scans. This is achieved
by pressing 's'. Btscanner will then prompt for a filename to save the
summary to. When a summary log is written out, the internal summary cache
is cleared and starts from the beginning again. Therefore a summary is only
a summary since the last one was written.


Configuration files
-------------------

The main configuration file is called btscanner.xml and resides in
$INSTALL_PREFIX/etc/ which by default is /usr/local/etc. The DTD for this
XML file is called btscanner.dtd and resides in the same directory. When
an alternate configuration file is used, the DTD is still called from the
original position.

Btscanner uses the IEEE OUI list to look up the manufacturers of each
card. This is installed in $INSTALL_PREFIX/share/oui.txt which by default
is /usr/local/share/oui.txt.

Output files
------------

Btscanner normally outputs a log file of all actions and errors into a file
called btscanner.log. This is located in the working directory of the
executable. Btscanner also keeps a static store of all devices found. This
is located in ~/bts by default. The Directory structure of the store is

   ~/bts/<bdaddr>/info

Both the log file and the store directory are set in the configuration
file and can be changed.

