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 Barry currently relies on an old version of the libusb library.  This
  41 should be fixed in future versions, but in the meantime, you can download
  42 a tarball of libusb from the Barry file download page.
  43
  44 Alternatively you can check out the 2005/12/30 V1_0_DEVEL tag/branch from
  45 libusb's CVS.  To grab a specific date version of libusb, use the
  46 following CVS commands:
  47
  48         cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/libusb \
  49                 co -r V1_0_DEVEL -d libusb-1_0_devel libusb
  50         cd libusb-1_0_devel
  51         cvs update -Pd -r V1_0_DEVEL -D 2005/12/30
  52
  53 Barry uses the asynchronous library calls, which is why the development
  54 branch is used.  The libusb devel branch is well along in its development
  55 cycle, so don't be afraid to play with it.
  56
  57 To build Barry:
  58
  59         - Edit Makefile.conf to point to the proper location for libusb
  60                 headers and library files
  61         - Enter the src/ directory and type 'make'
  62         - If you want to generate doxygen documentation, run 'doxygen'
  63                 as well.  The resulting files will be in doc/doxygen/html/
  64                 This has been tested with Doxygen 1.4.5
  65         - make install - install a static library in the install/
  66                 subdirectory. This is needed if you want to play with
  67                 the opensync module.
  68
  69 This will give you a command line tool called 'btool'.  Use the -h
  70 switch for help on its command line options.  Some good ones to start with
  71 are -l to list the devices found, and -t to list the Database Database.
  72
  73
  74 BlackBerry protocol:
  75 --------------------
  76 No BlackBerry-related protocol project would be complete without referencing
  77 the fine documentation from the Cassis project, which tackled the earlier
  78 serial protocol.  You can find this documentation at:
  79
  80         http://off.net/cassis/protocol-description.html
  81
  82 There were some major and minor differences found between the serial
  83 protocol and the USB protocol.  Some of the new handheld devices use new
  84 database record access commands, and in these cases the record format changes.
  85 See the code for more detailed information.
  86
  87 Further documentation on the USB protocol is planned.  Stay tuned.
  88
  89
  90 Playing with the protocol:
  91 --------------------------
  92 The USB captures were performed on a Windows XP Pro system running UsbSnoop
  93 from http://benoit.papillault.free.fr/usbsnoop/index.php
  94
  95 You can use the convo.awk and translate.cc tools to turn these very verbose
  96 logs into something more manageable.  Other than the normal USB control
  97 commands at the beginning of each conversation, it was found that only
  98 USB Bulk Transfers were used.
  99
 100 The btool utility is at the stage where it can be used instead of UsbSnoop,
 101 for database operations.  You can use the -v switch to turn on data packet
 102 dumping, which will display the sent and received packets in canonical hex
 103 format as btool talks to the device.  You can use this in combination with
 104 the -d switch to capture new database records to reverse engineer.
 105
 106 If you reverse engineer some of the unimplemented packet formats, please
 107 send patches and/or documentation to the mailing list!
 108
 109 See the Hacking file for more information on getting started reverse
 110 engineering the protocol.
 111
 112
 113 Some notes on code architecture:
 114 --------------------------------
 115
 116 Lowest level:
 117         Lowest level is the libusb software, currently using the DEVEL branch
 118
 119 USB layer:
 120         usbwrap.{h,cc}          - C++ wrapper for libusb
 121         data.{h,cc}             - C++ data class for buffer management
 122                                   and hex log file input and output
 123         connect.cc              - low level USB test program, capable of
 124                                   using data file scripts to talk to a
 125                                   device via bulk read/write
 126         debug.h                 - general debugging output support
 127
 128
 129 Barry low level layer:
 130         packet.{h,cc}           - low level packet builder class, having
 131                                   knowledge of specific protocol commands
 132                                   in order to hide protocol details behind
 133                                   an API
 134         protostructs.h          - low level, packed structs representing the
 135                                   USB protocol
 136         time.{h,cc}             - time conversions between 1900-based minutes
 137                                   and C's 1970-based time_t
 138
 139
 140 Barry API layer:
 141         base64.{h,cc}           - base64 encoding and decoding (for LDIF)
 142         builder.h               - C++ virtual wrappers to connect record and
 143                                   controller in a generic way
 144         endian.h                - big/little endian defines
 145         error.{h,cc}            - common exception classes for Barry layer
 146         probe.{h,cc}            - USB probe class to find Blackberry devices
 147         protocol.{h,cc}         - structs and defines for packets seen on wire
 148         common.{h,cc}           - general API and utilities
 149         socket.{h,cc}           - socket class encapsulating the Blackberry
 150                                   logical socket
 151         record.{h,cc}           - programmer-friendly record classes
 152         parser.{h,cc}           - C++ virtual wrappers to connect record
 153                                   and controller in a generic way
 154         controller.{h,cc}       - high level API class
 155         controllertmpl.h
 156         s11n-boost.h            - serialization functions for record.h classes
 157
 158         barry.h                 - application header (only one needed)
 159
 160
 161 Misc utilities:
 162         btool.cc                - command line testing utility
 163         convo.awk               - script to convert UsbSnoop log files into
 164                                   trimmed-down request/response conversations
 165         translate.cc            - translate UsbSnoop log file data into
 166                                   hex+ascii dumps
 167         upldif.cc               - takes an ldap LDIF file on stdin and
 168                                   uploads contact data to the Blackberry
 169
 170 Enjoy!
 171
 172 October 2006
 173