Bluetooth
Pairing audio devices and gamepads in archr-launcher, and what the hardware can do
You Will Probably Need a USB Adapter
Of the RK3326 boards ArchR supports, only the GameForce Chi declares a Bluetooth radio in its device tree, and the device tree itself carries a note saying that radio does not work for lack of firmware. The R36S and every other supported board have no Bluetooth chip at all.
So in practice, Bluetooth on ArchR means plugging in a USB Bluetooth adapter. The kernel builds the USB HCI driver plus the Broadcom, Intel, and Realtek helpers, so most common adapters are recognised without extra work.
When you plug in a USB Wi-Fi or Bluetooth adapter, the launcher tells you whether the image has its driver and firmware and whether the interface came up. Settings › Network › USB adapters lists the adapters connected now and the ones connected before, with the same verdict, and the chips whose drivers and firmware this image includes. Detecting the interface does not prove that pairing or audio work on a particular adapter. Check the chip before you buy: the name on the box does not tell it.
The Software Stack
ArchR uses BlueZ 5.83 with PipeWire as the audio backend. There is no bluealsa. PipeWire is built with SBC, AAC, aptX, and LDAC.
The HSP and HFP backends are disabled in the build, which has one consequence worth knowing before you buy anything: a Bluetooth headset works as a stereo output only. Its microphone will not appear as an input device.
Pairing in archr-launcher
Bluetooth is off by default (controllers.bluetooth.enabled=0).
Turn Bluetooth on
Open Settings › Network › Bluetooth and turn Bluetooth on. This starts bluetooth.service and the pairing agent. Y searches for nearby devices.
Put the device in pairing mode
Most gamepads have a small pairing button near the USB port; most headsets require holding the power button until the LED flashes rapidly.
Scan and pair
The Bluetooth screen lists Paired devices at the top followed by Available devices discovered nearby, with an icon indicating whether each device is a Controller or Audio device:
- Press Y to scan again (
Refresh). - Highlight an Available device and press A to pair and connect (
Pair). - Highlight a Paired device and press A to connect or disconnect it, or press X to forget it (
Forget, after a confirmation).
Route the audio
ArchR enables automatic switching when an audio device connects. If the output does not switch to your Bluetooth speaker or headset, open Settings › Sound and display › Audio output and select the Bluetooth sink there.
Where Pairings Are Stored
Paired devices live under /storage/.cache/bluetooth. ArchR archives that folder to /storage/roms/backups/bluetooth.tar every time you pair or remove a device, and unpacks the archive again every time the Bluetooth service starts. You can do both by hand over SSH:
archr-bluetooth save
archr-bluetooth restoreThe archr-bluetooth helper backs the launcher UI as well: archr-bluetooth list prints the paired devices, and trust, remove, connect, and disconnect each take a MAC address. Running it with no arguments prints the list of commands.
What Happens When You Launch a Game
runemu.sh stops the pairing agent before starting an emulator and starts it again when you return to archr-launcher. Devices that are already connected stay connected. You just cannot pair anything new while a game is running.
Syncthing, Tailscale, ZeroTier, and the simple HTTP server are also stopped during the game and started again afterwards, freeing wireless airtime if you are using a USB Wi-Fi dongle at the same time.
Controller Mappings
archr-launcher uses SDL2 (GameController and Joystick), with the controller mapping database in /storage/.config/SDL-GameControllerDB/gamecontrollerdb.txt. That database affects applications that use SDL controller mappings; not every emulator uses it (RetroArch, for example, uses udev). You can customize which physical button performs each action inside the launcher in Settings › Controls › Launcher (launcher.buttons).
/storage/.config/SDL-GameControllerDB/gamecontrollerdb.txt is a symlink into /usr/config, on the system root filesystem, which pacman updates. Do not edit that copy. To add a custom SDL mapping line for an unrecognized Bluetooth controller, remove the symlink, copy the file into its place, and edit the copy:
cd /storage/.config/SDL-GameControllerDB
rm gamecontrollerdb.txt
cp /usr/config/SDL-GameControllerDB/gamecontrollerdb.txt .Updates can still replace custom controller mappings, so keep a separate backup of your lines and add them again if needed. Resetting the configuration (Settings › Storage › Restore factory defaults) also restores the symlink.
When Audio Breaks
Turning a headset off without disconnecting it first sometimes leaves PipeWire holding a dead sink, resulting in silence until the audio services restart. PipeWire runs as a system service on ArchR:
systemctl restart pipewire pipewire-pulse wireplumberIf the USB adapter itself stops responding, toggle Bluetooth off and on in Settings › Network › Bluetooth, which is equivalent to:
archr-bluetooth disable
archr-bluetooth enable