Attachment 31547 Details for Bug 52514 – patch

[patch] patch

patch (text/plain), 18.74 KB, created by Jan Hornyak on 2003-06-01 12:43:49 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Jan Hornyak

Created: 2003-06-01 12:43:49 UTC

Size: 18.74 KB

patch

obsolete

>--- original.sgml	Sun May 25 12:34:18 2003
>+++ chapter.sgml	Sun Jun  1 13:31:56 2003
>@@ -6732,6 +6732,395 @@
> 	support AAAA records.</para>
>     </sect2>
>   </sect1>
>+
>+  <sect1 id="network-bluetooth">
>+    <sect1info>
>+      <authorgroup>
>+        <author>
>+          <firstname>Pav</firstname>
>+          <surname>Lucistnik</surname>
>+          <contrib>Written by </contrib>
>+          <affiliation>
>+            <address><email>pav@oook.cz</email></address>
>+          </affiliation>
>+        </author>
>+      </authorgroup>
>+    </sect1info>
>+    <title>Bluetooth</title>
>+    
>+    <indexterm><primary>Bluetooth</primary></indexterm>
>+    <sect2>
>+      <title>Introduction</title>
>+      <para>Bluetooth is a wireless technology for creating personal networks
>+        operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
>+        Networks are usually formed ad-hoc from portable devices like mobile
>+        phones, handhelds and laptops.  Unlike the other popular wireless
>+        technology, Wi-Fi, Bluetooth offers higher level service profiles,
>+        e.g.  FTP-like file servers, file pushing, voice transport, serial
>+        line emulation and more.</para>
>+      
>+      <para>The Bluetooth stack in &os; is implemented using the Netgraph
>+        facility (see &man.netgraph.4;).
>+        A Broad variety of USB dongles is supported by the &man.ng.ubt.4; driver.
>+        The 3Com PC Card 3CRWB60-A is supported by the &man.ng.bt3c.4; driver.
>+        Serial and UART based Bluetooth devices are supported via
>+        &man.ng.h4.4; and &man.hcseriald.8;.  This chapter describes using
>+        a USB Bluetooth dongle.  Bluetooth support is available
>+	in &os; 5.0 and newer systems.</para>
>+    </sect2>
>+    
>+    <sect2>
>+      <title>Plugging in the Device</title>
>+      <para>Device drivers are by default available as kernel modules.
>+        Before attaching a device, you need to load the driver into the
>+	kernel:</para>
>+      
>+      <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>
>+      
>+      <para>If the Bluetooth device is present in the system during system
>+        startup, load the module from <filename>/boot/loader.conf</filename>:</para>
>+        
>+      <programlisting>ng_ubt_load="YES"</programlisting>
>+        
>+      <para>Plug in your USB dongle.  Similar output will appear on the console
>+        (or in syslog):</para>
>+      
>+      <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
>+ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
>+ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3;
>+      wMaxPacketSize=49; nframes=6, buffer size=294</screen>
>+      
>+      <para>Copy <filename>/usr/src/share/examples/netgraph/bluetooth/rc.bluetooth</filename>
>+        to some convenient place, like <filename>/etc/rc.bluetooth</filename>.
>+        This script is used to start and stop the Bluetooth stack.  It is a good idea
>+        to stop the stack before unplugging the device, but it is not (usually)
>+        fatal.  When starting the stack, you will receive output similar to this:</para>
>+      
>+      <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput>
>+BD_ADDR: 00:02:72:00:d4:1a
>+Features: 0xff 0xff 0xf 00 00 00 00 00 
>+&lt;3-Slot&gt; &lt;5-Slot&gt; &lt;Encryption&gt; &lt;Slot offset&gt;
>+&lt;Timing accuracy&gt; &lt;Switch&gt; &lt;Hold mode&gt; &lt;Sniff mode&gt;
>+&lt;Park mode&gt; &lt;RSSI&gt; &lt;Channel quality&gt; &lt;SCO link&gt;
>+&lt;HV2 packets&gt; &lt;HV3 packets&gt; &lt;u-law log&gt; &lt;A-law log&gt; &lt;CVSD&gt;
>+&lt;Paging scheme&gt; &lt;Power control&gt; &lt;Transparent SCO data&gt; 
>+Max. ACL packet size: 192 bytes
>+Number of ACL packets: 8
>+Max. SCO packet size: 64 bytes
>+Number of SCO packets: 8</screen>
>+      
>+    </sect2>
>+    
>+    <indexterm><primary>HCI</primary></indexterm>
>+    <sect2>
>+      <title>HCI and Inquiry</title>
>+
>+      <para>Now it is time to discover some nearby Bluetooth devices.
>+        Tasks like discovering devices, and such are done with
>+        the &man.hccontrol.8; utility.  You will receive a list of discoverable
>+        devices in a few seconds:</para>
>+
>+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
>+Inquiry result, num_responses=1
>+Inquiry result #0
>+        BD_ADDR: 00:80:37:29:19:a4
>+        Page Scan Rep. Mode: 0x1
>+        Page Scan Period Mode: 00
>+        Page Scan Mode: 00
>+        Class: 52:02:04
>+        Clock offset: 0x78ef
>+Inquiry complete. Status: No error [00]</screen>
>+
>+      <para><literal>BD_ADDR</literal> is the unique address of a Bluetooth device, similar to MAC
>+        addresses of network cards.  This address is needed for further
>+        communication with a device.  Let us try to read the device's name:</para>
>+
>+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 0 0 0</userinput>
>+BD_ADDR: 00:80:37:29:19:a4
>+Name: Pav's T39</screen>
>+
>+      <para>If you perform a discovery on a different Bluetooth device, it will find
>+        your computer as <quote>your.host.name (ubt0)</quote>.</para>
>+
>+      <para>You can list active baseband connections:</para>
>+
>+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
>+Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State
>+00:80:37:29:19:a4     41  ACL    0 MAST    NONE       0     0 OPEN</screen>
>+
>+      <para>Handle is useful for manually disconnecting a connection:</para>
>+
>+      <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
>+Connection handle: 41
>+Reason: Connection terminated by local host [0x16]</screen>
>+
>+      <para>Refer to <command>hccontrol help</command> for a complete listing of
>+        available commands.  Note that the majority of commands does not require
>+        superuser privileges.</para>
>+                                
>+    </sect2>
>+    
>+    <indexterm><primary>L2CAP</primary></indexterm>
>+    <sect2>
>+      <title>L2CAP</title>
>+
>+      <para>L2CAP is a higher level of connection in Bluetooth standards.
>+        A useful command is &man.l2ping.8;, which can be used to ping
>+        other devices.  Some devices might not return all of the data
>+        send to them, so <emphasis>0 bytes</emphasis> as in this example
>+        is a normal state.</para>
>+
>+      <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
>+0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 
>+0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 
>+0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 
>+0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>
>+
>+      <para>The &man.l2control.8; utility is used to configure L2CAP nodes
>+        and read their state.  This example shows file transfer to a Palm
>+        handheld:</para>
>+
>+      <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
>+L2CAP channels:
>+Remote BD_ADDR     SCID/ DCID   PSM  IMTU/ OMTU State
>+00:07:e0:00:0b:ca    66/   64     3   132/  672 OPEN
>+&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
>+L2CAP connections:
>+Remote BD_ADDR    Handle Flags Pending State
>+00:07:e0:00:0b:ca     41 O           0 OPEN</screen>
>+
>+      <para>Another diagnostic tool is &man.btsockstat.1;.  It does a similar
>+        job as &man.netstat.1; does, but for Bluetooth sockets, logical
>+        connections on top of baseband connections.  The example output shows
>+        the same connection as l2control above:</para>
>+
>+      <screen>&prompt.user; <userinput>btsockstat</userinput>
>+Active L2CAP sockets
>+PCB      Recv-Q Send-Q Local address/PSM       Foreign address   CID   State
>+c2afe900      0      0 00:02:72:00:d4:1a/3     00:07:e0:00:0b:ca 66    OPEN
>+Active RFCOMM sessions
>+L2PCB    PCB      Flag MTU   Out-Q DLCs State
>+c2afe900 c2b53380 1    127   0     Yes  OPEN
>+Active RFCOMM sockets
>+PCB      Recv-Q Send-Q Local address     Foreign address   Chan DLCI State
>+c2e8bc80      0    250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3    6    OPEN</screen>
>+
>+    </sect2>
>+    
>+    <indexterm><primary>pairing</primary></indexterm>
>+    <sect2>
>+      <title>Pairing of Devices</title>
>+
>+      <para>By default, Bluetooth communication is not authenticated and any device
>+        can talk to any other device.  Some devices, like mobile phones, require
>+        authentication for some functionality, like Internet connections.  This
>+        is done with PIN numbers - you enter the same (up to 16 digits long)
>+        number on both devices.  This operation is called <emphasis>pairing</emphasis>.
>+        The daemon that answers pairing requests is &man.hcsecd.8;.  Copy
>+        <filename>/usr/src/usr.sbin/bluetooth/hcsecd/hcsecd.conf</filename>
>+        to <filename>/usr/local/etc</filename> and edit it.  The following is an
>+	example section for a mobile phone, with the PIN arbitrarily set to 1234:</para>
>+
>+      <programlisting>device {
>+        bdaddr  00:80:37:29:19:a4;
>+        name    "Pav's T39";
>+        key     nokey;
>+        pin     "1234";
>+      }</programlisting>
>+
>+      <para>You can choose any PIN you like.  Note that some devices, like
>+        headsets, have a fixed PIN built in.  Start <command>hcsecd -d</command>.
>+        The <option>-d</option> switch forces the daemon to stay in the
>+        terminal and not fork to the background, so we can see what is happening.
>+        Set the remote device to receive pairing and initiate the HCI connection
>+        to the remote device.  The remote device should say that pairing was
>+        accepted, and let you enter the PIN.  Enter the same PIN as you have in your
>+        <filename>hcsecd.conf</filename>.  Now your PC and remote device are paired.
>+        Alternatively, you can initiate pairing on the remote device.
>+        This will appear in the <command>hcsecd</command> output:</para>
>+
>+<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
>+hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
>+hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
>+hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
>+hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
>+hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting>
>+
>+    </sect2>
>+    
>+    <indexterm><primary>SDP</primary></indexterm>
>+    <sect2>
>+      <title>Service Discovery Protocol (SDP)</title>
>+      <para>If you want to know which services a Bluetooth device offers, and
>+        on which RFCOMM channels, build <application>libbluetooth</application>
>+        and <application>sdp-1.0rc3</application> from <ulink
>+        url="http://www.geocities.com/m_evmenkin/">Maksim Yevmenkin's
>+        snapshot</ulink>.  Then, run <application>sdptool</application> and
>+        observe (the output is snipped a bit, as this tool is quite talky):</para>
>+
>+      <screen>&prompt.root; <userinput>sdptool browse 00:80:37:29:19:a4</userinput>
>+Browsing 00:80:37:29:19:A4 ...
>+Service Name: Dial-up Networking
>+Protocol Descriptor List:
>+  "L2CAP" (0x0100)
>+  "RFCOMM" (0x0003)
>+    Channel: 1
>+
>+Service Name: Fax
>+Protocol Descriptor List:
>+  "L2CAP" (0x0100)
>+  "RFCOMM" (0x0003)
>+    Channel: 2
>+
>+Service Name: Voice gateway
>+Service Class ID List:
>+  "Headset Audio Gateway" (0x1112)
>+  "Generic Audio" (0x1203)
>+Protocol Descriptor List: 
>+  "L2CAP" (0x0100)
>+  "RFCOMM" (0x0003)
>+    Channel: 3
>+</screen>
>+
>+      <para>... and so on.  You will need the channel number later for using
>+        a given service.  Some devices do not support browsing, they return
>+        an empty list, but you can try searching for a specific service.</para>
>+
>+      <screen>&prompt.root; <userinput>sdptool search --bdaddr 00:07:e0:00:0b:ca OPUSH</userinput></screen>
>+      
>+      <para>Offering services on &os; to other devices is done using the
>+        <application>sdpd</application> server.</para>
>+      <screen>&prompt.root; <userinput>sdpd</userinput></screen>
>+      
>+      <para>Registering a given Bluetooth service to a RFCOMM channel number:</para>
>+      <screen>&prompt.root; <userinput>sdptool add --channel=7 LAN</userinput></screen>
>+      
>+      <para>Checking services offered by our computer:</para>
>+      <screen>&prompt.root; <userinput>sdptool browse ff:ff:ff:00:00:00</userinput></screen>
>+    </sect2>
>+
>+    <sect2>
>+      <title>Dial-up Networking (DUN) and Local Area Network (LAN)</title>
>+
>+      <para>Bluetooth can be used for connecting to the Internet, either over
>+        PPP (mobile phones) or the local network (access points).  The Dial-up Networking
>+        profile on &os; is implemented with &man.ppp.8; and
>+        &man.rfcomm.pppd.8;, a wrapper that converts RFCOMM Bluetooth connections
>+        to something PPP can operate with.  Create PPP labels in
>+        <filename>/etc/ppp/ppp.conf</filename>, examples from the &man.rfcomm.pppd.8;
>+        manual page can be used.</para>
>+        
>+      <para>Connecting to the Internet through a mobile phone (DUN profile).  First, find
>+        out the correct RFCOMM channel on the remote device using
>+        <application>sdptool</application>.  Then, use &man.rfcomm.pppd.8;:</para>
>+
>+      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C 1 -l rfcomm-dialup</userinput></screen>
>+      
>+      <para>Running a Bluetooth access point on &os;.  First, register a
>+        RFCOMM channel for LAN service on the local <application>sdpd</application>.
>+        Then, start the PPP server.  Use <literal>BD_ADDR</literal> of the local Bluetooth device and
>+        the channel number registered with <application>sdpd</application>.</para>
>+      
>+      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:02:72:00:d4:1a -s -C 7 -l rfcomm-server</userinput></screen>
>+        
>+    </sect2>
>+
>+    <indexterm><primary>OBEX</primary></indexterm>
>+    <sect2>
>+      <title>OBEX Push (OPUSH)</title>
>+      <para>OBEX is a widely used protocol for simple file transfers between
>+        mobile devices.  It's main use is in infrared communication, where it is
>+        used for generic file transfers between notebooks or Palm handhelds,
>+        and for sending business cards or calendar entries between mobile
>+        phones and other devices with PIM applications.</para>
>+      
>+      <para>The OBEX client is implemented in the
>+        <application>obexapp</application> utility from <ulink                  
>+        url="http://www.geocities.com/m_evmenkin/">Maksim Yevmenkin's
>+        snapshot</ulink>.  It needs the <application>openobex</application>
>+        library from same package and the
>+        <filename role="package">devel/glib12</filename> port.  Note that
>+        <application>obexapp</application> does not require root privileges
>+        to operate.</para>
>+      
>+      <para>OBEX client.  First, find which channel on the remote device is IrMC
>+        Synchronization or OBEX Object Push.  After that, use
>+        <application>obexapp</application>.  Here is an example session where
>+        we download a file (device info from a mobile phone) and send
>+        a file (business card to the phone's directory):</para>
>+        
>+      <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C 10</userinput>
>+obex&gt; get
>+get: remote file&gt; telecom/devinfo.txt
>+get: local file&gt; devinfo-t39.txt
>+Success, response: OK, Success (0x20)
>+obex&gt; put
>+put: local file&gt; new.vcf
>+put: remote file&gt; new.vcf
>+Success, response: OK, Success (0x20)
>+obex&gt; di
>+Success, response: OK, Success (0x20)</screen>
>+
>+      <para>OBEX server.  First, register the OPUSH service with the local
>+        <application>sdpd</application>.  If OPUSH does not work,
>+        you can try the FTRN service instead.  Then, start the OBEX daemon
>+        using the channel number registered with sdpd:</para>
>+      
>+      <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
>+      
>+      <para>Received files will appear in <filename>/var/spool/obex</filename>.
>+        This can be overriden with the <option>-r</option> switch.  Make sure
>+        the directory exists, <application>obexapp</application> will not
>+        create it.  On a typical workstation with a single user it is useful
>+        to set a default owner of received files.  See obexapp(1)
>+        for details.</para>
>+      
>+    </sect2>
>+
>+    <sect2>
>+      <title>Serial Port Profile (SP)</title>
>+      <para>Bluetooth can be used to emulate serial port connections.
>+        To connect to a remote device, first locate the RFCOMM channel with the
>+        Serial Port profile.  Then, start the Serial Port Profile Daemon
>+        &man.rfcomm.sppd.1; with a free pseudo tty:</para>
>+
>+      <screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -c 1 -t /dev/ttyp6</userinput>
>+rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
>+
>+      <para>Now connect this pseudo tty to your actual terminal:</para>
>+      
>+      <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>
>+
>+    </sect2>
>+    
>+    <sect2>
>+      <title>Troubleshooting</title>
>+      
>+      <sect3>
>+        <title>A remote device cannot connect to us</title>
>+        <para>Some older devices do not support role switching.  By default,
>+          when &os; is accepting a connection, it tries to switch roles
>+          to become a master.  Devices which do not support this will not
>+          be able to connect.  Role switching is performed when a connection
>+          is being established, so we cannot ask the remote device if it does
>+          support role switching.  There is a driver option to disable role
>+          switching on our side:</para>
>+        <screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
>+      </sect3>
>+      
>+      <sect3>
>+        <title>Something is going wrong, can I see what exactly is happening?</title>
>+        <para>Yes, you can.  Use the <application>hcidump</application> tool
>+        from <ulink url="http://www.geocities.com/m_evmenkin/">Maksim Yevmenkin's
>+        snapshot</ulink>, which works much like &man.tcpdump.1;.  You can
>+        use it to display the content of Bluetooth packets on the terminal
>+        and to record Bluetooth communication for later analyzation.</para>
>+      </sect3>
>+      
>+    </sect2>
>+
>+  </sect1>
>+
> </chapter>
> 
> <!--

Actions: View | Diff

Attachments on bug 52514: 31546 | 31547