# bluetui

Terminal Bluetooth manager for Linux written in Python. Sits on top of BlueZ via the system D-Bus, no `sudo` required (PolicyKit handles authorization). The headline feature isn't the device list — it's that the same app turns the laptop into a real Bluetooth HID remote control for Smart TVs, registering as a HID device the way a stock Android-TV / Tizen / WebOS remote does.

## Architecture

Built on **[Textual](https://textual.textualize.io/)** for the TUI and **[dbus-next](https://github.com/altdesktop/python-dbus-next)** for async D-Bus. The repo is organized into one module per BlueZ surface:

```
bluetui/
├── bluez.py          # BluezManager — wraps BlueZ ObjectManager over D-Bus
├── agent.py          # org.bluez.Agent1 — PIN/passkey/confirm dialogs
├── audio.py          # pactl auto-routing for PulseAudio + PipeWire
├── classic_hid.py    # Classic-BT HID Device profile (TV remote)
├── hid_remote.py     # BLE HID over GATT (legacy, kept for testing)
├── remote_screen.py  # virtual-remote UI screen
├── widgets.py        # AdapterBar, DeviceList
└── modals.py         # Confirm/Pin/Info/Help/MediaControl dialogs
```

Device list groups by status (connected / paired / nearby), shows RSSI bars and battery percentage, and includes the standard pair / forget / trust / block / scan / power-toggle operations bound to single keys.

## Bluetooth HID remote

The distinctive feature. Most "PC as TV remote" projects either drive an IR blaster or speak the WiFi-based **Android TV Remote v2** protocol. bluetui does neither — it pretends to be a Bluetooth HID device and the TV pairs with it like it would pair with the OEM's own remote.

Implementation, per the README:

- Registers `org.bluez.Profile1` with UUID `0x1124` (HID)
- Builds an SDP record with a HID descriptor containing **Consumer Control (Report ID 1) + Keyboard (Report ID 2)**
- Opens raw L2CAP sockets on **PSM 17 (Control)** and **PSM 19 (Interrupt)** via `socket.AF_BLUETOOTH` + `BTPROTO_L2CAP`
- For pairing: agent switches to `NoInputNoOutput` so JustWorks goes through automatically
- After connect, force-disconnects A2DP/AVRCP/HSP profiles so TV audio doesn't drop into the laptop's speakers

Tested on TCL Android TV. Should work with any Samsung / LG / Sony TV that supports the BT HID-host profile, but coverage is "most but not all" — the README is upfront that some sets don't accept HID over Bluetooth at all.

## AVRCP and audio routing

When a paired audio device connects, bluetui auto-routes the system default sink to it via `pactl` (works on PulseAudio and PipeWire). Plays / pauses / skips via AVRCP. Volume goes through the system mixer rather than AVRCP-absolute-volume — the README notes that's a deliberate ergonomic choice. The auto-routing has a known race with BlueZ that the app retries automatically.

## Requirements

- Linux with **BlueZ ≥ 5.50** (Debian 11+, Ubuntu 20.04+, current Arch)
- Python ≥ 3.9
- `bluetoothd` running
- For audio routing: `pulseaudio` or `pipewire-pulse` + `pactl`
- For the emoji icons: a monospace font with `📺 🎧 ⌨` glyphs (JetBrains Mono / Fira Code Nerd / DejaVu Sans Mono)

Install:

```
git clone https://github.com/HelpFreedom/TUI_bluetooth.git
cd TUI_bluetooth
pip3 install --user -r requirements.txt
./bluetui.sh
```

(README example uses `bluetui.git` and `cd bluetui` — the repo's actual name is `TUI_bluetooth`. The packaging is informal: `requirements.txt` + a shell wrapper, no `pyproject.toml`, no PyPI release.)

Hot keys: `j`/`k` move, `Enter` connect, `p` pair, `f` forget, `t` trust, `b` block, `s` scan, `o` power, `i` info, `m` AVRCP, `r` open TV remote, `?` help, `q` quit.

## Watchlist status

On the [[toolbox/watchlist]] because the project is brand new — repo created **2026-05-01** (one day before this page), zero stars, single author, no tagged releases, no test suite visible, only the Russian README, install path is `pip3 install --user -r requirements.txt` rather than a packaged distribution. The TV-remote HID work is real and unusual; whether it stays maintained is the open question. Re-check 2026-08-02 to see if anyone else lands a PR, the README gets translated, the install path tightens, and TV compatibility expands beyond the TCL Android TV the author tested on.

## Repo

[github.com/HelpFreedom/TUI_bluetooth](https://github.com/HelpFreedom/TUI_bluetooth) — 0 stars, GPL-3.0, Python primary, repo created 2026-05-01, single author. README in Russian.