Usage manual for Btscanner ========================== Starting Btscanner ------------------ btscanner [--cfg=] [--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//info Both the log file and the store directory are set in the configuration file and can be changed.