
*****************************************************************************
*  CAUTION: This is alpha software.  Please make complete backups of your   *
*           Blackberry device before experimenting.  While the author has   *
*           had good success with this software, that is no guarantee that  *
*           you will.  Please make backups.                                 *
*****************************************************************************

Introduction:
-------------
Barry is a GPL C++ library to interface with USB BlackBerry handheld devices
on Linux.  This is one of Net Direct Inc.'s (http://www.netdirect.ca/)
open source projects.

The SourceForge project page can be found at:
	http://sourceforge.net/projects/barry/

Barry is currently in early development, but is reaching stages of usefulness.
For example, it is possible to retrieve Address Book contact data, and export
it in text or LDAP LDIF format.


Installation:
-------------
You need:
	pkg-config		for configure to autodetect library locations

	libusb, stable (0.1.x)
				http://libusb.sourceforge.net/

	openssl
				http://www.openssl.org/

	boost 1.33 (optional)
				http://www.boost.org/

If building directly from CVS instead of from a release tarball, you also need:
	automake (1.9)		run from buildgen.sh
	autoconf (2.59)		run from buildgen.sh


Boost:

Boost is needed for the serialization library, which you need if you want
to save downloads for later uploads to the device.

Libusb:

Install the stable libusb packages (library and devel) from your distribution.
Version 0.1.x is the series you want, and is commonly available.

OpenSSL:

OpenSSL is needed for password hashing.



Dependency packages for common distributions:
---------------------------------------------
The following is a list of packages you'll need to install to build Barry,
if you are using one of the below common distributions.  Other distributions
should have similar package names.

	Fedora 5 and 6:
	---------------
	Use the yum package manager to install the following:

		pkgconfig
		libusb-devel
		openssl-devel
		boost-devel (optional)

	Debian stable:
	--------------
	Use the apt-get package manager to install the following:

		pkg-config
		libusb-dev
		libssl-dev
		libboost-serialization-dev


To build Barry:
---------------

	If starting from CVS, run buildgen.sh with no arguments.

	export PKG_CONFIG_PATH=/path/to/external/libusb
				Only needed if you want to use a libusb
				installed in a non-standard location

	./configure

		set --prefix as needed
		set --with-boost=/path/to/root/boost if you want
			the -f switch to work in btool

	make

	su
	make install

	This will give you a command line tool called 'btool'.  Use the -h
	switch for help on its command line options.  Some good ones to start with
	are -l to list the devices found, and -t to list the Database Database.


To generate the Doxygen documentation:
--------------------------------------

	run 'doxygen' from inside the src/ directory.

	The resulting files will be in doc/doxygen/html/
	This has been tested with Doxygen 1.4.5


To build the OpenSync module:
-----------------------------

	(see opensync-plugin/README for more information)

	cd opensync-plugin
	./configure
	make
	su
	make install


To build the Barry Backup GUI:
------------------------------

	(see gui/README for dependency information)

	cd gui
	# set PKG_CONFIG_PATH if needed...
	./configure
	make
	su
	make install


BlackBerry protocol:
--------------------
No BlackBerry-related protocol project would be complete without referencing
the fine documentation from the Cassis project, which tackled the earlier
serial protocol.  You can find this documentation at:

	http://off.net/cassis/protocol-description.html

There were some major and minor differences found between the serial
protocol and the USB protocol.  Some of the new handheld devices use new
database record access commands, and in these cases the record format changes.
See the code for more detailed information.

Further documentation on the USB protocol is planned.  Stay tuned.


Playing with the protocol:
--------------------------
The USB captures were performed on a Windows XP Pro system running UsbSnoop
from http://benoit.papillault.free.fr/usbsnoop/index.php

You can use the convo.awk and translate.cc tools to turn these very verbose
logs into something more manageable.  Other than the normal USB control
commands at the beginning of each conversation, it was found that only
USB Bulk Transfers were used.

The btool utility is at the stage where it can be used instead of UsbSnoop,
for database operations.  You can use the -v switch to turn on data packet
dumping, which will display the sent and received packets in canonical hex
format as btool talks to the device.  You can use this in combination with
the -d switch to capture new database records to reverse engineer.

If you reverse engineer some of the unimplemented packet formats, please
send patches and/or documentation to the mailing list!

See the Hacking file for more information on getting started reverse
engineering the protocol.


Some notes on code architecture:
--------------------------------

Lowest level:
	Lowest level is the libusb software, currently using the stable branch

USB layer:
	usbwrap.{h,cc}		- C++ wrapper for libusb
	data.{h,cc}		- C++ data class for buffer management
				  and hex log file input and output
	debug.h			- general debugging output support


Barry low level layer:
	packet.{h,cc}		- low level packet builder class, having
				  knowledge of specific protocol commands
				  in order to hide protocol details behind
				  an API
	protostructs.h		- low level, packed structs representing the
				  USB protocol
	time.{h,cc}		- time conversions between 1900-based minutes
				  and C's 1970-based time_t


Barry API layer:
	base64.{h,cc}		- base64 encoding and decoding (for LDIF)
	builder.h		- C++ virtual wrappers to connect record and
				  controller in a generic way
	endian.h		- big/little endian defines... only used for
				  compiling the library, never installed
	error.{h,cc}		- common exception classes for Barry layer
	probe.{h,cc}		- USB probe class to find Blackberry devices
	protocol.{h,cc}		- structs and defines for packets seen on wire
	common.{h,cc}		- general API and utilities
	socket.{h,cc}		- socket class encapsulating the Blackberry
				  logical socket
	record.{h,cc}		- programmer-friendly record classes
	parser.{h,cc}		- C++ virtual wrappers to connect record
				  and controller in a generic way
	controller.{h,cc}	- high level API class
	controllertmpl.h
	version.{h,cc}		- library version information
	s11n-boost.h		- serialization functions for record.h classes

	barry.h			- C++ application header (only one needed)
	cbarry.h		- C application header (incomplete)


Misc utilities:
	btool.cc		- command line testing utility
	bcharge.cc		- set device to use 500mA, and also enables
				  database access for Blackberry Pearl devices
	breset.cc		- does a USB level software reset on all
				  Blackberry devices found
	convo.awk		- script to convert UsbSnoop log files into
				  trimmed-down request/response conversations
	ktrans.cc		- turns USB kernel capture logs from 2.6
				  kernels into hex+ascii dumps
	translate.cc		- translate UsbSnoop log file data into
				  hex+ascii dumps
	upldif.cc		- takes an ldap LDIF file on stdin and
				  uploads contact data to the Blackberry

Example code:
	addcontact.cc		- example on adding a contact record to
				  the device


Enjoy!

February 2007

