- large update to the doc/www web pages, moving some of the
[barry.git] / README
blobf8094a31f5f30a9c422c334dd8487e36e095dd97
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 *****************************************************************************
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.
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.
23 Installation:
24 -------------
25 You need:
26         pkg-config              for configure to autodetect library locations
28         libusb, stable (0.1.x)
29                                 http://libusb.sourceforge.net/
31         openssl
32                                 http://www.openssl.org/
34         boost 1.33 (optional)
35                                 http://www.boost.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
42 Boost:
44 Boost is needed for the serialization library, which you need if you want
45 to save downloads for later uploads to the device.
47 Libusb:
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.
52 OpenSSL:
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.
64         Fedora 5 and 6:
65         ---------------
66         Use the yum package manager to install the following:
68                 pkgconfig
69                 libusb-devel
70                 openssl-devel
71                 boost-devel (optional)
73         Debian stable:
74         --------------
75         Use the apt-get package manager to install the following:
77                 pkg-config
78                 libusb-dev
79                 libssl-dev
80                 libboost-serialization-dev
83 To build Barry:
84 ---------------
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
92         ./configure
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)
103         make
105         su
106         make install
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)
127         cd opensync-plugin
128         ./configure
129         make
130         su
131         make install
134 To build the Barry Backup GUI:
135 ------------------------------
137         (see gui/README for dependency information)
139         cd gui
140         # set PKG_CONFIG_PATH if needed...
141         ./configure
142         make
143         su
144         make install
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:
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 --------------------------------
189 Lowest level:
190         Lowest level is the libusb software, currently using the stable branch
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
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
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
230         barry.h                 - C++ application header (only one needed)
231         cbarry.h                - C application header (incomplete)
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
249 Example code:
250         addcontact.cc           - example on adding a contact record to
251                                   the device
254 Enjoy!
256 September 2007