Bluetooth

From NixOS Wiki
Jump to: navigation, search

Enabling Bluetooth Support

Presumptions

  • NixOS 24.11 (or newer)
  • PipeWire audio (PulseAudio has been superseded. Disregard any references to PulseAudio.)
  • Classic channels configuration

Please extrapolate for other NixOS versions, configurations, flakes, hardware, et cetera.

To enable support for Bluetooth devices, amend your system configuration as follows:

Breeze-text-x-plain.png
/etc/nixos/configuration.nix

hardware.bluetooth = {
  enable = true;
  powerOnBoot = true;
  settings = {
    General = {
      Experimental = true; # Show battery charge of Bluetooth devices
    };


Pairing Bluetooth Devices

Graphical User Interface (GUI)

In order to use Bluetooth devices, they must be paired with your NixOS machine. Heavier desktop environments will usually provide a Bluetooth management GUI which you can use to pair devices.

If your desktop environment does not provide such a GUI, you can additionally enable the blueman service, which provides blueman-applet and blueman-manager with the snippet below. 

services.blueman.enable = true;

Command Line Interface (CLI)

Alternatively, Bluetooth devices can be paired from the command line using bluetoothctl. 

$ bluetoothctl
[bluetooth] # power on
[bluetooth] # agent on
[bluetooth] # default-agent
[bluetooth] # scan on
...put device in pairing mode and wait [hex-address] to appear here...
[bluetooth] # pair [hex-address]
[bluetooth] # connect [hex-address]

Bluetooth devices automatically connect with bluetoothctl as well: 

$ bluetoothctl
[bluetooth] # trust [hex-address]

Troubleshooting

Audio Dropouts with Intel AX210 Wi-Fi/Bluetooth

Problem: Poor Bluetooth range and frequent audio dropouts

Situation: NixOS 25.05, desktop PC w/ Intel AX210 card

The following configuration improves the Bluetooth range and reduces audio dropouts at the expense of power savings. However, it does not 100% resolve the dropouts.

The problem is the Intel AX210 card. The problem is not caused by NixOS. NixOS' configuration makes it easy to work around.

Breeze-text-x-plain.png
/etc/nixos/configuration.nix

  # This is to fix frequent Bluetooth audio dropouts.
  boot.extraModprobeConfig = ''
    # Keep Bluetooth coexistence disabled for better BT audio stability
    options iwlwifi bt_coex_active=0

    # Enable software crypto (helps BT coexistence sometimes)
    options iwlwifi swcrypto=1

    # Disable power saving on Wi-Fi module to reduce radio state changes that might disrupt BT
    options iwlwifi power_save=0

    # Disable Unscheduled Automatic Power Save Delivery (U-APSD) to improve BT audio stability
    options iwlwifi uapsd_disable=1

    # Disable D0i3 power state to avoid problematic power transitions
    options iwlwifi d0i3_disable=1

    # Set power scheme for performance (iwlmvm)
    options iwlmvm power_scheme=1
  '';

  hardware.bluetooth = {
    enable = true;
    powerOnBoot = true;
    settings = {
      General = {
        ControllerMode = "bredr"; # Fix frequent Bluetooth audio dropouts
        Experimental = true;
        FastConnectable = true;
      };
      Policy = {
        AutoEnable = true;
      };
  };


USB device needs to be unplugged/re-plugged after suspend

Some USB device/host combinations don't play well with the suspend/resume cycle, and need to be unplugged and then re-plugged to work again.

It is possible to simulate a unplug/re-plug cycle using the /sys filesystem.

This gist provides a script and instructions to set-up a workaround for these devices.

Bluetooth fails to power on with Failed to set power on: org.bluez.Error.Blocked

If journalctl -eu bluetooth shows Failed to set mode: Blocked through rfkill (0x12), rfkill might be blocking it: 

$ rfkill
ID TYPE      DEVICE      SOFT      HARD
 1 wlan      phy0   unblocked unblocked
37 bluetooth hci0   blocked unblocked

Unblock it first: 

$ sudo rfkill unblock bluetooth

Cannot use bluetooth while it previously worked

Symptoms:

  • When using bluetoothctl, getting "No agent is registered".
  • When using blueman or anything using dbus to talk to bluez, getting dbus.exceptions.DBusException: org.freedesktop.DBus.Error.AccessDenied: Rejected send message"

This possibly can be fixed by restarting the display-manager session. The session management may have had an issue with registering your current session and doesn't allow you to control bluetooth. 

$ sudo systemctl restart display-manager.service

No audio when using headset in HSP/HFP mode

If the output of dmesg | grep Bluetooth shows a line similar to Bluetooth: hci0: BCM: Patch brcm/BCM-0a5c-6410.hcd not found then your machine uses a Broadcom chipset without the required firmware installed.

To fix this, add hardware.enableAllFirmware = true; to your /etc/nixos/configuration.nix then reboot.

See also

Legacy

Using Bluetooth headsets with PulseAudio

To allow Bluetooth audio devices to be used with PulseAudio, amend /etc/nixos/configuration.nix as follows: 

{
  hardware.pulseaudio.enable = true;
  hardware.bluetooth.enable = true;
}

You will need to restart PulseAudio; try systemctl --user daemon-reload; systemctl --user restart pulseaudio.

You can verify that PulseAudio has loaded the Bluetooth module by running pactl list | grep -i 'Name.*module.*blue'; Bluetooth modules should be present in the list.

Using Bluetooth headset buttons to control media player

Some bluetooth headsets have buttons for pause/play or to skip to the next track. To make these buttons usable with media players supporting the dbus-based MPRIS standard, one can use mpris-proxy that is part of bluez package. The following snippet can be used in Home Manager to start this program as a daemon: 

systemd.user.services.mpris-proxy = {
    description = "Mpris proxy";
    after = [ "network.target" "sound.target" ];
    wantedBy = [ "default.target" ];
    serviceConfig.ExecStart = "${pkgs.bluez}/bin/mpris-proxy";
};

Or, starting with Home Manager 21.05, enable the mpris-proxy service.

Warning: This is unnecessary and may cause issues if using PipeWire & Wireplumber, which is the default over PulseAudio on NixOS since 24.11

System-Wide PulseAudio

When you are running PulseAudio system-wide then you will need to add the following modules to your default.pa configuration: 

hardware.pulseaudio.configFile = pkgs.writeText "default.pa" ''
  load-module module-bluetooth-policy
  load-module module-bluetooth-discover
  ## module fails to load with 
  ##   module-bluez5-device.c: Failed to get device path from module arguments
  ##   module.c: Failed to load module "module-bluez5-device" (argument: ""): initialization failed.
  # load-module module-bluez5-device
  # load-module module-bluez5-discover
'';

Enabling extra codecs

While pulseaudio itself only has support for the SBC bluetooth codec there is out-of-tree support for AAC, APTX, APTX-HD and LDAC.

To enable extra codecs add the following to /etc/nixos/configuration.nix: 

{
...
  hardware.pulseaudio = {
    enable = true;
    package = pkgs.pulseaudioFull;
  };
...
}

Enabling A2DP Sink

Modern headsets will generally try to connect using the A2DP profile. To enable this for your bluetooth connection, add the following to /etc/nixos/configuration.nix 

{
  hardware.bluetooth.settings = {
    General = {
      Enable = "Source,Sink,Media,Socket";
    };
  };
}

This configuration may be unnecessary and does not work with bluez5 (Unknown key Enable for group General ).

Managing audio devices

pavucontrol can be used to reconfigure the device:

  • To enable A2DP, change the profile to “High Fidelity Playback (A2DP Sink)” on the “Configuration” tab.
  • To set the device as the default audio output, select “set as fallback” on the “Output Devices” tab.

Alternatively, the device can be configured via the command line:

  • To enable A2DP, run: 
    $ pacmd set-card-profile "$(pactl list cards short | egrep -o bluez_card[[:alnum:]._]+)" a2dp_sink
  • To set the device as the default audio output, run: 
    $ pacmd set-default-sink "$(pactl list sinks short | egrep -o bluez_sink[[:alnum:]._]+)"

You can also set pulseaudio to automatically switch audio to the connected bluetooth device when it connects, in order to do this add the following entry into the pulseaudio config 

{
...
hardware.pulseaudio.extraConfig = "
  load-module module-switch-on-connect
";
...
}

Note that you may need to clear the pulseaudio config located at ~/.config/pulse to get this to work. Also you may have to unset and then set the default audio device to the bluetooth device, see https://github.com/NixOS/nixpkgs/issues/86441 for more info

Troubleshooting

When connecting to an audio device: Failed to connect: org.bluez.Error.Failed

You need to use pulseaudioFull, see #Using Bluetooth headsets with PulseAudio.

See also

Retrieved from "https://nixos.wiki/index.php?title=Bluetooth&oldid=14124"