Differences between revisions 11 and 73 (spanning 62 versions)
Revision 11 as of 2008-02-10 13:53:08
Size: 3431
Editor: PeMac
Comment:
Revision 73 as of 2022-01-20 14:59:41
Size: 12896
Comment: make translation header easy to include in translations
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
We asume you have a Bluetooth adapter in your computer and a Bluetooth device (such as a mobile phone or PDA) and want to exchange data between that device and your Debian system.

Install Bluetooth support:

{{{
aptitude install bluetooth
}}}

Read `/usr/share/doc/bluez-utils/README.Debian.gz` to get some understanding of what's going on.

You need to be able to pair devices, for which you need a ''passkey-agent'', either this for GNOME:
{{{
aptitude install bluez-gnome
}}}

Or this for KDE:
{{{
aptitude install kdebluetooth
}}}
#language en
##For Translators - to have a constantly up to date translation header in you page, you can just add a line like the following (with the comment's character at the start of the line removed)
## <<Include(BluetoothUser, ,from="^##TAG:TRANSLATION-HEADER-START",to="^##TAG:TRANSLATION-HEADER-END")>>
##TAG:TRANSLATION-HEADER-START
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: [[BluetoothUser|English]] - [[fr/BluetoothUser|Français]] - [[it/BluetoothUser|Italiano]] - [[ja/BluetoothUser|日本語 (Nihongo)]]-~
##TAG:TRANSLATION-HEADER-END
----
'''Using Bluetooth in a Debian system'''

Bluetooth is a standard providing short-range wireless communication between devices, generally for linking an audio device, mouse, keyboard, phone, etc. to your PC. This article documents how to configure a Bluetooth adapter with Debian and pair it with a device. Bluetooth audio is separately documented on the [[BluetoothUser/a2dp]] page.

Information for developers, related to the internal packaging of Bluetooth within Debian, can be found on the [[Bluetooth]] page.

<<TableOfContents(3)>>

== Introduction ==

We assume you have a Bluetooth adapter in your computer and a Bluetooth device (such as a mobile phone or PDA).
This documents describes what you need to do to use Bluetooth to communicate with other Bluetooth devices.

The steps described below are required before you can use the services Bluetooth offers. Once you have setup Bluetooth, you can
for example
 * exchange data with devices, such as sending music or videos to/from your phone
 * use a mobile phone to give your computer mobile internet access
 * use Bluetooth peripherals with your computer, such as a Bluetooth wireless mouse

See the links below for details.

----

== Preparation ==

