Install bleak by default, so Bluetooth works from a plain pip install

CHANGELOG.md

@@ -15,6 +15,12 @@
   number, so 1.29.0 comes before 1.9.4, and nrf and mimxrt boards with a
   `.uf2` are included.
 
+- `pip install pydevices-mpftp` now installs bleak, so Bluetooth (`-d
+  ble://NAME`) works from a default install like everything else. On WSL the
+  sidecar runs on the Windows Python, which still needs
+  `python.exe -m pip install bleak`, and the VS Code extension's Python needs
+  it for Bluetooth too.
+
 ## v0.1.1 (2026-10-10)
 
 - `firmware ptable` reads a classic ESP32's, an S2's or a P4's `firmware.bin`

README.md

@@ -43,6 +43,11 @@ Published as **`pydevices.mpftp`** under [PyDevices](https://github.com/PyDevice
   - WSL / Windows serial: a Windows Python (it sees the `COM` ports)
   - Native Linux: the system `python3`, or set `mpftp.pythonPath`
 - For CircuitPython packages: [`circup`](https://pypi.org/project/circup/) on the **same** Python (`pip install circup`)
+- For Bluetooth (`ble://`): [`bleak`](https://pypi.org/project/bleak/) on the **same** Python (`pip install bleak`)
+
+`pip install pydevices-mpftp` installs all of these with the CLI and the
+browser interface. The extension bundles only mpremote and pyserial, so its
+Python needs circup and bleak for those two features.
 
 ## Install
 

cli/src/mpftp/ble.py

@@ -11,9 +11,11 @@
 REPL: it's 19 to 35 times faster (measured in docs/plans/ble.md). A board
 without it still works, over the REPL alone.
 
-bleak is the only dependency beyond the standard library, and only for BLE:
-``python -m pip install bleak`` into the Python the sidecar runs on (on WSL,
-the Windows one, because Windows owns the radio).
+bleak is the only dependency beyond the standard library, and only for BLE.
+``pip install pydevices-mpftp`` brings it. The sidecar's Python needs it too
+when that is a different one: on WSL the Windows Python, because Windows owns
+the radio, and the VS Code extension's, which bundles only mpremote and
+pyserial.
 """
 
 from __future__ import annotations

docs/agent-guide.md

@@ -180,7 +180,8 @@ export MPFTP_BLE_PASSWORD=...     # the board's bledev password; never print it
   board has no password. If the board lost its keys (a chip erase), the link
   drops at the first write: unpair (`python -m bledev.bleak unpair NAME`) and
   pair again. Unpair every board you paired before you finish.
-- The sidecar's Windows Python needs bleak (`python.exe -m pip install --user
+- `pip install pydevices-mpftp` brings bleak, but on WSL the sidecar runs on
+  the Windows Python, which needs it too (`python.exe -m pip install --user
   bleak`).
 
 More, including the measurements: [docs/plans/ble.md](plans/ble.md).

docs/user-guide.md

@@ -40,6 +40,9 @@ with a single serial ownership model so the UI and agents do not fight over the
   - **Native Linux:** the system `python3`, or set `mpftp.pythonPath`
 - For CircuitPython libraries: [`circup`](https://pypi.org/project/circup/) on the **same** interpreter
   (`python.exe -m pip install circup` on WSL/Windows)
+- For Bluetooth (`ble://`): [`bleak`](https://pypi.org/project/bleak/) on the same
+  interpreter (`python.exe -m pip install bleak` on WSL/Windows). `pip install
+  pydevices-mpftp` brings both.
 
 ### Install
 
@@ -96,7 +99,9 @@ board started with `pairing="passkey"` needs this computer paired once: run
 `python -m bledev.bleak pair NAME` and type in the passkey the board shows
 (or use Windows Settings, Add device); after that mpftp uses the bond, with no
 password if the board has none. A board with `pairing="justworks"` is paired
-by mpftp itself.
+by mpftp itself. `pip install pydevices-mpftp` installs bleak, the Bluetooth
+library mpftp uses. On WSL the radio belongs to Windows, so the Windows Python
+the sidecar runs on needs it: `python.exe -m pip install bleak`.
 
 In VS Code and the PWA, pick **Look for Bluetooth boards…** in the Connect
 list. It lists what's advertising bledev's REPL nearby, strongest signal

pyproject.toml

@@ -24,13 +24,18 @@ classifiers = [
 # mpremote and pyserial are bounded to the range CI tests: mpftp subclasses
 # mpremote's SerialTransport and calls its internals, which change between
 # releases. circup and esptool are only run through their command lines, so
-# they stay unbounded. extension/vendor-requirements.txt bundles one version
-# of mpremote and pyserial from inside these ranges into the VSIX.
+# they stay unbounded. bleak (Bluetooth, ble://) is called through its public
+# API, bounded below by the first release with the calls mpftp makes and
+# above by the newest major version it has been run on.
+# extension/vendor-requirements.txt bundles one version of mpremote and
+# pyserial from inside these ranges into the VSIX; bleak has native parts per
+# platform, so the extension leaves it to the sidecar's Python.
 dependencies = [
   "mpremote>=1.28,<1.30",
   "pyserial>=3.5,<4",
   "circup",
   "esptool",
+  "bleak>=1.0,<4",
 ]
 
 [project.optional-dependencies]