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