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