doc/www/hacking.html

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