--- 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 @@
BlueZ - The Bluetooth Stack
-Installing BlueZ
+What is BlueZ?
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
-bluez-libs and bluez-utils. Devices that need Broadcom firmware
+Linux Bluetooth stack. The ebuild that provides what we need is
+bluez. Devices that need Broadcom firmware
files or the like may need bluez-firmware.
+
+
+
+
+BlueZ permission control
+
+
+
+
+Before installing, it is a good idea to choose how to control users' ability to
+use bluetooth.
+
+
+
+There are two methods:
+
+
+
+
+ - "consolekit": identifies users who are sat in front of the computer,
+ and grants them access;
+ - "plugdev": allows members of the plugdev group to use bluetooth
+
+
+
+Although the permission policy can be tuned by editing the dbus permission rules
+for bluez, the consolekit USE flag must be set accordingly
+
+
+
+ - consolekit — means the consolekit method is used and requires
+ it to be enabled in some dependencies
+ - -consolekit — selects the plugdev method, and does not
+ require any consolekit support in dependencies.
+
+
+
+
+
+
+Installing bluez
+
+
+
+
+Now we can install the package, using the following command.
+
-
-# emerge net-wireless/bluez-libs net-wireless/bluez-utils
+
+# emerge net-wireless/bluez
+
+This ebuild might require certain USE flags to be enabled for other ebuilds:
+
+
+
+ - sys-fs/udev must have the extras flag enabled
+ - When bluez is built with consolekit enabled (see above),
+ sys-auth/pambase must have it enabled too.
+
+
+
+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 test-programs USE flag
+for bluez, which will install some testing utilities. But this is a
+limited set of tools, mainly intended for testing — you probably want to
+install an external bluetooth utilities package.
+
+
-BlueZ configuration and PIN pairing
+Start BlueZ
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).)
(Start up Bluetooth)
# /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
-
-This shows that the Bluetooth device has been recognised. As you might have
-noticed the device is DOWN. Let's configure it so that we can bring it
-up. The configuration file is at /etc/bluetooth/hcid.conf. The
-required changes to the config file are shown below. For additional details
-please refer to man hcid.conf.
-
-
-
-(Recommended changes to be made to the file are shown)
-
-# HCId options
-options {
- # Automatically initialize new devices
- autoinit yes;
-
-(Change security to "auto")
- # 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;
-
-(You only need a pin helper if you are using <=bluez-libs-2.x and <=bluez-utils-2.x)
-(Change pin_helper to use /etc/bluetooth/pin-helper)
- # PIN helper
- pin_helper /etc/bluetooth/pin-helper;
-}
-
-# Default settings for HCI devices
-device {
-(Set your device name here, you can call it anything you want)
- # 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;
-
-(Leave as is, if you don't know what exactly these do)
- # Authentication and Encryption (Security Mode 3)
- #auth enable;
- #encrypt enable;
-}
-
-
-
-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
+rc-update.
-
-(Replace 123456 with your desired pin number.)
-123456
+
+(We can also add it to the default runlevel.)
+# rc-update add bluetooth default
+ * bluetooth added to runlevel default
-
-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.
-
-
-
-Beginning with >=bluez-libs-3.x and >=bluez-utils-3.x, pin helpers
-have been replaced by passkey agents. There are a few different graphical
-passkey agents available to help manage your PIN, such as bluez-gnome and
-kdebluetooth. You can also use passkey-agent (found in
-bluez-utils) from the command line.
-
-
+
-Services configuration
+PIN Pairing
-Now that we have concluded with the configuration of BlueZ, it's time to restart
-the necessary services.
+In =bluez-4, there is no global PIN — when a device is paired you
+need some bluetooth utility to input a PIN. One such utility
+is simple-agent, part of bluez testing utilities (when built
+with USE="test-programs").
-
-# /etc/init.d/bluetooth restart
-(We can also add it to the default runlevel.)
-# rc-update add bluetooth default
- * bluetooth added to runlevel default
- * rc-update complete.
-
+
+Before pairing, you must know the bluetooth adapter id
+(run /usr/sbin/hciconfig, 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 hcid and sdpd 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 hcitool scan — the result is a
+list of devices, with their friendly names and MAC addresses.
-
-(Check to see if the services are running)
-# ps -ae | grep hcid
-26050 ? 00:00:00 hcid
-# ps -ae | grep sdpd
-26054 ? 00:00:00 sdpd
+
+ Find the MAC address:
+$ hcitool scan
+Scanning ...
+ 05:04:03:02:01:00 friendly-name
-# hciconfig -a
+ Find the adapter ID:
+$ /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)
+
+ And then pair the device
+$ simple-agent hci0 05:04:03:02:01:00
+RequestPinCode (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
+Enter PIN Code: 1234
+ (Now the remote device will ask you for this same PIN.)
+Release
+New device (/org/bluez/..../hci0/dev_05_04_03_02_01_00)
+
+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.
+
+
@@ -367,6 +369,13 @@
the hcitool command for the same.
+
+
+Some devices have a visibility setting, which if disabled will prevent
+your device from detecting them.
+
+
+
# hcitool dev
Devices:
@@ -391,7 +400,7 @@
-# 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 @@
(Enter the address of the device you want to connect to)
device 00:0A:0B:0C:0D:0E;
+ # RFCOMM channel for the connection
+ (Optional. If not specified, it will use channel 1)
+ channel 1;
+
}
@@ -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 sdptool,
+part of bluez.
+
+
+
+(The second parameter is the MAC address of the device you want to connect to)
+$ 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)
+(So if you want to connect to OBEX Object Push, use channel 4)
+ 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
+
+(Each service is described in lines like the ones above.)
+Service Name: Serial Port
+Service RecHandle: 0x10002
+Service Class ID List:
+...
+
+
+
Each time you call the rfcomm 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 @@
-KDE makes use of kdebluetooth and provides more utilities than its Gnome
+KDE makes use of kbluetooth and provides more utilities than its Gnome
counterpart as seen below.
@@ -596,8 +645,8 @@
-
-# emerge kdebluetooth
+
+# emerge kbluetooth
@@ -608,19 +657,23 @@
-
- app-mobilephone/obexftp: File transfer over OBEX for mobile phones
+ app-mobilephone/gnokii: 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 bluetooth USE flag set to
+ ensure that gnokii has Bluetooth support.
-
- app-mobilephone/bemused: Bemused is a system which allows you to
- control your music collection from your phone, using Bluetooth.
+ app-mobilephone/obexftp: File transfer over OBEX for mobile phones.
+ You will need the bluetooth USE flag set to ensure
+ that obexftp has Bluetooth support.
-
- app-pda/multisync: Multisync allows you to sync contacts, calendar
+ app-pda/multisync-gui: 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 irmc USE flag set to
- ensure that multisync has Bluetooth support.
+ Evolution e-mail client.
-
net-wireless/opd and net-wireless/ussp-push are command line