Bluetooth
Pairing audio devices and gamepads, and what the hardware can actually 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.
The 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
Bluetooth is off by default (controllers.bluetooth.enabled=0).
Turn Bluetooth on
ES → Controller & Bluetooth Settings → Enable Bluetooth. This starts bluetooth.service and the pairing agent, which takes a few seconds.
Put the device in pairing mode
This varies. Most gamepads have a small pairing button near the USB port, most headsets want the power button held until the LED flashes quickly.
Scan
Same menu → Pair Bluetooth pads automatically finds gamepads on its own. Pair a Bluetooth device manually shows everything it sees, including headsets, and lets you pick.
Route the audio
For a headset, go to ES → System Settings → Audio output and select it there. Audio does not move on its own.
Bluetooth device list in the same menu shows what is paired and lets you connect, disconnect or forget a device.
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 same command does everything the menu does. 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 kills the pairing agent before starting an emulator and starts it again when you come back. 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 stopped for the duration of the game, which also frees airtime if you are using a USB WiFi dongle at the same time.
Controller mappings
EmulationStation writes the mapping it learns from you to /storage/.config/emulationstation/es_input.cfg. That file is EmulationStation's own, and it is what the menus use.
Games and emulators use SDL instead, and SDL reads its mapping database from /storage/.config/SDL-GameControllerDB/gamecontrollerdb.txt. That path is a symlink into /usr/config, which lives on the read-only system partition, so you cannot append to it. To add your own line, delete the symlink, copy the real file into its place and edit the copy:
cd /storage/.config/SDL-GameControllerDB
rm gamecontrollerdb.txt
cp /usr/config/SDL-GameControllerDB/gamecontrollerdb.txt .From then on the file is yours and system updates no longer refresh it, so you lose new mappings added upstream. The symlink is only put back if you reset the configuration, because the script that creates it runs once, on first boot.
When audio breaks
Turning a headset off without disconnecting it first sometimes leaves PipeWire holding a dead sink, and you get silence until the services restart. PipeWire runs as a system service on ArchR, not a user one:
systemctl restart pipewire pipewire-pulse wireplumberIf the adapter itself stops responding, toggle Bluetooth off and on in the menu, which is the same as:
archr-bluetooth disable
archr-bluetooth enable