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