Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 286826 - Bluetooth Guide out of date
Summary: Bluetooth Guide out of date
Status: RESOLVED FIXED
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Other documents (show other bugs)
Hardware: All Linux
: High normal with 4 votes (vote)
Assignee: Docs Team
URL: http://www.gentoo.org/doc/en/bluetoot...
Whiteboard:
Keywords:
: 300164 302894 (view as bug list)
Depends on: 266690
Blocks:
  Show dependency tree
 
Reported: 2009-09-28 18:55 UTC by Tyler Montbriand
Modified: 2012-06-29 19:09 UTC (History)
12 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments
suggested changes to the guide (bluetooth-guide.patch,6.09 KB, patch)
2010-08-07 18:45 UTC, Nuno Silva
Details | Diff
suggested changes to the guide (2nd version) (bluetooth-guide-2nd.patch,10.12 KB, patch)
2010-08-19 22:26 UTC, Nuno Silva
Details | Diff
suggested changes to the guide (3rd version) (bluetooth-guide-3rd.patch,10.21 KB, patch)
2010-10-24 20:08 UTC, Nuno Silva
Details | Diff
suggested changes to the guide (4th version) (bluetooth-guide-4th.patch,14.54 KB, patch)
2010-11-02 22:40 UTC, Nuno Silva
Details | Diff
suggested changes to the guide (5th version) (bluetooth-guide-5th.patch,14.57 KB, patch)
2010-11-14 00:47 UTC, Nuno Silva
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Tyler Montbriand 2009-09-28 18:55:25 UTC
The Gentoo Linux Bluetooth Guide no longer accurately describes how to use
bluez-libs and bluez-utils.  In particular it mentions two ways to set your PIN,
neither of which appear to exist in the current interface.  It also instructs
you to add bluetooth to the default runlevel when bluetooth now runs itself
when udev detects a usable interface.  It also instructs the user to look for
processes that no longer appear to exist, use tools that no longer exist,
et cetera.

I've managed to find little to nothing outside of gentoo on how to use this.
The best advice I've had is to use the new 'bluez' package instead which,
while unstable, is held as the modern replacement, but it's not documented
either.  Most of its users seem to use Gnome or KDE applications for bluetooth,
with no knowledge of how to do system-level testing of it as bluez-utils used
to provide.

I think that's unfortunate.  The ability to do real system configuration and
testing on a machine without the enormous weight of a window system is one of
the things that makes gentoo the most valuable to me.

Reproducible: Always

Steps to Reproduce:
Comment 1 nm (RETIRED) gentoo-dev 2009-09-29 07:37:44 UTC
We do need to update our guide, but I don't have the least idea how to proceed.

See also bug #266690 -- there are many things that need fixin'. http://bugs.gentoo.org/show_bug.cgi?id=266690

I CCed some herds and members responsible for bluez and related packages.

What do we need to do, folks?
Comment 2 Tyler Montbriand 2009-11-20 22:52:37 UTC
I guess they didn't hear.
Comment 3 Xavier Neys (RETIRED) gentoo-dev 2010-01-08 17:04:12 UTC
*** Bug 300164 has been marked as a duplicate of this bug. ***
Comment 4 nm (RETIRED) gentoo-dev 2010-01-31 04:29:01 UTC
*** Bug 302894 has been marked as a duplicate of this bug. ***
Comment 5 Pariksheet Nanda 2010-03-29 10:35:09 UTC
Please also change all references to net-wireless/bluez-libs and net-wireless/bluez-utils to simply net-wireless/bluez to reflect the new package name in Portage.
Comment 6 nm (RETIRED) gentoo-dev 2010-03-29 15:47:46 UTC
(In reply to comment #5)
> Please also change all references to net-wireless/bluez-libs and
> net-wireless/bluez-utils to simply net-wireless/bluez to reflect the new
> package name in Portage.

It's not that simple. There's far more to do than just change package names -- if it were that easy we'd have done it months ago.

Please don't clutter the bug with useless suggestions.
Comment 7 Jan Holecek 2010-06-01 10:08:10 UTC
> It's not that simple. There's far more to do than just change package names --
> if it were that easy we'd have done it months ago.

<ping>Is there any progress?</ping> :) 

