README

   1
   2 *****************************************************************************
   3 *  CAUTION: This is alpha software.  Please make complete backups of your   *
   4 *           Blackberry device before experimenting.  While the author has   *
   5 *           had good success with this software, that is no guarantee that  *
   6 *           you will.  Please make backups.                                 *
   7 *****************************************************************************
   8
   9 Introduction:
  10 -------------
  11 Barry is a GPL C++ library to interface with USB BlackBerry handheld devices
  12 on Linux.  This is one of Net Direct Inc.'s (http://www.netdirect.ca/)
  13 open source projects.
  14
  15 The SourceForge project page can be found at:
  16         http://sourceforge.net/projects/barry/
  17
  18 Barry is currently in early development, but is reaching stages of usefulness.
  19 For example, it is possible to retrieve Address Book contact data, and export
  20 it in text or LDAP LDIF format.
  21
  22
  23 Installation:
  24 -------------
  25 You need:
  26         libusb, devel branch (as of 2005/12/30)
  27                                 http://libusb.sourceforge.net/
  28
  29         boost 1.33 (optional)
  30                                 http://www.boost.org/
  31
  32
  33 Boost:
  34
  35 Boost is needed for the serialization library, which you need if you want
  36 to save downloads for later uploads to the device.
  37
  38 Libusb:
  39
  40 Check out the 2005/12/30 V1_0_DEVEL tag/branch from CVS, or download it
  41 as a tarball from the Barry file download page.
  42
  43 To grab a specific date version of libusb, use the following CVS commands:
  44
  45         cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/libusb \
  46                 co -r V1_0_DEVEL -d libusb-1_0_devel libusb
  47         cd libusb-1_0_devel
  48         cvs update -Pd -r V1_0_DEVEL -D 2005/12/30
  49
  50 Barry uses the asynchronous library calls, which is why the development
  51 branch is used.  The libusb devel branch is well along in its development
  52 cycle, so don't be afraid to play with it.
  53
  54 To build Barry:
  55
  56         - Edit Makefile.conf to point to the proper location for libusb
  57                 headers and library files
  58         - Enter the src/ directory and type 'make'
  59         - If you want to generate doxygen documentation, run 'doxygen'
  60                 as well.  The resulting files will be in doc/doxygen/html/
  61                 This has been tested with Doxygen 1.4.5
  62
  63 This will give you a command line tool called 'btool'.  Use the -h
  64 switch for help on its command line options.  Some good ones to start with
  65 are -l to list the devices found, and -t to list the Database Database.
  66
  67
  68 BlackBerry protocol:
  69 --------------------
  70 No BlackBerry-related protocol project would be complete without referencing
  71 the fine documentation from the Cassis project, which tackled the earlier
  72 serial protocol.  You can find this documentation at:
  73
  74         http://off.net/cassis/protocol-description.html
  75
  76 There were some major and minor differences found between the serial
  77 protocol and the USB protocol.  Some of the new handheld devices use new
  78 database record access commands, and in these cases the record format changes.
  79 See the code for more detailed information.
  80
  81 Further documentation on the USB protocol is planned.  Stay tuned.
  82
  83
  84 Playing with the protocol:
  85 --------------------------
  86 The USB captures were performed on a Windows XP Pro system running UsbSnoop
  87 from http://benoit.papillault.free.fr/usbsnoop/index.php
  88
  89 You can use the convo.awk and translate.cc tools to turn these very verbose
  90 logs into something more manageable.  Other than the normal USB control
  91 commands at the beginning of each conversation, it was found that only
  92 USB Bulk Transfers were used.
  93
  94 The btool utility is at the stage where it can be used instead of UsbSnoop,
  95 for database operations.  You can use the -v switch to turn on data packet
  96 dumping, which will display the sent and received packets in canonical hex
  97 format as btool talks to the device.  You can use this in combination with
  98 the -d switch to capture new database records to reverse engineer.
  99
 100 If you reverse engineer some of the unimplemented packet formats, please
 101 send patches and/or documentation to the mailing list!
 102
 103 See the Hacking file for more information on getting started reverse
 104 engineering the protocol.
 105
 106
 107 Some notes on code architecture:
 108 --------------------------------
 109
 110 Lowest level:
 111         Lowest level is the libusb software, currently using the DEVEL branch
 112
 113 USB layer:
 114         usbwrap.{h,cc}          - C++ wrapper for libusb
 115         data.{h,cc}             - C++ data class for buffer management
 116                                   and hex log file input and output
 117         connect.cc              - low level USB test program, capable of
 118                                   using data file scripts to talk to a
 119                                   device via bulk read/write
 120         debug.h                 - general debugging output support
 121
 122
 123 Barry low level layer:
 124         protostructs.h          - low level, packed structs representing the
 125                                   USB protocol
 126         time.{h,cc}             - time conversions between 1900-based minutes
 127                                   and C's 1970-based time_t
 128
 129
 130 Barry API layer:
 131         base64.{h,cc}           - base64 encoding and decoding (for LDIF)
 132         builder.h               - C++ virtual wrappers to connect record and
 133                                   controller in a generic way
 134         error.{h,cc}            - common exception classes for Barry layer
 135         probe.{h,cc}            - USB probe class to find Blackberry devices
 136         protocol.{h,cc}         - structs and defines for packets seen on wire
 137         common.{h,cc}           - general API and utilities
 138         socket.{h,cc}           - socket class encapsulating the Blackberry
 139                                   logical socket
 140         record.{h,cc}           - programmer-friendly record classes
 141         parser.{h,cc}           - C++ virtual wrappers to connect record
 142                                   and controller in a generic way
 143         controller.{h,cc}       - high level API class
 144         s11n-boost.h            - serialization functions for record.h classes
 145
 146         barry.h                 - application header (only one needed)
 147
 148
 149 Misc utilities:
 150         btool.cc                - command line testing utility
 151         convo.awk               - script to convert UsbSnoop log files into
 152                                   trimmed-down request/response conversations
 153         translate.cc            - translate UsbSnoop log file data into
 154                                   hex+ascii dumps
 155
 156 Enjoy!
 157
 158 December 2005
 159