doc/www/hacking.php

   1 <? include ("barry.inc"); ?>
   2
   3 <? createHeader("Hacking Barry"); ?>
   4
   5 <? createSubHeader("BlackBerry protocol"); ?>
   6
   7 <p>No BlackBerry-related protocol project would be complete without referencing
   8 the fine documentation from the Cassis project, which tackled the earlier
   9 serial protocol.  You can find this documentation at:
  10
  11 <ul>
  12 <a href="http://off.net/cassis/protocol-description.html">http://off.net/cassis/protocol-description.html</a>
  13 </ul>
  14
  15 <p>There were some major and minor differences found between the serial
  16 protocol and the USB protocol.  Some of the new handheld devices use new
  17 database record access commands, and in these cases the record format changes.
  18 See the code for more detailed information.</p>
  19
  20 <p>Further documentation on the USB protocol is planned.  Stay tuned.</p>
  21
  22
  23 <? createSubHeader("Playing with the protocol"); ?>
  24
  25 <p>The USB captures were performed on a Windows XP Pro system running UsbSnoop
  26 from <a href="http://benoit.papillault.free.fr/usbsnoop/index.php">http://benoit.papillault.free.fr/usbsnoop/index.php</a></p>
  27
  28 <p>You can use the convo.awk and btranslate.cc tools to turn these very verbose
  29 logs into something more manageable.  Other than the normal USB control
  30 commands at the beginning of each conversation, it was found that only
  31 USB Bulk Transfers were used.</p>
  32
  33 <p>The btool utility is at the stage where it can be used instead of UsbSnoop,
  34 for database operations.  You can use the -v switch to turn on data packet
  35 dumping, which will display the sent and received packets in canonical hex
  36 format as btool talks to the device.  You can use this in combination with
  37 the -d switch to capture new database records to reverse engineer.</p>
  38
  39 <p>If you reverse engineer some of the unimplemented packet formats, please
  40 send patches and/or documentation to the
  41 <a href="http://sourceforge.net/mail/?group_id=153722">mailing list</a>!</p>
  42
  43 <p>See the doc/Hacking file for more information on getting started reverse
  44 engineering the protocol.</p>
  45
  46 <!--
  47
  48 <? createSubHeader("Some notes on code architecture"); ?>
  49
  50 <p><i>Note: this is currently out of date.</i></p>
  51
  52 <p>Lowest level:
  53 <ul>
  54         Lowest level is the libusb software.
  55 </ul>
  56
  57 <p>USB layer:
  58 <ul>
  59 <table border=0>
  60 <tr>
  61         <td valign=top>usbwrap.{h,cc}</td>
  62         <td valign=top>C++ wrapper for libusb</td>
  63 </tr><tr>
  64         <td valign=top>data.{h,cc}</td>
  65         <td valign=top>C++ data class for buffer management and hex log file input and output</td>
  66 </tr><tr>
  67         <td valign=top>debug.h</td>
  68         <td valign=top>general debugging output support</td>
  69 </table>
  70 </ul>
  71
  72
  73 <p>Barry low level layer:
  74 <ul>
  75 <table border=0>
  76 <tr>
  77         <td valign=top>packet.{h,cc}</td>
  78         <td valign=top>low level packet builder class, having knowledge of
  79                 specific protocol commands in order to hide protocol details
  80                 behind an API</td>
  81 </tr><tr>
  82         <td valign=top>protostructs.h</td>
  83         <td valign=top>low level, packed structs representing the USB protocol</td>
  84 </tr><tr>
  85         <td valign=top>time.{h,cc}</td>
  86         <td valign=top>time conversions between 1900-based minutes and C's 1970-based time_t</td>
  87 </table>
  88 </ul>
  89
  90
  91 <p>Barry API layer:
  92 <ul>
  93 <table border=0>
  94 <tr>
  95         <td valign=top>base64.{h,cc}</td>
  96         <td valign=top>base64 encoding and decoding (for LDIF)</td>
  97 </tr><tr>
  98         <td valign=top>builder.h</td>
  99         <td valign=top>C++ virtual wrappers to connect record and controller in a generic way</td>
 100 </tr><tr>
 101         <td valign=top>endian.h</td>
 102         <td valign=top>big/little endian defines... only used for compiling
 103                 the library, never installed</td>
 104 </tr><tr>
 105         <td valign=top>error.{h,cc}</td>
 106         <td valign=top>common exception classes for Barry layer</td>
 107 </tr><tr>
 108         <td valign=top>probe.{h,cc}</td>
 109         <td valign=top>USB probe class to find Blackberry devices</td>
 110 </tr><tr>
 111         <td valign=top>protocol.{h,cc}</td>
 112         <td valign=top>structs and defines for packets seen on wire</td>
 113 </tr><tr>
 114         <td valign=top>common.{h,cc}</td>
 115         <td valign=top>general API and utilities</td>
 116 </tr><tr>
 117         <td valign=top>socket.{h,cc}</td>
 118         <td valign=top>socket class encapsulating the Blackberry logical socket</td>
 119 </tr><tr>
 120         <td valign=top>record.{h,cc}</td>
 121         <td valign=top>programmer-friendly record classes</td>
 122 </tr><tr>
 123         <td valign=top>parser.{h,cc}</td>
 124         <td valign=top>C++ virtual wrappers to connect record and controller in a generic way</td>
 125 </tr><tr>
 126         <td valign=top>controller.{h,cc}, controllertmpl.h</td>
 127         <td valign=top>high level API class</td>
 128 </tr><tr>
 129         <td valign=top>version.h</td>
 130         <td valign=top>library version information and API</td>
 131 </tr><tr>
 132         <td valign=top>s11n-boost.h</td>
 133         <td valign=top>serialization functions for record.h classes</td>
 134 </tr><tr>
 135         <td valign=top>barry.h</td>
 136         <td valign=top>application header (only one needed)</td>
 137 </tr><tr>
 138         <td valign=top>cbarry.h</td>
 139         <td valign=top>C application header (incomplete)</td>
 140 </tr>
 141 </table>
 142 </ul>
 143
 144 <p>Misc utilities:
 145 <ul>
 146 <table border=0>
 147 <tr>
 148         <td valign=top>btool.cc</td>
 149         <td valign=top>command line testing utility</td>
 150 </tr><tr>
 151         <td valign=top>bcharge.cc</td>
 152         <td valign=top>set device to use 500mA, and also enables database access for Blackberry Pearl devices</td>
 153 </tr><tr>
 154         <td valign=top>breset.cc</td>
 155         <td valign=top>does a USB level software reset on all Blackberry devices found</td>
 156 </tr><tr>
 157         <td valign=top>convo.awk</td>
 158         <td valign=top>script to convert UsbSnoop log files into trimmed-down request/response conversations</td>
 159 </tr><tr>
 160         <td valign=top>ktrans.cc</td>
 161         <td valign=top>turns USB kernel capture logs from 2.6 kernels into hex+ascii dumps</td>
 162 </tr><tr>
 163         <td valign=top>translate.cc</td>
 164         <td valign=top>translate UsbSnoop log file data into hex+ascii dumps</td>
 165 </tr><tr>
 166         <td valign=top>upldif.cc</td>
 167         <td valign=top>takes an ldap LDIF file on stdin and uploads contact data to the Blackberry, overwriting existing contacts</td>
 168 </tr>
 169 </table>
 170 </ul>
 171
 172 <p>Example code:
 173 <ul>
 174 <table border=0>
 175 <tr>
 176         <td valign=top>addcontact.cc</td>
 177         <td valign=top>example for adding a contact record to the device</td>
 178 </tr>
 179 </table>
 180 </ul>
 181
 182 -->
 183
 184 <p>Enjoy!</p>
 185