docs/52514: Handbook: new chapter about Bluetooth

Pav Lucistnik pav at oook.cz
Wed May 21 06:30:03 UTC 2003


>Number:         52514
>Category:       docs
>Synopsis:       Handbook: new chapter about Bluetooth
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue May 20 23:30:00 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator:     Pav Lucistnik
>Release:        FreeBSD 5.1-BETA i386
>Organization:
>Environment:
System: FreeBSD pav.oook.cz 5.1-BETA FreeBSD 5.1-BETA #1: Tue May 20 21:30:57 CEST 2003 root at pav.oook.cz:/usr/obj/usr/src/sys/PAV i386


	
>Description:
This is new chapter for Handbook, covering usage of The Bluetooth stack
on coming 5.1-RELEASE. It's based on my Bluetooth on FreeBSD webpage.
It was reviewed and approved by Maksim Yevmenkin, author of Bluetooth
code. Then it was review by Christian Brueffer (brueffer@).

We'd like to get a review by at least one docproj elder before brueffer
commits it. 

Another question is where this should go. brueffer@ suggests after
Wireless Networking chapter, I suggest putting it after IPv6 as
a last chapter of Advanced networking.

Apply to /usr/doc/en_US.ISO8859-1/books/handbook/advanced-networking
>How-To-Repeat:
	
>Fix:

--- chapter.sgml.orig	Tue May 20 21:11:44 2003
+++ chapter.sgml	Tue May 20 23:15:03 2003
@@ -6687,6 +6687,388 @@
 	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 at oook.cz</email></address>
+          </affiliation>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Bluetooth</title>
+    
+    <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 FreeBSD is implemented using Netgraph.
+        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 only on 
+	FreeBSD 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 
+<3-Slot> <5-Slot> <Encryption> <Slot offset>
+<Timing accuracy> <Switch> <Hold mode> <Sniff mode>
+<Park mode> <RSSI> <Channel quality> <SCO link>
+<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
+<Paging scheme> <Power control> <Transparent SCO data> 
+Max. ACL packet size: 192 bytes
+Number of ACL packets: 8
+Max. SCO packet size: 64 bytes
+Number of SCO packets: 8</screen>
+      
+    </sect2>
+    
+    <sect2>
+      <title>HCI and Inquiry</title>
+
+      <para>Now it is time to discover some nearby bluetooth devices.
+        Discovering devices and many other interesting tasks is 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>BD_ADDR 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>
+    
+    <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>
+    
+    <sect2>
+      <title>Pairing of Devices</title>
+
+      <para>By default, Bluetooth communication is not authorized 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>
+    
+    <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 Evmenkin'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 FreeBSD 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 FreeBSD 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 FreeBSD.  First, register a
+        RFCOMM channel for LAN service on the local <application>sdpd</application>.
+        Then, start the ppp server.  Use BD_ADDR 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>
+
+    <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 Evmenkin'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> get
+get: remote file> telecom/devinfo.txt
+get: local file> devinfo-t39.txt
+Success, response: OK, Success (0x20)
+obex> put
+put: local file> new.vcf
+put: remote file> new.vcf
+Success, response: OK, Success (0x20)
+obex> 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 FreeBSD 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 Evmenkin'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>
 
 <!--
>Release-Note:
>Audit-Trail:
>Unformatted:



More information about the freebsd-doc mailing list