Attachment #251849 for bug #286826

View | Details | Raw Unified | Return to bug 286826 | Differences between
Collapse All | Expand All




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

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


<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>gnome-bluetooth</c> and
<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>
<!-- 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>

</p>

<pre caption="Running l2ping">
# <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

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


</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.<!-- always or depends on some USE? -->
</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.

<body>

<p>
KDE makes use of <c>kbluetooth</c> and provides more utilities than its Gnome
counterpart as seen below.
</p>


  </li>
</ul>

<pre caption="Installing kbluetooth">
# <i>emerge kbluetooth</i>
</pre>

</body>


<ul>
  <li>
    <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/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-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.
    ensure that <c>multisync</c> has Bluetooth support.
  </li>
  <li>
    <c>net-wireless/opd</c> and <c>net-wireless/ussp-push</c> are command line

Return to bug 286826

Lines 172-203 Link Here

(-)bluetooth-guide.xml?revision=1.17.orig (-20 / +199 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>
		187
		188	<section>
		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>
185		196
186	<pre caption="Installing bluez-libs and bluez-utils">	197	<p>
187	# <i>emerge net-wireless/bluez-libs net-wireless/bluez-utils</i>	198	There are two methods:
		199	</p>
		200
		201	<ul>
		202	<!-- This needs to be clarified. This is what I think
		203	consolekit is, but I don't use it. -->
		204	<li>"consolekit": identifies users who are sat in front of the computer,
		205	and grants them access;</li>
		206	<li>"plugdev": allows members of the plugdev group to use bluetooth</li>
		207	</ul>
		208
		209
		210	<p>
		211	Although the permission policy can be tuned by editing the dbus permission rules
		212	for <c>bluez</c>, the <c>consolekit</c> USE flag must be set accordingly
		213	</p>
		214
		215	<ul>
		216	<li><c>consolekit</c> — means the consolekit method is used and requires
		217	it to be enabled in some dependencies</li>
		218	<li><c>-consolekit</c> — selects the plugdev method, and does not
		219	require any consolekit support in dependencies.</li>
		220	</ul>
		221
		222	</body>
		223	</section>
		224
		225	<section>
		226	<title>Installing bluez</title>
		227
		228	<body>
		229	<p>
		230	Now we can install the package, using the following command.
		231	</p>
		232	<pre caption="Installing bluez">
		233	# <i>emerge net-wireless/bluez</i>
188	</pre>	234	</pre>
189		235
		236	<p>
		237	This ebuild might require certain USE flags to be enabled for other ebuilds:
		238	</p>
		239
		240	<ul>
		241	<li><c>sys-fs/udev</c> must have the <c>extras</c> flag enabled</li>
		242	<li>When <c>bluez</c> is built with <c>consolekit</c> enabled (see above),
		243	<c>sys-auth/pambase</c> must have it enabled too.</li>
		244	</ul>
		245
		246	<p>
		247	Now the bluetooth stack is completely installed, but you need other tools to do
		248	anything useful with it.
		249	</p>
		250
		251	<p>
		252	You can get some tools enabling the <c>test-programs</c> USE flag
		253	for <c>bluez</c>, which will install some testing utilities. But this is a
		254	limited set of tools, mainly intended for testing — you probably want to
		255	install an external bluetooth utilities package.
		256	</p>
190	</body>	257	</body>
191	</section>	258	</section>
		259
192	<section>	260	<section>
193	<title>BlueZ configuration and PIN pairing</title>	261	<title>BlueZ configuration</title>
194	<body>	262	<body>
195		263
196	<p>	264	<p>
197	Now it's time to see if the Bluetooth device is being picked up correctly by the	265	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.	266	system. We start up the required Bluetooth services first. (It may have been
		267	started when you plugged the device, if it uses some hotpluggable interface
		268	(like USB).)
199	</p>	269	</p>
200		270
		271	<!-- hcid and sdpd are not started by bluez-4. I suppose those are
		272	built when USE="old-daemons" in bluez. I didn't have to change any
		273	setting to get it running. It was UP and there is no hcid.conf -->
		274
201	<pre caption="Running hciconfig">	275	<pre caption="Running hciconfig">
202	<comment>(Start up Bluetooth)</comment>	276	<comment>(Start up Bluetooth)</comment>
203	# <i>/etc/init.d/bluetooth start</i>	277	# <i>/etc/init.d/bluetooth start</i>
Lines 273-281 Link Here
273	#encrypt enable;	347	#encrypt enable;
274	}	348	}
275	</pre>	349	</pre>
		350	</body>
		351	</section>
276		352
		353	<section>
		354	<title>PIN pairing (<bluez-4)</title>
		355	<body>
