hidbridge 1.2.3__tar.gz

hidbridge-1.2.3/.gitignore

@@ -0,0 +1,37 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.whl
+*.tar.gz
+
+# --- PlatformIO / firmware build output ---
+.pio/
+.pioenvs/
+.piolibdeps/
+firmware/*/.pio/
+
+# --- editor / OS ---
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# --- local secrets / runtime state (NEVER commit) ---
+# The device passcode PIN lives OUTSIDE the repo at ~/.config/bt_hid/idevice.pin (0600).
+*.pin
+idevice.pin
+targets.json
+# The network backend auth token also lives OUTSIDE the repo at ~/.config/bt_hid/net.token (0600);
+# block it anywhere in case it is ever copied into a tree.
+net.token
+*.token
+.claude/worktrees/

hidbridge-1.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Munk Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hidbridge-1.2.3/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: hidbridge
+Version: 1.2.3
+Summary: Drive a Bluetooth-HID target (iPad / iPhone / any host) from Linux -- keyboard + pointer over the host BlueZ stack or a Pico 2W / ESP32 serial-attached BLE peripheral
+Project-URL: Homepage, https://github.com/martinmunk/hidbridge
+Project-URL: Repository, https://github.com/martinmunk/hidbridge
+Project-URL: Issues, https://github.com/martinmunk/hidbridge/issues
+Author: Martin Munk Hansen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,bluez,esp32,hid,hog,ipad,keyboard,mouse,pico
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB) :: Human Interface Device (HID)
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pyserial>=3.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: dongle
+Requires-Dist: dbus-python>=1.2; extra == 'dongle'
+Requires-Dist: pygobject>=3.40; extra == 'dongle'
+Provides-Extra: mcu
+Requires-Dist: pyserial>=3.5; extra == 'mcu'
+Description-Content-Type: text/markdown
+
+# hidbridge (Python)
+
+The Python side of **hidbridge** -- a Linux toolbox that presents a Bluetooth-LE HID
+keyboard + relative pointer to any BLE-HID (HOG) host and drives it programmatically: type text,
+press keys, move/click the pointer, and enter a lock-screen passcode.
+
+Two backends, one report layer:
+
+- **dongle** -- the host's own **BlueZ** stack (a USB Bluetooth adapter). A small daemon
+  (`ble_hid`) exports the HID-over-GATT peripheral; the CLI talks to it over a Unix socket.
+  Needs `dbus` + `PyGObject` (system python) and usually root.
+- **mcu** -- a **Raspberry Pi Pico 2 W** or an **ESP32** running the firmware in
+  `../firmware/`, reached over **USB serial**. The MCU owns its own BLE stack + bond database,
+  so it sidesteps the HID-over-GATT CCCD/Report-Reference subscription quirk that trips BlueZ with
+  some hosts. Needs only `pyserial`; no dbus, no daemon, no root.
+- **net** -- an **Ethernet/WiFi ESP32** running that same firmware, reached over **TCP** (no USB
+  cable): `--backend net --host hidbridge-<nick>.local`. **TLS-PSK encrypted** and fails closed -- the
+  provisioned token is the pre-shared key; set it on the board over USB once with
+  `hidbridge net-provision`. Needs Python 3.13+ (ssl PSK). Stdlib-only (sockets + ssl); no pyserial,
+  dbus, daemon, or root. See [`../docs/bt-hid-network-backend.md`](../docs/bt-hid-network-backend.md).
+
+Both backends emit the **exact same report bytes** via `hidbridge.reports` (the single source of
+truth for the HID report descriptor), so behaviour is identical regardless of transport.
+
+## Install
+
+**As a consumer** (released wheels are on PyPI):
+
+```bash
+pip install "hidbridge[mcu]"      # + pyserial for the Pico/ESP32 serial backend
+pip install hidbridge             # core only: reports + the net (TCP) backend
+```
+
+Source, issues and firmware releases: <https://github.com/martinmunk/hidbridge>. The release flow
+(wheel and firmware version independently; the git tag is the version):
+[`docs/releasing.md`](https://github.com/martinmunk/hidbridge/blob/main/docs/releasing.md).
+
+**From source** (this checkout):
+
+```bash
+# from this directory (hidbridge/python)
+pip install -e ".[mcu]"        # Pico / ESP32 serial backend (pyserial)
+pip install -e ".[dongle]"     # BlueZ backend (dbus-python + PyGObject; system python)
+pip install -e ".[dev]"        # + pytest, ruff, build
+```
+
+The **dongle** backend must run under the **system python** (`/usr/bin/python3`) because
+`dbus` + `AF_BLUETOOTH` sockets are only available there. On Debian/Ubuntu install the system
+deps with apt instead of pip:
+
+```bash
+sudo apt install python3-dbus python3-gi
+```
+
+For a venv that still sees them, create it with `--system-site-packages`
+(`uv venv --system-site-packages` or `python3 -m venv --system-site-packages`).
+
+## Quick start
+
+```bash
+# MCU backend (a Pico on /dev/ttyACM0) -- no root, no daemon
+hidbridge --backend pico type "hello world"
+hidbridge --backend pico move 40 0
+hidbridge --backend pico click left
+
+# dongle backend (BlueZ) -- needs the daemon up + root
+sudo hidbridge pair-mode                 # advertise as a keyboard; pair from the host's Bluetooth settings
+sudo hidbridge connect mini5             # (re)connect a bonded target
+sudo hidbridge type "hello"
+sudo hidbridge unlock                    # types the passcode from ~/.config/bt_hid/idevice.pin (never logged)
+
+# named targets (device -> backend map in ~/.config/bt_hid/targets.json)
+hidbridge targets add labpad pico:/dev/ttyACM0 AA:BB:CC:DD:EE:FF
+hidbridge --target labpad type "hi"
+```
+
+Run `hidbridge --help` for the full subcommand list.
+
+## Python API
+
+The driving surface is two context managers that mirror the hardware: a **`HidBridge`** is the board
+channel; **`bridge.connect(name)`** advertises a bonded identity, waits until it is ready, and hands
+back a **`HidSession`** you drive. You pass a *location* ("/dev/ttyUSB3", a net host, "hci1", or
+nothing to autodetect) -- never a board type; the board self-identifies into `bridge.info` /
+`bridge.capabilities`.
+
+```python
+from hidbridge import HidBridge
+
+with HidBridge("/dev/ttyUSB3") as bridge, bridge.connect("laptop3") as s:
+    s.type("hello world")
+    s.key("enter")
+    s.move(40, 0)          # relative pointer
+    s.click("left")
+    s.scroll(-3)
+# leaving the `with` disconnects but keeps the bond -- no idle connections
+```
+
+The session verbs are the whole vocabulary: `type(text)`, `key(name, mod=0)`, `move(dx, dy)`,
+`click(button="left")`, `scroll(clicks)`. Who builds the report bytes is a backend detail -- an MCU
+board delegates each verb to the firmware (the target slot's keyboard layout applies board-side); a
+dongle builds the bytes host-side. Either way the surface is identical. "Unlock an iPad" is just
+typing the passcode: `s.type(pin); s.key("enter")`.
+
+For the single-host case, `hidbridge.session(location, device)` opens the board, connects the one
+device, and yields the session (tearing both down on exit):
+
+```python
+from hidbridge import session
+
+with session("/dev/ttyUSB3", "laptop3") as s:
+    s.type("hi")
+```
+
+Errors are typed under `HidbridgeError`: `NotBonded`, `ConnectTimeout`, `Unsupported`,
+`CapacityError`, `IncompatibleFirmware`. Multiple sessions can be open at once on a board that
+supports it (the ESP32 holds several identities); otherwise a second `connect()` raises. The wheel
+version is `hidbridge.__version__`.
+
+## The passcode PIN (secret, external)
+
+`hidbridge unlock` (and the trust-overlay helper) read the device passcode from
+`~/.config/bt_hid/idevice.pin` -- a `0600` file that lives **outside** this repo and is **never
+committed or logged**. Create it yourself:
+
+```bash
+mkdir -p ~/.config/bt_hid && umask 077 && printf '%s' 1234 > ~/.config/bt_hid/idevice.pin
+```
+
+The passcode is expanded to HID frames locally; only frames are ever sent, never the string.
+
+## Layout
+
+```
+python/
+  pyproject.toml          PEP 621 metadata, console_script `hidbridge`, ruff + pytest config
+  src/hidbridge/          the package
+    reports.py            PURE HID report layer (stdlib only) -- the report-byte source of truth
+    controller.py         backend-agnostic report driver (type/key/move/click/unlock/timeline)
+    conn.py               HidSession: connect-on-demand context manager, readiness gate
+    targets.py            device -> backend registry + per-bond identity slots
+    naming.py             per-adapter runtime names (multi-daemon isolation) + slot names
+    adapter.py            BlueZ adapter discovery / dongle selection (sysfs + dbus)
+    ble_hid.py            the HID-over-GATT peripheral daemon (dongle backend)
+    central.py / central_core.py   on-host BLE-central HID self-test (dongle/MCU parity)
+    transport_pico.py / link_pico.py     Pico serial transport + link backend
+    transport_esp32.py / link_esp32.py   ESP32 serial transport + link backend
+    dismiss_trust.py      hands-free "Trust This Computer" overlay dismissal
+    cli.py                the `hidbridge` command
+    _scripts/             reference launcher + systemd unit + pair-mode/service shell helpers
+  tests/                  pytest suite (offline by default; hardware tests skip)
+```
+
+## Tests
+
+```bash
+pytest                    # offline suite (hardware/live tests skip automatically)
+```
+
+Hardware-gated tests opt in via env vars, e.g. `BT_HID_LOOPBACK=1` (on-host BLE loopback,
+needs two adapters + root) or `BT_HID_CENTRAL=1` (central self-test, needs the built-in adapter
++ an MCU). `*_live.py` tests need a real bonded host.
+
+## Lint
+
+```bash
+ruff check .
+```
+
+The ruleset is deliberately scoped (see `pyproject.toml`): it enforces the pyflakes correctness
+rules but tolerates this codebase's dense one-liner report/parser style.

hidbridge-1.2.3/README.md

@@ -0,0 +1,171 @@
+# hidbridge (Python)
+
+The Python side of **hidbridge** -- a Linux toolbox that presents a Bluetooth-LE HID
+keyboard + relative pointer to any BLE-HID (HOG) host and drives it programmatically: type text,
+press keys, move/click the pointer, and enter a lock-screen passcode.
+
+Two backends, one report layer:
+
+- **dongle** -- the host's own **BlueZ** stack (a USB Bluetooth adapter). A small daemon
+  (`ble_hid`) exports the HID-over-GATT peripheral; the CLI talks to it over a Unix socket.
+  Needs `dbus` + `PyGObject` (system python) and usually root.
+- **mcu** -- a **Raspberry Pi Pico 2 W** or an **ESP32** running the firmware in
+  `../firmware/`, reached over **USB serial**. The MCU owns its own BLE stack + bond database,
+  so it sidesteps the HID-over-GATT CCCD/Report-Reference subscription quirk that trips BlueZ with
+  some hosts. Needs only `pyserial`; no dbus, no daemon, no root.
+- **net** -- an **Ethernet/WiFi ESP32** running that same firmware, reached over **TCP** (no USB
+  cable): `--backend net --host hidbridge-<nick>.local`. **TLS-PSK encrypted** and fails closed -- the
+  provisioned token is the pre-shared key; set it on the board over USB once with
+  `hidbridge net-provision`. Needs Python 3.13+ (ssl PSK). Stdlib-only (sockets + ssl); no pyserial,
+  dbus, daemon, or root. See [`../docs/bt-hid-network-backend.md`](../docs/bt-hid-network-backend.md).
+
+Both backends emit the **exact same report bytes** via `hidbridge.reports` (the single source of
+truth for the HID report descriptor), so behaviour is identical regardless of transport.
+
+## Install
+
+**As a consumer** (released wheels are on PyPI):
+
+```bash
+pip install "hidbridge[mcu]"      # + pyserial for the Pico/ESP32 serial backend
+pip install hidbridge             # core only: reports + the net (TCP) backend
+```
+
+Source, issues and firmware releases: <https://github.com/martinmunk/hidbridge>. The release flow
+(wheel and firmware version independently; the git tag is the version):
+[`docs/releasing.md`](https://github.com/martinmunk/hidbridge/blob/main/docs/releasing.md).
+
+**From source** (this checkout):
+
+```bash
+# from this directory (hidbridge/python)
+pip install -e ".[mcu]"        # Pico / ESP32 serial backend (pyserial)
+pip install -e ".[dongle]"     # BlueZ backend (dbus-python + PyGObject; system python)
+pip install -e ".[dev]"        # + pytest, ruff, build
+```
+
+The **dongle** backend must run under the **system python** (`/usr/bin/python3`) because
+`dbus` + `AF_BLUETOOTH` sockets are only available there. On Debian/Ubuntu install the system
+deps with apt instead of pip:
+
+```bash
+sudo apt install python3-dbus python3-gi
+```
+
+For a venv that still sees them, create it with `--system-site-packages`
+(`uv venv --system-site-packages` or `python3 -m venv --system-site-packages`).
+
+## Quick start
+
+```bash
+# MCU backend (a Pico on /dev/ttyACM0) -- no root, no daemon
+hidbridge --backend pico type "hello world"
+hidbridge --backend pico move 40 0
+hidbridge --backend pico click left
+
+# dongle backend (BlueZ) -- needs the daemon up + root
+sudo hidbridge pair-mode                 # advertise as a keyboard; pair from the host's Bluetooth settings
+sudo hidbridge connect mini5             # (re)connect a bonded target
+sudo hidbridge type "hello"
+sudo hidbridge unlock                    # types the passcode from ~/.config/bt_hid/idevice.pin (never logged)
+
+# named targets (device -> backend map in ~/.config/bt_hid/targets.json)
+hidbridge targets add labpad pico:/dev/ttyACM0 AA:BB:CC:DD:EE:FF
+hidbridge --target labpad type "hi"
+```
+
+Run `hidbridge --help` for the full subcommand list.
+
+## Python API
+
+The driving surface is two context managers that mirror the hardware: a **`HidBridge`** is the board
+channel; **`bridge.connect(name)`** advertises a bonded identity, waits until it is ready, and hands
+back a **`HidSession`** you drive. You pass a *location* ("/dev/ttyUSB3", a net host, "hci1", or
+nothing to autodetect) -- never a board type; the board self-identifies into `bridge.info` /
+`bridge.capabilities`.
+
+```python
+from hidbridge import HidBridge
+
+with HidBridge("/dev/ttyUSB3") as bridge, bridge.connect("laptop3") as s:
+    s.type("hello world")
+    s.key("enter")
+    s.move(40, 0)          # relative pointer
+    s.click("left")
+    s.scroll(-3)
+# leaving the `with` disconnects but keeps the bond -- no idle connections
+```
+
+The session verbs are the whole vocabulary: `type(text)`, `key(name, mod=0)`, `move(dx, dy)`,
+`click(button="left")`, `scroll(clicks)`. Who builds the report bytes is a backend detail -- an MCU
+board delegates each verb to the firmware (the target slot's keyboard layout applies board-side); a
+dongle builds the bytes host-side. Either way the surface is identical. "Unlock an iPad" is just
+typing the passcode: `s.type(pin); s.key("enter")`.
+
+For the single-host case, `hidbridge.session(location, device)` opens the board, connects the one
+device, and yields the session (tearing both down on exit):
+
+```python
+from hidbridge import session
+
+with session("/dev/ttyUSB3", "laptop3") as s:
+    s.type("hi")
+```
+
+Errors are typed under `HidbridgeError`: `NotBonded`, `ConnectTimeout`, `Unsupported`,
+`CapacityError`, `IncompatibleFirmware`. Multiple sessions can be open at once on a board that
+supports it (the ESP32 holds several identities); otherwise a second `connect()` raises. The wheel
+version is `hidbridge.__version__`.
+
+## The passcode PIN (secret, external)
+
+`hidbridge unlock` (and the trust-overlay helper) read the device passcode from
+`~/.config/bt_hid/idevice.pin` -- a `0600` file that lives **outside** this repo and is **never
+committed or logged**. Create it yourself:
+
+```bash
+mkdir -p ~/.config/bt_hid && umask 077 && printf '%s' 1234 > ~/.config/bt_hid/idevice.pin
+```
+
+The passcode is expanded to HID frames locally; only frames are ever sent, never the string.
+
+## Layout
+
+```
+python/
+  pyproject.toml          PEP 621 metadata, console_script `hidbridge`, ruff + pytest config
+  src/hidbridge/          the package
+    reports.py            PURE HID report layer (stdlib only) -- the report-byte source of truth
+    controller.py         backend-agnostic report driver (type/key/move/click/unlock/timeline)
+    conn.py               HidSession: connect-on-demand context manager, readiness gate
+    targets.py            device -> backend registry + per-bond identity slots
+    naming.py             per-adapter runtime names (multi-daemon isolation) + slot names
+    adapter.py            BlueZ adapter discovery / dongle selection (sysfs + dbus)
+    ble_hid.py            the HID-over-GATT peripheral daemon (dongle backend)
+    central.py / central_core.py   on-host BLE-central HID self-test (dongle/MCU parity)
+    transport_pico.py / link_pico.py     Pico serial transport + link backend
+    transport_esp32.py / link_esp32.py   ESP32 serial transport + link backend
+    dismiss_trust.py      hands-free "Trust This Computer" overlay dismissal
+    cli.py                the `hidbridge` command
+    _scripts/             reference launcher + systemd unit + pair-mode/service shell helpers
+  tests/                  pytest suite (offline by default; hardware tests skip)
+```
+
+## Tests
+
+```bash
+pytest                    # offline suite (hardware/live tests skip automatically)
+```
+
+Hardware-gated tests opt in via env vars, e.g. `BT_HID_LOOPBACK=1` (on-host BLE loopback,
+needs two adapters + root) or `BT_HID_CENTRAL=1` (central self-test, needs the built-in adapter
++ an MCU). `*_live.py` tests need a real bonded host.
+
+## Lint
+
+```bash
+ruff check .
+```
+
+The ruleset is deliberately scoped (see `pyproject.toml`): it enforces the pyflakes correctness
+rules but tolerates this codebase's dense one-liner report/parser style.

hidbridge-1.2.3/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hidbridge"
+# Version is single-sourced from src/hidbridge/_version.py (baseline 1.0.0). The `wheel/release/<X.Y.Z>`
+# release build rewrites that file from the git tag before `uv build` -- the tag is the source of
+# truth. See docs/releasing.md.
+dynamic = ["version"]
+description = "Drive a Bluetooth-HID target (iPad / iPhone / any host) from Linux -- keyboard + pointer over the host BlueZ stack or a Pico 2W / ESP32 serial-attached BLE peripheral"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Martin Munk Hansen" }]
+keywords = ["bluetooth", "ble", "hid", "hog", "keyboard", "mouse", "ipad", "bluez", "pico", "esp32"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Hardware :: Universal Serial Bus (USB) :: Human Interface Device (HID)",
+]
+
+# Core runtime is stdlib-only for the PURE report layer (hidbridge.reports).
+# Backends pull extra deps -- install the extra(s) you need:
+#   pip install "hidbridge[mcu]"      # Pico / ESP32 over USB serial (pyserial)
+#   pip install "hidbridge[dongle]"   # the host's own BlueZ stack (dbus + PyGObject)
+# On Debian/Ubuntu the dongle backend deps are usually the apt packages
+# python3-dbus + python3-gi (system-python only); the [dongle] extra is provided
+# for venvs built with --system-site-packages.
+dependencies = []
+
+[project.optional-dependencies]
+mcu = ["pyserial>=3.5"]
+dongle = ["dbus-python>=1.2", "PyGObject>=3.40"]
+dev = ["pytest>=7.0", "ruff>=0.4", "build>=1.0", "pyserial>=3.5"]
+
+[project.scripts]
+hidbridge = "hidbridge.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/martinmunk/hidbridge"
+Repository = "https://github.com/martinmunk/hidbridge"
+Issues = "https://github.com/martinmunk/hidbridge/issues"
+
+[tool.hatch.version]
+# Single-source the version from the package (release build rewrites this file from the git tag).
+path = "src/hidbridge/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hidbridge"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hidbridge", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+# --- lint: mirrors the source project's scoped ruleset (dense bit-parser style is deliberate) ---
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+# EXPLICIT select (not extend-select): pin the exact rule scope so a ruff release that BROADENS its
+# default set (0.16 did -- it started pulling RUF/S/SIM/UP/I/... and lit up 160 house-style "errors")
+# cannot silently expand what CI enforces. This is pyflakes correctness (F) + the E4/E7/E9 + W subset,
+# and nothing else; the dense one-liner report/bit style stays tolerated (see the ignore list below).
+select = ["E4", "E7", "E9", "F", "W"]
+ignore = [
+    "E701", "E702", "E703",      # multi-statement one-liners: deliberate in the report/bit code
+    "E401",                       # `import a,b,c`: deliberate house style
+    "E402",                       # imports after a guarded block
+    "E731", "E741",              # lambda-assign / ambiguous names (l, I, O): harmless here
+    "F841",                       # unused locals often capture a parsed field with a side effect
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: requires real hardware (BT adapter / MCU / iPad); deselected by default",
+]

hidbridge-1.2.3/src/hidbridge/__init__.py

@@ -0,0 +1,42 @@
+"""bt_hid -- Linux Bluetooth-HID peripheral toolbox (keyboard + mouse to an iPad/iPhone).
+
+Import `bt_hid.reports` for the PURE report layer (stdlib only). The emulator / adapter modules
+pull in bluetooth deps (AF_BLUETOOTH sockets, dbus) that only exist under the system python, so
+they are NOT imported here -- import them explicitly when needed.
+
+`HidBridge` is the driving entry point (`with HidBridge(...) as bridge: bridge.connect(...) as s`),
+with `session()` a single-host shorthand. The `bridge` module imports only the stdlib-clean
+controller/reports layers at load time (the real serial/net/dongle board drivers are pulled in
+lazily), so `import hidbridge` stays free of bluetooth/serial deps.
+"""
+
+from ._version import __version__  # noqa: E402
+from .bridge import (  # noqa: E402
+    CapacityError,
+    ConnectTimeout,
+    HidBridge,
+    HidbridgeError,
+    HidSession,
+    IncompatibleFirmware,
+    NotBonded,
+    ProbeError,
+    Unsupported,
+    session,
+)
+
+
+def discover():
+    """List plugged-in hidbridge boards: [{port, board, fw, device}] (vendor-gated + handshake).
+
+    Lazy-imports the serial drivers so `import hidbridge` stays free of serial/dbus deps.
+    """
+    from .board import discover as _discover
+    return _discover()
+
+
+__all__ = [
+    "__version__",
+    "HidBridge", "HidSession", "session", "discover",
+    "HidbridgeError", "NotBonded", "ConnectTimeout", "Unsupported", "CapacityError",
+    "IncompatibleFirmware", "ProbeError",
+]

hidbridge-1.2.3/src/hidbridge/_scripts/bt-hid.service.in

@@ -0,0 +1,19 @@
+[Unit]
+Description=bt_hid BLE HID keyboard+mouse peripheral on adapter %i (dongle only)
+Documentation=file://__REPO__/tools/bt_hid/README.md
+After=bluetooth.service
+Wants=bluetooth.service
+
+[Service]
+Type=simple
+# Instance %i is the ADAPTER id (hciN / MAC / USB-path). Each instance pins ONE dongle and gets its
+# OWN per-adapter control socket + D-Bus objects + advertised name (see tools/bt_hid/naming.py), so
+# you can run bt-hid@hci1 and bt-hid@hci2 side by side to two different iPads. Do NOT set a fixed
+# BT_HID_SOCK here -- that would force every instance onto one socket and re-introduce the collision.
+ExecStart=/usr/bin/python3 __REPO__/tools/bt_hid/bt_hid --adapter %i pair-mode
+Restart=on-failure
+RestartSec=2
+# The daemon refuses the built-in adapter by design; it only ever configures the dongle.
+
+[Install]
+WantedBy=multi-user.target

hidbridge-1.2.3/src/hidbridge/_scripts/bt_hid

@@ -0,0 +1,11 @@
+#!/usr/bin/python3
+"""bt_hid launcher -- MUST run under the system python (needs dbus + AF_BLUETOOTH; uv's CPython
+lacks both). Thin shim onto bt_hid.cli.main().
+"""
+import os
+import sys
+
+from hidbridge.cli import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()

hidbridge-1.2.3/src/hidbridge/_scripts/pair-mode.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Bring the USB Bluetooth dongle up as a discoverable BLE HID keyboard so an iPad/iPhone can pair.
+# Runs the daemon in the foreground (Ctrl-C to stop). Uses sudo (BlueZ adapter config needs root).
+# Scoped to the DONGLE only; refuses the built-in adapter unless BT_HID_FORCE_BUILTIN=1.
+#
+# Multi-adapter: set BT_HID_ADAPTER=hciN to pin a specific dongle (default: auto-detect the sole
+# dongle -- errors if ambiguous; run `tools/bt_hid/bt_hid preflight`). The advertised name defaults
+# to HIDBRIDGE-dongle-<hciN> (per-adapter) unless BT_HID_NAME is set.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# --adapter is a PARENT (pre-subcommand) option; --name/--force-builtin are pair-mode options.
+PARENT=()
+[ -n "${BT_HID_ADAPTER:-}" ] && PARENT+=(--adapter "$BT_HID_ADAPTER")
+SUB=(pair-mode)
+[ -n "${BT_HID_NAME:-}" ] && SUB+=(--name "$BT_HID_NAME")
+[ "${BT_HID_FORCE_BUILTIN:-0}" = "1" ] && SUB+=(--force-builtin)
+echo "Starting BLE HID keyboard on the dongle (${BT_HID_ADAPTER:-auto}); pair from the iPad now."
+exec sudo -n BT_HID_ADAPTER="${BT_HID_ADAPTER:-}" BT_HID_NAME="${BT_HID_NAME:-}" \
+     /usr/bin/python3 "$HERE/bt_hid" "${PARENT[@]}" "${SUB[@]}"

hidbridge-1.2.3/src/hidbridge/_scripts/service.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Manage the bt_hid BLE HID daemon as a systemd unit (persists across shells + reboots).
+# Branch-tracked (unit template = bt-hid.service.in) so it is reviewable + cleanly removable --
+# NOT a hand-installed artifact. The unit is a templated instance bt-hid@<ADAPTER>.service: the
+# instance parameter is the ADAPTER id (hciN), so you can run one daemon PER dongle concurrently
+# (bt-hid@hci1 to iPadA + bt-hid@hci2 to iPadB). Each instance gets its own per-adapter control
+# socket + D-Bus objects + advertised name (see tools/bt_hid/naming.py).
+#
+# Usage:
+#   sudo tools/bt_hid/service.sh install [ADAPTER]   # install + enable + start (default: auto dongle)
+#   sudo tools/bt_hid/service.sh start   [ADAPTER]
+#   sudo tools/bt_hid/service.sh stop    [ADAPTER]
+#   sudo tools/bt_hid/service.sh status  [ADAPTER]
+#   sudo tools/bt_hid/service.sh logs    [ADAPTER]
+#   sudo tools/bt_hid/service.sh uninstall [ADAPTER] # stop + disable + remove the unit file
+#
+# ADAPTER defaults to the auto-resolved single dongle (errors if ambiguous -- run `bt_hid preflight`).
+# For a quick throwaway run without installing a persistent unit, use:  tools/bt_hid/pair-mode.sh
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/../.." && pwd)"
+UNIT_TEMPLATE="/etc/systemd/system/bt-hid@.service"
+CMD="${1:-status}"
+# Resolve the adapter instance: explicit arg, else the auto-detected sole dongle's hciN.
+default_adapter() {
+  /usr/bin/python3 "$HERE/bt_hid" adapters 2>/dev/null | awk '/<-- USED/{print $1; exit}'
+}
+ADAPTER="${2:-$(default_adapter || true)}"
+[ -n "$ADAPTER" ] || { echo "no adapter given and none auto-resolved; run: $HERE/bt_hid preflight"; exit 2; }
+INSTANCE="bt-hid@${ADAPTER}.service"
+
+need_root() { [ "$(id -u)" = "0" ] || { echo "run with sudo"; exit 1; }; }
+
+install_unit() {
+  need_root
+  sed "s#__REPO__#${REPO}#g" "$HERE/bt-hid.service.in" > "$UNIT_TEMPLATE"
+  systemctl daemon-reload
+  echo "installed $UNIT_TEMPLATE (REPO=$REPO)"
+}
+
+case "$CMD" in
+  install)
+    install_unit
+    systemctl enable --now "$INSTANCE"
+    systemctl --no-pager status "$INSTANCE" | head -6 || true
+    ;;
+  start)   need_root; [ -f "$UNIT_TEMPLATE" ] || install_unit; systemctl start "$INSTANCE"; systemctl --no-pager status "$INSTANCE" | head -5 || true ;;
+  stop)    need_root; systemctl stop "$INSTANCE" || true ;;
+  status)  systemctl --no-pager status "$INSTANCE" | head -8 || true ;;
+  logs)    journalctl -u "$INSTANCE" --no-pager -n "${3:-40}" ;;
+  uninstall)
+    need_root
+    systemctl disable --now "$INSTANCE" 2>/dev/null || true
+    rm -f "$UNIT_TEMPLATE"
+    systemctl daemon-reload
+    echo "removed $UNIT_TEMPLATE"
+    ;;
+  *) echo "usage: $0 {install|start|stop|status|logs|uninstall} [ADAPTER]"; exit 2 ;;
+esac