Attachment 243633 Details for Bug 286826 – suggested changes to the guide (2nd version)

[patch] suggested changes to the guide (2nd version)

bluetooth-guide-2nd.patch (text/plain), 10.12 KB, created by Nuno Silva on 2010-08-19 22:26:41 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Nuno Silva

Created: 2010-08-19 22:26:41 UTC

Size: 10.12 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-08-19 23:17:48.000000000 +0100
>@@ -172,32 +172,106 @@
> <chapter id="bluez">
> <title>BlueZ - The Bluetooth Stack</title>
> <section>
>-<title>Installing BlueZ</title>
>+<title>What is BlueZ?</title>
> <body>
> 
> <p>
> 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>.
> </p>
>+</body>
>+</section>
>+
>+<section>
>+<title>BlueZ permission control</title>
>+
>+<body>
>+<p>
>+Before installing, it is a good idea to choose how to control users' ability to
>+use bluetooth.
>+</p>
> 
>-<pre caption="Installing bluez-libs and bluez-utils">
>-# <i>emerge net-wireless/bluez-libs net-wireless/bluez-utils</i>
>+<p>
>+There are two methods:
>+</p>
>+
>+<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>
>+
>+
>+<p>
>+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
>+</p>
>+
>+<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>
>+<p>
>+Now we can install the package, using the following command.
>+</p>
>+<pre caption="Installing bluez">
>+# <i>emerge net-wireless/bluez</i>
> </pre>
> 
>+<p>
>+This ebuild might require certain USE flags to be enabled for other ebuilds:
>+</p>
>+
>+<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>
>+
>+<p>
>+Now the bluetooth stack is completely installed, but you need other tools to do
>+anything useful with it.
>+</p>
>+
>+<p>
>+You can get some tools 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.
>+</p>
> </body>
> </section>
>+
> <section>
>-<title>BlueZ configuration and PIN pairing</title>
>+<title>BlueZ configuration</title>
> <body>
> 
> <p>
> 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).)
> </p>
> 
>+
>+
> <pre caption="Running hciconfig">
> <comment>(Start up Bluetooth)</comment>
> # <i>/etc/init.d/bluetooth start</i>
>@@ -273,9 +347,14 @@
>         #encrypt enable;
> }
> </pre>
>+</body>
>+</section>
> 
>+<section>
>+<title>PIN pairing (&lt;bluez-4)</title>
>+<body>
> <p>
>-After that, we have to configure the Bluetooth device PIN. That will help in
>+After configuration, we have to configure the Bluetooth device PIN. That will help in
> pairing this device with another one.
> </p>
> 
>@@ -295,12 +374,68 @@
> 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>kbluetooth</c>. You can also use <c>passkey-agent</c> (found in
> <c>bluez-utils</c>) from the command line.
> </note>
>+</body>
>+</section>
>+
>+<section> 
>+<title>PIN Pairing (=bluez-4, with simple-agent)</title>
>+<body>
>+<p>
>+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>).
>+</p>
> 
>+<p>
>+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.
>+</p>
>+
>+<p>
>+
>+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.
>+</p>
>+
>+<pre caption="pairing with simple-agent">
>+  <comment>Find the MAC address:</comment>
>+$ hcitool scan
>+Scanning ...
>+	05:04:03:02:01:00	friendly-name
>+
>+  <comment>Find the adapter ID:</comment>
>+$ /usr/sbin/hciconfig
>+hci0:   Type: USB
>+        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
>+
>+  <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>
>+
>+<p>
>+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.
>+
>+</p>
> </body>
> </section>
>+
> <section>
> <title>Services configuration</title>
> <body>
>@@ -391,7 +526,7 @@
> </p>
> 
> <pre caption="Running l2ping">
>-# <i>l2ping 00:0A:0B:0C:0D:0E</i>
>+# <i>l2ping 00:0A:0B:0C:0D:0E -c 4</i>
> 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 +570,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 +619,42 @@
> </p>
> 
> <p>
>+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.
>+</p>
>+
>+<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, you would 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>
>+
>+<p>
> 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 +749,7 @@
> <body>
> 
> <p>
>-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.
> </p>
> 
>@@ -596,8 +771,8 @@
>   </li>
> </ul>
> 
>-<pre caption="Installing kdebluetooth">
>-# <i>emerge kdebluetooth</i>
>+<pre caption="Installing kbluetooth">
>+# <i>emerge kbluetooth</i>
> </pre>
> 
> </body>
>@@ -608,19 +783,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