Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 6 Mar 2014 17:08:22 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r44152 - head/en_US.ISO8859-1/books/handbook/advanced-networking
Message-ID:  <201403061708.s26H8MKk001612@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Thu Mar  6 17:08:22 2014
New Revision: 44152
URL: http://svnweb.freebsd.org/changeset/doc/44152

Log:
  Initial shuffle through Bluetooth chapter to improve flow.
  Some sections renamed.
  Flow is now using USB first followed by the various protocols
  and utilities.
  More commits to come.
  
  Sponsored by: iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml	Thu Mar  6 15:29:05 2014	(r44151)
+++ head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml	Thu Mar  6 17:08:22 2014	(r44152)
@@ -2216,9 +2216,6 @@ freebsdap       00:11:95:c3:0d:ac    1  
       <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
@@ -2236,12 +2233,15 @@ freebsdap       00:11:95:c3:0d:ac    1  
 	Bluetooth PC Card 3CRWB60-A is supported by the
 	&man.ng.bt3c.4; driver.  Serial and UART based Bluetooth
 	devices are supported by &man.sio.4;, &man.ng.h4.4; and
-	&man.hcseriald.8;.  This section describes the use of a
-	<acronym>USB</acronym> Bluetooth dongle.</para>
-    </sect2>
+	&man.hcseriald.8;.</para>
+
+      <para>This section describes the use of a
+	<acronym>USB</acronym> Bluetooth dongle on a &os; system.  It
+	then describes the various Bluetooth protocols and
+	utilities.</para>
 
     <sect2>
-      <title>Plugging in the Device</title>
+      <title>Loading Bluetooth Support</title>
 
       <para>By default, Bluetooth device drivers are available as
 	kernel modules.  Before attaching a device, load the driver
@@ -2284,8 +2284,7 @@ Number of SCO packets: 8</screen>
     </sect2>
 
     <sect2>
-      <title>Host Controller Interface
-	(<acronym>HCI</acronym>)</title>
+      <title>Finding Other Bluetooth Devices</title>
 
       <indexterm>
 	<primary>HCI</primary>
@@ -2380,6 +2379,157 @@ Reason: Connection terminated by local h
     </sect2>
 
     <sect2>
