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 *****************************************************************************
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/)
15 The SourceForge project page can be found at:
16 http://sourceforge.net/projects/barry/
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.
26 pkg-config for configure to autodetect library locations
28 libusb, stable (0.1.x)
29 http://libusb.sourceforge.net/
32 http://www.openssl.org/
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
44 Boost is needed for the serialization library, which you need if you want
45 to save downloads for later uploads to the device.
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.
54 OpenSSL is needed for password hashing.
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.
66 Use the yum package manager to install the following:
71 boost-devel (optional)
75 Use the apt-get package manager to install the following:
80 libboost-serialization-dev
86 If starting from CVS, run buildgen.sh with no arguments.
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
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)
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.
113 To generate the Doxygen documentation:
114 --------------------------------------
116 run 'doxygen' from inside the src/ directory.
118 The resulting files will be in doc/doxygen/html/
119 This has been tested with Doxygen 1.4.5
122 To build the OpenSync module:
123 -----------------------------
125 (see opensync-plugin/README for more information)
134 To build the Barry Backup GUI:
135 ------------------------------
137 (see gui/README for dependency information)
140 # set PKG_CONFIG_PATH if needed...
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:
153 http://off.net/cassis/protocol-description.html
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.
160 Further documentation on the USB protocol is planned. Stay tuned.
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
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.
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.
179 If you reverse engineer some of the unimplemented packet formats, please
180 send patches and/or documentation to the mailing list!
182 See the Hacking file for more information on getting started reverse
183 engineering the protocol.
186 Some notes on code architecture:
187 --------------------------------
190 Lowest level is the libusb software, currently using the stable branch
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
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
204 protostructs.h - low level, packed structs representing the
206 time.{h,cc} - time conversions between 1900-based minutes
207 and C's 1970-based time_t
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
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
227 version.{h,cc} - library version information
228 s11n-boost.h - serialization functions for record.h classes
230 barry.h - C++ application header (only one needed)
231 cbarry.h - C application header (incomplete)
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
246 upldif.cc - takes an ldap LDIF file on stdin and
247 uploads contact data to the Blackberry
250 addcontact.cc - example on adding a contact record to