Bluetooth

Enabling Bluetooth support

To enable support for Bluetooth devices, add hardware.bluetooth.enable to /etc/nixos/configuration.nix:

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

Tip

In order to affect your system by your nix-language-specific changes you have to evaluate it, run (as root):

# nixos-rebuild switch

Pairing Bluetooth devices

This article or section needs expansion.

Reason: This article is a stub. (Discuss in Talk:Bluetooth#)
Please consult the pedia article metapage for guidelines on contributing.

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 install the blueman package. This provides a tray icon process (blueman-applet) and a GUI management application (blueman-manager).

Pairing devices from the command line

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]

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;

    # NixOS allows either a lightweight build (default) or full build of PulseAudio to be installed.
    # Only the full build has Bluetooth support, so it must be selected here.
    package = pkgs.pulseaudioFull;
  };

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

Tip

In order to affect your system by your nix-language-specific changes you have to evaluate it, run (as root):

# nixos-rebuild switch

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.

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.extraConfig = "
  [general]
  Enable=Source,Sink,Media,Socket
"
...
}

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:]._]+)"

Troubleshooting

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.

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

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