+      <title>Device Pairing</title>
+
+      <para>By default, Bluetooth communication is not authenticated,
+	and any device can talk to any other device.  A Bluetooth
+	device, such as a cellular phone, may choose to require
+	authentication to provide a particular service.  Bluetooth
+	authentication is normally done with a
+	<emphasis><acronym>PIN</acronym> code</emphasis>, an ASCII
+	string up to 16 characters in length.  The user is required
+	to enter the same <acronym>PIN</acronym> code on both devices.
+	Once the user has entered the <acronym>PIN</acronym> code,
+	both devices will generate a <emphasis>link key</emphasis>.
+	After that, the link key can be stored either in the devices
+	or in a persistent storage.  Next time, both devices will
+	use the previously generated link key.  This procedure is
+	called <emphasis>pairing</emphasis>.  Note that if the link
+	key is lost by either device, the pairing must be
+	repeated.</para>
+
+      <para>The &man.hcsecd.8; daemon is responsible for handling
+	Bluetooth authentication requests.  The default configuration
+	file is <filename>/etc/bluetooth/hcsecd.conf</filename>.  An
+	example section for a cellular phone with the
+	<acronym>PIN</acronym> code arbitrarily set to
+	<quote>1234</quote> is shown below:</para>
+
+      <programlisting>device {
+        bdaddr  00:80:37:29:19:a4;
+        name    "Pav's T39";
+        key     nokey;
+        pin     "1234";
+      }</programlisting>
+
+      <para>The only limitation on <acronym>PIN</acronym> codes is
+	length.  Some devices, such as Bluetooth headsets, may have
+	a fixed <acronym>PIN</acronym> code built in.  The
+	<option>-d</option> switch forces &man.hcsecd.8; to stay in
+	the foreground, so it is easy to see what is happening.  Set
+	the remote device to receive pairing and initiate the
+	Bluetooth connection to the remote device.  The remote device
+	should indicate that pairing was accepted and request the
+	<acronym>PIN</acronym> code.  Enter the same
+	<acronym>PIN</acronym> code listed in
+	<filename>hcsecd.conf</filename>.  Now the computer and the
+	remote device are paired.  Alternatively, pairing can be
+	initiated on the remote device.</para>
+
+      <para>The following line can be added to
+	<filename>/etc/rc.conf</filename> to configure &man.hcsecd.8;
+	to start automatically on system start:</para>
+
+      <programlisting>hcsecd_enable="YES"</programlisting>
+
+      <para>The following is a sample of the &man.hcsecd.8; daemon
+	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>Network Access with
+	<acronym>PPP</acronym> Profiles</title>
+
+      <para>The Dial-Up Networking (<acronym>DUN</acronym>) profile is
+	mostly used with modems and cellular phones.  The scenarios
+	covered by this profile are the following:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Use of a cellular phone or modem by a computer as a
+	    wireless modem for connecting to a dial-up Internet access
+	    server, or for using other dial-up services.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Use of a cellular phone or modem by a computer to
+	    receive data calls.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Network access with a <acronym>PPP</acronym> profile can
+	be used in the following situations:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><acronym>LAN</acronym> access for a single Bluetooth
+	    device.</para>
+	</listitem>
+
+	<listitem>
+	  <para><acronym>LAN</acronym> access for multiple Bluetooth
+	    devices.</para>
+	</listitem>
+
+	<listitem>
+	  <para>PC to PC connection using <acronym>PPP</acronym>
+	    networking over serial cable emulation.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>In &os;, these profiles are implemented with &man.ppp.8;
+	and the &man.rfcomm.pppd.8; wrapper which converts a
+	<acronym>RFCOMM</acronym> Bluetooth connection into something
+	<acronym>PPP</acronym> can use.  Before a profile can be used,
+	a new <acronym>PPP</acronym> label must be created in
+	<filename>/etc/ppp/ppp.conf</filename>.  Consult
+	&man.rfcomm.pppd.8; for examples.</para>
+
+      <para>In the following example, &man.rfcomm.pppd.8; is used
+	to open a <acronym>RFCOMM</acronym> connection to a remote
+	device with a BD_ADDR of <literal>00:80:37:29:19:a4</literal>
+	on a <acronym>DUN</acronym> <acronym>RFCOMM</acronym> channel.
+	The actual <acronym>RFCOMM</acronym> channel number will be
+	obtained from the remote device via <acronym>SDP</acronym>.
+	It is possible to specify the <acronym>RFCOMM</acronym>
+	channel by hand, and in this case &man.rfcomm.pppd.8; will
+	not perform the <acronym>SDP</acronym> query.  Use
+	&man.sdpcontrol.8; to find out the <acronym>RFCOMM</acronym>
+	channel on the remote device.</para>
+
+      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>
+
+      <para>In order to provide network access with the
+	<acronym>PPP</acronym> <acronym>LAN</acronym> service,
+	&man.sdpd.8; must be running and a new entry for
+	<acronym>LAN</acronym> clients must be created in
+	<filename>/etc/ppp/ppp.conf</filename>.  Consult
+	&man.rfcomm.pppd.8; for examples.  Finally, start the
+	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server on a
+	valid <acronym>RFCOMM</acronym> channel number.  The
+	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server will
+	automatically register the Bluetooth <acronym>LAN</acronym>
+	service with the local <acronym>SDP</acronym> daemon.  The
+	example below shows how to start the <acronym>RFCOMM</acronym>
+	<acronym>PPP</acronym> server.</para>
+
+      <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Bluetooth Protocols</title>
+      
+      <para>This section describes the various Bluetooth utilities,
+	their function, and available utilities.</para>
+   
+    <sect3>
       <title>Logical Link Control and Adaptation Protocol
 	(<acronym>L2CAP</acronym>)</title>
 
@@ -2455,10 +2605,10 @@ c2afe900 c2b53380 1    127   0     Yes  
 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>
+    </sect3>
 
-    <sect2>
-      <title><acronym>RFCOMM</acronym> Protocol</title>
+    <sect3>
+      <title>Radio Frequency Communication (<acronym>RFCOMM</acronym>)</title>
 
       <para>The <acronym>RFCOMM</acronym> protocol provides emulation
 	of serial ports over the <acronym>L2CAP</acronym> protocol.
