os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Initial shuffle through Bluetooth chapter to improve flow.

Browse source 
Some sections renamed.
Flow is now using USB first followed by the various protocols
and utilities.
More commits to come.

Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-03-06 17:08:22 +00:00
parent 603da73e64
commit e65a11e899
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44152
1 changed files with 172 additions and 174 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

346
en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
View file

@ -2216,9 +2216,6 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen>
<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 54M 22:1 100 EPS</screen>
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 host [0x16]</screen>
</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 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>
</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 00:07:e0:00:0b:ca 3 6 OPEN</scree
<para>In &os;, <acronym>RFCOMM</acronym> is implemented at the
Bluetooth sockets layer.</para>
</sect2>
</sect3>
<sect2>
<title>Pairing of Devices</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>
<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)</screen>
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/ttyp6...</screen>
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/ttyp6...</screen>
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>