From owner-svn-doc-head@FreeBSD.ORG Thu Mar 6 17:08:22 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id F099F26B; Thu, 6 Mar 2014 17:08:22 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id DA7DCE22; Thu, 6 Mar 2014 17:08:22 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s26H8MWe001613; Thu, 6 Mar 2014 17:08:22 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s26H8MKk001612; Thu, 6 Mar 2014 17:08:22 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403061708.s26H8MKk001612@svn.freebsd.org> From: Dru Lavigne Date: Thu, 6 Mar 2014 17:08:22 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Mar 2014 17:08:23 -0000 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 Bluetooth - - Introduction - 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 - USB Bluetooth dongle. - + &man.hcseriald.8;. + + This section describes the use of a + USB Bluetooth dongle on a &os; system. It + then describes the various Bluetooth protocols and + utilities. - Plugging in the Device + Loading Bluetooth Support 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 - Host Controller Interface - (<acronym>HCI</acronym>) + Finding Other Bluetooth Devices HCI @@ -2380,6 +2379,157 @@ Reason: Connection terminated by local h + Device Pairing + + 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 + PIN code, an ASCII + string up to 16 characters in length. The user is required + to enter the same PIN code on both devices. + Once the user has entered the PIN code, + both devices will generate a link key. + 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 pairing. Note that if the link + key is lost by either device, the pairing must be + repeated. + + The &man.hcsecd.8; daemon is responsible for handling + Bluetooth authentication requests. The default configuration + file is /etc/bluetooth/hcsecd.conf. An + example section for a cellular phone with the + PIN code arbitrarily set to + 1234 is shown below: + + device { + bdaddr 00:80:37:29:19:a4; + name "Pav's T39"; + key nokey; + pin "1234"; + } + + The only limitation on PIN codes is + length. Some devices, such as Bluetooth headsets, may have + a fixed PIN code built in. The + 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 + PIN code. Enter the same + PIN code listed in + hcsecd.conf. Now the computer and the + remote device are paired. Alternatively, pairing can be + initiated on the remote device. + + The following line can be added to + /etc/rc.conf to configure &man.hcsecd.8; + to start automatically on system start: + + hcsecd_enable="YES" + + The following is a sample of the &man.hcsecd.8; daemon + output: + + 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 + + + + Network Access with + <acronym>PPP</acronym> Profiles + + The Dial-Up Networking (DUN) profile is + mostly used with modems and cellular phones. The scenarios + covered by this profile are the following: + + + + 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. + + + + Use of a cellular phone or modem by a computer to + receive data calls. + + + + Network access with a PPP profile can + be used in the following situations: + + + + LAN access for a single Bluetooth + device. + + + + LAN access for multiple Bluetooth + devices. + + + + PC to PC connection using PPP + networking over serial cable emulation. + + + + In &os;, these profiles are implemented with &man.ppp.8; + and the &man.rfcomm.pppd.8; wrapper which converts a + RFCOMM Bluetooth connection into something + PPP can use. Before a profile can be used, + a new PPP label must be created in + /etc/ppp/ppp.conf. Consult + &man.rfcomm.pppd.8; for examples. + + In the following example, &man.rfcomm.pppd.8; is used + to open a RFCOMM connection to a remote + device with a BD_ADDR of 00:80:37:29:19:a4 + on a DUN RFCOMM channel. + The actual RFCOMM channel number will be + obtained from the remote device via SDP. + It is possible to specify the RFCOMM + channel by hand, and in this case &man.rfcomm.pppd.8; will + not perform the SDP query. Use + &man.sdpcontrol.8; to find out the RFCOMM + channel on the remote device. + + &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup + + In order to provide network access with the + PPP LAN service, + &man.sdpd.8; must be running and a new entry for + LAN clients must be created in + /etc/ppp/ppp.conf. Consult + &man.rfcomm.pppd.8; for examples. Finally, start the + RFCOMM PPP server on a + valid RFCOMM channel number. The + RFCOMM PPP server will + automatically register the Bluetooth LAN + service with the local SDP daemon. The + example below shows how to start the RFCOMM + PPP server. + + &prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-server + + + + Bluetooth Protocols + + This section describes the various Bluetooth utilities, + their function, and available utilities. + + Logical Link Control and Adaptation Protocol (<acronym>L2CAP</acronym>) @@ -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 - + - - <acronym>RFCOMM</acronym> Protocol + + Radio Frequency Communication (<acronym>RFCOMM</acronym>) The RFCOMM protocol provides emulation of serial ports over the L2CAP protocol. @@ -2488,74 +2638,9 @@ c2e8bc80 0 250 00:02:72:00:d4:1a In &os;, RFCOMM is implemented at the Bluetooth sockets layer. - - - - Pairing of Devices + - 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 - PIN code, an ASCII - string up to 16 characters in length. The user is required - to enter the same PIN code on both devices. - Once the user has entered the PIN code, - both devices will generate a link key. - 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 pairing. Note that if the link - key is lost by either device, the pairing must be - repeated. - - The &man.hcsecd.8; daemon is responsible for handling - Bluetooth authentication requests. The default configuration - file is /etc/bluetooth/hcsecd.conf. An - example section for a cellular phone with the - PIN code arbitrarily set to - 1234 is shown below: - - device { - bdaddr 00:80:37:29:19:a4; - name "Pav's T39"; - key nokey; - pin "1234"; - } - - The only limitation on PIN codes is - length. Some devices, such as Bluetooth headsets, may have - a fixed PIN code built in. The - 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 - PIN code. Enter the same - PIN code listed in - hcsecd.conf. Now the computer and the - remote device are paired. Alternatively, pairing can be - initiated on the remote device. - - The following line can be added to - /etc/rc.conf to configure &man.hcsecd.8; - to start automatically on system start: - - hcsecd_enable="YES" - - The following is a sample of the &man.hcsecd.8; daemon - output: - - 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 - - - + Service Discovery Protocol (<acronym>SDP</acronym>) @@ -2659,89 +2744,9 @@ Bluetooth Profile Descriptor List: channel: &prompt.root; sdpcontrol -l browse - + - - Dial-Up Networking and Network Access with - <acronym>PPP</acronym> Profiles - - The Dial-Up Networking (DUN) profile is - mostly used with modems and cellular phones. The scenarios - covered by this profile are the following: - - - - 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. - - - - Use of a cellular phone or modem by a computer to - receive data calls. - - - - Network access with a PPP profile can - be used in the following situations: - - - - LAN access for a single Bluetooth - device. - - - - LAN access for multiple Bluetooth - devices. - - - - PC to PC connection using PPP - networking over serial cable emulation. - - - - In &os;, these profiles are implemented with &man.ppp.8; - and the &man.rfcomm.pppd.8; wrapper which converts a - RFCOMM Bluetooth connection into something - PPP can use. Before a profile can be used, - a new PPP label must be created in - /etc/ppp/ppp.conf. Consult - &man.rfcomm.pppd.8; for examples. - - In the following example, &man.rfcomm.pppd.8; is used - to open a RFCOMM connection to a remote - device with a BD_ADDR of 00:80:37:29:19:a4 - on a DUN RFCOMM channel. - The actual RFCOMM channel number will be - obtained from the remote device via SDP. - It is possible to specify the RFCOMM - channel by hand, and in this case &man.rfcomm.pppd.8; will - not perform the SDP query. Use - &man.sdpcontrol.8; to find out the RFCOMM - channel on the remote device. - - &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup - - In order to provide network access with the - PPP LAN service, - &man.sdpd.8; must be running and a new entry for - LAN clients must be created in - /etc/ppp/ppp.conf. Consult - &man.rfcomm.pppd.8; for examples. Finally, start the - RFCOMM PPP server on a - valid RFCOMM channel number. The - RFCOMM PPP server will - automatically register the Bluetooth LAN - service with the local SDP daemon. The - example below shows how to start the RFCOMM - PPP server. - - &prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-server - - - + <acronym>OBEX</acronym> Object Push (<acronym>OPUSH</acronym>) Profile @@ -2800,10 +2805,10 @@ Success, response: OK, Success (0x20)OBEX server. &prompt.root; obexapp -s -C 10 - + - - Serial Port Profile + + Serial Port Profile (<acronym>SPP</acronym>) The Serial Port Profile (SPP) allows Bluetooth devices to perform serial cable emulation. This @@ -2828,14 +2833,12 @@ rfcomm_sppd[94692]: Starting on /dev/tty port: &prompt.root; cu -l ttyp6 - + + Troubleshooting - - A Remote Device Cannot Connect - 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: &prompt.root; hccontrol -n ubt0hci write_node_role_switch 0 - - - - Displaying Bluetooth Packets - Use the third-party package + To display Bluetooth packets, use the third-party package hcidump, which is available as a comms/hcidump 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. -