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>