[[PackageManagement#Installing.2C_removing.2C_upgrading_software|Install]] Bluetooth support (package DebianPkg:bluetooth) :

Read `/usr/share/doc/bluez/README.Debian.gz` to get some understanding of what's going on.

Make sure the Bluetooth daemon is running. If it's not running, start it.

{{{
# service bluetooth status
bluetooth is running
}}}

{{{
# service bluetooth start
}}}

----

== Pairing ==

For security reasons, Bluetooth devices will only talk to each other if they have been "introduced" first (a bit like in real life :-)).
This is referred to as [[http://en.wikipedia.org/wiki/Bluetooth#Pairing|Pairing]].

Note that pairing is usually only required the first time two devices interact. Afterwards, they will remember each other, and no exchange of PINs is necessary.
This will however depend on the devices involved (on some devices this may be configurable).

To pair devices, you need a ''passkey-agent''. Options are:

=== Pairing using a GUI tool ===

[[PackageManagement#Installing.2C_removing.2C_upgrading_software|Install]] one of the following packages:

 * [[DebianPkg:gnome-bluetooth]] (for GNOME)
 * [[bluedevil]] (for KDE)
 * or [[DebianPkg:blueman]] (Gtk2)

Log out of your desktop session and log back in - this is required for the pairing pop-up in the next step to appear correctly.
Line 27: Line 76:
The device will then ask for a PIN, you can make one up.
(choose four digits, say ''2309'' )
The device will then ask for a PIN, you can make one up,
(choose four digits, say ''2309'' ).
Line 43: Line 92:
 /!\ further help requested

== Tips ==
A Broadcom bluetooth dongle may start off in hidden mode ([http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=384379 bug report here])

=== Pairing using CLI ===

If you do not want to or cannot use Gnome or KDE, you can also use
''bluetooth-agent'' or ''bluetoothctl'' for the pairing.


==== Using bluetooth-agent ====

Bluetooth-agent is a part of package DebianPkg:bluez, so it should already be available if Bluetooth has been configured on your system.

Just start bluetooth-agent (as root), giving an arbitrary PIN, such as 4835:
{{{
# bluetooth-agent 4835
}}}

Then, as described above, choose something like the "setup", "connect" or "Bluetooth" menu on the device to be paired,
and search for Bluetooth devices. Select your computer once found; the device should prompt you for a PIN. Now enter the PIN you gave to bluetooth-agent, and pairing is completed.

''Note:'' Instead of initiating the pairing process from the phone, you can also initiate it from the computer. Start ''bluetoogh-agent'' as explained above, then run a command that will try to connect to the phone, e.g.
{{{
rfcomm connect hci0 <phone address>
}}}

where <phone address> is your phone's bluetooth address, as shown by ''hcitool scan'' (note that this will only work if the ''phone'' is discoverable, though the computer need not be). This will force a connection from computer to phone, which should cause the phone to ask you to confirm the connection attempt by prompting for a PIN. Enter the pin you used with bluetooth-agent.

==== Using bluetoothctl ====

If bluetooth-agent is not available, try bluetoothctl:

Start the bluetoothctl interactive command. Enter "help" to get a list of available commands.

 * Turn the power to the controller on by entering "power on". It is off by default.
 * Enter "devices" to get the MAC Address of the device with which to pair.
 * Enter device discovery mode with "scan on" command if device is not yet on the list.
 * Turn the agent on with "agent on".
 * Enter "pair '''MAC Address'''" to do the pairing (tab completion works).
 * If using a device without a PIN, one may need to manually trust the device before it can reconnect successfully. Enter "trust '''MAC Address'''" to do so.
 * Finally, use "connect '''MAC address'''" to establish a connection.

=== Using a Bluetooth mouse ===

To use a Bluetooth mouse, first the support for Bluetooth must be installed on the system. See [[#Preparation|above]].

If your machine has a graphical environment with a GUI for pairing Bluetooth devices, chances are you can discover and pair your device easily from there. See above [[#Pairing_using_a_GUI_tool|how to pair using a GUI tool]].

If that does not succeed or you need to use the command line you can try running

{{{
hcitool scan
}}}

to get the bluetooth MAC address of the mouse.

An initial connection can be done with
{{{
hidd --connect <BTaddress>
}}}

where <BTaddress> is the MAC address obtained with the previous command.

To enable further automatic reconnections (e.g. on reboot), you need to run
{{{
/usr/share/doc/bluez/examples/test-device trusted <BTaddress>
}}}

to mark the device as trusted.

----

== Troubleshooting ==

=== General pairing issues ===

In order for the pairing to work as described above, your computer's bluetooth interfaces must be discoverable.
A bluetooth dongle may start off in hidden mode ([[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=384379|bug report here]])
Line 52: Line 173:
This should probably instead be added to /etc/init.d/bluetooth.
Or using ''hciconfig'':
{{{
# hciconfig hci0 piscan
}}}

Then ''hciconfig'' should show the flags ''ISCAN PSCAN'', indicating bluetooth is discoverable (i.e. can be scanned). After you finished pairing, it's best to make your computer hidden again:

{{{
# dbus-send --system --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter.SetMode string:off
}}}

Or using ''hciconfig'':
{{{
# hciconfig hci0 noscan
}}}
Line 61: Line 198:
Search for remote bluetooth devices Search for remote Bluetooth devices
Line 66: Line 203:

== KDE Issues ==
Restart the Bluetooth services
{{{
sudo service bluetooth restart
}}}

Force connection to device
{{{
sudo hidd --connect <BT_Address>
}}}


=== Helpful Configuration Files ===

/etc/default/bluetooth - Default HID bluez setting - enable for mice and keyboards
{{{
HID2HCI_ENABLED=1
}}}

/etc/bluetooth/hcid.conf - HCI bluez settings - configure static device information
{{{
device 00:1E:52:FB:68:55 {
    name "Apple Wireless Keyboard";
    auth enable;
    encrypt enable;}
}}}


=== KDE Issues ===
{{{#!wiki important
This section is very outdated and needs a full rewrite.

KDE now uses !BlueDevil instead of KDEBluetooth. The programs listed below no longer exist. Devices can be paired with !BlueDevil by running bluedevil-wizard in your terminal.
}}}
Line 84: Line 251:
# /etc/init.d/bluetooth restart # service bluetooth restart
Line 91: Line 258:
Some of this information was gleamed from [http://ubuntuforums.org/showthread.php?t=225703&highlight=dbus-send+-system+-dest%3Dorg.bluez+%2Forg%2Fbluez%2Fhci0+org.bluez.Adapter.SetMode+string%3Adiscoverable ubuntuformus]

=== HID : Human Interface Device ===
  * ["HOWTO/BluetoothMouse"] - Using a Bluetooth mouse
##Some of this information was gleaned from [[http://ubuntuforums.org/showthread.php?t=225703&highlight=dbus-send+-system+-dest%3Dorg.bluez+%2Forg%2Fbluez%2Fhci0+org.bluez.Adapter.SetMode+string%3Adiscoverable|ubuntuforums]]


=== GNOME topics ===

In DebianWheezy with GnomeShell the settings for Bluetooth can be found at
 * ''System Settings > Bluetooth'': Lists paired devices, allows sending of data
 * in [[Nautilus]] in the ''~/public'' folder: When opening this folder, you find a notification bar to define the sharing of data. This includes the sharing via WebDAV, but also via Bluetooth. Furthermore, one can enable receiving files via Bluetooth. These files are stored in ''~/downloads''.
 * in order to be able to receive files from a paired device enable the following options in "Personal File Sharing Preferences" (/usr/bin/gnome-file-share-properties):
   * Receive Files over Bluetooth / Receive files in Downloads folder over Bluetooth
   * Receive Files over Bluetooth / Notify about received files

{{attachment:Personal_File_Sharing_Preferences_Receive_Files_over_Bluetooth.png}}


=== Can't reconnect after sleep ===

You may notice that you can't automatically reconnect to a device after it goes to sleep. You would for example notice the following errors in your logs:

{{{
bluetoothd[487]: Authentication attempt without agent
bluetoothd[487]: Access denied: org.bluez.Error.Rejected
}}}

This could be because the device is not marked as "trusted". To fix this, try the following command in a `bluetoothctl` shell:

{{{
trust 00:1D:43:6D:03:26
}}}

... where `00:1D:43:6D:03:26` is the device identifier for the speaker.

You may also want to have Pulseaudio automatically connect to the newly discovered output, by adding this to `~/.config/pulse/default.pa`:

{{{
# automatically switch to newly-connected devices
load-module module-switch-on-connect
}}}

Note: this fix was found in the [[https://wiki.archlinux.org/index.php/Bluetooth_headset#Setting_up_auto_connection|Arch Linux wiki]].


=== Audio device issues (With pairing, quality, codec selection, etc.) ===

See the [[BluetoothUser/a2dp]] page for full documentation on Bluetooth audio in Debian.

----

== See also ==

 * UseYourCellPhoneAsModem
 * [[BluetoothPalmOSConnection]]
 * [[BluetoothUser/a2dp | A2DP]] - Using a high quality audio device (like bluetooth headphones)

----
Line 97: Line 315:
* Wikipedia:Bluethooth
----
CategoryHardware

 * [[WikiPedia:Bluetooth|Bluetooth- Wikipedia]]
 * [[http://www.bluez.org/|BlueZ]] - Official Linux Bluetooth protocol stack
## and [[http://wiki.bluez.org/|Wiki]]
## * [[http://wiki.bluez.org/wiki/HOWTO/Bonding|Bonding and pairing]]
 * [[http://wiki.maemo.org/Bluetooth_DUN|HowTo set up bluetooth IP networking using Dial-Up Networking and PPP]]

----

CategoryHardware CategoryModem CategorySound CategoryNetwork CategoryWireless

Translation(s): English - Français - Italiano - 日本語 (Nihongo)


Using Bluetooth in a Debian system

Bluetooth is a standard providing short-range wireless communication between devices, generally for linking an audio device, mouse, keyboard, phone, etc. to your PC. This article documents how to configure a Bluetooth adapter with Debian and pair it with a device. Bluetooth audio is separately documented on the BluetoothUser/a2dp page.

Information for developers, related to the internal packaging of Bluetooth within Debian, can be found on the Bluetooth page.

Introduction

We assume you have a Bluetooth adapter in your computer and a Bluetooth device (such as a mobile phone or PDA). This documents describes what you need to do to use Bluetooth to communicate with other Bluetooth devices.

The steps described below are required before you can use the services Bluetooth offers. Once you have setup Bluetooth, you can for example

  • exchange data with devices, such as sending music or videos to/from your phone
  • use a mobile phone to give your computer mobile internet access
  • use Bluetooth peripherals with your computer, such as a Bluetooth wireless mouse

See the links below for details.


Preparation

Install Bluetooth support (package bluetooth) :

Read /usr/share/doc/bluez/README.Debian.gz to get some understanding of what's going on.

Make sure the Bluetooth daemon is running. If it's not running, start it.

# service bluetooth status
bluetooth is running

# service bluetooth start


Pairing

For security reasons, Bluetooth devices will only talk to each other if they have been "introduced" first (a bit like in real life :-)). This is referred to as Pairing.

Note that pairing is usually only required the first time two devices interact. Afterwards, they will remember each other, and no exchange of PINs is necessary. This will however depend on the devices involved (on some devices this may be configurable).

To pair devices, you need a passkey-agent. Options are:

Pairing using a GUI tool

Install one of the following packages:

Log out of your desktop session and log back in - this is required for the pairing pop-up in the next step to appear correctly.

On your Bluetooth device you can now try to pair. On the device you need to choose something like the "setup", "connect" or "Bluetooth" menu and then search for Bluetooth devices. You should find your Debian system, called something like debian-0, where debian is the hostname of your Debian system. On your device, select the Debian system. The device will then ask for a PIN, you can make one up, (choose four digits, say 2309 ).

On your computer you will get a pop-up information balloon asking for the PIN, something like Pairing request from Phone (xx:xx:xx:xx:xx:xx) where Phone is the name of your phone and xx:xx:xx:xx:xx:xx is its MAC address.

Click on the information balloon.

Another window will pop-up. It asks for the PIN, enter the one you just made up. (e.g. 2309 ) and press [Enter].

Your phone sees that the PIN matches and shows it on its display.

Both devices are now paired.

Pairing using CLI

If you do not want to or cannot use Gnome or KDE, you can also use bluetooth-agent or bluetoothctl for the pairing.

Using bluetooth-agent

Bluetooth-agent is a part of package bluez, so it should already be available if Bluetooth has been configured on your system.

Just start bluetooth-agent (as root), giving an arbitrary PIN, such as 4835:

# bluetooth-agent 4835

Then, as described above, choose something like the "setup", "connect" or "Bluetooth" menu on the device to be paired, and search for Bluetooth devices. Select your computer once found; the device should prompt you for a PIN. Now enter the PIN you gave to bluetooth-agent, and pairing is completed.

Note: Instead of initiating the pairing process from the phone, you can also initiate it from the computer. Start bluetoogh-agent as explained above, then run a command that will try to connect to the phone, e.g.

rfcomm connect hci0 <phone address>

where <phone address> is your phone's bluetooth address, as shown by hcitool scan (note that this will only work if the phone is discoverable, though the computer need not be). This will force a connection from computer to phone, which should cause the phone to ask you to confirm the connection attempt by prompting for a PIN. Enter the pin you used with bluetooth-agent.

Using bluetoothctl

If bluetooth-agent is not available, try bluetoothctl:

Start the bluetoothctl interactive command. Enter "help" to get a list of available commands.

  • Turn the power to the controller on by entering "power on". It is off by default.
  • Enter "devices" to get the MAC Address of the device with which to pair.
  • Enter device discovery mode with "scan on" command if device is not yet on the list.
  • Turn the agent on with "agent on".
  • Enter "pair MAC Address" to do the pairing (tab completion works).

  • If using a device without a PIN, one may need to manually trust the device before it can reconnect successfully. Enter "trust MAC Address" to do so.

  • Finally, use "connect MAC address" to establish a connection.

Using a Bluetooth mouse

To use a Bluetooth mouse, first the support for Bluetooth must be installed on the system. See above.

If your machine has a graphical environment with a GUI for pairing Bluetooth devices, chances are you can discover and pair your device easily from there. See above how to pair using a GUI tool.

If that does not succeed or you need to use the command line you can try running

hcitool scan

to get the bluetooth MAC address of the mouse.

An initial connection can be done with

hidd --connect <BTaddress>

where <BTaddress> is the MAC address obtained with the previous command.

To enable further automatic reconnections (e.g. on reboot), you need to run

/usr/share/doc/bluez/examples/test-device trusted <BTaddress>

to mark the device as trusted.


Troubleshooting

General pairing issues

In order for the pairing to work as described above, your computer's bluetooth interfaces must be discoverable. A bluetooth dongle may start off in hidden mode (bug report here)

To fix this you can run:

# dbus-send --system --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter.SetMode string:discoverable

Or using hciconfig:

# hciconfig hci0 piscan

Then hciconfig should show the flags ISCAN PSCAN, indicating bluetooth is discoverable (i.e. can be scanned). After you finished pairing, it's best to make your computer hidden again:

# dbus-send --system --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter.SetMode string:off

Or using hciconfig:

# hciconfig hci0 noscan

Helpful Commands

Display your Bluetooth device (for proof that it was installed properly)

hcitool dev

Search for remote Bluetooth devices

hcitool scan

Restart the Bluetooth services

sudo service bluetooth restart

Force connection to device

sudo hidd --connect <BT_Address>

Helpful Configuration Files

/etc/default/bluetooth - Default HID bluez setting - enable for mice and keyboards

HID2HCI_ENABLED=1

/etc/bluetooth/hcid.conf - HCI bluez settings - configure static device information

device 00:1E:52:FB:68:55 {
    name "Apple Wireless Keyboard";
    auth enable;
    encrypt enable;}

KDE Issues

This section is very outdated and needs a full rewrite.

KDE now uses BlueDevil instead of KDEBluetooth. The programs listed below no longer exist. Devices can be paired with BlueDevil by running bluedevil-wizard in your terminal.

Since the PIN should be implemented on a user level, we need to make some changes to /etc/bluetooth/hcid.conf

comment out the line

passkey "2309";

and add the following line directly below it (Note: kdebluetooth includes the program kbluepin):

# passkey "2309";
pin_helper /usr/bin/bluez-pin;

KDE also expects a file /etc/bluetooth/link_key to be present.

# touch /etc/bluetooth/link_key
# chmod 644 /etc/bluetooth/link_key
# service bluetooth restart

In KDE, run kbluetoothd. Click on the Bluetooth icon in the system tray, this loads Konqueror with the Bluetooth:// URL. You should be able to see your device and do some simple file transfers by clicking on the device and choosing the proper transfer protocol.

Scanning for the PC from your device should bring up a window in KDE that asks you for a PIN. Now you can send files to your PC (KDE should bring up a program to handle this).

GNOME topics

In DebianWheezy with GnomeShell the settings for Bluetooth can be found at

  • System Settings > Bluetooth: Lists paired devices, allows sending of data

  • in Nautilus in the ~/public folder: When opening this folder, you find a notification bar to define the sharing of data. This includes the sharing via WebDAV, but also via Bluetooth. Furthermore, one can enable receiving files via Bluetooth. These files are stored in ~/downloads.

  • in order to be able to receive files from a paired device enable the following options in "Personal File Sharing Preferences" (/usr/bin/gnome-file-share-properties):
    • Receive Files over Bluetooth / Receive files in Downloads folder over Bluetooth
    • Receive Files over Bluetooth / Notify about received files

Personal_File_Sharing_Preferences_Receive_Files_over_Bluetooth.png

Can't reconnect after sleep

You may notice that you can't automatically reconnect to a device after it goes to sleep. You would for example notice the following errors in your logs:

bluetoothd[487]: Authentication attempt without agent
bluetoothd[487]: Access denied: org.bluez.Error.Rejected

This could be because the device is not marked as "trusted". To fix this, try the following command in a bluetoothctl shell:

trust 00:1D:43:6D:03:26

... where 00:1D:43:6D:03:26 is the device identifier for the speaker.

You may also want to have Pulseaudio automatically connect to the newly discovered output, by adding this to ~/.config/pulse/default.pa:

# automatically switch to newly-connected devices
load-module module-switch-on-connect

Note: this fix was found in the Arch Linux wiki.

Audio device issues (With pairing, quality, codec selection, etc.)

See the BluetoothUser/a2dp page for full documentation on Bluetooth audio in Debian.


See also



CategoryHardware CategoryModem CategorySound CategoryNetwork CategoryWireless