Attachment #241795 for bug #286826




<chapter id="bluez">
<title>BlueZ - The Bluetooth Stack</title>
<section>
<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 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>

<p>
There are two methods:
<ul>
<!-- This needs to be clarified. This is what I think
consolekit is, but I don't use it. -->
  <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>

<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
<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>
</p>
</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>

<!-- Should this be said here, or we assume the user knows how to deal
with this? -->
<p>
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>
</p>

<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</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. (It may have been
started when you plugged the device, if it uses some hotpluggable interface
(like USB).)
</p>

<!-- hcid and sdpd are not started by bluez-4. I suppose those are
built when USE="old-daemons" in bluez. I didn't have to change any
setting to get it running. It was UP and there is no hcid.conf -->

<pre caption="Running hciconfig">
<comment>(Start up Bluetooth)</comment>
# <i>/etc/init.d/bluetooth start</i>

        #encrypt enable;
}
</pre>
</body>
</section>

<section>
<title>PIN pairing (<c>&lt;bluez-4</c>)</title>
<body>
<p>
After configuration, we have to configure the Bluetooth device PIN. That will help in
pairing this device with another one.
</p>


<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>PIN Pairing (<c>=bluez-4</c>, with <c>simple-agent</c>)</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>
<!-- Does it work with friendly names too? -->
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.
<!-- Should this be developed to include instructions on how to do it
with other tools? -->
</p>
</body>
</section>

<section>
<title>Services configuration</title>
<body>

Return to bug 286826

Lines 172-203 Link Here

(-)bluetooth-guide.xml?revision=1.17.orig (-8 / +140 lines)
172	<chapter id="bluez">	172	<chapter id="bluez">
173	<title>BlueZ - The Bluetooth Stack</title>	173	<title>BlueZ - The Bluetooth Stack</title>
174	<section>	174	<section>
175	<title>Installing BlueZ</title>	175	<title>What is BlueZ?</title>
176	<body>	176	<body>
177		177
178	<p>	178	<p>
179	Now that the device is detected by the kernel, we need a layer that lets	179	Now that the device is detected by the kernel, we need a layer that lets
180	applications communicate with the Bluetooth device. BlueZ provides the official	180	applications communicate with the Bluetooth device. BlueZ provides the official
181	Linux Bluetooth stack. The ebuilds that provide what we need are	181	Linux Bluetooth stack. The ebuild that provides what we need is
182	<c>bluez-libs</c> and <c>bluez-utils</c>. Devices that need Broadcom firmware	182	<c>bluez</c>. Devices that need Broadcom firmware
183	files or the like may need <c>bluez-firmware</c>.	183	files or the like may need <c>bluez-firmware</c>.
184	</p>	184	</p>
		185	</body>
		186	</section>
185		187
186	<pre caption="Installing bluez-libs and bluez-utils">	188	<section>
187	# <i>emerge net-wireless/bluez-libs net-wireless/bluez-utils</i>	189	<title>BlueZ permission control</title>
		190
		191	<body>
		192	<p>
		193	Before installing, it is a good idea to choose how to control users' ability to
		194	use bluetooth.
		195	</p>
		196
		197	<p>
		198	There are two methods:
		199	<ul>
		200	<!-- This needs to be clarified. This is what I think
		201	consolekit is, but I don't use it. -->
		202	<li>"consolekit": identifies users who are sat in front of the computer,
		203	and grants them access;</li>
		204	<li>"plugdev": allows members of the plugdev group to use bluetooth</li>
		205	</ul>
		206	</p>
		207
		208	<p>
		209	Although the permission policy can be tuned by editing the dbus permission rules
		210	for <c>bluez</c>, the <c>consolekit</c> USE flag must be set accordingly
		211	<ul>
		212	<li><c>consolekit</c> — means the consolekit method is used and requires
		213	it to be enabled in some dependencies</li>
		214	<li><c>-consolekit</c> — selects the plugdev method, and does not
		215	require any consolekit support in dependencies.</li>
		216	</ul>
		217	</p>
		218	</body>
		219	</section>
		220
		221	<section>
		222	<title>Installing bluez</title>
		223
		224	<body>
		225	<p>
		226	Now we can install the package, using the following command.
		227	</p>
		228	<pre caption="Installing bluez">
		229	# <i>emerge net-wireless/bluez</i>
188	</pre>	230	</pre>
189		231
		232	<!-- Should this be said here, or we assume the user knows how to deal
		233	with this? -->
		234	<p>
		235	This ebuild might require certain USE flags to be enabled for other ebuilds:
		236	<ul>
		237	<li><c>sys-fs/udev</c> must have the <c>extras</c> flag enabled</li>
		238	<li>When <c>bluez</c> is built with <c>consolekit</c> enabled (see above),
		239	<c>sys-auth/pambase</c> must have it enabled too.</li>
		240	</ul>
		241	</p>
		242
		243	<p>
		244	Now the bluetooth stack is completely installed, but you need other tools to do
		245	anything useful with it.
		246	</p>
		247
		248	<p>
		249	You can get some tools enabling the <c>test-programs</c> USE flag
		250	for <c>bluez</c>, which will install some testing utilities. But this is a
		251	limited set of tools, mainly intended for testing — you probably want to
		252	install an external bluetooth utilities package.
		253	</p>
