Alpine Linux - User contributions [en]

Bluetooth

2024-09-20T22:54:42Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded. HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace, when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

{{Cmd|1=UserspaceHID=false}}

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:52:41Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded. HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

{{Cmd|1=UserspaceHID=false}}

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:51:52Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded. HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:50:39Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace when userspace HID support is enabled.

HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:49:39Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:49:18Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:48:11Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:47:22Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device, when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:43:54Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device, when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:41:45Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device, when userspace HID support is enabled but the <code>uhid</code> kernel module is not loaded.

This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:36:29Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a device which requires the <code>uhid</code> kernel module when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace. This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:36:02Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a device which requires the <code>uhid</code> kernel module, when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace. This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:35:29Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a device which requires the <code>uhid</code> kernel module.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace. This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>:

<code>UserspaceHID=false</code>

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Bluetooth

2024-09-20T22:34:53Z

Rakslice: /* "org.bluez.Error.NotAvailable br-connection-profile-unavailable" */

{{Draft|work in progress}}

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites and Basic Installation ==

=== Prerequisites ===
{{todo|test bluetooth with [[mdev]]}}

{{Pkg|eudev}} should be installed and setup:

{{Cmd|# setup-devd udev}}

=== Basic Installation ===

Basic installation is as follows:

# Install {{Pkg|bluez}}
#* Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>
# Load the <code>btusb</code> kernel module
# Add user to the <code>lp</code> group
# Start and enable the Bluetooth service

{{Cmd|# apk add bluez
# apk add bluez-deprecated
# modprobe btusb
# adduser $USER lp
# rc-service bluetooth start
# rc-update add bluetooth default}}

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>:

{{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool:

{{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to restart the Bluetooth service before continuing.}}

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Pairing ==

=== Using <code>bluetoothctl</code> ===

Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# #trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

== Configuration ==

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section:

{{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level:

{{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue:

{{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module:

{{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a device which requires the <code>uhid</code> kernel module.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting:

{{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace. This includes keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>.

{{Cmd|UserspaceHID=false}}

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}:

{{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

== See Also ==

* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

Udhcpc

2021-12-09T13:22:30Z

Rakslice:

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example of <code>udhcpc_opts</code> in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

The default configuration of <code>udhcpc</code> may be overridden by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs for <code>udhcpc.conf</code> are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2021-12-09T13:21:48Z

Rakslice:

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

The default configuration of <code>udhcpc</code> may be overridden by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs for <code>udhcpc.conf</code> are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2021-12-09T13:20:43Z

Rakslice: editing for clarity

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

The default configuration of <code>udhcpc</code> may be overwritten by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2021-12-09T13:20:00Z

Rakslice:

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

Its default configuration may be overwritten by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2021-12-09T13:19:17Z

Rakslice: Added a note about udhcpc_opts

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

You can add arbitrary command line parameters to use for <code>udhcpc</code> in the <code>udhcpc_opts</code> setting in <code>/etc/network/interfaces</code>. See the example in [[Configure Networking#IPv4 DHCP Configuration|the main networking article]].

Its default configuration may be overwritten by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]

Udhcpc

2021-12-09T13:12:26Z

Rakslice: Cleaned up the formatting; clarified ADSL; some rewording for clarity

{{Expand|Please help us expand this article by contributing.}}

You may want to customize the behavior of the default DHCP client (<code>udhcpc</code> from busybox), which is called by <code>/sbin/ifup</code> by having "<code>dhcp</code>" in <code>/etc/network/interfaces</code>.

The default behavior is driven by the script <code>/usr/share/udhcpc/default.script</code>

Entries in <code>/etc/network/interfaces</code> for DHCP interfaces will drive the <code>udhcpc</code> command line. For example: 

<pre>auto eth0
iface eth0 inet dhcp
hostname myhostname</pre>

will set these parameters on the command line: 

<pre>-i eth0 -x hostname:myhostname</pre>

The hostname will send the DHCP option to the server to tell the server the name of this client.

The documentation for <code>udhcpc</code> can be found in [https://udhcp.busybox.net/README.udhcpc the busybox udhcpc readme file] 

Its default configuration may be overwritten by <code>/etc/udhcpc/udhcpc.conf</code>

Authorized key:value pairs are:

{| cellpadding="15" border="1" class="wikitable"
|-
! key
| default value
| possible values
|-
| NO_GATEWAY
| -
| <list of iface names>
|-
| IF_METRIC
| -
| <metric value>
|-
| IF_PEER_DNS
| yes
| <anything but yes>
|-
| RESOLV_CONF
| /etc/resolv.conf
| no ; NO ; -
|-
| NO_DNS
| -
| <list of iface names>
|}

Example <code>/etc/udhcpc/udhcpc.conf</code>:

RESOLV_CONF="no" # Prevents overwriting of /etc/resolv.conf

Custom scripts can be added as <code>/etc/udhcpc/pre-*</code> and <code>/etc/udhcpc/post-*</code> to be run before/after deconfig/renew/bound DHCP events. They must be set as '''executable''' by root, e.g. <code>chmod 744</code>

As an example, <code>/etc/udhcpc/post-bound/mtu</code> could contain, to change the interface MTU from the default (1500) to 1492, which is useful if [https://en.wikipedia.org/wiki/Maximum_transmission_unit on ADSL that uses PPPoE] (which uses 8 bytes for its own header):

r=$(/sbin/ip route | grep ^default | head -n 1)
# Needs iproute2 package, rather than busybox's "ip", to change mtu
/sbin/ip route replace $r mtu 1492

Hack alert:
I needed to restart my firewall (which replaces the <code>iptables</code> script from Alpine) when the client binds to a new IP, so I added the following line in the function <code>bound()</code>, right after '<code>resolvconf</code>':

/etc/init.d/iptables reload

The reload drops all firewall rules, re-acquires the Internal and external IPs, and re-writes the rules. I'm sure there is a better way.

[[Category:Networking]]
[[Category:Embedded Systems]]