Anyway, while I do not understand the bluetooth stuff to judge the above, I do think the guide would become much more useful even as it is if there were a hint on how to pair devices without a fancy desktop. 

I had to strace hcid to discover the undocumented file /var/lib/bluetooth/nn:...:nn/pincodes to pair my phone with a new laptop. BTW. Is this file beyond all those (nasty, imho) passkey agents? As the file works under both latest Bluez 3.x and Bluez 4.x it should be safe to add it to the guide.

I really wasn't able to find this information anywhere on the web. Moreover, the file is not created by emerge.

P.S. The simple-agent did not work for me neither with bluez-utils 3.x nor with bluez 4.x.
Comment 8 Denilson Sá Maia 2010-06-01 18:41:35 UTC
(In reply to comment #7)
> I do think the guide would become much more useful even as it is if
> there were a hint on how to pair devices without a fancy desktop. 

That's exactly what I need most. Currently I have neither KDE nor Gnome, and I don't plan to install a full, huge KDE just for bluetooth pairing (and I don't even know if that would work). I'd install some packages (even Gnome packages) if I knew which ones were needed, but currently all the information about this is outdated.

Thus, right now I have no idea about how to pair a device. And, well, Bluetooth devices are useless without pairing. I'll later try to use that undocumented file, not sure if I will succeed.
Comment 9 Jan Holecek 2010-06-05 10:57:01 UTC
(In reply to comment #8)
> Thus, right now I have no idea about how to pair a device. And, well, Bluetooth
> devices are useless without pairing. I'll later try to use that undocumented
> file, not sure if I will succeed.

It's fairly simple once you know it reads the file.

Each bluetooth adapter of your host, i.e. each device you see with hciconfig gets a directory /var/lib/bluetooth/nn:nn:...:nn where the last part is the BD address of the device (as shown by hciconfig). This directory seems to keep device specific information part of which are pins for pairing in the pincodes file.

The file is line-oriented where each line is of a form
<BD address> <pin>
where <BD address> is the BD address of a remote device and <pin> is the PIN for pairing host bluetooth device to the remote one. For bluetooth headsets with fixed predefined PIN, you put the predefined PIN there. For pairing with a cell phone, for instance, you put the same PIN there that you type on the cell phone upon pairing. 

Hope this helps.
Comment 10 Denilson Sá Maia 2010-06-05 13:16:08 UTC
I also know that bluetooth devices I had paired long time ago are listed in "linkkeys" file. However, while using this pincodes file I could not make the device get listed in linkkeys, maybe just because I have no idea on how it works and how to do that.

Anyway, using picodes I could finally access my mobile phone again, without asking for confirmation every time! Thank you!
Comment 11 Samuli Suominen (RETIRED) gentoo-dev 2010-06-21 11:23:33 UTC
Can someone add a note in the bluetooth guide that it's obsolete and it doesn't apply anymore? It's really confusing for users at the moment.
Comment 12 nm (RETIRED) gentoo-dev 2010-06-21 19:02:19 UTC
(In reply to comment #11)
> Can someone add a note in the bluetooth guide that it's obsolete and it doesn't
> apply anymore? It's really confusing for users at the moment.

I guess I'll have to do that, even though I was trying to avoid it. No one's responded to my repeated help requests.
Comment 13 Petteri Räty (RETIRED) gentoo-dev 2010-06-24 18:37:33 UTC
(In reply to comment #12)
> 
> I guess I'll have to do that, even though I was trying to avoid it. No one's
> responded to my repeated help requests.
> 

I hope bluez evolves enough so that things just work and we don't need a dedicated guide. I haven't tried bluez recently to see what the current status is but the direction has been promising.
Comment 14 Robert J. Brown 2010-07-13 14:30:51 UTC
We *ALWAYS* need documentation.  Code without documentation is at the least non-useful, and potentially dangerous.  The documentation is actually more important than the code.  With good documentation, we can always write the code.  It is much harder to go the other way -- from reverse engineering the code to write the documentation.

(In reply to comment #13)
> (In reply to comment #12)
> > 
> > I guess I'll have to do that, even though I was trying to avoid it. No one's
> > responded to my repeated help requests.
> > 
> I hope bluez evolves enough so that things just work and we don't need a
> dedicated guide. I haven't tried bluez recently to see what the current status
> is but the direction has been promising.

Comment 15 Nuno Silva 2010-08-07 18:45:40 UTC
Created attachment 241795 [details, diff]
suggested changes to the guide

I'm attaching a patch (against revision 1.17) with some changes I made while setting BlueZ up on a computer. I hope some of those are useful.

- I didn't change the section on kernel configuration, because I skipped it (it seems I had already configured the kernel correctly);

- I'm not sure if I understand what consolekit is about - I don't use it - but I tried to describe it. Maybe someone who knows what it is can say if I got it correctly?

- I described how I pair it here with simple-agent, which Jan Holecek couldn't get to work. Jan, can you check if it works this way?

- I left sections with what's probably <bluez-4 stuff (like hcid.conf and the old pairing instructions) there. I don't know whether all of this should be deleted as, e.g., hcid can still be built.
Comment 16 Nuno Silva 2010-08-19 22:26:41 UTC
Created attachment 243633 [details, diff]
suggested changes to the guide (2nd version)

Here is another patch (against v1.17, includes the previous changes), with more changes. What I said about the previous patch still holds true.

So here is what I did:

- Changed "l2ping" invocation to send only 4 packets, so the user
doesn't have to guess how to stop it.

- Added a paragraph and some code on how to find out the channel
number for a bluetooth service. Also added the channel setting to the
example rfcomm.conf.

- Changed renamed ebuild names, like kdebluetooth, which seems to be
kbluetooth now, as reported by Peter Gazi.

- Added gnokii to the list of "Other Interesting
Applications". (Because I use it and I though other people might find
it interesting. If someone believes it shouldn't be here, just say!)

- Removed app-mobilephone/bemused, which is not on the tree anymore. (Thanks to a3li on #gentoo for pointing out CVS to know about dead packages.)

- Changed app-pda/multisync to app-pda/multisync-gui, which seems to
be multisync's replacement.

- Added a note saying USE="bluetooth" is required for obexftp, and
removed the one on USE="irmc" for multisync, because there is no such
USE flag in the ebuild.

- Removed the comment about explaining or not explaining the USE
flags, we expect users to know how to deal with them at this stage.

- Fixed some XML errors I made in the previous patch.
Comment 17 Nuno Silva 2010-10-24 20:08:28 UTC
Created attachment 251849 [details, diff]
suggested changes to the guide (3rd version)

Change the "bluez-gnome" example to "gnome-bluetooth", as the former will be removed from the tree on 24 Nov 2010 (gnome-bluetooth is the suggested alternative).
Comment 18 Nuno Silva 2010-11-02 22:40:04 UTC
Created attachment 252969 [details, diff]
suggested changes to the guide (4th version)

Some more changes:

- Removed instructions for the old daemons;

- Removed the old pairing method (which doesn't work with bluez 4)

- Renamed the section about the BlueZ configuration, because there's no configuration now (what was there were instructions for the old daemons), just information about the init.d script (and the example was updated to show the current output). I removed the text about DOWN devices because the solution was editing the old config files, and (at least here) devices are always UP when connected.


- A note: One of the commands used to check whether BlueZ is correctly configured is "hciconfig -a". It was removed, but I wonder if this is still useful. It probably is, but only with some updated instructions on how to change the device settings. (I can do some research, but I still don't know how to do that.)
Comment 19 Nuno Silva 2010-11-14 00:47:30 UTC
Created attachment 254259 [details, diff]
suggested changes to the guide (5th version)

A couple (small) changes:
- Mention in the installation section that USE=test-programs builds a pairing tool. It was already mentioned in the previous patch, but only in the pairing section. (This avoids having users finding out they have to rebuild bluez to get simple-agent.)

- Fix a grammar error.
Comment 20 James Broadhead 2011-05-22 11:29:06 UTC
The old guide is still live and "a work in progress" since 2009. Can these changes be merged sometime soon?
Comment 21 nm (RETIRED) gentoo-dev 2011-05-22 21:45:32 UTC
(In reply to comment #20)
> The old guide is still live and "a work in progress" since 2009. Can these
> changes be merged sometime soon?

No, it hasn't, only since mid-2010:

http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/doc/en/bluetooth-guide.xml?view=log

The work will be done when there's someone available. The GDP knows the guide needs to be updated. The most recent patch addresses some of the issues, but it doesn't look like we can apply it and still have a valid, working document.
Comment 22 hitachi 2011-08-31 11:09:42 UTC
(In reply to comment #19)
> Created attachment 254259 [details, diff]
> suggested changes to the guide (5th version)
> 
> A couple (small) changes:
> - Mention in the installation section that USE=test-programs builds a pairing
> tool. It was already mentioned in the previous patch, but only in the pairing
> section. (This avoids having users finding out they have to rebuild bluez to
> get simple-agent.)
> 
> - Fix a grammar error.

"sys-auth/pambase must have it enabled too." has no langer the useflag extras.
Comment 23 Nuno Silva 2012-03-17 19:52:00 UTC
(In reply to comment #22)
> "sys-auth/pambase must have it enabled too." has no langer the useflag
> extras.

That does not refer to USE=extras, but to USE=consolekit:

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

(Well, at least that's what I have in my local copy, I hope I didn't upload a diff against something else.)
Comment 24 Samuli Suominen (RETIRED) gentoo-dev 2012-03-17 20:01:51 UTC
(In reply to comment #23)
> (In reply to comment #22)
> > "sys-auth/pambase must have it enabled too." has no langer the useflag
> > extras.
> 
> That does not refer to USE=extras, but to USE=consolekit:
> 
>    <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>
> 
> (Well, at least that's what I have in my local copy, I hope I didn't upload
> a diff against something else.)

And it isn't even true. USE=consolekit in pambase is used only by pam_ck_connector.so (for startx). 
All of the display managers in Portage work fine without this USE flag set, because they have internal setup and they don't use the pam module.
I don't think the bluez guide should become a guide for using ConsoleKit, so these should just be removed.
Comment 25 Ezequiel Garcia 2012-05-03 20:14:35 UTC
I would like to help with this issue. One of the main reasons, if not *the*
reason I use gentoo is the vast amount of documentation available.

For that reason I think it is rather unfortunate that the guide is
so much outdated:

For start here is something I can quickly grasp:

1. hcid daemon is now dead, and so it's hcid.conf, this has
been replaced by bluetoothd.
2. bluetoothd now depends on dbus to be running.

IMHO, the current guide, altough of some utility, is rather confusing.

I could try to write something, as long as someone provides some
guidance.
Comment 26 Sven Vermeulen (RETIRED) gentoo-dev 2012-05-22 19:20:57 UTC
I'd recommend to focus the development of the guide on the wiki (there's https://wiki.gentoo.org/wiki/Bluetooth) and we can go from there...
Comment 27 Sven Vermeulen (RETIRED) gentoo-dev 2012-06-29 19:09:54 UTC
There you go, bluetooth now redirects to the wiki.