From 87dc149db87a8079c5f11b3c74eb04b40d17be87 Mon Sep 17 00:00:00 2001 From: KurdtNervanna <136639095+KurdtNervanna@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:51:24 -0500 Subject: [PATCH 1/3] Bluetooth devices: pad battery level, clearer message when a pad needs a PIN or cable rsos-bt list adds an optional 4th field (BlueZ Battery Percentage) for a connected device; the screen shows "connected, 85%". A pairing that fails with AuthenticationFailed or a PIN/passkey request now says the pad needs a PIN or a USB cable first. Tests, docs and rsos.pot updated. Co-Authored-By: Claude Sonnet 5.5 --- .../common/rootfs-overlay/usr/bin/rsos-bt | 18 ++++++++-- .../board/common/tests/bt-test.sh | 13 ++++--- docs/build.md | 12 ++++++- frontend/Makefile | 5 +++ frontend/po/rsos.pot | 14 ++++++++ frontend/src/ui/bt_ui.c | 35 ++++++++++++++++--- frontend/tests/fake-rsos-bt.sh | 22 ++++++++---- 7 files changed, 101 insertions(+), 18 deletions(-) diff --git a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt index bdf5968..47acfef 100755 --- a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt +++ b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt @@ -6,7 +6,12 @@ # rsos-bt list FILE write the devices BlueZ knows to FILE (replaced # atomically), one per line: "MACstatename", # state = connected, paired or found (seen by the -# scan, with a name: nameless ones are left out) +# scan, with a name: nameless ones are left out). +# An optional 4th field holds extras, a comma-separated +# list of key=value (readers ignore unknown keys): +# battery=85 (BlueZ "Battery Percentage", for a +# connected device that reports one), e.g. +# "MACconnectednamebattery=85" # rsos-bt scan on|off start discovery in the background (it stops by # itself after RSOS_BT_SCAN_S seconds, default 300) / # stop it @@ -51,6 +56,12 @@ has() { btctl info "$1" | grep -q "^[[:space:]]*$2: yes" } +# battery MAC: the battery percentage BlueZ reports ("Battery Percentage: +# 0x55 (85)"), nothing if the device does not report one +battery() { + btctl info "$1" | sed -n 's/^[[:space:]]*Battery Percentage:.*(\([0-9]\{1,3\}\)).*$/\1/p' | head -n 1 +} + # "Device MAC name" lines -> "MAC name" devices() { btctl devices "$@" | sed -n 's/^Device \([0-9A-Fa-f:]\{17\}\) *\(.*\)$/\1 \2/p' @@ -72,6 +83,8 @@ list() { name=$(echo "$name" | tr -d '\t') if echo "$conn" | grep -qix "$mac"; then st=connected + bat=$(battery "$mac") + extra=${bat:+battery=$bat} elif echo "$paired" | grep -qix "$mac"; then st=paired else @@ -82,7 +95,8 @@ list() { "$(echo "$mac" | tr 'a-f' 'A-F')" ] && continue st=found fi - printf '%s%s%s%s%s\n' "$mac" "$tab" "$st" "$tab" "$name" + printf '%s%s%s%s%s%s\n' "$mac" "$tab" "$st" "$tab" "$name" "${extra:+$tab$extra}" + extra= done > "$out.tmp" else : > "$out.tmp" diff --git a/buildroot-external/board/common/tests/bt-test.sh b/buildroot-external/board/common/tests/bt-test.sh index 16aa8e0..a55347a 100755 --- a/buildroot-external/board/common/tests/bt-test.sh +++ b/buildroot-external/board/common/tests/bt-test.sh @@ -3,7 +3,7 @@ # bluetoothctl that keeps its devices in a file: the list format (connected, # paired, found; nameless devices left out; colour codes stripped), pair = # pair + trust + connect with the Just Works agent, a pad that does not pair, -# connect / disconnect / forget, the scan started in the background and +# the battery of a connected pad (the battery= extra of the optional 4th field), connect / disconnect / forget, the scan started in the background and # stopped, a bad address, Bluetooth off. The real bluetoothctl and pads need # the device. set -u @@ -53,7 +53,8 @@ devices) info) awk -v m="\$2" '\$1 == m { print "Device " m " (public)"; print "\tPaired: " (\$2 ? "yes" : "no") - print "\tTrusted: " (\$3 ? "yes" : "no"); print "\tConnected: " (\$4 ? "yes" : "no") }' \$D + print "\tTrusted: " (\$3 ? "yes" : "no"); print "\tConnected: " (\$4 ? "yes" : "no") + if (\$4 && m == "E4:17:D8:00:00:01") print "\tBattery Percentage: 0x55 (85)" }' \$D ;; pair) [ "\$2" = A0:5A:5D:00:00:03 ] && { echo "Failed to pair: org.bluez.Error.AuthenticationFailed"; exit 1; } @@ -74,8 +75,8 @@ bt() { $SH "$BT" "$@"; } echo "rsos-bt ($SH)" check "list" bt list "$W/list" -check "list: connected, found, found; the nameless one and colour codes left out" \ - [ "$(cat "$W/list")" = "E4:17:D8:00:00:01${T}connected${T}8BitDo SN30 Pro +check "list: connected (with its battery), found, found; the nameless one and colour codes left out" \ + [ "$(cat "$W/list")" = "E4:17:D8:00:00:01${T}connected${T}8BitDo SN30 Pro${T}battery=85 F0:13:C3:00:00:02${T}found${T}Stadia5RHM-1a2b A0:5A:5D:00:00:03${T}found${T}Wireless Controller" ] check "scan on starts a background bluetoothctl" bt scan on @@ -90,13 +91,15 @@ check " ... Just Works agent, then trust and connect" \ grep -q 'bluetoothctl trust F0:13:C3:00:00:02' $LOG && grep -q 'connect F0:13:C3:00:00:02' $LOG" bt list "$W/list" check " ... now connected" grep -q "^F0:13:C3:00:00:02${T}connected${T}" "$W/list" +check " ... no extras field for a pad that does not report one" \ + grep -qx "F0:13:C3:00:00:02${T}connected${T}Stadia5RHM-1a2b" "$W/list" out=$(bt pair A0:5A:5D:00:00:03) rc=$? check "a pad that does not pair: exit 1, the reason" \ [ "$rc:$out" = "1:rsos-bt: pairing failed: Failed to pair: org.bluez.Error.AuthenticationFailed" ] check "disconnect" bt disconnect E4:17:D8:00:00:01 bt list "$W/list" -check " ... paired, not connected" grep -q "^E4:17:D8:00:00:01${T}paired${T}8BitDo SN30 Pro$" "$W/list" +check " ... paired, not connected, no battery" grep -q "^E4:17:D8:00:00:01${T}paired${T}8BitDo SN30 Pro$" "$W/list" check "connect" bt connect E4:17:D8:00:00:01 check "forget" bt forget E4:17:D8:00:00:01 bt list "$W/list" diff --git a/docs/build.md b/docs/build.md index b024999..238dc1b 100644 --- a/docs/build.md +++ b/docs/build.md @@ -779,11 +779,21 @@ helper (it never blocks the menu), which drives `bluetoothctl` non-interactively: ``` -rsos-bt list FILE # MACconnected|paired|foundname +rsos-bt list FILE # MACconnected|paired|foundname[extras] rsos-bt scan on|off # background discovery while the screen is open rsos-bt pair|connect|disconnect|forget MAC ``` +A connected pad that reports its battery through BlueZ (`Battery Percentage` +in `bluetoothctl info`) gets the extra `battery=85` and the list shows +"connected, 85%". The optional 4th field is a comma-separated list of +`key=value` extras (`MACconnectednamebattery=85`); the frontend +ignores keys it does not know, so more can be added; no extras, no 4th field. +If pairing without a PIN fails +(`AuthenticationFailed`, or a PIN / passkey request: e.g. a PlayStation 3 pad, +which must be paired through a USB cable first) the player gets a message that +says so instead of the generic "put it in pairing mode". + Paired devices are **trusted**, so they come back by themselves: bluetoothd puts bonded classic devices on the controller's accept list (page scan for them only: a classic HID pad pages the console when it is switched on) and diff --git a/frontend/Makefile b/frontend/Makefile index ec0423a..e0d0534 100644 --- a/frontend/Makefile +++ b/frontend/Makefile @@ -359,6 +359,11 @@ check-ui: $(UIPREVIEW) --keys "start down down a down down down down down a sleep:500 wait:1600 sleep:300 down down \ expect:|Wireless_Controller a sleep:1500 expect:dialog:Could_not_pair a wait:300 \ expect:menu:Bluetooth_devices|Wireless_Controller b sleep:500" + rm -rf $(UI_CHECK_DIR)/bt + FAKE_BT_DIR=$(UI_CHECK_DIR)/bt FAKE_BT_FAIL=pin $(UIPREVIEW) --root $(UI_CHECK_DIR) --quiet \ + --bt-helper $(CURDIR)/tests/fake-rsos-bt.sh \ + --keys "start down down a down down down down down a sleep:500 wait:1600 sleep:300 down down \ + expect:|Wireless_Controller a sleep:1500 expect:dialog:This_controller_could_not_pair_without_a_PIN" rm -rf $(UI_CHECK_DIR)/bt $(UI_CHECK_DIR)/data/rsos/settings.ini @echo "check-ui: game options act on their game after Favorite re-sorts the list (review F-H4)" rm -rf $(UI_CHECK_DIR)-games && mkdir -p $(UI_CHECK_DIR)-games/data/roms/nes \ diff --git a/frontend/po/rsos.pot b/frontend/po/rsos.pot index 99f0d5f..47a7198 100644 --- a/frontend/po/rsos.pot +++ b/frontend/po/rsos.pot @@ -839,6 +839,13 @@ msgstr "" msgid "please wait..." msgstr "" +#. TRANSLATORS: Bluetooth devices: connected pad and its +#. battery level; %d is a percentage (keep %%) +#: src/ui/bt_ui.c:164 +#, c-format +msgid "connected, %d%%" +msgstr "" + #: src/ui/bt_ui.c:145 msgid "connected" msgstr "" @@ -895,6 +902,13 @@ msgstr "" msgid "%s connected" msgstr "" +#. TRANSLATORS: message; pairing without a PIN failed (some pads, +#. e.g. a PlayStation 3 pad, must be paired with a USB cable or +#. need a PIN first) +#: src/ui/bt_ui.c:333 +msgid "This controller could not pair without a PIN. Some controllers must be paired with a USB cable first." +msgstr "" + #: src/ui/bt_ui.c:308 msgid "Could not pair the controller. Put it in pairing mode and try again." msgstr "" diff --git a/frontend/src/ui/bt_ui.c b/frontend/src/ui/bt_ui.c index 1703837..fb2c83c 100644 --- a/frontend/src/ui/bt_ui.c +++ b/frontend/src/ui/bt_ui.c @@ -9,8 +9,9 @@ * menu: * rsos-bt scan on|off when the screen opens (and every minute while * it is open) / closes - * rsos-bt list FILE every BT_LIST_MS: "MAC\tstate\tname" lines, - * state connected|paired|found + * rsos-bt list FILE every BT_LIST_MS: "MAC\tstate\tname[\tkey=value,...]" + * lines, state connected|paired|found; the extras + * (unknown keys are ignored): battery= * rsos-bt pair|connect|disconnect|forget MAC * Paired devices are trusted, so they reconnect by themselves when * Bluetooth comes on and when the pad is switched on (bluetoothd). @@ -34,6 +35,7 @@ enum { ACT_NONE = 0, ACT_PAIR, ACT_CONNECT, ACT_DISCONNECT, ACT_FORGET }; struct btdev { char mac[18]; bool paired, connected; + int battery; /* percent, -1 = unknown */ char name[80]; }; @@ -71,10 +73,20 @@ static void scan(struct ui *ui, bool on) B.next_scan = ui->now + BT_SCAN_MS; } -/* the line "MAC\tstate\tname" -> d */ +/* the extras "key=value,key=value": the keys known here, others are ignored */ +static void parse_extras(char *x, struct btdev *d) +{ + char *save = NULL; + + for (char *kv = strtok_r(x, ",", &save); kv; kv = strtok_r(NULL, ",", &save)) + if (!strncmp(kv, "battery=", 8) && kv[8] >= '0' && kv[8] <= '9' && atoi(kv + 8) <= 100) + d->battery = atoi(kv + 8); +} + +/* the line "MAC\tstate\tname[\tkey=value,...]" -> d */ static bool parse_line(char *l, struct btdev *d) { - char *st = strchr(l, '\t'), *name; + char *st = strchr(l, '\t'), *name, *x = NULL; if (!st || st - l != 17) return false; @@ -83,11 +95,16 @@ static bool parse_line(char *l, struct btdev *d) if (name) *name++ = 0; memset(d, 0, sizeof(*d)); + d->battery = -1; + if (name && (x = strchr(name, '\t'))) + *x++ = 0; strlcpy_(d->mac, l, sizeof(d->mac)); d->connected = !strcmp(st, "connected"); d->paired = d->connected || !strcmp(st, "paired"); if (!d->paired && strcmp(st, "found")) return false; + if (x) + parse_extras(x, d); strlcpy_(d->name, name && *name ? name : l, sizeof(d->name)); return true; } @@ -141,6 +158,10 @@ static void items(struct ui *ui, struct menu *m) strlcpy_(it->value, B.act == ACT_PAIR ? _("pairing...") : B.act == ACT_CONNECT ? _("connecting...") : _("please wait..."), sizeof(it->value)); + else if (d->connected && d->battery >= 0) + /* TRANSLATORS: Bluetooth devices: connected pad and its + * battery level; %d is a percentage (keep %%) */ + snprintf(it->value, sizeof(it->value), _("connected, %d%%"), d->battery); else if (d->connected) strlcpy_(it->value, _("connected"), sizeof(it->value)); } @@ -304,6 +325,12 @@ static void act_done(struct ui *ui, const struct hw_job_result *r) if (r->status == 0) /* TRANSLATORS: toast; %s is the controller's name */ ui_toastf(ui, _("%s connected"), B.act_name); + else if (act == ACT_PAIR && (strstr(r->out, "Authentication") || strstr(r->out, "PIN") || + strstr(r->out, "asskey"))) + /* TRANSLATORS: message; pairing without a PIN failed (some pads, + * e.g. a PlayStation 3 pad, must be paired with a USB cable or + * need a PIN first) */ + message_open(ui, _("This controller could not pair without a PIN. Some controllers must be paired with a USB cable first.")); else if (act == ACT_PAIR) message_open(ui, _("Could not pair the controller. Put it in pairing mode and try again.")); else diff --git a/frontend/tests/fake-rsos-bt.sh b/frontend/tests/fake-rsos-bt.sh index 7b61550..aaef932 100755 --- a/frontend/tests/fake-rsos-bt.sh +++ b/frontend/tests/fake-rsos-bt.sh @@ -1,10 +1,12 @@ #!/bin/sh # fake-rsos-bt.sh: a stand-in for rsos-bt (buildroot-external/board/common/ # rootfs-overlay/usr/bin/rsos-bt) for the preview tool (--bt-helper): the -# devices live in $FAKE_BT_DIR/devices ("MACstatename", the format -# of "rsos-bt list"), created with one paired and two found devices; every +# devices live in $FAKE_BT_DIR/devices ("MACstatename[key=value,...]", the +# format of "rsos-bt list"), created with one paired and two found devices; every # call is logged to $FAKE_BT_DIR/calls.log. FAKE_BT_FAIL=pair makes pairing -# fail. +# fail, FAKE_BT_FAIL=pin makes it fail as a pad that needs a PIN or a cable +# does. A device that gets connected reports battery=70 and a key the frontend +# does not know (it must ignore it); the Wireless Controller has an unknown key too. D=${FAKE_BT_DIR:?FAKE_BT_DIR is not set} mkdir -p "$D" DEV=$D/devices @@ -14,12 +16,16 @@ if [ ! -f "$DEV" ]; then "E4:17:D8:00:00:01" paired "8BitDo SN30 Pro" \ "F0:13:C3:00:00:02" found "Stadia5RHM-1a2b" \ "A0:5A:5D:00:00:03" found "Wireless Controller" > "$DEV" + sed "/^A0:5A:5D:00:00:03/s/\$/${T}future=1/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" fi echo "$*" >> "$D/calls.log" -# set MAC STATE: change the state of a device +# set MAC STATE: change the state of a device (connected: with a battery) set_state() { - sed "s/^${1}${T}[a-z]*${T}/${1}${T}${2}${T}/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + sed "/^${1}${T}/s/${T}[a-z]\{1,\}=[^${T}]*\$//; s/^${1}${T}[a-z]*${T}/${1}${T}${2}${T}/" "$DEV" > "$DEV.tmp" && + mv "$DEV.tmp" "$DEV" + [ "$2" = connected ] && sed "/^${1}${T}/s/\$/${T}battery=70,future=x/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + return 0 } case "$1" in @@ -30,7 +36,11 @@ scan) ;; pair) sleep 1 if [ "${FAKE_BT_FAIL:-}" = pair ]; then - echo "rsos-bt: pairing failed: org.bluez.Error.AuthenticationFailed" + echo "rsos-bt: pairing failed: org.bluez.Error.Failed" + exit 1 + fi + if [ "${FAKE_BT_FAIL:-}" = pin ]; then + echo "rsos-bt: pairing failed: Failed to pair: org.bluez.Error.AuthenticationFailed" exit 1 fi set_state "$2" connected From ab6276d31f731c8cc3dccab3e357b3fbb6ff53d4 Mon Sep 17 00:00:00 2001 From: KurdtNervanna <136639095+KurdtNervanna@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:50:02 -0500 Subject: [PATCH 2/3] input: a pointer is no gamepad; document Bluetooth keyboards and mice A trackpad, tablet or a pad's touchpad node (absolute X, 4+ buttons, no KEY_A) was taken for an unconfigured gamepad and got a player port. Move the node classification into classify_dev() and exclude pointers from the generic heuristic (explicit pad bits still win). Test: make check-input (classify). docs/input-design.md: what works for USB/Bluetooth keyboards and mice today and what is not built (core keyboard/mouse forwarding, menu cursor). Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- docs/input-design.md | 19 +++++++++++++++++ frontend/src/input/input.c | 33 ++++++++++++++++++++++++----- frontend/tests/test_input.c | 42 +++++++++++++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 488c35b..6060678 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ layer cake, and every setting lives in one menu. - RetroPie hotkeys: **Select+Start** exit, **Select+R/L** save/load state, **Select+Left/Right** state slot, **Select+X** in-game menu, **Select+B** reset. - **Select+R2** fast-forward, **Select+L2** screenshot, **Select+Y** game switcher (jump between your recent games, each resumed where you left it). - Remaps per system and per game, including the RetroStone2's optional 6-button Mega Drive layout. -- **Keyboard** (menus): arrows move, **Enter** = A (open, confirm), **Esc** or **Backspace** = B (back), **Tab** = Select, **Space** = Start, X / Y, **Page Up / Page Down** = L / R, **Home / End** = L2 / R2. A keyboard is not a game controller (games need a pad or the built-in buttons), but in a game **Esc** opens the in-game menu (with Exit) and **Tab** is the hotkey button (**Tab+Space** exits). +- **Keyboard** (menus): arrows move, **Enter** = A (open, confirm), **Esc** or **Backspace** = B (back), **Tab** = Select, **Space** = Start, X / Y, **Page Up / Page Down** = L / R, **Home / End** = L2 / R2. A keyboard is not a game controller (games need a pad or the built-in buttons), but in a game **Esc** opens the in-game menu (with Exit) and **Tab** is the hotkey button (**Tab+Space** exits). A Bluetooth keyboard works the same once paired (Settings > Network > Bluetooth devices); mice are not used yet. **Finding games** - **Letter jump** and **search** (in one list or across all games). diff --git a/docs/input-design.md b/docs/input-design.md index e3c0db1..a774d1f 100644 --- a/docs/input-design.md +++ b/docs/input-design.md @@ -100,6 +100,25 @@ Additional handling: a keyboard can still leave it: **Esc opens the in-game menu** (in the menus Esc stays B), and **Tab works as the hotkey button** of section 4 (Tab+Space exits, Tab+X menu, Tab+Page Down / Page Up save / load a state...), from any keyboard whatever the player order. Test: `make check-input` (`keyboard_in_game`). +- **Keyboards and mice (USB and Bluetooth)**: a Bluetooth keyboard or mouse reaches the frontend as an ordinary + `/dev/input/event*` node (BlueZ HID over `uhid`, docs/build.md "Networking"), so the rules are the same for USB and + Bluetooth. `classify_dev()` in `src/input/input.c` sorts a node by its capability bits: a pad (`BTN_GAMEPAD`, + `BTN_JOYSTICK`, `BTN_TRIGGER_HAPPY`, or an absolute X with 4+ buttons), a keyboard (`KEY_ENTER` and `KEY_A`) or + nothing. What works today: + - **Keyboard, menus and the in-game hotkeys**: yes, as above. A keyboard's media-key or system-control nodes are + separate devices and are ignored (a system "power" key does what the power button does). + - **Mouse, trackpad, tablet** (and a pad's touchpad node): **ignored**. There is no cursor in the menus, and the host + does not offer `RETRO_DEVICE_MOUSE` / `POINTER` / `KEYBOARD` to cores (`GET_INPUT_DEVICE_CAPABILITIES` is + joypad + analog, `SET_KEYBOARD_CALLBACK` is refused, `input_state_cb` returns 0 for everything else), so DOSBox + Pure and ScummVM see no mouse and no physical keyboard from any USB or Bluetooth device; they use their on-screen + keyboard and move their cursor with the pad. A pointer node is no longer taken for an unconfigured gamepad + (it used to when it had an absolute X and 4+ buttons). Test: `make check-input` (`classify`). + - **Pairing**: Settings > Network > Bluetooth devices pairs with Just Works (no PIN). A keyboard or mouse that + needs a PIN or a passkey typed on it cannot be paired from the console (no agent). The list does not say what + kind of device an entry is. TODO(hw): confirm with a real keyboard and mouse. + - **Not built (bigger)**: forwarding keyboard (`RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK`, `RETRO_DEVICE_KEYBOARD`) + and mouse (`RETRO_DEVICE_MOUSE`/`POINTER`, relative axes + buttons per port) to cores, a menu cursor, and a + device-type label in the Bluetooth list (`bluetoothctl info` `Icon:`). - **Rumble** (done, batch 2): the libretro rumble interface (`retro_set_rumble_state`) is forwarded to an evdev FF_RUMBLE effect on pads that support it (`input_rumble()` in `src/input/input.c`). The pad's node is opened read-write (read-only fallback: no rumble); `EV_FF` + `FF_RUMBLE` in its capabilities marks it. One effect per pad, diff --git a/frontend/src/input/input.c b/frontend/src/input/input.c index 1707448..ac1df22 100644 --- a/frontend/src/input/input.c +++ b/frontend/src/input/input.c @@ -1595,6 +1595,31 @@ static bool name_is_builtin_stick(const struct input *in, const char *name) return s && *s && !strcmp(name, s); } +/* + * What an unknown evdev node is, from its capability bits (no ioctl, so the + * host tests can feed it). USB and Bluetooth (uhid) devices look the same. + * A pointer (mouse, trackpad, tablet, a pad's touchpad node) is no gamepad + * even with 4+ keys and an absolute X: the generic heuristic would hand it a + * player port. Pointers are not used by this layer yet + * (docs/input-design.md, "Keyboards and mice"). + */ +enum dev_kind { DK_OTHER, DK_PAD, DK_KEYBOARD }; + +static enum dev_kind classify_dev(const unsigned long *keybits, const unsigned long *absbits, int nkeys) +{ + bool pointer = TEST_BIT(BTN_LEFT, keybits) || TEST_BIT(BTN_TOUCH, keybits) || + TEST_BIT(BTN_TOOL_FINGER, keybits) || TEST_BIT(BTN_TOOL_PEN, keybits); + + if (TEST_BIT(BTN_GAMEPAD, keybits) || TEST_BIT(BTN_JOYSTICK, keybits) || + TEST_BIT(BTN_TRIGGER_HAPPY1, keybits)) + return DK_PAD; + if (TEST_BIT(KEY_ENTER, keybits) && TEST_BIT(KEY_A, keybits)) + return DK_KEYBOARD; + if (TEST_BIT(ABS_X, absbits) && nkeys >= 4 && !pointer) + return DK_PAD; + return DK_OTHER; +} + static int dev_open(struct input *in, const char *node) { char path[64]; @@ -1650,13 +1675,11 @@ static int dev_open(struct input *in, const char *node) if (d->builtin_stick) d->builtin = true; if (!d->builtin) { - bool pad = TEST_BIT(BTN_GAMEPAD, keybits) || TEST_BIT(BTN_JOYSTICK, keybits) || - TEST_BIT(BTN_TRIGGER_HAPPY1, keybits) || - (TEST_BIT(ABS_X, absbits) && nkeys >= 4 && !TEST_BIT(KEY_A, keybits)); + enum dev_kind kind = classify_dev(keybits, absbits, nkeys); - if (pad) { + if (kind == DK_PAD) { /* external gamepad */ - } else if (TEST_BIT(KEY_ENTER, keybits) && TEST_BIT(KEY_A, keybits)) { + } else if (kind == DK_KEYBOARD) { d->keyboard = true; } else if (TEST_BIT(KEY_POWER, keybits) && nkeys <= 4 && in->cfg.handle_power_key) { d->power_only = true; diff --git a/frontend/tests/test_input.c b/frontend/tests/test_input.c index 1bd66b2..91fc7d3 100644 --- a/frontend/tests/test_input.c +++ b/frontend/tests/test_input.c @@ -304,6 +304,47 @@ static void keyboard_in_game(void) rig_close(&r); } +/* ------------------------------ Bluetooth/USB keyboards and mice (classify) */ +static void set_keys(unsigned long *bits, const int *codes, int n) +{ + for (int i = 0; i < n; i++) + bits[codes[i] / BITS_PER_LONG_] |= 1ul << (codes[i] % BITS_PER_LONG_); +} + +static enum dev_kind kind_of(const int *keys, int nk, const int *abs, int na) +{ + unsigned long kb[NBITS(KEY_CNT)] = { 0 }, ab[NBITS(ABS_CNT)] = { 0 }; + + set_keys(kb, keys, nk); + set_keys(ab, abs, na); + return classify_dev(kb, ab, nk); +} + +static void classify(void) +{ + static const int kbd[] = { KEY_ENTER, KEY_A, KEY_ESC, KEY_TAB, KEY_SPACE }; + static const int mouse[] = { BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_SIDE, BTN_EXTRA }; + static const int trackpad[] = { BTN_LEFT, BTN_TOUCH, BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP }; + static const int media[] = { KEY_VOLUMEUP, KEY_VOLUMEDOWN, KEY_MUTE, KEY_PLAYPAUSE }; + static const int pad[] = { BTN_SOUTH, BTN_EAST, BTN_NORTH, BTN_WEST }; + static const int cheap[] = { BTN_TRIGGER, BTN_THUMB, BTN_TOP, BTN_PINKIE }; + static const int absxy[] = { ABS_X, ABS_Y }; + + puts("input: what a Bluetooth/USB keyboard, mouse or trackpad is"); + CHECK(kind_of(kbd, 5, NULL, 0) == DK_KEYBOARD, "a keyboard is a keyboard"); + CHECK(kind_of(mouse, 5, NULL, 0) == DK_OTHER, "a relative mouse is ignored"); + CHECK(kind_of(trackpad, 4, absxy, 2) == DK_OTHER, "an absolute trackpad is no gamepad"); + CHECK(kind_of(media, 4, NULL, 0) == DK_OTHER, "a keyboard's media-key node is ignored"); + CHECK(kind_of(pad, 4, absxy, 2) == DK_PAD, "a gamepad is a pad"); + CHECK(kind_of(cheap, 4, absxy, 2) == DK_PAD, "a joystick-style pad is a pad"); + CHECK(kind_of(cheap, 4, NULL, 0) == DK_PAD, "joystick buttons alone are a pad"); + { + static const int hmm[] = { 0x2c0 /* BTN_TRIGGER_HAPPY1 */ }; + + CHECK(kind_of(hmm, 1, NULL, 0) == DK_PAD, "a pad with only BTN_TRIGGER_HAPPY keys"); + } +} + int main(void) { puts("input: overflow recovery with stale events in the read buffer"); @@ -313,5 +354,6 @@ int main(void) menu_to_game(); stick_detect(); keyboard_in_game(); + classify(); return failures ? 1 : 0; } From a0ff7b6e7ddeb105e62adf878b8ebfc6887b4bdb Mon Sep 17 00:00:00 2001 From: KurdtNervanna <136639095+KurdtNervanna@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:01:05 -0500 Subject: [PATCH 3/3] Bluetooth headphones (A2DP) prototype: bluez-alsa, routing, pairing screen - defconfigs (retrostone2 + release): BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_AUDIO, BR2_PACKAGE_BLUEZ_ALSA (names checked against Buildroot 2026.02.3) - rsos-net: bluealsa -p a2dp-source (the daemon name in bluez-alsa 4.3.1) with bluetoothd - rsos-bt: audio=headphones in the list extras field for A2DP sinks (cached), rsos-bt sink - frontend audio: try plug:bluealsa first (120 ms buffer), fall back to the card when it does not open or the sink vanishes; settings audio_bluetooth - devices screen: headphones shown/worded as such; stub tests, check-ui - docs/bluetooth-audio.md: design and the risks to measure on hardware Untested on hardware. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + .../common/rootfs-overlay/usr/bin/rsos-bt | 44 ++++++- .../common/rootfs-overlay/usr/bin/rsos-net | 8 ++ .../board/common/tests/bt-test.sh | 21 +++- .../configs/retrostone2_defconfig | 2 + .../configs/retrostone2_release_defconfig | 2 + docs/bluetooth-audio.md | 116 ++++++++++++++++++ docs/build.md | 2 +- frontend/Makefile | 13 ++ frontend/po/rsos.pot | 27 +++- frontend/src/audio/audio.c | 70 ++++++++--- frontend/src/audio/audio.h | 15 +++ frontend/src/host/host.c | 14 +++ frontend/src/ui/bt_ui.c | 30 ++++- frontend/tests/fake-rsos-bt.sh | 14 ++- 15 files changed, 350 insertions(+), 29 deletions(-) create mode 100644 docs/bluetooth-audio.md diff --git a/README.md b/README.md index 6060678..d27f969 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,7 @@ program also builds and tests on a PC: `cd frontend && make check`. Details: [do | [rom-transfer.md](docs/rom-transfer.md) | USB, web page and Windows share | | [updates.md](docs/updates.md) | Signed system updates (`.rsu` packages, keys) | | [power.md](docs/power.md) | Battery, charging, shutdown | +| [bluetooth-audio.md](docs/bluetooth-audio.md) | Bluetooth headphones (A2DP): routing, pairing, what to measure | | [pro-storage.md](docs/pro-storage.md) | RetroStone2 Pro: eMMC and M.2 storage, starter card; game covers, multi-disc games, memory speed | | [translating.md](docs/translating.md) | Adding or fixing a translation | | [homebrew.md](docs/homebrew.md) | The bundled games and their licences | diff --git a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt index 47acfef..ef1419c 100755 --- a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt +++ b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-bt @@ -10,8 +10,11 @@ # An optional 4th field holds extras, a comma-separated # list of key=value (readers ignore unknown keys): # battery=85 (BlueZ "Battery Percentage", for a -# connected device that reports one), e.g. -# "MACconnectednamebattery=85" +# connected device that reports one) and +# audio=headphones (an A2DP sink: headphones, speaker), e.g. +# "MACconnectednamebattery=85,audio=headphones" +# rsos-bt sink exit 0 if an A2DP sink is connected (the "bluealsa" +# ALSA PCM then plays to it), 1 if not; for scripts # rsos-bt scan on|off start discovery in the background (it stops by # itself after RSOS_BT_SCAN_S seconds, default 300) / # stop it @@ -34,8 +37,10 @@ SCAN_S=${RSOS_BT_SCAN_S:-300} DAEMON_PID=${RSOS_BT_DAEMON_PID:-/run/rsos-net/bluetoothd.pid} PATH=${RSOS_BT_PATH:-/usr/bin:/usr/sbin:/bin:/sbin} export PATH +KINDS=$RUN_DIR/kinds # MACaudio|other cache (bluetoothctl info is slow) ESC=$(printf '\033') +TAB=$(printf '\t') die() { echo "rsos-bt: $*" @@ -67,6 +72,23 @@ devices() { btctl devices "$@" | sed -n 's/^Device \([0-9A-Fa-f:]\{17\}\) *\(.*\)$/\1 \2/p' } +# kind MAC: "audio" for an A2DP sink (headphones, speaker), "other" for the +# rest, empty while BlueZ does not know yet (no UUIDs or icon, e.g. a device +# the scan has just seen). Known answers are cached: the list runs every 1.5 s. +kind() { + k=$(grep "^$1$TAB" "$KINDS" 2> /dev/null | cut -f2) + if [ -z "$k" ]; then + info=$(btctl info "$1") + if echo "$info" | grep -qi 'UUID:.*\(Audio Sink\|0000110b-\)\|Icon: audio-'; then + k=audio + elif echo "$info" | grep -q 'UUID:\|Icon:'; then + k=other + fi + [ -n "$k" ] && mkdir -p "$RUN_DIR" 2> /dev/null && printf '%s\t%s\n' "$1" "$k" >> "$KINDS" + fi + echo "$k" +} + # bluetoothd, started by rsos-net bt on bt_running() { [ -f "$DAEMON_PID" ] && kill -0 "$(cat "$DAEMON_PID")" 2> /dev/null @@ -95,6 +117,8 @@ list() { "$(echo "$mac" | tr 'a-f' 'A-F')" ] && continue st=found fi + # audio=headphones: an A2DP sink (headphones, speaker) + [ "$(kind "$mac")" = audio ] && extra=${extra:+$extra,}audio=headphones printf '%s%s%s%s%s%s\n' "$mac" "$tab" "$st" "$tab" "$name" "${extra:+$tab$extra}" extra= done > "$out.tmp" @@ -105,6 +129,15 @@ list() { bt_running || die "Bluetooth is off" } +# sink: an A2DP sink is connected +sink() { + bt_running || return 1 + for mac in $(devices Connected | cut -d' ' -f1); do + [ "$(kind "$mac")" = audio ] && return 0 + done + return 1 +} + scan_off() { if [ -f "$RUN_DIR/scan.pid" ]; then kill "$(cat "$RUN_DIR/scan.pid")" 2> /dev/null @@ -156,6 +189,7 @@ pair() { cmd=$1 case "$cmd" in list) list "$2"; exit $? ;; +sink) sink; exit $? ;; scan) case "$2" in on) scan_on ;; @@ -166,7 +200,7 @@ scan) ;; pair | connect | disconnect | forget) ;; *) - echo "usage: rsos-bt {list FILE|scan on|off|pair|connect|disconnect|forget MAC}" >&2 + echo "usage: rsos-bt {list FILE|sink|scan on|off|pair|connect|disconnect|forget MAC}" >&2 exit 2 ;; esac @@ -187,6 +221,10 @@ disconnect) ;; forget) btctl remove "$mac" > /dev/null + if [ -f "$KINDS" ]; then + grep -v "^$mac$TAB" "$KINDS" > "$KINDS.tmp" + mv -f "$KINDS.tmp" "$KINDS" + fi devices Paired | grep -qi "^$mac " && die "cannot remove $mac" exit 0 ;; diff --git a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-net b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-net index db8c210..d641d17 100755 --- a/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-net +++ b/buildroot-external/board/common/rootfs-overlay/usr/bin/rsos-net @@ -57,6 +57,7 @@ ETH_MODULES=$RSOS_BOARD_ETH_MODULES BT_MODULE=${RSOS_BOARD_BT_MODULE:-hci_uart} BT_HCI=hci0 BLUETOOTHD=/usr/libexec/bluetooth/bluetoothd +BLUEALSA_BIN=/usr/bin/bluealsa BT_STORE=/data/rsos/bluetooth.img BT_STORE_MNT=/var/lib/bluetooth @@ -278,6 +279,12 @@ bt_on() { "$BLUETOOTHD" -n > /dev/null 2>&1 9>&- & echo $! > "$RUN_DIR/bluetoothd.pid" fi + # Bluetooth headphones: the bluealsa daemon serves the "bluealsa" ALSA PCM (A2DP + # source only: no headset / hands-free). It waits for bluetoothd itself. + if [ -x "$BLUEALSA_BIN" ] && [ ! -f "$RUN_DIR/bluealsa.pid" ]; then + "$BLUEALSA_BIN" -p a2dp-source > /dev/null 2>&1 9>&- & + echo $! > "$RUN_DIR/bluealsa.pid" + fi } # BlueZ keeps its pairings in /var/lib/bluetooth///, with @@ -324,6 +331,7 @@ bt_store_umount() { } bt_off() { + kill_pidfile "$RUN_DIR/bluealsa.pid" kill_pidfile "$RUN_DIR/bluetoothd.pid" # Let bluetoothd write its state and exit before the store goes away. i=0 diff --git a/buildroot-external/board/common/tests/bt-test.sh b/buildroot-external/board/common/tests/bt-test.sh index a55347a..359d6fc 100755 --- a/buildroot-external/board/common/tests/bt-test.sh +++ b/buildroot-external/board/common/tests/bt-test.sh @@ -31,6 +31,7 @@ E4:17:D8:00:00:01 1 1 1 8BitDo SN30 Pro F0:13:C3:00:00:02 0 0 0 Stadia5RHM-1a2b A0:5A:5D:00:00:03 0 0 0 Wireless Controller 11:22:33:44:55:66 0 0 0 11-22-33-44-55-66 +00:1B:66:00:00:07 0 0 0 WH-Headphones EOF cat > "$W/bin/bluetoothctl" << EOF #!/bin/sh @@ -54,7 +55,11 @@ info) awk -v m="\$2" '\$1 == m { print "Device " m " (public)"; print "\tPaired: " (\$2 ? "yes" : "no") print "\tTrusted: " (\$3 ? "yes" : "no"); print "\tConnected: " (\$4 ? "yes" : "no") - if (\$4 && m == "E4:17:D8:00:00:01") print "\tBattery Percentage: 0x55 (85)" }' \$D + if (\$4 && m == "E4:17:D8:00:00:01") print "\tBattery Percentage: 0x55 (85)" + if (\$4 && \$5 ~ /Headphones/) print "\tBattery Percentage: 0x37 (55)" + if (\$5 ~ /Headphones/) { print "\tIcon: audio-headphones" + print "\tUUID: Audio Sink (0000110b-0000-1000-8000-00805f9b34fb)" } + else if (\$5 !~ /^[0-9]/) print "\tIcon: input-gaming" }' \$D ;; pair) [ "\$2" = A0:5A:5D:00:00:03 ] && { echo "Failed to pair: org.bluez.Error.AuthenticationFailed"; exit 1; } @@ -78,7 +83,9 @@ check "list" bt list "$W/list" check "list: connected (with its battery), found, found; the nameless one and colour codes left out" \ [ "$(cat "$W/list")" = "E4:17:D8:00:00:01${T}connected${T}8BitDo SN30 Pro${T}battery=85 F0:13:C3:00:00:02${T}found${T}Stadia5RHM-1a2b -A0:5A:5D:00:00:03${T}found${T}Wireless Controller" ] +A0:5A:5D:00:00:03${T}found${T}Wireless Controller +00:1B:66:00:00:07${T}found${T}WH-Headphones${T}audio=headphones" ] +check "sink: none connected" sh -c "! $SH '$BT' sink" check "scan on starts a background bluetoothctl" bt scan on pid=$(cat "$W/run/scan.pid" 2> /dev/null) check " ... which runs" kill -0 "$pid" @@ -97,6 +104,16 @@ out=$(bt pair A0:5A:5D:00:00:03) rc=$? check "a pad that does not pair: exit 1, the reason" \ [ "$rc:$out" = "1:rsos-bt: pairing failed: Failed to pair: org.bluez.Error.AuthenticationFailed" ] +check "pair headphones: ok" bt pair 00:1B:66:00:00:07 +bt list "$W/list" +check " ... connected, marked audio=headphones, with its battery first" grep -q "^00:1B:66:00:00:07${T}connected${T}WH-Headphones${T}battery=55,audio=headphones$" "$W/list" +check " ... a pad stays a plain three-field line" grep -q "^F0:13:C3:00:00:02${T}connected${T}Stadia5RHM-1a2b$" "$W/list" +check "sink: the headphones are connected" bt sink +bt disconnect 00:1B:66:00:00:07 +check "sink: not after a disconnect" sh -c "! $SH '$BT' sink" +bt connect 00:1B:66:00:00:07 +bt forget 00:1B:66:00:00:07 +check " ... forgotten: its kind is not kept" sh -c "! grep -q 00:1B:66:00:00:07 '$W/run/kinds'" check "disconnect" bt disconnect E4:17:D8:00:00:01 bt list "$W/list" check " ... paired, not connected, no battery" grep -q "^E4:17:D8:00:00:01${T}paired${T}8BitDo SN30 Pro$" "$W/list" diff --git a/buildroot-external/configs/retrostone2_defconfig b/buildroot-external/configs/retrostone2_defconfig index 3db2d23..2da0bbc 100644 --- a/buildroot-external/configs/retrostone2_defconfig +++ b/buildroot-external/configs/retrostone2_defconfig @@ -96,7 +96,9 @@ BR2_PACKAGE_WPA_SUPPLICANT=y BR2_PACKAGE_WPA_SUPPLICANT_CLI=y BR2_PACKAGE_BLUEZ5_UTILS=y BR2_PACKAGE_BLUEZ5_UTILS_CLIENT=y +BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_AUDIO=y BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_HID=y +BR2_PACKAGE_BLUEZ_ALSA=y # Root filesystem (one A/B slot): ext4, mounted read-only, kernel + dtb + # boot.scr in /boot. 384 MiB = the slot size in genimage.cfg. diff --git a/buildroot-external/configs/retrostone2_release_defconfig b/buildroot-external/configs/retrostone2_release_defconfig index de6f24d..fcefa41 100644 --- a/buildroot-external/configs/retrostone2_release_defconfig +++ b/buildroot-external/configs/retrostone2_release_defconfig @@ -96,7 +96,9 @@ BR2_PACKAGE_WPA_SUPPLICANT=y BR2_PACKAGE_WPA_SUPPLICANT_CLI=y BR2_PACKAGE_BLUEZ5_UTILS=y BR2_PACKAGE_BLUEZ5_UTILS_CLIENT=y +BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_AUDIO=y BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_HID=y +BR2_PACKAGE_BLUEZ_ALSA=y # Root filesystem (one A/B slot): ext4, mounted read-only, kernel + dtb + # boot.scr in /boot. 384 MiB = the slot size in genimage.cfg. diff --git a/docs/bluetooth-audio.md b/docs/bluetooth-audio.md new file mode 100644 index 0000000..3da9527 --- /dev/null +++ b/docs/bluetooth-audio.md @@ -0,0 +1,116 @@ +# Bluetooth headphones (A2DP) + +**Status: prototype, host-tested only.** Nothing here has run on a RetroStone2 yet; the "Measure on hardware" +list at the end is what has to be checked before this is a feature. Bluetooth controllers are in +[build.md](build.md) ("Bluetooth controllers"); this page is the audio side. + +## What is in the image + +| Piece | Where | +|---|---| +| BlueZ A2DP/AVRCP plugin | `BR2_PACKAGE_BLUEZ5_UTILS_PLUGINS_AUDIO=y` | +| bluez-alsa 4.3.1 (the `bluealsa` daemon, the `bluealsa` ALSA plugin, SBC) | `BR2_PACKAGE_BLUEZ_ALSA=y` | +| `bluealsa -p a2dp-source`, started and stopped with bluetoothd | `rsos-net bt on|off` | +| device kinds in the pairing screen, `rsos-bt sink` | `rsos-bt`, `frontend/src/ui/bt_ui.c` | +| the ALSA side | `frontend/src/audio/audio.c`, `host.c` | + +Both option names were checked against the Buildroot 2026.02.3 sources (`package/bluez5_utils/Config.in`, +`package/bluez-alsa/Config.in`); `BR2_PACKAGE_BLUEZ_ALSA` selects the audio plugin, SBC, alsa-lib's mixer and +glib itself, the explicit plugin line only documents the dependency. Only `retrostone2_defconfig` and its release +twin changed (the other boards have no Bluetooth). AAC/aptX/LDAC are not built (no fdk-aac, libopenaptx): SBC is +what every headphone must support, and what the A20 can afford. Headset/hands-free (HFP, mono microphone audio) +is off: the `bluealsa` daemon runs with `-p a2dp-source` only. + +## ALSA routing + +There is no sound server: the frontend, the libretro cores (through the frontend's host process) and any SDL2 +port talk to ALSA directly. bluez-alsa installs `/etc/alsa/conf.d/20-bluealsa.conf`, which defines the `bluealsa` +PCM. It plays to **the most recently connected** Bluetooth device (`DEV=00:00:00:00:00:00`) and **fails to open** +when none is connected. That failure is the routing rule: + +1. `audio_open()` first tries `plug:bluealsa` (`plug` converts the 48 kHz S16 stereo the host writes to whatever + rate the codec negotiated; 48 kHz is mandatory for an SBC sink, so normally nothing is converted). +2. If it opens, the stream is Bluetooth: the buffer is at least `latency_bt_ms` (120 ms, `audio.h`), because + A2DP delivers in chunks. +3. If it does not (Bluetooth off, no `bluealsa` daemon, headphones not connected), the existing choice applies, + unchanged: `audio_internal` (the codec, speaker and headphone jack) or `audio_hdmi` for a docked console + (`board.ini`, `docs/porting.md`). + +So the priority is **Bluetooth, then HDMI, then the codec**, and no setting has to be touched: connect the +headphones in Settings > Network > Bluetooth devices and the next game (or resume) plays through them. The +settings key `audio_bluetooth = false` keeps the sound on the card (headphones stay paired for other uses). +If the headphones vanish while a game runs (switched off, out of range), `snd_pcm_writei` returns `-ENODEV`; +the host then reopens on the card (`audio_lost()` in `audio_process()`) and stays there until the next open. +Headphones that connect *during* a game are picked up at the next open (game start, or return from the menu); +switching mid-game would need a periodic probe and a pacing reset, which is left out of the prototype. + +Native SDL2 ports (not on `main` yet) are separate processes: the launcher should do the same, i.e. export +`SDL_AUDIODRIVER=alsa` and `AUDIODEV=plug:bluealsa` when `rsos-bt sink` exits 0, and the card's `plughw:` device +otherwise (`board_get()->audio_internal_dev`). The decision is taken once at launch: a game that is already +running keeps its device. + +## Pairing screen and rsos-bt + +`rsos-bt list` marks devices that BlueZ reports as an A2DP sink (UUID `110b` or an `audio-*` icon) with `audio=headphones` +in the optional fourth field, the shared extras list: comma-separated `key=value` pairs, unknown keys ignored by the +reader, three fields when a device has none. The pad battery work uses the same field (`battery=`): + +``` +MACconnected|paired|foundname[key=value[,key=value...]] +00:1B:66:00:00:07connectedWH-1000XM3battery=55,audio=headphones +``` + +The answer is cached in `/run/rsos-bt/kinds` (a `bluetoothctl info` per device and per 1.5 s refresh would be +too slow); a device whose UUIDs BlueZ does not know yet has no kind until it does. The screen shows a connected +audio device as "headphones" (with its battery, "headphones, 55%", when it reports one) instead of "connected", and failure messages say headphones. `rsos-bt sink` exits 0 when +an audio device is connected. Pair, connect, disconnect and forget are the same commands as for pads. Pairing is +Just Works; very old headphones that insist on a PIN (0000) are not supported. Headphones reconnect by themselves +when switched on, as long as they were trusted at pairing, like pads. + +Tests: `board/common/tests/bt-test.sh` (stub `bluetoothctl` with headphones: kind field, `sink`, forget drops the +cache) and `make check-ui` (the screen with `frontend/tests/fake-rsos-bt.sh`: pairing headphones, the failure +message). + +## Volume + +The wheel is analog: it drives the codec's output, **not** Bluetooth. A2DP has its own absolute volume +(AVRCP), and bluez-alsa keeps it per device as a mixer control (`bluealsa` ctl). Until the frontend exposes it, +the headphones' own buttons are the volume control; the volume the headphones start at is whatever they +remember. Nothing in the prototype sets it. Open question for the frontend: show a volume bar in the OSD that +drives `amixer -D bluealsa` while Bluetooth is the output. + +## Risks: measure on hardware + +1. **Latency.** A2DP/SBC typically adds 100-250 ms. That is fine for most RPGs and strategy games and bad for + rhythm games and twitchy platformers. The host's pacing follows the audio fill, so video stays smooth, but + the sound is late by the pipeline delay. Measure with a click track (video flash and audio click against a + camera) and check `audio: ... open` in the log for the real buffer; tune `latency_bt_ms` + (120 ms is a guess: too low underruns, too high is just later). +2. **WiFi/Bluetooth coexistence.** The AP6210 shares one 2.4 GHz radio between WiFi (SDIO) and Bluetooth (UART). + Streaming A2DP while WiFi transfers (ROM transfer, scraping, SMB) can stutter the audio or slow the + transfer. Test A2DP during a WiFi download on a 2.4 GHz network (the AP6210 is 2.4 GHz only, so there is no 5 GHz + way out) and look at whether the chip's coexistence settings in the firmware need attention. +3. **SBC cost on the A20.** Encoding 48 kHz stereo SBC is cheap compared with an emulator, but the A20 is + already busy with cores in `performance` governor. Measure the `bluealsa` daemon CPU with a heavy core (N64, PSX) and + count `underruns` in the frontend log. The `plug` resampling path should be idle (48 kHz in, 48 kHz out). +4. **Volume** (above): no wheel control, possibly very loud or very quiet at first connect. +5. **Native-game sleep/quit handling.** The frontend freezes and kills native games with process-group + SIGSTOP/SIGCONT/SIGKILL. A stopped game's open `bluealsa` PCM stops feeding the `bluealsa` daemon, which should + underrun quietly (keep-alive), but check that nothing clicks or latches when the game resumes, that a + SIGKILLed game does not leave the transport acquired (the next game must open the PCM at once), and that + the `bluealsa` daemon itself is never in the group that is signalled (it is started by `rsos-net`, outside the game's + group). +6. **AVRCP buttons.** BlueZ turns the headphones' play/volume buttons into a uinput device. The frontend's input + hotplug could treat that as a keyboard or pad: check `/proc/bus/input/devices` and that it does not steal a + player slot or fire menu keys. +7. **Reconnect and boot.** Do the headphones reconnect after power-on while a game is running or at boot? Does + bluealsa survive `rsos-net bt off`/`on` cycles (Settings toggle) and the frontend respawn? Is the ext4 + pairing store (`bluetooth.img`) mounted before bluealsa registers its endpoints? +8. **Sleep/idle power.** An idle open A2DP transport keeps the radio busy; check that closing audio on idle + suspends the stream (bluez-alsa does so after a few seconds without data) and what Bluetooth costs in + battery with and without headphones. +9. **dbus policy.** The `bluealsa` daemon must be allowed to own `org.bluealsa` on the system bus (bluez-alsa installs + `/etc/dbus-1/system.d/bluealsa.conf` for root); verify it is in the image. (Checked against + the bluez-alsa 4.3.1 sources: the daemon is `bluealsa` (`/usr/bin/bluealsa`; the `bluealsad` name is from later + releases), `-p a2dp-source` is a valid profile argument, at least one `-p` is mandatory, and `bluealsa.conf` is + installed in the D-Bus config directory. Not yet run.) diff --git a/docs/build.md b/docs/build.md index 238dc1b..b27972c 100644 --- a/docs/build.md +++ b/docs/build.md @@ -810,7 +810,7 @@ it like a USB pad. Tests: `board/common/tests/bt-test.sh` (rsos-bt against a stub `bluetoothctl`) and `make check-ui` (the screen with `frontend/tests/fake-rsos-bt.sh`). TODO(hw): pairing and reconnecting a classic pad and an LE pad (the Stadia controller) on the RetroStone2's -BCM20710. +BCM20710. Headphones (A2DP through bluez-alsa) are in [bluetooth-audio.md](bluetooth-audio.md). **SMB share `\\RETROSTONE`**: `ksmbd.ko` (module, `CONFIG_SMB_SERVER=m`) and ksmbd-tools are in the image but **never started at boot** and **not wired diff --git a/frontend/Makefile b/frontend/Makefile index e0d0534..122dd4e 100644 --- a/frontend/Makefile +++ b/frontend/Makefile @@ -364,6 +364,19 @@ check-ui: $(UIPREVIEW) --bt-helper $(CURDIR)/tests/fake-rsos-bt.sh \ --keys "start down down a down down down down down a sleep:500 wait:1600 sleep:300 down down \ expect:|Wireless_Controller a sleep:1500 expect:dialog:This_controller_could_not_pair_without_a_PIN" + @echo " headphones (fourth field audio): a failed pairing says headphones, a good one connects" + rm -rf $(UI_CHECK_DIR)/bt + FAKE_BT_DIR=$(UI_CHECK_DIR)/bt FAKE_BT_FAIL=pair $(UIPREVIEW) --root $(UI_CHECK_DIR) --quiet \ + --bt-helper $(CURDIR)/tests/fake-rsos-bt.sh \ + --keys "start down down a down down down down down a sleep:500 wait:1600 sleep:300 down down down \ + expect:|WH-1000XM3 a sleep:1500 expect:dialog:Could_not_pair_the_headphones a wait:300 \ + expect:menu:Bluetooth_devices|WH-1000XM3 b sleep:500" + rm -rf $(UI_CHECK_DIR)/bt + FAKE_BT_DIR=$(UI_CHECK_DIR)/bt $(UIPREVIEW) --root $(UI_CHECK_DIR) --quiet \ + --bt-helper $(CURDIR)/tests/fake-rsos-bt.sh \ + --keys "start down down a down down down down down a sleep:500 wait:1600 sleep:300 down down down \ + expect:|WH-1000XM3 a sleep:1500 expect:toast=WH-1000XM3_connected b sleep:500" + grep -qx 'pair 00:1B:66:00:00:07' $(UI_CHECK_DIR)/bt/calls.log rm -rf $(UI_CHECK_DIR)/bt $(UI_CHECK_DIR)/data/rsos/settings.ini @echo "check-ui: game options act on their game after Favorite re-sorts the list (review F-H4)" rm -rf $(UI_CHECK_DIR)-games && mkdir -p $(UI_CHECK_DIR)-games/data/roms/nes \ diff --git a/frontend/po/rsos.pot b/frontend/po/rsos.pot index 47a7198..f4158bc 100644 --- a/frontend/po/rsos.pot +++ b/frontend/po/rsos.pot @@ -813,8 +813,8 @@ msgstr "" #. TRANSLATORS: Settings > Network > Bluetooth devices: the hint at the #. top (one line, keep it short) -#: src/ui/bt_ui.c:122 -msgid "Put the controller in pairing mode" +#: src/ui/bt_ui.c:142 +msgid "Put the controller or headphones in pairing mode" msgstr "" #. TRANSLATORS: Bluetooth devices: list headings @@ -839,6 +839,13 @@ msgstr "" msgid "please wait..." msgstr "" +#. TRANSLATORS: Bluetooth devices: connected headphones and +#. their battery level; %d is a percentage (keep %%) +#: src/ui/bt_ui.c:167 +#, c-format +msgid "headphones, %d%%" +msgstr "" + #. TRANSLATORS: Bluetooth devices: connected pad and its #. battery level; %d is a percentage (keep %%) #: src/ui/bt_ui.c:164 @@ -846,6 +853,12 @@ msgstr "" msgid "connected, %d%%" msgstr "" +#. TRANSLATORS: Bluetooth devices: a connected audio device, +#. the sound plays through it (short) +#: src/ui/bt_ui.c:175 +msgid "headphones" +msgstr "" + #: src/ui/bt_ui.c:145 msgid "connected" msgstr "" @@ -909,10 +922,20 @@ msgstr "" msgid "This controller could not pair without a PIN. Some controllers must be paired with a USB cable first." msgstr "" +#. TRANSLATORS: error message, Bluetooth headphones +#: src/ui/bt_ui.c:351 +msgid "Could not pair the headphones. Put them in pairing mode and try again." +msgstr "" + #: src/ui/bt_ui.c:308 msgid "Could not pair the controller. Put it in pairing mode and try again." msgstr "" +#. TRANSLATORS: error message, Bluetooth headphones +#: src/ui/bt_ui.c:356 +msgid "Could not connect the headphones. Switch them on and try again." +msgstr "" + #: src/ui/bt_ui.c:310 msgid "Could not connect the controller. Switch it on and try again." msgstr "" diff --git a/frontend/src/audio/audio.c b/frontend/src/audio/audio.c index 423e808..26084fe 100644 --- a/frontend/src/audio/audio.c +++ b/frontend/src/audio/audio.c @@ -25,6 +25,8 @@ static struct { int fade_in; /* frames left in the fade-in ramp */ int16_t last_l, last_r; /* last frame written (fade-out start) */ bool paused; + bool bt; /* the stream goes to Bluetooth headphones */ + bool lost; /* ... and the sink vanished */ struct audio_stats st; char dev[64]; } A = { .latency_ms = 64 }; @@ -34,6 +36,7 @@ void audio_config_defaults(struct audio_config *cfg) memset(cfg, 0, sizeof(*cfg)); cfg->latency_ms = 64; cfg->periods = 4; + cfg->latency_bt_ms = 120; } static bool name_has(const char *s, const char *sub) @@ -146,23 +149,45 @@ int audio_open(const struct audio_config *cfg, enum audio_output out, int prefil if (A.cfg.latency_ms > 0 && A.latency_ms < A.cfg.latency_ms) A.latency_ms = A.cfg.latency_ms; A.out = out; - dev = audio_pick_device(&A.cfg, out); - if (!dev) { - hlog(HLOG_WARN, "audio: no ALSA card for the %s", out == AUDIO_OUT_HDMI ? "HDMI output" : "LCD"); - return -ENODEV; - } - hstrlcpy(A.dev, dev, sizeof(A.dev)); - err = snd_pcm_open(&pcm, dev, SND_PCM_STREAM_PLAYBACK, SND_PCM_NONBLOCK); - if (err < 0) { - hlog(HLOG_WARN, "audio: cannot open %s: %s", dev, snd_strerror(err)); - return err; + A.bt = A.lost = false; + /* Bluetooth headphones first: bluez-alsa fails the open when no sink + * is connected (no bluealsa, no headphones), then the card is used. */ + pcm = NULL; + if (A.cfg.device_bt && *A.cfg.device_bt && + snd_pcm_open(&pcm, A.cfg.device_bt, SND_PCM_STREAM_PLAYBACK, SND_PCM_NONBLOCK) >= 0) { + int lat = A.cfg.latency_bt_ms > A.latency_ms ? A.cfg.latency_bt_ms : A.latency_ms; + + if (setup(pcm, lat, A.cfg.periods) >= 0) { + A.bt = true; + dev = A.cfg.device_bt; + prefill_ms = lat / 2; + } else { + hlog(HLOG_WARN, "audio: cannot configure %s, using the card", A.cfg.device_bt); + snd_pcm_close(pcm); + pcm = NULL; + } + } else { + pcm = NULL; } - err = setup(pcm, A.latency_ms, A.cfg.periods); - if (err < 0) { - hlog(HLOG_WARN, "audio: cannot configure %s: %s", dev, snd_strerror(err)); - snd_pcm_close(pcm); - return err; + if (!pcm) { + dev = audio_pick_device(&A.cfg, out); + if (!dev) { + hlog(HLOG_WARN, "audio: no ALSA card for the %s", out == AUDIO_OUT_HDMI ? "HDMI output" : "LCD"); + return -ENODEV; + } + err = snd_pcm_open(&pcm, dev, SND_PCM_STREAM_PLAYBACK, SND_PCM_NONBLOCK); + if (err < 0) { + hlog(HLOG_WARN, "audio: cannot open %s: %s", dev, snd_strerror(err)); + return err; + } + err = setup(pcm, A.latency_ms, A.cfg.periods); + if (err < 0) { + hlog(HLOG_WARN, "audio: cannot configure %s: %s", dev, snd_strerror(err)); + snd_pcm_close(pcm); + return err; + } } + hstrlcpy(A.dev, dev, sizeof(A.dev)); A.pcm = pcm; A.paused = false; A.st.opens++; @@ -265,6 +290,11 @@ static int write_raw(const int16_t *frames, int n) recover((int)w); continue; } + if (w == -ENODEV && A.bt) { + /* the headphones are gone: the host reopens on the card */ + A.lost = true; + break; + } if (w < 0) { hlog_once("alsa-write", "audio: write error %s", snd_strerror((int)w)); break; @@ -394,6 +424,16 @@ bool audio_paused(void) return A.paused; } +bool audio_is_bluetooth(void) +{ + return A.pcm && A.bt; +} + +bool audio_lost(void) +{ + return A.pcm && A.lost; +} + void audio_get_stats(struct audio_stats *st) { *st = A.st; diff --git a/frontend/src/audio/audio.h b/frontend/src/audio/audio.h index 7b6502f..8c397d2 100644 --- a/frontend/src/audio/audio.h +++ b/frontend/src/audio/audio.h @@ -36,6 +36,14 @@ struct audio_config { * e.g. "hdmi" gives hdmi:CARD=N,DEV=0, the card's own IEC958 set-up * (vc4-hdmi on the Raspberry Pi takes IEC958 subframes only) */ const char *hdmi_pcm; + /* Bluetooth headphones (A2DP through bluez-alsa): the PCM to try first, + * before the LCD / HDMI card, e.g. "plug:bluealsa" (it plays to the + * most recently connected device and fails to open when none is + * connected, so audio falls back to the card). NULL = never. */ + const char *device_bt; + /* its buffer (A2DP adds 100-250 ms anyway; SBC encodes in chunks): + * default 120 ms, never below latency_ms */ + int latency_bt_ms; }; struct audio_stats { @@ -79,6 +87,13 @@ double audio_fill(void); * resume: fade-in. */ void audio_pause(bool pause); bool audio_paused(void); + +/* True when the open stream goes to Bluetooth headphones. */ +bool audio_is_bluetooth(void); +/* True once the Bluetooth sink vanished under an open stream (headphones + * switched off or out of range): the caller closes and reopens, which falls + * back to the card. Cleared by audio_open(). */ +bool audio_lost(void); void audio_keepalive(void); /* Adds silence (e.g. to reach a target fill). */ diff --git a/frontend/src/host/host.c b/frontend/src/host/host.c index 961c690..5d0e7d2 100644 --- a/frontend/src/host/host.c +++ b/frontend/src/host/host.c @@ -449,6 +449,15 @@ static void audio_process(void) double fill, ratio; int cap, n; + if (audio_lost()) { + /* the Bluetooth headphones went away: back to the card */ + hlog(HLOG_INFO, "audio: Bluetooth sink lost, using the card"); + audio_close(); + audio_cfg.device_bt = NULL; + if (audio_wanted) + audio_open(&audio_cfg, audio_out, audio_latency_ms() / 2); + host_reevaluate_pacing(); + } core_audio_lock(); if (!H.ain_n) { core_audio_unlock(); @@ -2152,6 +2161,11 @@ static void load_settings(void) audio_cfg.device_hdmi = board_get()->audio_hdmi_dev; if (board_get()->audio_hdmi_pcm[0]) audio_cfg.hdmi_pcm = board_get()->audio_hdmi_pcm; + /* Bluetooth headphones through bluez-alsa (docs/bluetooth-audio.md): + * tried first when a sink is connected; audio_bluetooth = false in + * the settings keeps the sound on the card */ + if (ini_get_bool(&s, "", "audio_bluetooth", true)) + audio_cfg.device_bt = "plug:bluealsa"; audio_cfg.latency_ms = H.cfg.audio_latency_ms > 0 ? H.cfg.audio_latency_ms : ini_get_int(&s, "", "audio_latency_ms", 64); audio_set_latency(audio_cfg.latency_ms); diff --git a/frontend/src/ui/bt_ui.c b/frontend/src/ui/bt_ui.c index fb2c83c..749cce9 100644 --- a/frontend/src/ui/bt_ui.c +++ b/frontend/src/ui/bt_ui.c @@ -11,7 +11,7 @@ * it is open) / closes * rsos-bt list FILE every BT_LIST_MS: "MAC\tstate\tname[\tkey=value,...]" * lines, state connected|paired|found; the extras - * (unknown keys are ignored): battery= + * (unknown keys are ignored): battery=, audio=headphones * rsos-bt pair|connect|disconnect|forget MAC * Paired devices are trusted, so they reconnect by themselves when * Bluetooth comes on and when the pad is switched on (bluetoothd). @@ -36,6 +36,7 @@ struct btdev { char mac[18]; bool paired, connected; int battery; /* percent, -1 = unknown */ + bool audio; /* headphones, speaker (an A2DP sink) */ char name[80]; }; @@ -81,6 +82,8 @@ static void parse_extras(char *x, struct btdev *d) for (char *kv = strtok_r(x, ",", &save); kv; kv = strtok_r(NULL, ",", &save)) if (!strncmp(kv, "battery=", 8) && kv[8] >= '0' && kv[8] <= '9' && atoi(kv + 8) <= 100) d->battery = atoi(kv + 8); + else if (!strcmp(kv, "audio=headphones")) + d->audio = true; } /* the line "MAC\tstate\tname[\tkey=value,...]" -> d */ @@ -136,7 +139,7 @@ static void items(struct ui *ui, struct menu *m) m->n = 0; /* TRANSLATORS: Settings > Network > Bluetooth devices: the hint at the * top (one line, keep it short) */ - it = menu_add(m, MI_INFO, ID_BT_HINT, _("Put the controller in pairing mode")); + it = menu_add(m, MI_INFO, ID_BT_HINT, _("Put the controller or headphones in pairing mode")); it->disabled = true; for (int pass = 0; pass < 2; pass++) { bool header = false; @@ -158,12 +161,19 @@ static void items(struct ui *ui, struct menu *m) strlcpy_(it->value, B.act == ACT_PAIR ? _("pairing...") : B.act == ACT_CONNECT ? _("connecting...") : _("please wait..."), sizeof(it->value)); + else if (d->connected && d->audio && d->battery >= 0) + /* TRANSLATORS: Bluetooth devices: connected headphones and + * their battery level; %d is a percentage (keep %%) */ + snprintf(it->value, sizeof(it->value), _("headphones, %d%%"), d->battery); else if (d->connected && d->battery >= 0) /* TRANSLATORS: Bluetooth devices: connected pad and its * battery level; %d is a percentage (keep %%) */ snprintf(it->value, sizeof(it->value), _("connected, %d%%"), d->battery); else if (d->connected) - strlcpy_(it->value, _("connected"), sizeof(it->value)); + /* TRANSLATORS: Bluetooth devices: a connected audio device, + * the sound plays through it (short) */ + strlcpy_(it->value, d->audio ? _("headphones") : _("connected"), + sizeof(it->value)); } } if (!any_found) { @@ -299,8 +309,12 @@ void bt_devices_open(struct ui *ui) static void act_done(struct ui *ui, const struct hw_job_result *r) { int act = B.act; + bool audio = false; B.act = 0; + for (int i = 0; i < B.n; i++) + if (!strcmp(B.dev[i].mac, B.act_mac)) + audio = B.dev[i].audio; if (r->status != 0) LOGW("bt: %s: %s", B.act_mac, r->out); /* shown at once, before the next list */ @@ -332,9 +346,15 @@ static void act_done(struct ui *ui, const struct hw_job_result *r) * need a PIN first) */ message_open(ui, _("This controller could not pair without a PIN. Some controllers must be paired with a USB cable first.")); else if (act == ACT_PAIR) - message_open(ui, _("Could not pair the controller. Put it in pairing mode and try again.")); + message_open(ui, audio ? + /* TRANSLATORS: error message, Bluetooth headphones */ + _("Could not pair the headphones. Put them in pairing mode and try again.") : + _("Could not pair the controller. Put it in pairing mode and try again.")); else - message_open(ui, _("Could not connect the controller. Switch it on and try again.")); + message_open(ui, audio ? + /* TRANSLATORS: error message, Bluetooth headphones */ + _("Could not connect the headphones. Switch them on and try again.") : + _("Could not connect the controller. Switch it on and try again.")); break; case ACT_FORGET: if (r->status == 0) diff --git a/frontend/tests/fake-rsos-bt.sh b/frontend/tests/fake-rsos-bt.sh index aaef932..d0a9eac 100755 --- a/frontend/tests/fake-rsos-bt.sh +++ b/frontend/tests/fake-rsos-bt.sh @@ -5,7 +5,8 @@ # format of "rsos-bt list"), created with one paired and two found devices; every # call is logged to $FAKE_BT_DIR/calls.log. FAKE_BT_FAIL=pair makes pairing # fail, FAKE_BT_FAIL=pin makes it fail as a pad that needs a PIN or a cable -# does. A device that gets connected reports battery=70 and a key the frontend +# does. Headphones carry audio=headphones in the extras ("sink" says whether +# one is connected). A device that gets connected reports battery=70 and a key the frontend # does not know (it must ignore it); the Wireless Controller has an unknown key too. D=${FAKE_BT_DIR:?FAKE_BT_DIR is not set} mkdir -p "$D" @@ -17,6 +18,8 @@ if [ ! -f "$DEV" ]; then "F0:13:C3:00:00:02" found "Stadia5RHM-1a2b" \ "A0:5A:5D:00:00:03" found "Wireless Controller" > "$DEV" sed "/^A0:5A:5D:00:00:03/s/\$/${T}future=1/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + # headphones: the extras carry audio=headphones + printf '%s\t%s\t%s\t%s\n' "00:1B:66:00:00:07" found "WH-1000XM3" audio=headphones >> "$DEV" fi echo "$*" >> "$D/calls.log" @@ -25,6 +28,14 @@ set_state() { sed "/^${1}${T}/s/${T}[a-z]\{1,\}=[^${T}]*\$//; s/^${1}${T}[a-z]*${T}/${1}${T}${2}${T}/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" [ "$2" = connected ] && sed "/^${1}${T}/s/\$/${T}battery=70,future=x/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + # the kind of a device does not change: audio=headphones stays (last, after battery) + if [ "$1" = 00:1B:66:00:00:07 ]; then + if [ "$2" = connected ]; then + sed "/^${1}${T}/s/\$/,audio=headphones/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + else + sed "/^${1}${T}/s/\$/${T}audio=headphones/" "$DEV" > "$DEV.tmp" && mv "$DEV.tmp" "$DEV" + fi + fi return 0 } @@ -33,6 +44,7 @@ list) cp "$DEV" "$2.tmp" && mv "$2.tmp" "$2" ;; scan) ;; +sink) grep -q "${T}connected${T}.*audio=headphones" "$DEV" || exit 1 ;; pair) sleep 1 if [ "${FAKE_BT_FAIL:-}" = pair ]; then