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 Dependency packages for common distributions:
  59 ---------------------------------------------
  60 The following is a list of packages you'll need to install to build Barry,
  61 if you are using one of the below common distributions.  Other distributions
  62 should have similar package names.
  63
  64         Fedora 5 and 6:
  65         ---------------
  66         Use the yum package manager to install the following:
  67
  68                 pkgconfig
  69                 libusb-devel
  70                 openssl-devel
  71                 boost-devel (optional)
  72
  73         Debian stable:
  74         --------------
  75         Use the apt-get package manager to install the following:
  76
  77                 pkg-config
  78                 libusb-dev
  79                 libssl-dev
  80                 libboost-serialization-dev
  81
  82
  83 To build Barry:
  84 ---------------
  85
  86         If starting from CVS, run buildgen.sh with no arguments.
  87
  88         export PKG_CONFIG_PATH=/path/to/external/libusb
  89                                 Only needed if you want to use a libusb
  90                                 installed in a non-standard location
  91
  92         ./configure
  93
  94                 set --prefix as needed
  95                 set --with-boost=/path/to/root/boost if you want
  96                         the -f switch to work in btool
  97                 set --enable-gui to recursively build the gui/ subdirectory
  98                         (see gui/README for more info)
  99                 set --enable-opensync-plugin to recursively build the
 100                         opensync-plugin/ subdirectory
 101                         (see opensync-plugin/README for more info)
 102
 103         make
 104
 105         su
 106         make install
 107
 108         This will give you a command line tool called 'btool'.  Use the -h
 109         switch for help on its command line options.  Some good ones to start with
 110         are -l to list the devices found, and -t to list the Database Database.
 111
 112
 113 To generate the Doxygen documentation:
 114 --------------------------------------
 115
 116         run 'doxygen' from inside the src/ directory.
 117
 118         The resulting files will be in doc/doxygen/html/
 119         This has been tested with Doxygen 1.4.5
 120
 121
 122 To build the OpenSync module:
 123 -----------------------------
 124
 125         (see opensync-plugin/README for more information)
 126
 127         cd opensync-plugin
 128         ./configure
 129         make
 130         su
 131         make install
 132
 133
 134 To build the Barry Backup GUI:
 135 ------------------------------
 136
 137         (see gui/README for dependency information)
 138
 139         cd gui
 140         # set PKG_CONFIG_PATH if needed...
 141         ./configure
 142         make
 143         su
 144         make install
 145
 146
 147 BlackBerry protocol:
 148 --------------------
 149 No BlackBerry-related protocol project would be complete without referencing
 150 the fine documentation from the Cassis project, which tackled the earlier
 151 serial protocol.  You can find this documentation at:
 152
 153         http://off.net/cassis/protocol-description.html
 154
 155 There were some major and minor differences found between the serial
 156 protocol and the USB protocol.  Some of the new handheld devices use new
 157 database record access commands, and in these cases the record format changes.
 158 See the code for more detailed information.
 159
 160 Further documentation on the USB protocol is planned.  Stay tuned.
 161
 162
 163 Playing with the protocol:
 164 --------------------------
 165 The USB captures were performed on a Windows XP Pro system running UsbSnoop
 166 from http://benoit.papillault.free.fr/usbsnoop/index.php
 167
 168 You can use the convo.awk and translate.cc tools to turn these very verbose
 169 logs into something more manageable.  Other than the normal USB control
 170 commands at the beginning of each conversation, it was found that only
 171 USB Bulk Transfers were used.
 172
 173 The btool utility is at the stage where it can be used instead of UsbSnoop,
 174 for database operations.  You can use the -v switch to turn on data packet
 175 dumping, which will display the sent and received packets in canonical hex
 176 format as btool talks to the device.  You can use this in combination with
 177 the -d switch to capture new database records to reverse engineer.
 178
 179 If you reverse engineer some of the unimplemented packet formats, please
 180 send patches and/or documentation to the mailing list!
 181
 182 See the Hacking file for more information on getting started reverse
 183 engineering the protocol.
 184
 185
 186 Some notes on code architecture:
 187 --------------------------------
 188
 189 Lowest level:
 190         Lowest level is the libusb software, currently using the stable branch
 191
 192 USB layer:
 193         usbwrap.{h,cc}          - C++ wrapper for libusb
 194         data.{h,cc}             - C++ data class for buffer management
 195                                   and hex log file input and output
 196         debug.h                 - general debugging output support
 197
 198
 199 Barry low level layer:
 200         packet.{h,cc}           - low level packet builder class, having
 201                                   knowledge of specific protocol commands
 202                                   in order to hide protocol details behind
 203                                   an API
 204         protostructs.h          - low level, packed structs representing the
 205                                   USB protocol
 206         time.{h,cc}             - time conversions between 1900-based minutes
 207                                   and C's 1970-based time_t
 208
 209
 210 Barry API layer:
 211         base64.{h,cc}           - base64 encoding and decoding (for LDIF)
 212         builder.h               - C++ virtual wrappers to connect record and
 213                                   controller in a generic way
 214         endian.h                - big/little endian defines... only used for
 215                                   compiling the library, never installed
 216         error.{h,cc}            - common exception classes for Barry layer
 217         probe.{h,cc}            - USB probe class to find Blackberry devices
 218         protocol.{h,cc}         - structs and defines for packets seen on wire
 219         common.{h,cc}           - general API and utilities
 220         socket.{h,cc}           - socket class encapsulating the Blackberry
 221                                   logical socket
 222         record.{h,cc}           - programmer-friendly record classes
 223         parser.{h,cc}           - C++ virtual wrappers to connect record
 224                                   and controller in a generic way
 225         controller.{h,cc}       - high level API class
 226         controllertmpl.h
 227         version.{h,cc}          - library version information
 228         s11n-boost.h            - serialization functions for record.h classes
 229
 230         barry.h                 - C++ application header (only one needed)
 231         cbarry.h                - C application header (incomplete)
 232
 233
 234 Misc utilities:
 235         btool.cc                - command line testing utility
 236         bcharge.cc              - set device to use 500mA, and also enables
 237                                   database access for Blackberry Pearl devices
 238         breset.cc               - does a USB level software reset on all
 239                                   Blackberry devices found
 240         convo.awk               - script to convert UsbSnoop log files into
 241                                   trimmed-down request/response conversations
 242         ktrans.cc               - turns USB kernel capture logs from 2.6
 243                                   kernels into hex+ascii dumps
 244         translate.cc            - translate UsbSnoop log file data into
 245                                   hex+ascii dumps
 246         upldif.cc               - takes an ldap LDIF file on stdin and
 247                                   uploads contact data to the Blackberry
 248
 249 Example code:
 250         addcontact.cc           - example on adding a contact record to
 251                                   the device
 252
 253
 254 Enjoy!
 255
 256 September 2007
 257