docs/52514, Bluetooth Handbook Chapter

Sun Jun 1 06:20:15 UTC 2003

The following reply was made to PR docs/52514; it has been noted by GNATS.

From: Hiten Pandya <hmp at FreeBSD.ORG>
To: bug-followup at FreeBSD.ORG
Cc: pav at oook.cz
Subject: Re: docs/52514, Bluetooth Handbook Chapter
Date: Sat, 31 May 2003 23:17:41 -0700

 Hello Pav.

 Thanks for this nice documentation what it is needed most.  Here are
 some comments on your Bluetooth documentation:

 First of all, this chapter should be in the ``Desktop'' section, just as
 Murray pointed out.

 --- chapter.sgml.orig	Tue May 20 21:11:44 2003
 +++ chapter.sgml	Tue May 20 23:15:03 2003
 @@ -6687,6 +6687,388 @@
 +  <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>

 	Some <indexterms> would help:

 		Bluetooth, Wi-Fi, Ad-hoc etc.

 	You should provide <indexterms> for the various acronyms and
 	abbreviations used throughout this chapter.  It will make it
 	easier to find information in the printed version of the
 	Handbook.

 +    
 +    <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,

 		This could probably be:
 		"Unlike its counterpart, <acronym>Wi-Fi</acronym>," ...

 +      <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 Bluetooth stack in FreeBSD is implemented using the Netgraph
 	facility (see &man.netgraph.4;).  A broad variety of USB dongles ...

 +        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>

 	Bluetooth support is available in FreeBSD 5.0 and newer
 	systems ...

 	(Also, you must note somewhere that the core Netgraph module is
 	required if its loaded via a KLD.  You should also explan the
 	various Bluetooth kernel configuration options, and how to
 	utilise them)

 +    <sect2>
 +      <title>HCI and Inquiry</title>
 +
 +      <para>Now it is time to discover some nearby bluetooth devices.

 	s/bluetooth/Bluetooth/

 +        Discovering devices and many other interesting tasks is done with

 	"Interesting taks like discovering devices, and such are done with..."

 +      <para>BD_ADDR is the unique address of a bluetooth device, similar to MAC

 	<literal>BD_ADDR</literal>

 +      <para>If you perform a discovery on a different bluetooth device, it will find

 	s/bluetooth/Bluetooth/, this should be done whereever you have
 	used "bluetooth.

 +      <title>Pairing of Devices</title>
 +
 +      <para>By default, Bluetooth communication is not authorized and any device

 	Isn't ``authenticatied'' a better word instead of ``authorized''?
 	Because at start of the chapter, you said its unlicensed, and
 	available for personal networks; which makes ``authorized''
 	sound a little obfuscated, IMHO.

 +
 +      <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>

 		Use &man.hcsecd.8; ?

 +    <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

 	Erm, hmm.  According to his emails to me.  His surname is ``Yevmenkin.''

 +    <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

 	Use &os;, instead of FreeBSD.  This should be done everywhere.

 +        to something ppp can operate with.  Create ppp labels in

 	s/ppp/PPP/, wherever ``ppp'' is used.

 +        url="http://www.geocities.com/m_evmenkin/">Maksim Evmenkin's

 	See my comment above.

 +    <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

 	&man.hcidump.<sect> (I don't recall its section number)

 +        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>

 	Lastly, you should use formal structure instead of ``Question and
 	Answer'' type structure for this (Troubleshooting) section.  We
 	are trying to cut down on QA sections in the Handbook, last time
 	I checked.

 	Thanks Pav.  Hope my comments help.

 		-- Hiten (hmp at FreeBSD.ORG)