From owner-freebsd-doc@FreeBSD.ORG Sat May 24 13:50:12 2003 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 604C237B401 for ; Sat, 24 May 2003 13:50:12 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 7C46F43F85 for ; Sat, 24 May 2003 13:50:11 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h4OKoBUp070034 for ; Sat, 24 May 2003 13:50:11 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h4OKoB1A070033; Sat, 24 May 2003 13:50:11 -0700 (PDT) Date: Sat, 24 May 2003 13:50:11 -0700 (PDT) Message-Id: <200305242050.h4OKoB1A070033@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Murray Stokely Subject: Re: docs/52514: Handbook: new chapter about Bluetooth X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Murray Stokely List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 24 May 2003 20:50:12 -0000 The following reply was made to PR docs/52514; it has been noted by GNATS. From: Murray Stokely To: Pav Lucistnik 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. > > > + > + > + > + > + > + Pav > + Lucistnik > + Written by > + > +
pav@oook.cz
> + > + > + > + > + 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 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. > + > + 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. > + > + > + > + Plugging in the Device > + Device drivers are by default available as kernel modules. > + Before attaching a device, you need to load the driver into the > + kernel: > + > + &prompt.root; kldload ng_ubt > + > + If the Bluetooth device is present in the system during system > + startup, load the module from /boot/loader.conf: > + > + ng_ubt_load="YES" > + > + Plug in your USB dongle. Similar output will appear on the console > + (or in syslog): > + > + 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 > + > + Copy /usr/src/share/examples/netgraph/bluetooth/rc.bluetooth > + to some convenient place, like /etc/rc.bluetooth. > + 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: > + > + &prompt.root; /etc/rc.bluetooth start ubt0 > +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 > + > + > + > + > + HCI and Inquiry > + > + 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: > + > + &prompt.user; hccontrol -n ubt0hci inquiry > +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] > + > + 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: > + > + &prompt.user; hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 0 0 0 > +BD_ADDR: 00:80:37:29:19:a4 > +Name: Pav's T39 > + > + If you perform a discovery on a different bluetooth device, it will find > + your computer as your.host.name (ubt0). > + > + You can list active baseband connections: > + > + &prompt.user; hccontrol -n ubt0hci read_connection_list > +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 > + > + Handle is useful for manually disconnecting a connection: > + > + &prompt.root; hccontrol -n ubt0hci disconnect 41 > +Connection handle: 41 > +Reason: Connection terminated by local host [0x16] > + > + Refer to hccontrol help for a complete listing of > + available commands. Note that the majority of commands does not require > + superuser privileges. > + > + > + > + > + L2CAP > + > + 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 0 bytes as in this example > + is a normal state. > + > + &prompt.root; l2ping -a 00:80:37:29:19:a4 > +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 > + > + The &man.l2control.8; utility is used to configure L2CAP nodes > + and read their state. This example shows file transfer to a Palm > + handheld: > + > + &prompt.user; l2control -a 00:02:72:00:d4:1a read_channel_list > +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; l2control -a 00:02:72:00:d4:1a read_connection_list > +L2CAP connections: > +Remote BD_ADDR Handle Flags Pending State > +00:07:e0:00:0b:ca 41 O 0 OPEN > + > + 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: > + > + &prompt.user; btsockstat > +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 > + > + > + > + > + Pairing of Devices > + > + 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 pairing. > + The daemon that answers pairing requests is &man.hcsecd.8;. Copy > + /usr/src/usr.sbin/bluetooth/hcsecd/hcsecd.conf > + to /usr/local/etc and edit it. The following is an > + example section for a mobile phone, with the PIN arbitrarily set to 1234: > + > + device { > + bdaddr 00:80:37:29:19:a4; > + name "Pav's T39"; > + key nokey; > + pin "1234"; > +} > + > + You can choose any PIN you like. Note that some devices, like > + headsets, have a fixed PIN built in. Start hcsecd -d. > + The 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 > + hcsecd.conf. Now your PC and remote device are paired. > + Alternatively, you can initiate pairing on the remote device. > + This will appear in the hcsecd 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 (SDP) > + If you want to know which services a Bluetooth device offers, and > + on which RFCOMM channels, build libbluetooth > + and sdp-1.0rc3 from + url="http://www.geocities.com/m_evmenkin/">Maksim Evmenkin's > + snapshot. Then, run sdptool and > + observe (the output is snipped a bit, as this tool is quite talky): > + > + &prompt.root; sdptool browse 00:80:37:29:19:a4 > +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 > + > + > + ... 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. > + > + &prompt.root; sdptool search --bdaddr 00:07:e0:00:0b:ca OPUSH > + > + Offering services on FreeBSD to other devices is done using the > + sdpd server. > + &prompt.root; sdpd > + > + Registering a given Bluetooth service to a RFCOMM channel number: > + &prompt.root; sdptool add --channel=7 LAN > + > + Checking services offered by our computer: > + &prompt.root; sdptool browse ff:ff:ff:00:00:00 > + > + > + > + Dial-up Networking (DUN) and Local Area Network (LAN) > + > + 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 > + /etc/ppp/ppp.conf, examples from the &man.rfcomm.pppd.8; > + manual page can be used. > + > + Connecting to the Internet through a mobile phone (DUN profile). First, find > + out the correct RFCOMM channel on the remote device using > + sdptool. Then, use &man.rfcomm.pppd.8;: > + > + &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C 1 -l rfcomm-dialup > + > + Running a Bluetooth access point on FreeBSD. First, register a > + RFCOMM channel for LAN service on the local sdpd. > + Then, start the ppp server. Use BD_ADDR of the local Bluetooth device and > + the channel number registered with sdpd. > + > + &prompt.root; rfcomm_pppd -a 00:02:72:00:d4:1a -s -C 7 -l rfcomm-server > + > + > + > + > + OBEX Push (OPUSH) > + 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. > + > + The OBEX client is implemented in the > + obexapp utility from + url="http://www.geocities.com/m_evmenkin/">Maksim Evmenkin's > + snapshot. It needs the openobex > + library from same package and the > + devel/glib12 port. Note that > + obexapp does not require root privileges > + to operate. > + > + OBEX client. First, find which channel on the remote device is IrMC > + Synchronization or OBEX Object Push. After that, use > + obexapp. 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): > + > + &prompt.user; obexapp -a 00:80:37:29:19:a4 -C 10 > +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) > + > + OBEX server. First, register the OPUSH service with the local > + sdpd. If OPUSH does not work, > + you can try the FTRN service instead. Then, start the OBEX daemon > + using the channel number registered with sdpd: > + > + &prompt.root; obexapp -s -C 10 > + > + Received files will appear in /var/spool/obex. > + This can be overriden with the switch. Make sure > + the directory exists, obexapp 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. > + > + > + > + > + Serial Port Profile (SP) > + 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: > + > + &prompt.root; rfcomm_sppd -a 00:07:E0:00:0B:CA -c 1 -t /dev/ttyp6 > +rfcomm_sppd[94692]: Starting on /dev/ttyp6... > + > + Now connect this pseudo tty to your actual terminal: > + > + &prompt.root; cu -l ttyp6 > + > + > + > + > + Troubleshooting > + > + > + A remote device cannot connect to us > + 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: > + &prompt.root; hccontrol -n ubt0hci write_node_role_switch 0 > + > + > + > + Something is going wrong, can I see what exactly is happening? > + Yes, you can. Use the hcidump tool > + from Maksim Evmenkin's > + snapshot, 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. > + > + > + > + > + > + > > >