Hacking Barry
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 btranslate.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 doc/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.

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}, controllertmpl.h | high level API class
version.h | library version information and API
s11n-boost.h | serialization functions for record.h classes
barry.h | 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, overwriting existing contacts

Example code:

addcontact.cc | example for adding a contact record to the device

Enjoy!

Copyright © 2008 - Net Direct Inc.