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         pkg-config              for configure to autodetect library locations
  27
  28         libusb, stable (0.1.x)
  29                                 http://libusb.sourceforge.net/
  30
  31         openssl
  32                                 http://www.openssl.org/
  33
  34         boost 1.33 (optional)
  35                                 http://www.boost.org/
  36
  37 If building directly from CVS instead of from a release tarball, you also need:
  38         automake (1.9)          run from buildgen.sh
  39         autoconf (2.59)         run from buildgen.sh
  40
  41
  42 Boost:
  43
  44 Boost is needed for the serialization library, which you need if you want
  45 to save downloads for later uploads to the device.
  46
  47 Libusb:
  48
  49 Install the stable libusb packages (library and devel) from your distribution.
  50 Version 0.1.x is the series you want, and is commonly available.
  51
  52 OpenSSL:
  53
  54 OpenSSL is needed for password hashing.
  55
  56
  57
  58 To build Barry:
  59 ---------------
  60
  61         If starting from CVS, run buildgen.sh with no arguments.
  62
  63         export PKG_CONFIG_PATH=/path/to/external/libusb
  64                                 Only needed if you want to use a libusb
  65                                 installed in a non-standard location
  66
  67         ./configure
  68
  69                 set --prefix as needed
  70                 set --with-boost=/path/to/root/boost if you want
  71                         the -f switch to work in btool
  72
  73         make
  74
  75         su
  76         make install
  77
  78         This will give you a command line tool called 'btool'.  Use the -h
  79         switch for help on its command line options.  Some good ones to start with
  80         are -l to list the devices found, and -t to list the Database Database.
  81
  82
  83 To generate the Doxygen documentation:
  84 --------------------------------------
  85
  86         run 'doxygen' from inside the src/ directory.
  87
  88         The resulting files will be in doc/doxygen/html/
  89         This has been tested with Doxygen 1.4.5
  90
  91
  92 To build the OpenSync module:
  93 -----------------------------
  94
  95         cd opensync-plugin
  96         ./configure
  97
  98                 set --with-libusb
  99                 set --with-barry
 100
 101         make
 102         su
 103         make install
 104
 105
 106 To build the Barry Backup GUI:
 107 ------------------------------
 108
 109         (see gui/README for dependency information)
 110
 111         cd gui
 112         # set PKG_CONFIG_PATH if needed...
 113         ./configure
 114         make
 115         su
 116         make install
 117
 118
 119 BlackBerry protocol:
 120 --------------------
 121 No BlackBerry-related protocol project would be complete without referencing
 122 the fine documentation from the Cassis project, which tackled the earlier
 123 serial protocol.  You can find this documentation at:
 124
 125         http://off.net/cassis/protocol-description.html
 126
 127 There were some major and minor differences found between the serial
 128 protocol and the USB protocol.  Some of the new handheld devices use new
 129 database record access commands, and in these cases the record format changes.
 130 See the code for more detailed information.
 131
 132 Further documentation on the USB protocol is planned.  Stay tuned.
 133
 134
 135 Playing with the protocol:
 136 --------------------------
 137 The USB captures were performed on a Windows XP Pro system running UsbSnoop
 138 from http://benoit.papillault.free.fr/usbsnoop/index.php
 139
 140 You can use the convo.awk and translate.cc tools to turn these very verbose
 141 logs into something more manageable.  Other than the normal USB control
 142 commands at the beginning of each conversation, it was found that only
 143 USB Bulk Transfers were used.
 144
 145 The btool utility is at the stage where it can be used instead of UsbSnoop,
 146 for database operations.  You can use the -v switch to turn on data packet
 147 dumping, which will display the sent and received packets in canonical hex
 148 format as btool talks to the device.  You can use this in combination with
 149 the -d switch to capture new database records to reverse engineer.
 150
 151 If you reverse engineer some of the unimplemented packet formats, please
 152 send patches and/or documentation to the mailing list!
 153
 154 See the Hacking file for more information on getting started reverse
 155 engineering the protocol.
 156
 157
 158 Some notes on code architecture:
 159 --------------------------------
 160
 161 Lowest level:
 162         Lowest level is the libusb software, currently using the DEVEL branch
 163
 164 USB layer:
 165         usbwrap.{h,cc}          - C++ wrapper for libusb
 166         data.{h,cc}             - C++ data class for buffer management
 167                                   and hex log file input and output
 168         connect.cc              - low level USB test program, capable of
 169                                   using data file scripts to talk to a
 170                                   device via bulk read/write
 171         debug.h                 - general debugging output support
 172
 173
 174 Barry low level layer:
 175         packet.{h,cc}           - low level packet builder class, having
 176                                   knowledge of specific protocol commands
 177                                   in order to hide protocol details behind
 178                                   an API
 179         protostructs.h          - low level, packed structs representing the
 180                                   USB protocol
 181         time.{h,cc}             - time conversions between 1900-based minutes
 182                                   and C's 1970-based time_t
 183
 184
 185 Barry API layer:
 186         base64.{h,cc}           - base64 encoding and decoding (for LDIF)
 187         builder.h               - C++ virtual wrappers to connect record and
 188                                   controller in a generic way
 189         endian.h                - big/little endian defines
 190         error.{h,cc}            - common exception classes for Barry layer
 191         probe.{h,cc}            - USB probe class to find Blackberry devices
 192         protocol.{h,cc}         - structs and defines for packets seen on wire
 193         common.{h,cc}           - general API and utilities
 194         socket.{h,cc}           - socket class encapsulating the Blackberry
 195                                   logical socket
 196         record.{h,cc}           - programmer-friendly record classes
 197         parser.{h,cc}           - C++ virtual wrappers to connect record
 198                                   and controller in a generic way
 199         controller.{h,cc}       - high level API class
 200         controllertmpl.h
 201         s11n-boost.h            - serialization functions for record.h classes
 202
 203         barry.h                 - application header (only one needed)
 204
 205
 206 Misc utilities:
 207         btool.cc                - command line testing utility
 208         convo.awk               - script to convert UsbSnoop log files into
 209                                   trimmed-down request/response conversations
 210         translate.cc            - translate UsbSnoop log file data into
 211                                   hex+ascii dumps
 212         upldif.cc               - takes an ldap LDIF file on stdin and
 213                                   uploads contact data to the Blackberry
 214
 215 Enjoy!
 216
 217 February 2007
 218