Attachment 254259 Details for Bug 286826 – suggested changes to the guide (5th version)

[patch] suggested changes to the guide (5th version)

bluetooth-guide-5th.patch (text/plain), 14.57 KB, created by Nuno Silva on 2010-11-14 00:47:30 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Nuno Silva

Created: 2010-11-14 00:47:30 UTC

Size: 14.57 KB

patch

obsolete

>--- bluetooth-guide.xml?revision=1.17.orig	2010-08-03 22:31:10.000000000 +0100
>+++ bluetooth-guide.xml?revision=1.17	2010-11-14 00:50:55.000000000 +0000
>@@ -172,185 +172,187 @@
> <chapter id="bluez">
> <title>BlueZ - The Bluetooth Stack</title>
> <section>
>-<title>Installing BlueZ</title>
>+<title>What is BlueZ?</title>
> <body>
> 
> 
> Now that the device is detected by the kernel, we need a layer that lets
> applications communicate with the Bluetooth device. BlueZ provides the official
>-Linux Bluetooth stack. The ebuilds that provide what we need are
>-<c>bluez-libs</c> and <c>bluez-utils</c>. Devices that need Broadcom firmware
>+Linux Bluetooth stack. The ebuild that provides what we need is
>+<c>bluez</c>. Devices that need Broadcom firmware 
> files or the like may need <c>bluez-firmware</c>.
> 
>+</body>
>+</section>
>+
>+<section>
>+<title>BlueZ permission control</title>
>+
>+<body>
>+
>+
>+Before installing, it is a good idea to choose how to control users' ability to
>+use bluetooth.
>+
>+
>+
>+There are two methods:
>+
>+
>+<ul>
>+
>+ <li>"consolekit": identifies users who are sat in front of the computer,
>+ and grants them access;</li>
>+ <li>"plugdev": allows members of the plugdev group to use bluetooth</li>
>+</ul>
>+
>+
>+Although the permission policy can be tuned by editing the dbus permission rules
>+for <c>bluez</c>, the <c>consolekit</c> USE flag must be set accordingly
>+
>+
>+<ul>
>+ <li><c>consolekit</c> &mdash; means the consolekit method is used and requires
>+ it to be enabled in some dependencies</li>
>+ <li><c>-consolekit</c> &mdash; selects the plugdev method, and does not
>+ require any consolekit support in dependencies.</li>
>+</ul>
>+
>+</body>
>+</section>
>+
>+<section>
>+<title>Installing bluez</title>
>+
>+<body>
>+
>+
>+Now we can install the package, using the following command.
>+
> 
>-<pre caption="Installing bluez-libs and bluez-utils">
>-# emerge net-wireless/bluez-libs net-wireless/bluez-utils
>+<pre caption="Installing bluez">
>+# emerge net-wireless/bluez
> </pre>
> 
>+
>+This ebuild might require certain USE flags to be enabled for other ebuilds:
>+
>+
>+<ul>
>+ <li><c>sys-fs/udev</c> must have the <c>extras</c> flag enabled</li>
>+ <li>When <c>bluez</c> is built with <c>consolekit</c> enabled (see above),
>+ <c>sys-auth/pambase</c> must have it enabled too.</li>
>+</ul>
>+
>+
>+Now the bluetooth stack is completely installed, but you need other tools to do
>+anything useful with it.
>+
>+
>+
>+You can get some tools (including a CLI tool to pair devices) enabling
>+the <c>test-programs</c> USE flag
>+for <c>bluez</c>, which will install some testing utilities. But this is a
>+limited set of tools, mainly intended for testing &mdash; you probably want to
>+install an external bluetooth utilities package.
>+
> </body>
> </section>
>+
> <section>
>-<title>BlueZ configuration and PIN pairing</title>
>+<title>Start BlueZ</title>
> <body>
> 
> 
> Now it's time to see if the Bluetooth device is being picked up correctly by the
>-system. We start up the required Bluetooth services first.
>+system. We start up the required Bluetooth services first. (It may have been
>+started when you plugged the device, if it uses some hotpluggable interface
>+(like USB).)
> 
> 
> <pre caption="Running hciconfig">
> <comment>(Start up Bluetooth)</comment>
> # /etc/init.d/bluetooth start
> * Starting Bluetooth ...
>-* Starting hcid ... [ ok ]
>-* Starting sdpd ... [ ok ]
> * Starting rfcomm ... [ ok ]
> 
> # hciconfig
> hci0: Type: USB
> BD Address: 00:01:02:03:04:05 ACL MTU: 192:8 SCO MTU: 64:8
>- DOWN
>+ UP RUNNING PSCAN
> RX bytes:131 acl:0 sco:0 events:18 errors:0
> TX bytes:565 acl:0 sco:0 commands:17 errors:0
> </pre>
> 
>-
>-This shows that the Bluetooth device has been recognised. As you might have
>-noticed the device is <e>DOWN</e>. Let's configure it so that we can bring it
>-up. The configuration file is at <path>/etc/bluetooth/hcid.conf</path>. The
>-required changes to the config file are shown below. For additional details
>-please refer to <c>man hcid.conf</c>.
>-
>-
>-<pre caption="Editing /etc/bluetooth/hcid.conf">
>-<comment>(Recommended changes to be made to the file are shown)</comment>
>-
>-# HCId options
>-options {
>- # Automatically initialize new devices
>- autoinit yes;
>-
>-<comment>(Change security to "auto")</comment>
>- # Security Manager mode
>- # none - Security manager disabled
>- # auto - Use local PIN for incoming connections
>- # user - Always ask user for a PIN
>- #
>- security auto;
>-
>- # Pairing mode
>- pairing multi;
>-
>-<comment>(You only need a pin helper if you are using &lt;=bluez-libs-2.x and &lt;=bluez-utils-2.x)
>-(Change pin_helper to use /etc/bluetooth/pin-helper)</comment>
>- # PIN helper
>- pin_helper /etc/bluetooth/pin-helper;
>-}
>-
>-# Default settings for HCI devices
>-device {
>-<comment>(Set your device name here, you can call it anything you want)</comment>
>- # Local device name
>- # %d - device id
>- # %h - host name
>- name "BlueZ at %h (%d)";
>-
>- # Local device class
>- class 0x3e0100;
>-
>- # Inquiry and Page scan
>- iscan enable; pscan enable;
>-
>- # Default link mode
>- lm accept;
>-
>- # Default link policy
>- lp rswitch,hold,sniff,park;
>-
>-<comment>(Leave as is, if you don't know what exactly these do)</comment>
>- # Authentication and Encryption (Security Mode 3)
>- #auth enable;
>- #encrypt enable;
>-}
>-</pre>
>-
>-
>-After that, we have to configure the Bluetooth device PIN. That will help in
>-pairing this device with another one.
>-
>+If BlueZ is not started when the device is detected and you use
>+bluetooth frequenty, you may want to add it to the default runlevel,
>+so that it starts automatically on boot. To do that, use
>+<c>rc-update</c>.
> 
>-<pre caption="Editing /etc/bluetooth/pin">
>-<comment>(Replace 123456 with your desired pin number.)</comment>
>-123456
>+<pre caption="Automatically start bluetooth on boot">
>+<comment>(We can also add it to the default runlevel.)</comment>
>+# rc-update add bluetooth default
>+ * bluetooth added to runlevel default
> </pre>
> 
>-<impo>
>-This number (of your choice) must be the same in all your hosts with Bluetooth
>-devices so they can be paired. This number must also be kept secret since anyone
>-with knowledge of this number can essentially establish connections with your
>-devices.
>-</impo>
>-
>-<note>
>-Beginning with <c>>=bluez-libs-3.x</c> and <c>>=bluez-utils-3.x</c>, pin helpers
>-have been replaced by passkey agents. There are a few different graphical
>-passkey agents available to help manage your PIN, such as <c>bluez-gnome</c> and
>-<c>kdebluetooth</c>. You can also use <c>passkey-agent</c> (found in
>-<c>bluez-utils</c>) from the command line.
>-</note>
>-
> </body>
> </section>
>+
> <section>
>-<title>Services configuration</title>
>+<title>PIN Pairing</title>
> <body>
> 
> 
>-Now that we have concluded with the configuration of BlueZ, it's time to restart
>-the necessary services.
>+In <c>=bluez-4</c>, there is no global PIN &mdash; when a device is paired you
>+need some bluetooth utility to input a PIN. One such utility
>+is <c>simple-agent</c>, part of bluez testing utilities (when built
>+with <c>USE="test-programs"</c>).
> 
> 
>-<pre caption="Starting the Bluetooth daemons">
>-# /etc/init.d/bluetooth restart
>-<comment>(We can also add it to the default runlevel.)</comment>
>-# rc-update add bluetooth default
>- * bluetooth added to runlevel default
>- * rc-update complete.
>-</pre>
>+
>+Before pairing, you must know the bluetooth adapter id
>+(run <c>/usr/sbin/hciconfig</c>, if you have several adapters, you need to
>+choose which one you want to pair.
>+
> 
> 
>-Let's be sure that the Bluetooth daemons started correctly. If we can see that
>-both <c>hcid</c> and <c>sdpd</c> are running, then we configured Bluetooth the
>-right way. After that, we can see if the devices are now up and running with
>-the configured options.
>+
>+You also need the MAC address of the device you want to pair with the
>+adapter. Some devices have this written in some label, others don't. To find it
>+out, make the device visible and run <c>hcitool scan</c> &mdash; the result is a
>+list of devices, with their friendly names and MAC addresses.
> 
> 
>-<pre caption="Checking whether Bluetooth daemons started correctly">
>-<comment>(Check to see if the services are running)</comment>
>-# ps -ae | grep hcid
>-26050 ? 00:00:00 hcid
>-# ps -ae | grep sdpd
>-26054 ? 00:00:00 sdpd
>+<pre caption="pairing with simple-agent">
>+ <comment>Find the MAC address:</comment>
>+$ hcitool scan
>+Scanning ...
>+	05:04:03:02:01:00	friendly-name
> 
>-# hciconfig -a
>+ <comment>Find the adapter ID:</comment>
>+$ /usr/sbin/hciconfig
> hci0: Type: USB
>- BD Address: 00:0A:0B:0C:0D:0E ACL MTU: 192:8 SCO MTU: 64:8
>- UP RUNNING PSCAN ISCAN
>- RX bytes:125 acl:0 sco:0 events:17 errors:0
>+ BD Address: 00:01:02:03:04:05 ACL MTU: 192:8 SCO MTU: 64:8
>+ UP RUNNING PSCAN
>+ RX bytes:131 acl:0 sco:0 events:18 errors:0
> TX bytes:565 acl:0 sco:0 commands:17 errors:0
>- Features: 0xff 0xff 0x0f 0x00 0x00 0x00 0x00 0x00
>- Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3
>- Link policy: RSWITCH HOLD SNIFF PARK
>- Link mode: SLAVE ACCEPT
>- Name: 'BlueZ at bluehat (0)'
>- Class: 0x3e0100
>- Service Classes: Networking, Rendering, Capturing, Object Transfer,
>- Audio
>- Device Class: Computer, Uncategorized
>- HCI Ver: 1.1 (0x1) HCI Rev: 0x1e7 LMP Ver: 1.1 (0x1) LMP Subver: 0x1e7
>- Manufacturer: Cambridge Silicon Radio (10)
>+
>+ <comment>And then pair the device</comment>
>+$ simple-agent hci0 05:04:03:02:01:00
>+RequestPinCode (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
>+Enter PIN Code: 1234
>+ <comment>(Now the remote device will ask you for this same PIN.)</comment>
>+Release
>+New device (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
> </pre>
> 
>+
>+Other bluetooth packages might be able to handle pairing. This involves a tool
>+which initiates pairing or a tool which listens for pairing requests, or both.
>+
>+
> </body>
> </section>
> </chapter>
>@@ -367,6 +369,13 @@
> the <c>hcitool</c> command for the same.
> 
> 
>+
>+<note>
>+Some devices have a visibility setting, which if disabled will prevent
>+your device from detecting them.
>+</note>
>+
>+
> <pre caption="Checking for local devices">
> # hcitool dev
> Devices:
>@@ -391,7 +400,7 @@
> 
> 
> <pre caption="Running l2ping">
>-# l2ping 00:0A:0B:0C:0D:0E
>+# l2ping 00:0A:0B:0C:0D:0E -c 4
> Ping: 00:0A:0B:0C:0D:0E from 00:01:02:03:04:05 (data size 20) ...
> 20 bytes from 00:0A:0B:0C:0D:0E id 200 time 69.85ms
> 20 bytes from 00:0A:0B:0C:0D:0E id 201 time 9.97ms
>@@ -435,6 +444,10 @@
> <comment>(Enter the address of the device you want to connect to)</comment>
> device 00:0A:0B:0C:0D:0E;
> 
>+ # RFCOMM channel for the connection
>+	<comment>(Optional. If not specified, it will use channel 1)</comment>
>+ channel 1;
>+
> }
> </pre>
> 
>@@ -480,6 +493,42 @@
> 
> 
> 
>+A bluetooth device may provide several services, on different
>+channels. To connect to those services using rfcomm, you need to find
>+out the right channel first. You can do that using <c>sdptool</c>,
>+part of bluez.
>+
>+
>+<pre caption="Finding the right channel (Bluetooth Service Discovery)">
>+<comment>(The second parameter is the MAC address of the device you want to connect to)</comment>
>+$ sdptool browse 00:01:02:03:04:05
>+Browsing 00:01:02:03:04:05 ...
>+Service Name: OBEX Object Push
>+Service RecHandle: 0x10001
>+Service Class ID List:
>+ "OBEX Object Push" (0x1105)
>+Protocol Descriptor List:
>+ "L2CAP" (0x0100)
>+ "RFCOMM" (0x0003)
>+<comment>(So if you want to connect to OBEX Object Push, use channel 4)</comment>
>+ Channel: 4
>+ "OBEX" (0x0008)
>+Language Base Attr List:
>+ code_ISO639: 0x656e
>+ encoding: 0x6a
>+ base_offset: 0x100
>+Profile Descriptor List:
>+ "OBEX Object Push" (0x1105)
>+ Version: 0x0100
>+
>+<comment>(Each service is described in lines like the ones above.)</comment>
>+Service Name: Serial Port
>+Service RecHandle: 0x10002
>+Service Class ID List:
>+<comment>...</comment>
>+</pre>
>+
>+
> Each time you call the <c>rfcomm</c> command, you can also specify the physical
> device you want to use. Below you can see a small example specifiying the
> physical device on the above two commands.
>@@ -574,7 +623,7 @@
> <body>
> 
> 
>-KDE makes use of <c>kdebluetooth</c> and provides more utilities than its Gnome
>+KDE makes use of <c>kbluetooth</c> and provides more utilities than its Gnome
> counterpart as seen below.
> 
> 
>@@ -596,8 +645,8 @@
> </li>
> </ul>
> 
>-<pre caption="Installing kdebluetooth">
>-# emerge kdebluetooth
>+<pre caption="Installing kbluetooth">
>+# emerge kbluetooth
> </pre>
> 
> </body>
>@@ -608,19 +657,23 @@
> 
> <ul>
> <li>
>- <c>app-mobilephone/obexftp</c>: File transfer over OBEX for mobile phones
>+ <c>app-mobilephone/gnokii</c>: Program to access some features
>+ like SMS, calendar and address book. It is also able to set some
>+ phone settings, like its clock. Has graphical and commandline
>+ interfaces. You will need the <c>bluetooth</c> USE flag set to
>+ ensure that <c>gnokii</c> has Bluetooth support.
> </li>
> <li>
>- <c>app-mobilephone/bemused</c>: Bemused is a system which allows you to
>- control your music collection from your phone, using Bluetooth.
>+ <c>app-mobilephone/obexftp</c>: File transfer over OBEX for mobile phones. 
>+ You will need the <c>bluetooth</c> USE flag set to ensure
>+ that <c>obexftp</c> has Bluetooth support.
> </li>
> <li>
>- <c>app-pda/multisync</c>: Multisync allows you to sync contacts, calendar
>+ <c>app-pda/multisync-gui</c>: Multisync allows you to sync contacts, calendar
> entries and notes from your mobile phone with your computer, over a
> Bluetooth connection (amongst other things). It includes such features as
> backing up this information and restoring it later, and syncing with the
>- Evolution e-mail client. You will need the <c>irmc</c> USE flag set to
>- ensure that <c>multisync</c> has Bluetooth support.
>+ Evolution e-mail client.
> </li>
> <li>
> <c>net-wireless/opd</c> and <c>net-wireless/ussp-push</c> are command line

Actions: View | Diff

Attachments on bug 286826: 241795 | 243633 | 251849 | 252969 | 254259