- moved Interface implementation to usbwrap.cc file
[barry.git] / README
blob98d31d9dc8c03070b936ee1731cabd23ba8ecf09
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
98         make
100         su
101         make install
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.
108 To generate the Doxygen documentation:
109 --------------------------------------
111         run 'doxygen' from inside the src/ directory.
113         The resulting files will be in doc/doxygen/html/
114         This has been tested with Doxygen 1.4.5
117 To build the OpenSync module:
118 -----------------------------
120         (see opensync-plugin/README for more information)
122         cd opensync-plugin
123         ./configure
124         make
125         su
126         make install
129 To build the Barry Backup GUI:
130 ------------------------------
132         (see gui/README for dependency information)
134         cd gui
135         # set PKG_CONFIG_PATH if needed...
136         ./configure
137         make
138         su
139         make install
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:
148         http://off.net/cassis/protocol-description.html
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.
155 Further documentation on the USB protocol is planned.  Stay tuned.
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
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.
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.
174 If you reverse engineer some of the unimplemented packet formats, please
175 send patches and/or documentation to the mailing list!
177 See the Hacking file for more information on getting started reverse
178 engineering the protocol.
181 Some notes on code architecture:
182 --------------------------------
184 Lowest level:
185         Lowest level is the libusb software, currently using the stable branch
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
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
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
225         barry.h                 - C++ application header (only one needed)
226         cbarry.h                - C application header (incomplete)
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
244 Example code:
245         addcontact.cc           - example on adding a contact record to
246                                   the device
249 Enjoy!
251 February 2007