Debian Codegraph @

USAGE

raw
1 Usage manual for Btscanner
2 ==========================
3
4 Starting Btscanner
5 ------------------
6 btscanner [--cfg=<config file>] [--no-reset]
7
8 Btscanner only accepts two command line arguments. The first one is --cfg
9 which can inform Btscanner of a new configuration file. The file is parsed
10 and validated against the configuration DTD. If the default or user
11 supplied configuration files fails to validate, Btscanner will not start.
12
13 The second command line option is to prevent Btscanner from resetting the
14 Bluetooth dongle before starting a scan. Some dongles will not reset
15 properly and will therefore prevent Btscanner from working correctly. The
16 dongle can be hard reset by removing and re-inserting it. I normal mode,
17 Btscanner tries to reset the dongle before starting each scan. It has been
18 found that sever common dongles appear to crash when performing lots of
19 consecutive scans.
20
21
22 Btscanner commands
23 ------------------
24
25 When Btscanner starts up, it does not start scanning. Scanning must be
26 initiated by selecting an inquiry scan or a brute force scan. This can be
27 done by pressing the 'i' or 'b' keys respectively.
28
29 Scan results are displayed on the main screen and by default the first in
30 the list is highlighted (selected). The list can be scrolled through by
31 using the up and down arrow keys. Pressing enter will display all the
32 available information regarding the devices. Pressing 'q' on the
33 informational screen will return to the device listing.
34
35 The device list can be sorted according to several parameters. This can be
36 achieved by pressing 's' on the device listing screen. A prompt will
37 appear which asks for the sorting parameters. Three main sort methods
38 exist:
39
40 1) Bluetooth address ('b'). This sorts the devices into ascending numerical
41 order. The Bluetooth address is taken as a single hexadecimal number
42 ranging from 0x0 to 0xffffffffffff.
43 2) First Seen ('f'). This compares the time and date of when each device was
44 first scanned. For instance, if each device was only scanned once,
45 Btscanner would append each new device found to the bottom of the list.
46 3) Last seen ('l'). This compares the time and date of when each device was
47 last scanned. For instance, if each device was scanned only once,
48 Btscanner would prepend each new device to the bottom of the displayed list.
49
50 To determine the nature of these sorting methods, it should be remembered
51 that each device stores two timestamps. The first time it was seen, which
52 once stored does not change, and the last time it was seen, which is
53 updated each time the device is re-scanned.
54
55 There is also a reversing function which can be applied to any of the
56 sorting methods. This is activated by prefixing the sort method with 'r'.
57
58 A scan can be interrupted by pressing 'a' (abort scan). This shuts down all
59 scanning threads and returns Btscanner to an idle state.
60
61 Btscanner is capable of saving a summary of device scans. This is achieved
62 by pressing 's'. Btscanner will then prompt for a filename to save the
63 summary to. When a summary log is written out, the internal summary cache
64 is cleared and starts from the beginning again. Therefore a summary is only
65 a summary since the last one was written.
66
67
68 Configuration files
69 -------------------
70
71 The main configuration file is called btscanner.xml and resides in
72 $INSTALL_PREFIX/etc/ which by default is /usr/local/etc. The DTD for this
73 XML file is called btscanner.dtd and resides in the same directory. When
74 an alternate configuration file is used, the DTD is still called from the
75 original position.
76
77 Btscanner uses the IEEE OUI list to look up the manufacturers of each
78 card. This is installed in $INSTALL_PREFIX/share/oui.txt which by default
79 is /usr/local/share/oui.txt.
80
81 Output files
82 ------------
83
84 Btscanner normally outputs a log file of all actions and errors into a file
85 called btscanner.log. This is located in the working directory of the
86 executable. Btscanner also keeps a static store of all devices found. This
87 is located in ~/bts by default. The Directory structure of the store is
88
89 ~/bts/<bdaddr>/info
90
91 Both the log file and the store directory are set in the configuration
92 file and can be changed.
93