doc/www/rawchannel.php

   1 <? include ("barry.inc"); ?>
   2
   3 <? createHeader("Use Blackberry USB channels with Barry"); ?>
   4
   5 <? createSubHeader("Introduction"); ?>
   6
   7 <p>The Blackberry provides the ability for programs to send and receive data over the USB port via named channels.
   8 On device there are two APIs which provide access to these channels:
   9 <ul>
  10         <li><a href="http://www.blackberry.com/developers/docs/5.0.0api/net/rim/device/api/system/USBPort.html">net.rim.device.api.system.USBPort</a></li>
  11         <li><a href="http://www.blackberry.com/developers/docs/5.0.0api/javax/microedition/io/Connector.html">javax.microedition.io.Connector</a></li>
  12 </ul>
  13 </p>
  14
  15 <p>Barry provides APIs and tools to access the PC side of these USB
  16 channels. The Barry APIs provide similar functionality to the <a
  17 href="http://docs.blackberry.com/en/developers/deliverables/1093/Desktop_API_Reference_Guide_46.pdf">Blackberry
  18 Desktop Manager API</a>.</p>
  19
  20 <p>To use USB channels with Barry you will also need the following:
  21 <ul>
  22         <li> a working Barry install, version 0.17 or later </li>
  23         <li> a program which uses USB channels installed on your Blackberry </li>
  24 </ul>
  25 </p>
  26
  27 <? createSubHeader("Using USB channels to talk to 'USB Demo'"); ?>
  28
  29 <p>As part of the examples provided with the Blackberry JDEs there is a demo
  30 application called 'USB Demo' which can be found in <tt>samples/com/rim/samples/device/usbdemo</tt> in the
  31 installation folder of the JDE. You should build this and install it on your Blackberry.</p>
  32
  33 <p>The Blackberry JDEs come with an example application for the Blackberry Desktop Manager API in
  34 <tt>samples/usbclient</tt> in the installation folder. The equivalent PC side usbclient can be
  35 found in the Barry source in <tt>examples/usbclient.cc</tt></p>
  36
  37 <p>Once the example is compiled it should be used by first running the
  38 'USB Demo' application on the Blackberry and selecting one of the
  39 'Connect' options from the menu. Once the 'USB Demo' application is
  40 waiting then it's possible to run the <tt>usbclient</tt> example to
  41 communicate with the Blackberry application.
  42
  43 <? createSubHeader("Using USB channels as a stream"); ?>
  44
  45 <p>The raw channel API provided by Barry exposes the channel interface
  46 as sending and receiving of packets of data. While this closely
  47 reflects the USB channel protocol, it can be unhelpful for
  48 applications which are designed with <a
  49 href="http://en.wikipedia.org/wiki/Stream_(computing)">streams</a> as
  50 their communication mechanisms. To accommodate this Barry provides
  51 a tool called <tt>brawchannel</tt>. This tool redirects the named
  52 channel over STDIN and STDOUT, allowing easy communication with
  53 pre-existing tools.</p>
  54
  55 <p>For example the following shows an example of using
  56 <tt>brawchannel</tt> to talk to the 'USB Demo' application mentioned
  57 in the previous section.</p>
  58
  59 <p>First it's necessary to run 'USB Demo' on the Blackberry and select
  60 the 'Connect (low level)' menu option.  With that running it's then
  61 possible to run <tt>brawchannel</tt> by supplying the channel name on
  62 the command line. For the 'USB Demo' application this channel name is
  63 <tt>JDE_USBClient</tt>.</p>
  64
  65 <pre>user@machine:~$ brawchannel JDE_USBClient</pre>
  66
  67 <p>If all goes well then you should see nothing but a flashing
  68 cursor. The 'USB Demo' application expects us to say hello, so
  69 type:</p>
  70
  71 <pre>Hello from Barry.&lt;RET&gt;</pre>
  72
  73 <p>You should then see two things, firstly your terminal should now
  74 look like the following:</p>
  75
  76 <pre>user@machine:~$ brawchannel JDE_USBClient
  77 Hello from Barry.
  78 Hello from Device</pre>
  79
  80 <p>Secondly the message you typed should appear on the device (along
  81 with the demo application complaining that it's not the expected
  82 text).  Next we need to say goodbye to the device, so type:</p>
  83
  84 <pre>Goodbye from Barry.&lt;RET&gt;</pre>
  85
  86 <p>The device should then say goodbye back, followed by it closing the connection.</p>
  87
  88 <p>It's also possible to use other programs, such as <tt>socat</tt> to
  89 use the <tt>brawchannel</tt> tool to communicate with the USB channel
  90 via other mechanisms such as TCP/IP sockets.</p>
  91
  92 <p>For further information please see the man page for <tt>brawchannel</tt>.</pre>
  93
  94 <? createSubHeader("Using USB channels in your application"); ?>
  95
  96 <p>It is also possible to use USB channels directly in your
  97 application by linking to the Barry library. To make use of these USB
  98 channels you will need to create an instance of the
  99 <tt>Barry::Mode::RawChannel</tt> class. The Barry source code
 100 demonstrates creation of a RawChannel in
 101 <tt>examples/usbclient.cc</tt> and <tt>tools/brawchannel.cc</tt>.</p>
 102
 103 <p>In it's most basic form this can be done with the following code:</p>
 104 <pre>Barry::Init();
 105 Barry::Probe probe;
 106 if( probe.GetCount() <= 0 ) {
 107     // No blackberry found
 108     return 1;
 109 }
 110
 111 auto_ptr<SocketRoutingQueue> router;
 112 router.reset(new SocketRoutingQueue());
 113 router->SpinoffSimpleReadThread();
 114
 115 Barry::Controller con(probe.Get(0), *router);
 116
 117 Barry::Mode::RawChannel rawChannel(con);
 118
 119 rawChannel.Open("", CHANNEL_NAME);</pre>
 120
 121 <p>With data then sent and received using <tt>rawChannel.Send()</tt> and <tt>rawChannel.Receive()</tt>.</p>