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