277	<p>	356	<p>
278	After that, we have to configure the Bluetooth device PIN. That will help in	357	After configuration, we have to configure the Bluetooth device PIN. That will help in
279	pairing this device with another one.	358	pairing this device with another one.
280	</p>	359	</p>
281		360
Lines 294-306 Link Here
294	<note>	373	<note>
295	Beginning with <c>>=bluez-libs-3.x</c> and <c>>=bluez-utils-3.x</c>, pin helpers	374	Beginning with <c>>=bluez-libs-3.x</c> and <c>>=bluez-utils-3.x</c>, pin helpers
296	have been replaced by passkey agents. There are a few different graphical	375	have been replaced by passkey agents. There are a few different graphical
297	passkey agents available to help manage your PIN, such as <c>bluez-gnome</c> and	376	passkey agents available to help manage your PIN, such as <c>gnome-bluetooth</c> and
298	<c>kdebluetooth</c>. You can also use <c>passkey-agent</c> (found in	377	<c>kbluetooth</c>. You can also use <c>passkey-agent</c> (found in
299	<c>bluez-utils</c>) from the command line.	378	<c>bluez-utils</c>) from the command line.
300	</note>	379	</note>
		380	</body>
		381	</section>
		382
		383	<section>
		384	<title>PIN Pairing (=bluez-4, with simple-agent)</title>
		385	<body>
		386	<p>
		387	In <c>=bluez-4</c>, there is no global PIN — when a device is paired you
		388	need some bluetooth utility to input a PIN. One such utility
		389	is <c>simple-agent</c>, part of bluez testing utilities (when built
		390	with <c>USE="test-programs"</c>).
		391	</p>