@@ -2488,74 +2638,9 @@ c2e8bc80      0    250 00:02:72:00:d4:1a
 
       <para>In &os;, <acronym>RFCOMM</acronym> is implemented at the
 	Bluetooth sockets layer.</para>
-    </sect2>
-
-    <sect2>
-      <title>Pairing of Devices</title>
+    </sect3>
 
-      <para>By default, Bluetooth communication is not authenticated,
-	and any device can talk to any other device.  A Bluetooth
-	device, such as a cellular phone, may choose to require
-	authentication to provide a particular service.  Bluetooth
-	authentication is normally done with a
-	<emphasis><acronym>PIN</acronym> code</emphasis>, an ASCII
-	string up to 16 characters in length.  The user is required
-	to enter the same <acronym>PIN</acronym> code on both devices.
-	Once the user has entered the <acronym>PIN</acronym> code,
-	both devices will generate a <emphasis>link key</emphasis>.
-	After that, the link key can be stored either in the devices
-	or in a persistent storage.  Next time, both devices will
-	use the previously generated link key.  This procedure is
-	called <emphasis>pairing</emphasis>.  Note that if the link
-	key is lost by either device, the pairing must be
-	repeated.</para>
-
-      <para>The &man.hcsecd.8; daemon is responsible for handling
-	Bluetooth authentication requests.  The default configuration
-	file is <filename>/etc/bluetooth/hcsecd.conf</filename>.  An
-	example section for a cellular phone with the
-	<acronym>PIN</acronym> code arbitrarily set to
-	<quote>1234</quote> is shown below:</para>
-
-      <programlisting>device {
-        bdaddr  00:80:37:29:19:a4;
-        name    "Pav's T39";
-        key     nokey;
-        pin     "1234";
-      }</programlisting>
-
-      <para>The only limitation on <acronym>PIN</acronym> codes is
-	length.  Some devices, such as Bluetooth headsets, may have
-	a fixed <acronym>PIN</acronym> code built in.  The
-	<option>-d</option> switch forces &man.hcsecd.8; to stay in
-	the foreground, so it is easy to see what is happening.  Set
-	the remote device to receive pairing and initiate the
-	Bluetooth connection to the remote device.  The remote device
-	should indicate that pairing was accepted and request the
-	<acronym>PIN</acronym> code.  Enter the same
-	<acronym>PIN</acronym> code listed in
-	<filename>hcsecd.conf</filename>.  Now the computer and the
-	remote device are paired.  Alternatively, pairing can be
-	initiated on the remote device.</para>
-
-      <para>The following line can be added to
-	<filename>/etc/rc.conf</filename> to configure &man.hcsecd.8;
-	to start automatically on system start:</para>
-
-      <programlisting>hcsecd_enable="YES"</programlisting>
-
-      <para>The following is a sample of the &man.hcsecd.8; daemon
-	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>
+    <sect3>
       <title>Service Discovery Protocol
 	(<acronym>SDP</acronym>)</title>
 
@@ -2659,89 +2744,9 @@ Bluetooth Profile Descriptor List:
 	channel:</para>
 
       <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>
-    </sect2>
+    </sect3>
 
