|
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:
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.
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.
Note: this is currently out of date.
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!
|
