From c08e1ef2fa83d572e88a4a19dad8adc9fb162549 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Sun, 11 Oct 2026 03:31:02 -0500 Subject: [PATCH] Install bleak by default, so Bluetooth works from a plain pip install pyproject.toml says every capability comes with a default install, but ble:// needed a separate pip install bleak. bleak is now a dependency, bounded to the majors mpftp has been run on (1.x for Python 3.9, 3.x today). The docs say where it still has to be installed by hand: the Windows Python the sidecar uses on WSL, and the extension's Python. --- CHANGELOG.md | 6 ++++++ README.md | 5 +++++ cli/src/mpftp/ble.py | 8 +++++--- docs/agent-guide.md | 3 ++- docs/user-guide.md | 7 ++++++- pyproject.toml | 9 +++++++-- 6 files changed, 31 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c0e4730..7caf48b 100644 --- a/CHANGELOG.md +++ b/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` diff --git a/README.md b/README.md index 0634ffe..36ba034 100644 --- a/README.md +++ b/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 diff --git a/cli/src/mpftp/ble.py b/cli/src/mpftp/ble.py index f0aa598..d456b9c 100644 --- a/cli/src/mpftp/ble.py +++ b/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 diff --git a/docs/agent-guide.md b/docs/agent-guide.md index d064e1b..6aa9d32 100644 --- a/docs/agent-guide.md +++ b/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). diff --git a/docs/user-guide.md b/docs/user-guide.md index 88ea3e0..bcf9d5a 100644 --- a/docs/user-guide.md +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 874b1d1..0a8072e 100644 --- a/pyproject.toml +++ b/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]