301		392
		393	<p>
		394	Before pairing, you must know the bluetooth adapter id
		395	(run <c>/usr/sbin/hciconfig</c>, if you have several adapters, you need to
		396	choose which one you want to pair.
		397	</p>
		398
		399	<p>
		400	<!-- Does it work with friendly names too? -->
		401	You also need the MAC address of the device you want to pair with the
		402	adapter. Some devices have this written in some label, others don't. To find it
		403	out, make the device visible and run <c>hcitool scan</c> — the result is a
		404	list of devices, with their friendly names and MAC addresses.
		405	</p>
		406
		407	<pre caption="pairing with simple-agent">
		408	<comment>Find the MAC address:</comment>
		409	$ hcitool scan
		410	Scanning ...
		411	05:04:03:02:01:00 friendly-name
		412
		413	<comment>Find the adapter ID:</comment>
		414	$ /usr/sbin/hciconfig
		415	hci0: Type: USB
		416	BD Address: 00:01:02:03:04:05 ACL MTU: 192:8 SCO MTU: 64:8
		417	UP RUNNING PSCAN
		418	RX bytes:131 acl:0 sco:0 events:18 errors:0
		419	TX bytes:565 acl:0 sco:0 commands:17 errors:0
		420
		421	<comment>And then pair the device</comment>
		422	$ simple-agent hci0 05:04:03:02:01:00
		423	RequestPinCode (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
		424	Enter PIN Code: 1234
		425	<comment>(Now the remote device will ask you for this same PIN.)</comment>
		426	Release
		427	New device (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
		428	</pre>
		429
		430	<p>
		431	Other bluetooth packages might be able to handle pairing. This involves a tool
		432	which initiates pairing or a tool which listens for pairing requests, or both.
		433	<!-- Should this be developed to include instructions on how to do it
		434	with other tools? -->
		435	</p>
302	</body>	436	</body>
303	</section>	437	</section>
		438
304	<section>	439	<section>
305	<title>Services configuration</title>	440	<title>Services configuration</title>
306	<body>	441	<body>
Lines 391-397 Link Here
391	</p>	526	</p>
392		527
393	<pre caption="Running l2ping">	528	<pre caption="Running l2ping">
394	# <i>l2ping 00:0A:0B:0C:0D:0E</i>	529	# <i>l2ping 00:0A:0B:0C:0D:0E -c 4</i>
395	Ping: 00:0A:0B:0C:0D:0E from 00:01:02:03:04:05 (data size 20) ...	530	Ping: 00:0A:0B:0C:0D:0E from 00:01:02:03:04:05 (data size 20) ...
396	20 bytes from 00:0A:0B:0C:0D:0E id 200 time 69.85ms	531	20 bytes from 00:0A:0B:0C:0D:0E id 200 time 69.85ms
397	20 bytes from 00:0A:0B:0C:0D:0E id 201 time 9.97ms	532	20 bytes from 00:0A:0B:0C:0D:0E id 201 time 9.97ms
Lines 435-440 Link Here
435	<comment>(Enter the address of the device you want to connect to)</comment>	570	<comment>(Enter the address of the device you want to connect to)</comment>
436	device 00:0A:0B:0C:0D:0E;	571	device 00:0A:0B:0C:0D:0E;
437		572
		573	# RFCOMM channel for the connection
		574	<comment>(Optional. If not specified, it will use channel 1)</comment>
		575	channel 1;
		576
438	}	577	}
439	</pre>	578	</pre>
440		579
Lines 480-485 Link Here
480	</p>	619	</p>
481		620
482	<p>	621	<p>
		622	A bluetooth device may provide several services, on different
		623	channels. To connect to those services using rfcomm, you need to find
		624	out the right channel first. You can do that using <c>sdptool</c>,
		625	part of bluez.<!-- always or depends on some USE? -->
		626	</p>
		627
		628	<pre caption="Finding the right channel (Bluetooth Service Discovery)">
		629	<comment>(The second parameter is the MAC address of the device you want to connect to)</comment>
		630	$ sdptool browse 00:01:02:03:04:05
		631	Browsing 00:01:02:03:04:05 ...
		632	Service Name: OBEX Object Push
		633	Service RecHandle: 0x10001
		634	Service Class ID List:
		635	"OBEX Object Push" (0x1105)
		636	Protocol Descriptor List:
		637	"L2CAP" (0x0100)
		638	"RFCOMM" (0x0003)
		639	<comment>(So if you want to connect to OBEX Object Push, you would use channel 4)</comment>
		640	Channel: 4
		641	"OBEX" (0x0008)
		642	Language Base Attr List:
		643	code_ISO639: 0x656e
		644	encoding: 0x6a
		645	base_offset: 0x100
		646	Profile Descriptor List:
		647	"OBEX Object Push" (0x1105)
		648	Version: 0x0100
		649
		650	<comment>(Each service is described in lines like the ones above.)</comment>
		651	Service Name: Serial Port
		652	Service RecHandle: 0x10002
		653	Service Class ID List:
		654	<comment>...</comment>
		655	</pre>
		656
		657	<p>
483	Each time you call the <c>rfcomm</c> command, you can also specify the physical	658	Each time you call the <c>rfcomm</c> command, you can also specify the physical
484	device you want to use. Below you can see a small example specifiying the	659	device you want to use. Below you can see a small example specifiying the
485	physical device on the above two commands.	660	physical device on the above two commands.
Lines 574-580 Link Here
574	<body>	749	<body>
575		750
576	<p>	751	<p>
577	KDE makes use of <c>kdebluetooth</c> and provides more utilities than its Gnome	752	KDE makes use of <c>kbluetooth</c> and provides more utilities than its Gnome
578	counterpart as seen below.	753	counterpart as seen below.
579	</p>	754	</p>
580		755
Lines 596-603 Link Here
596	</li>	771	</li>
597	</ul>	772	</ul>
598		773
599	<pre caption="Installing kdebluetooth">	774	<pre caption="Installing kbluetooth">
600	# <i>emerge kdebluetooth</i>	775	# <i>emerge kbluetooth</i>
601	</pre>	776	</pre>
602		777
603	</body>	778	</body>
Lines 608-626 Link Here
608		783
609	<ul>	784	<ul>
610	<li>	785	<li>
611	<c>app-mobilephone/obexftp</c>: File transfer over OBEX for mobile phones	786	<c>app-mobilephone/gnokii</c>: Program to access some features
		787	like SMS, calendar and address book. It is also able to set some
		788	phone settings, like its clock. Has graphical and commandline
		789	interfaces. You will need the <c>bluetooth</c> USE flag set to
		790	ensure that <c>gnokii</c> has Bluetooth support.
612	</li>	791	</li>
613	<li>	792	<li>
614	<c>app-mobilephone/bemused</c>: Bemused is a system which allows you to	793	<c>app-mobilephone/obexftp</c>: File transfer over OBEX for mobile phones.
615	control your music collection from your phone, using Bluetooth.	794	You will need the <c>bluetooth</c> USE flag set to ensure
		795	that <c>obexftp</c> has Bluetooth support.
616	</li>	796	</li>
617	<li>	797	<li>
618	<c>app-pda/multisync</c>: Multisync allows you to sync contacts, calendar	798	<c>app-pda/multisync-gui</c>: Multisync allows you to sync contacts, calendar
619	entries and notes from your mobile phone with your computer, over a	799	entries and notes from your mobile phone with your computer, over a
620	Bluetooth connection (amongst other things). It includes such features as	800	Bluetooth connection (amongst other things). It includes such features as
621	backing up this information and restoring it later, and syncing with the	801	backing up this information and restoring it later, and syncing with the
622	Evolution e-mail client. You will need the <c>irmc</c> USE flag set to	802	Evolution e-mail client.
623	ensure that <c>multisync</c> has Bluetooth support.
624	</li>	803	</li>
625	<li>	804	<li>
626	<c>net-wireless/opd</c> and <c>net-wireless/ussp-push</c> are command line	805	<c>net-wireless/opd</c> and <c>net-wireless/ussp-push</c> are command line