Date: Sat, 24 May 2003 13:50:11 -0700 (PDT) From: Murray Stokely <murray@freebsd.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/52514: Handbook: new chapter about Bluetooth Message-ID: <200305242050.h4OKoB1A070033@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/52514; it has been noted by GNATS.
From: Murray Stokely <murray@freebsd.org>
To: Pav Lucistnik <pav@oook.cz>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/52514: Handbook: new chapter about Bluetooth
Date: Sat, 24 May 2003 13:45:18 -0700
I'm glad we're going to have this new content about Bluetooth, but I
don't think it belongs in a new chapter. Other interface technologies
such as USB, Firewire, SCSI, IDE, etc.. do not have their own
chapters.
I think this might belong as a section in the Desktop chapter.
- Murray
On Wed, May 21, 2003 at 08:25:11AM +0200, Pav Lucistnik wrote:
>
> >Number: 52514
> >Category: docs
> >Synopsis: Handbook: new chapter about Bluetooth
> >Confidential: no
> >Severity: non-critical
> >Priority: low
> >Responsible: freebsd-doc
> >State: open
> >Quarter:
> >Keywords:
> >Date-Required:
> >Class: doc-bug
> >Submitter-Id: current-users
> >Arrival-Date: Tue May 20 23:30:00 PDT 2003
> >Closed-Date:
> >Last-Modified:
> >Originator: Pav Lucistnik
> >Release: FreeBSD 5.1-BETA i386
> >Organization:
> >Environment:
> System: FreeBSD pav.oook.cz 5.1-BETA FreeBSD 5.1-BETA #1: Tue May 20 21:30:57 CEST 2003 root@pav.oook.cz:/usr/obj/usr/src/sys/PAV i386
>
>
>
> >Description:
> This is new chapter for Handbook, covering usage of The Bluetooth stack
> on coming 5.1-RELEASE. It's based on my Bluetooth on FreeBSD webpage.
> It was reviewed and approved by Maksim Yevmenkin, author of Bluetooth
> code. Then it was review by Christian Brueffer (brueffer@).
>
> We'd like to get a review by at least one docproj elder before brueffer
> commits it.
>
> Another question is where this should go. brueffer@ suggests after
> Wireless Networking chapter, I suggest putting it after IPv6 as
> a last chapter of Advanced networking.
>
> Apply to /usr/doc/en_US.ISO8859-1/books/handbook/advanced-networking
> >How-To-Repeat:
>
> >Fix:
>
> --- chapter.sgml.orig Tue May 20 21:11:44 2003
> +++ chapter.sgml Tue May 20 23:15:03 2003
> @@ -6687,6 +6687,388 @@
> support AAAA records.</para>
> </sect2>
> </sect1>
> +
> + <sect1 id="network-bluetooth">
> + <sect1info>
> + <authorgroup>
> + <author>
> + <firstname>Pav</firstname>
> + <surname>Lucistnik</surname>
> + <contrib>Written by </contrib>
> + <affiliation>
> + <address><email>pav@oook.cz</email></address>
> + </affiliation>
> + </author>
> + </authorgroup>
> + </sect1info>
> + <title>Bluetooth</title>
> +
> + <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,
> + e.g. FTP-like file servers, file pushing, voice transport, serial
> + line emulation and more.</para>
> +
> + <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 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>
> + </sect2>
> +
> + <sect2>
> + <title>Plugging in the Device</title>
> + <para>Device drivers are by default available as kernel modules.
> + Before attaching a device, you need to load the driver into the
> + kernel:</para>
> +
> + <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>
> +
> + <para>If the Bluetooth device is present in the system during system
> + startup, load the module from <filename>/boot/loader.conf</filename>:</para>
> +
> + <programlisting>ng_ubt_load="YES"</programlisting>
> +
> + <para>Plug in your USB dongle. Similar output will appear on the console
> + (or in syslog):</para>
> +
> + <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
> +ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
> +ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3;
> + wMaxPacketSize=49; nframes=6, buffer size=294</screen>
> +
> + <para>Copy <filename>/usr/src/share/examples/netgraph/bluetooth/rc.bluetooth</filename>
> + to some convenient place, like <filename>/etc/rc.bluetooth</filename>.
> + This script is used to start and stop the Bluetooth stack. It is a good idea
> + to stop the stack before unplugging the device, but it is not (usually)
> + fatal. When starting the stack, you will receive output similar to this:</para>
> +
> + <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput>
> +BD_ADDR: 00:02:72:00:d4:1a
> +Features: 0xff 0xff 0xf 00 00 00 00 00
> +<3-Slot> <5-Slot> <Encryption> <Slot offset>
> +<Timing accuracy> <Switch> <Hold mode> <Sniff mode>
> +<Park mode> <RSSI> <Channel quality> <SCO link>
> +<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD>
> +<Paging scheme> <Power control> <Transparent SCO data>
> +Max. ACL packet size: 192 bytes
> +Number of ACL packets: 8
> +Max. SCO packet size: 64 bytes
> +Number of SCO packets: 8</screen>
> +
> + </sect2>
> +
> + <sect2>
> + <title>HCI and Inquiry</title>
> +
> + <para>Now it is time to discover some nearby bluetooth devices.
> + Discovering devices and many other interesting tasks is done with
> + the &man.hccontrol.8; utility. You will receive a list of discoverable
> + devices in a few seconds:</para>
> +
> + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
> +Inquiry result, num_responses=1
> +Inquiry result #0
> + BD_ADDR: 00:80:37:29:19:a4
> + Page Scan Rep. Mode: 0x1
> + Page Scan Period Mode: 00
> + Page Scan Mode: 00
> + Class: 52:02:04
> + Clock offset: 0x78ef
> +Inquiry complete. Status: No error [00]</screen>
> +
> + <para>BD_ADDR is the unique address of a bluetooth device, similar to MAC
> + addresses of network cards. This address is needed for further
> + communication with a device. Let us try to read the device's name:</para>
> +
> + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 0 0 0</userinput>
> +BD_ADDR: 00:80:37:29:19:a4
> +Name: Pav's T39</screen>
> +
> + <para>If you perform a discovery on a different bluetooth device, it will find
> + your computer as <quote>your.host.name (ubt0)</quote>.</para>
> +
> + <para>You can list active baseband connections:</para>
> +
> + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
> +Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State
> +00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen>
> +
> + <para>Handle is useful for manually disconnecting a connection:</para>
> +
> + <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
> +Connection handle: 41
> +Reason: Connection terminated by local host [0x16]</screen>
> +
> + <para>Refer to <command>hccontrol help</command> for a complete listing of
> + available commands. Note that the majority of commands does not require
> + superuser privileges.</para>
> +
> + </sect2>
> +
> + <sect2>
> + <title>L2CAP</title>
> +
> + <para>L2CAP is a higher level of connection in Bluetooth standards.
> + A useful command is &man.l2ping.8;, which can be used to ping
> + other devices. Some devices might not return all of the data
> + send to them, so <emphasis>0 bytes</emphasis> as in this example
> + is a normal state.</para>
> +
> + <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
> +0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
> +0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
> +0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
> +0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>
> +
> + <para>The &man.l2control.8; utility is used to configure L2CAP nodes
> + and read their state. This example shows file transfer to a Palm
> + handheld:</para>
> +
> + <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
> +L2CAP channels:
> +Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State
> +00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN
> +&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
> +L2CAP connections:
> +Remote BD_ADDR Handle Flags Pending State
> +00:07:e0:00:0b:ca 41 O 0 OPEN</screen>
> +
> + <para>Another diagnostic tool is &man.btsockstat.1;. It does a similar
> + job as &man.netstat.1; does, but for Bluetooth sockets, logical
> + connections on top of baseband connections. The example output shows
> + the same connection as l2control above:</para>
> +
> + <screen>&prompt.user; <userinput>btsockstat</userinput>
> +Active L2CAP sockets
> +PCB Recv-Q Send-Q Local address/PSM Foreign address CID State
> +c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN
> +Active RFCOMM sessions
> +L2PCB PCB Flag MTU Out-Q DLCs State
> +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>
> +
> + <sect2>
> + <title>Pairing of Devices</title>
> +
> + <para>By default, Bluetooth communication is not authorized and any device
> + can talk to any other device. Some devices, like mobile phones, require
> + authentication for some functionality, like Internet connections. This
> + is done with PIN numbers - you enter the same (up to 16 digits long)
> + number on both devices. This operation is called <emphasis>pairing</emphasis>.
> + The daemon that answers pairing requests is &man.hcsecd.8;. Copy
> + <filename>/usr/src/usr.sbin/bluetooth/hcsecd/hcsecd.conf</filename>
> + to <filename>/usr/local/etc</filename> and edit it. The following is an
> + example section for a mobile phone, with the PIN arbitrarily set to 1234:</para>
> +
> + <programlisting>device {
> + bdaddr 00:80:37:29:19:a4;
> + name "Pav's T39";
> + key nokey;
> + pin "1234";
> +}</programlisting>
> +
> + <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>
> +
> +<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>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
> + snapshot</ulink>. Then, run <application>sdptool</application> and
> + observe (the output is snipped a bit, as this tool is quite talky):</para>
> +
> + <screen>&prompt.root; <userinput>sdptool browse 00:80:37:29:19:a4</userinput>
> +Browsing 00:80:37:29:19:A4 ...
> +Service Name: Dial-up Networking
> +Protocol Descriptor List:
> + "L2CAP" (0x0100)
> + "RFCOMM" (0x0003)
> + Channel: 1
> +
> +Service Name: Fax
> +Protocol Descriptor List:
> + "L2CAP" (0x0100)
> + "RFCOMM" (0x0003)
> + Channel: 2
> +
> +Service Name: Voice gateway
> +Service Class ID List:
> + "Headset Audio Gateway" (0x1112)
> + "Generic Audio" (0x1203)
> +Protocol Descriptor List:
> + "L2CAP" (0x0100)
> + "RFCOMM" (0x0003)
> + Channel: 3
> +</screen>
> +
> + <para>... and so on. You will need the channel number later for using
> + a given service. Some devices do not support browsing, they return
> + an empty list, but you can try searching for a specific service.</para>
> +
> + <screen>&prompt.root; <userinput>sdptool search --bdaddr 00:07:e0:00:0b:ca OPUSH</userinput></screen>
> +
> + <para>Offering services on FreeBSD to other devices is done using the
> + <application>sdpd</application> server.</para>
> + <screen>&prompt.root; <userinput>sdpd</userinput></screen>
> +
> + <para>Registering a given Bluetooth service to a RFCOMM channel number:</para>
> + <screen>&prompt.root; <userinput>sdptool add --channel=7 LAN</userinput></screen>
> +
> + <para>Checking services offered by our computer:</para>
> + <screen>&prompt.root; <userinput>sdptool browse ff:ff:ff:00:00:00</userinput></screen>
> + </sect2>
> +
> + <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
> + &man.rfcomm.pppd.8;, a wrapper that converts RFCOMM Bluetooth connections
> + to something ppp can operate with. Create ppp labels in
> + <filename>/etc/ppp/ppp.conf</filename>, examples from the &man.rfcomm.pppd.8;
> + manual page can be used.</para>
> +
> + <para>Connecting to the Internet through a mobile phone (DUN profile). First, find
> + out the correct RFCOMM channel on the remote device using
> + <application>sdptool</application>. Then, use &man.rfcomm.pppd.8;:</para>
> +
> + <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C 1 -l rfcomm-dialup</userinput></screen>
> +
> + <para>Running a Bluetooth access point on FreeBSD. First, register a
> + RFCOMM channel for LAN service on the local <application>sdpd</application>.
> + Then, start the ppp server. Use BD_ADDR of the local Bluetooth device and
> + the channel number registered with <application>sdpd</application>.</para>
> +
> + <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:02:72:00:d4:1a -s -C 7 -l rfcomm-server</userinput></screen>
> +
> + </sect2>
> +
> + <sect2>
> + <title>OBEX Push (OPUSH)</title>
> + <para>OBEX is a widely used protocol for simple file transfers between
> + mobile devices. It's main use is in infrared communication, where it is
> + used for generic file transfers between notebooks or Palm handhelds,
> + and for sending business cards or calendar entries between mobile
> + phones and other devices with PIM applications.</para>
> +
> + <para>The OBEX client is implemented in the
> + <application>obexapp</application> utility from <ulink
> + url="http://www.geocities.com/m_evmenkin/">Maksim Evmenkin's
> + snapshot</ulink>. It needs the <application>openobex</application>
> + library from same package and the
> + <filename role="package">devel/glib12</filename> port. Note that
> + <application>obexapp</application> does not require root privileges
> + to operate.</para>
> +
> + <para>OBEX client. First, find which channel on the remote device is IrMC
> + Synchronization or OBEX Object Push. After that, use
> + <application>obexapp</application>. Here is an example session where
> + we download a file (device info from a mobile phone) and send
> + a file (business card to the phone's directory):</para>
> +
> + <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C 10</userinput>
> +obex> get
> +get: remote file> telecom/devinfo.txt
> +get: local file> devinfo-t39.txt
> +Success, response: OK, Success (0x20)
> +obex> put
> +put: local file> new.vcf
> +put: remote file> new.vcf
> +Success, response: OK, Success (0x20)
> +obex> di
> +Success, response: OK, Success (0x20)</screen>
> +
> + <para>OBEX server. First, register the OPUSH service with the local
> + <application>sdpd</application>. If OPUSH does not work,
> + you can try the FTRN service instead. Then, start the OBEX daemon
> + using the channel number registered with sdpd:</para>
> +
> + <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
> +
> + <para>Received files will appear in <filename>/var/spool/obex</filename>.
> + This can be overriden with the <option>-r</option> switch. Make sure
> + the directory exists, <application>obexapp</application> will not
> + create it. On a typical workstation with a single user it is useful
> + to set a default owner of received files. See obexapp(1)
> + for details.</para>
> +
> + </sect2>
> +
> + <sect2>
> + <title>Serial Port Profile (SP)</title>
> + <para>Bluetooth can be used to emulate serial port connections.
> + To connect to a remote device, first locate the RFCOMM channel with the
> + Serial Port profile. Then, start the Serial Port Profile Daemon
> + &man.rfcomm.sppd.1; with a free pseudo tty:</para>
> +
> + <screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -c 1 -t /dev/ttyp6</userinput>
> +rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
> +
> + <para>Now connect this pseudo tty to your actual terminal:</para>
> +
> + <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>
> +
> + </sect2>
> +
> + <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
> + 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>
> +
> + </sect2>
> +
> + </sect1>
> +
> </chapter>
>
> <!--
> >Release-Note:
> >Audit-Trail:
> >Unformatted:
> _______________________________________________
> freebsd-doc@freebsd.org mailing list
> http://lists.freebsd.org/mailman/listinfo/freebsd-doc
> To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org"
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200305242050.h4OKoB1A070033>