README

   1 Introduction:
   2 -------------
   3 Barry is a GPL C++ library to interface with USB BlackBerry handheld devices
   4 on Linux.  This is one of Net Direct Inc.'s (http://www.netdirect.ca/)
   5 open source projects.
   6
   7 The SourceForge project page can be found at:
   8         http://sourceforge.net/projects/barry/
   9
  10 Barry is currently in early development, but is reaching stages of usefulness.
  11 For example, it is possible to retrieve Address Book contact data, and export
  12 it in text or LDAP LDIF format.
  13
  14
  15 Installation:
  16 -------------
  17 You need:
  18         libusb, devel branch    http://libusb.sourceforge.net/
  19
  20 Check out the V1_0_DEVEL tag/branch from CVS.
  21
  22 Barry uses the asynchronous library calls, which is why the development
  23 branch is used.  The libusb devel branch is well along in its development
  24 cycle, so don't be afraid to play with it.
  25
  26 This version of Barry has been tested using the 2005/11/25 libusb CVS tree.
  27
  28 To build Barry:
  29
  30         - Edit Makefile.conf to point to the proper location for libusb
  31                 headers and library files
  32         - Enter the src/ directory and type 'make'
  33         - If you want to generate doxygen documentation, run 'doxygen'
  34                 as well.  The resulting files will be in doc/doxygen/html/
  35                 This has been tested with Doxygen 1.4.5
  36
  37 This will give you a command line tool called 'btool'.  Use the -h
  38 switch for help on its command line options.  Some good ones to start with
  39 are -l to list the devices found, and -t to list the Database Database.
  40
  41
  42 BlackBerry protocol:
  43 --------------------
  44 No BlackBerry-related protocol project would be complete without referencing
  45 the fine documentation from the Cassis project, which tackled the earlier
  46 serial protocol.  You can find this documentation at:
  47
  48         http://off.net/cassis/protocol-description.html
  49
  50 There were some major and minor differences found between the serial
  51 protocol and the USB protocol.  Some of the new handheld devices use new
  52 database record access commands, and in these cases the record format changes.
  53 Barry tries to handle both.  See the code for more detailed information.
  54
  55 Further documentation on the USB protocol is planned.  Stay tuned.
  56
  57
  58 Playing with the protocol:
  59 --------------------------
  60 The USB captures were performed on a Windows XP Pro system running UsbSnoop
  61 from http://benoit.papillault.free.fr/usbsnoop/index.php
  62
  63 You can use the convo.awk and translate.cc tools to turn these very verbose
  64 logs into something more manageable.  Other than the normal USB control
  65 commands at the beginning of each conversation, it was found that only
  66 USB Bulk Transfers were used.
  67
  68 The btool utility is at the stage where it can be used instead of UsbSnoop,
  69 for database operations.  You can use the -v switch to turn on data packet
  70 dumping, which will display the sent and received packets in canonical hex
  71 format as btool talks to the device.  You can use this in combination with
  72 the -d switch to capture new database records to reverse engineer.
  73
  74 If you reverse engineer some of the unimplemented packet formats, please
  75 send patches and/or documentation to the mailing list!
  76
  77
  78 Some notes on code architecture:
  79 --------------------------------
  80
  81 Lowest level:
  82         Lowest level is the libusb software, currently using the DEVEL branch
  83
  84 USB layer:
  85         usbwrap.{h,cc}          - C++ wrapper for libusb
  86         data.{h,cc}             - C++ data class for buffer management
  87                                   and hex log file input and output
  88         connect.cc              - low level USB test program, capable of
  89                                   using data file scripts to talk to a
  90                                   device via bulk read/write
  91         debug.h                 - general debugging output support
  92
  93
  94 Barry API layer:
  95         error.{h,cc}            - common exception classes for Barry layer
  96         probe.{h,cc}            - USB probe class to find Blackberry devices
  97         protocol.{h,cc}         - structs and defines for packets seen on wire
  98         common.{h,cc}           - general API and utilities
  99         socket.{h,cc}           - socket class encapsulating the Blackberry
 100                                   logical socket
 101         record.{h,cc}           - programmer-friendly record classes
 102         parser.{h,cc}           - C++ virtual wrappers to connect record
 103                                   and controller in a generic way
 104         controller.{h,cc}       - high level API class
 105         btool.cc                - command line testing utility
 106
 107
 108 Misc utilities:
 109         convo.awk               - script to convert UsbSnoop log files into
 110                                   trimmed-down request/response conversations
 111         translate.cc            - translate UsbSnoop log file data into
 112                                   hex+ascii dumps
 113
 114 Enjoy!
 115
 116 November 2005
 117