-    <sect2>
-      <title>Dial-Up Networking and Network Access with
-	<acronym>PPP</acronym> Profiles</title>
-
-      <para>The Dial-Up Networking (<acronym>DUN</acronym>) profile is
-	mostly used with modems and cellular phones.  The scenarios
-	covered by this profile are the following:</para>
-
-      <itemizedlist>
-	<listitem>
-	  <para>Use of a cellular phone or modem by a computer as a
-	    wireless modem for connecting to a dial-up Internet access
-	    server, or for using other dial-up services.</para>
-	</listitem>
-
-	<listitem>
-	  <para>Use of a cellular phone or modem by a computer to
-	    receive data calls.</para>
-	</listitem>
-      </itemizedlist>
-
-      <para>Network access with a <acronym>PPP</acronym> profile can
-	be used in the following situations:</para>
-
-      <itemizedlist>
-	<listitem>
-	  <para><acronym>LAN</acronym> access for a single Bluetooth
-	    device.</para>
-	</listitem>
-
-	<listitem>
-	  <para><acronym>LAN</acronym> access for multiple Bluetooth
-	    devices.</para>
-	</listitem>
-
-	<listitem>
-	  <para>PC to PC connection using <acronym>PPP</acronym>
-	    networking over serial cable emulation.</para>
-	</listitem>
-      </itemizedlist>
-
-      <para>In &os;, these profiles are implemented with &man.ppp.8;
-	and the &man.rfcomm.pppd.8; wrapper which converts a
-	<acronym>RFCOMM</acronym> Bluetooth connection into something
-	<acronym>PPP</acronym> can use.  Before a profile can be used,
-	a new <acronym>PPP</acronym> label must be created in
-	<filename>/etc/ppp/ppp.conf</filename>.  Consult
-	&man.rfcomm.pppd.8; for examples.</para>
-
-      <para>In the following example, &man.rfcomm.pppd.8; is used
-	to open a <acronym>RFCOMM</acronym> connection to a remote
-	device with a BD_ADDR of <literal>00:80:37:29:19:a4</literal>
-	on a <acronym>DUN</acronym> <acronym>RFCOMM</acronym> channel.
-	The actual <acronym>RFCOMM</acronym> channel number will be
-	obtained from the remote device via <acronym>SDP</acronym>.
-	It is possible to specify the <acronym>RFCOMM</acronym>
-	channel by hand, and in this case &man.rfcomm.pppd.8; will
-	not perform the <acronym>SDP</acronym> query.  Use
-	&man.sdpcontrol.8; to find out the <acronym>RFCOMM</acronym>
-	channel on the remote device.</para>
-
-      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>
-
-      <para>In order to provide network access with the
-	<acronym>PPP</acronym> <acronym>LAN</acronym> service,
-	&man.sdpd.8; must be running and a new entry for
-	<acronym>LAN</acronym> clients must be created in
-	<filename>/etc/ppp/ppp.conf</filename>.  Consult
-	&man.rfcomm.pppd.8; for examples.  Finally, start the
-	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server on a
-	valid <acronym>RFCOMM</acronym> channel number.  The
-	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server will
-	automatically register the Bluetooth <acronym>LAN</acronym>
-	service with the local <acronym>SDP</acronym> daemon.  The
-	example below shows how to start the <acronym>RFCOMM</acronym>
-	<acronym>PPP</acronym> server.</para>
-
-      <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
-    </sect2>
-
-    <sect2>
+    <sect3>
       <title><acronym>OBEX</acronym> Object Push
 	(<acronym>OPUSH</acronym>) Profile</title>
 
@@ -2800,10 +2805,10 @@ Success, response: OK, Success (0x20)</s
 	to start the <acronym>OBEX</acronym> server.</para>
 
       <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
-    </sect2>
+    </sect3>
 
-    <sect2>
-      <title>Serial Port Profile</title>
+    <sect3>
+      <title>Serial Port Profile (<acronym>SPP</acronym>)</title>
 
       <para>The Serial Port Profile (<acronym>SPP</acronym>) allows
 	Bluetooth devices to perform serial cable emulation.  This
@@ -2828,14 +2833,12 @@ rfcomm_sppd[94692]: Starting on /dev/tty
 	port:</para>
 
       <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>
-    </sect2>
+    </sect3>
+  </sect2>
 
     <sect2>
       <title>Troubleshooting</title>
 
-      <sect3>
-	<title>A Remote Device Cannot Connect</title>
-
 	<para>Some older Bluetooth devices do not support role
 	  switching.  By default, when &os; is accepting a new
 	  connection, it tries to perform a role switch and become
@@ -2847,19 +2850,14 @@ rfcomm_sppd[94692]: Starting on /dev/tty
 	  switching on the local side:</para>
 
 	<screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
-      </sect3>
-
-      <sect3>
-	<title>Displaying Bluetooth Packets</title>
 
-	<para>Use the third-party package
+	<para>To display Bluetooth packets, use the third-party package
 	  <application>hcidump</application>, which is available as a
 	  <package>comms/hcidump</package> package or
 	  port.  This utility is similar to &man.tcpdump.1; and can
 	  be used to display the contents of Bluetooth packets on
 	  the terminal and to dump the Bluetooth packets to a
 	  file.</para>
-      </sect3>
     </sect2>
   </sect1>
 



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403061708.s26H8MKk001612>