Map

bluetui

Toolbox toolboxpythontuibluetoothlinuxwatchlistPythonGPL-3.0 ↳ show in map Markdown
title
bluetui
type
toolbox
summary
Terminal Bluetooth manager for Linux that doubles as a Bluetooth HID remote for Smart TVs
tags
python, tui, bluetooth, linux, watchlist
repo
https://github.com/HelpFreedom/TUI_bluetooth
language
Python
license
GPL-3.0
created
2026-05-02
updated
2026-05-02

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 for the TUI and 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 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 — 0 stars, GPL-3.0, Python primary, repo created 2026-05-01, single author. README in Russian.

Linked from