190	</body>	254	</body>
191	</section>	255	</section>
		256
192	<section>	257	<section>
193	<title>BlueZ configuration and PIN pairing</title>	258	<title>BlueZ configuration</title>
194	<body>	259	<body>
195		260
196	<p>	261	<p>
197	Now it's time to see if the Bluetooth device is being picked up correctly by the	262	Now it's time to see if the Bluetooth device is being picked up correctly by the
198	system. We start up the required Bluetooth services first.	263	system. We start up the required Bluetooth services first. (It may have been
		264	started when you plugged the device, if it uses some hotpluggable interface
		265	(like USB).)
199	</p>	266	</p>
200		267
		268	<!-- hcid and sdpd are not started by bluez-4. I suppose those are
		269	built when USE="old-daemons" in bluez. I didn't have to change any
		270	setting to get it running. It was UP and there is no hcid.conf -->
		271
201	<pre caption="Running hciconfig">	272	<pre caption="Running hciconfig">
202	<comment>(Start up Bluetooth)</comment>	273	<comment>(Start up Bluetooth)</comment>
203	# <i>/etc/init.d/bluetooth start</i>	274	# <i>/etc/init.d/bluetooth start</i>
Lines 273-281 Link Here
273	#encrypt enable;	344	#encrypt enable;
274	}	345	}
275	</pre>	346	</pre>
		347	</body>
		348	</section>
276		349
		350	<section>
		351	<title>PIN pairing (<c><bluez-4</c>)</title>
		352	<body>
277	<p>	353	<p>
278	After that, we have to configure the Bluetooth device PIN. That will help in	354	After configuration, we have to configure the Bluetooth device PIN. That will help in
279	pairing this device with another one.	355	pairing this device with another one.
280	</p>	356	</p>
281		357
Lines 298-306 Link Here
298	<c>kdebluetooth</c>. You can also use <c>passkey-agent</c> (found in	374	<c>kdebluetooth</c>. You can also use <c>passkey-agent</c> (found in
299	<c>bluez-utils</c>) from the command line.	375	<c>bluez-utils</c>) from the command line.
300	</note>	376	</note>
		377	</body>
		378	</section>
		379
		380	<section>
		381	<title>PIN Pairing (<c>=bluez-4</c>, with <c>simple-agent</c>)</title>
		382	<body>
		383	<p>
		384	In <c>=bluez-4</c>, there is no global PIN — when a device is paired you
		385	need some bluetooth utility to input a PIN. One such utility
		386	is <c>simple-agent</c>, part of bluez testing utilities (when built
		387	with <c>USE="test-programs"</c>).
		388	</p>
		389
		390	<p>
		391	Before pairing, you must know the bluetooth adapter id
		392	(run <c>/usr/sbin/hciconfig</c>, if you have several adapters, you need to
		393	choose which one you want to pair.
		394	</p>
		395
		396	<p>
		397	<!-- Does it work with friendly names too? -->
		398	You also need the MAC address of the device you want to pair with the
		399	adapter. Some devices have this written in some label, others don't. To find it
		400	out, make the device visible and run <c>hcitool scan</c> — the result is a
		401	list of devices, with their friendly names and MAC addresses.
		402	</p>
		403
		404	<pre caption="pairing with simple-agent">
		405	<comment>Find the MAC address:</comment>
		406	$ hcitool scan
		407	Scanning ...
		408	05:04:03:02:01:00 friendly-name
		409
		410	<comment>Find the adapter ID:</comment>
		411	$ /usr/sbin/hciconfig
		412	hci0: Type: USB
		413	BD Address: 00:01:02:03:04:05 ACL MTU: 192:8 SCO MTU: 64:8
		414	UP RUNNING PSCAN
		415	RX bytes:131 acl:0 sco:0 events:18 errors:0
		416	TX bytes:565 acl:0 sco:0 commands:17 errors:0
		417
		418	<comment>And then pair the device</comment>
		419	$ simple-agent hci0 05:04:03:02:01:00
		420	RequestPinCode (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
		421	Enter PIN Code: 1234
		422	<comment>(Now the remote device will ask you for this same PIN.)</comment>
		423	Release
		424	New device (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
		425	</pre>
301		426
		427	<p>
		428	Other bluetooth packages might be able to handle pairing. This involves a tool
		429	which initiates pairing or a tool which listens for pairing requests, or both.
		430	<!-- Should this be developed to include instructions on how to do it
		431	with other tools? -->
		432	</p>
302	</body>	433	</body>
303	</section>	434	</section>
		435
304	<section>	436	<section>
305	<title>Services configuration</title>	437	<title>Services configuration</title>
306	<body>	438	<body>