flash: use esptool write-flash, always show port menu, add flash command

- Use esptool v5's `write-flash` (no more deprecation warning); pin esptool>=5.
- Interactive runs always list the ports and wait for a choice (Enter = first) instead of silently auto-picking a lone port and flashing.
- New `flash` console script so the one-off shortens to `uvx --from "python-esp-bridge[flash]" flash` (`espbridge flash` still works).
- Bump to 0.12.1; update README/FIRMWARE docs.

Author: HamzaYslmn

README.md

@@ -32,7 +32,7 @@ are implemented in Python where they are easy to read, test and extend.
    one, it writes a *Huge APP* image with esptool):
 
    ```sh
-   uvx --from "python-esp-bridge[flash]" espbridge flash   # or: espbridge flash
+   uvx --from "python-esp-bridge[flash]" flash   # zero-install via uv
    ```
 
    Prefer building it yourself? Install the **`python esp bridge`** library

docs/FIRMWARE.md

@@ -94,12 +94,12 @@ toolchain. It lists the serial ports, lets you pick one, and writes the image
 over USB with esptool:
 
 ```sh
-uvx --from "python-esp-bridge[flash]" espbridge flash   # zero-install via uv
-# or, once installed:  pip install "python-esp-bridge[flash]"
-espbridge flash                # list ports and choose
-espbridge flash -p COM5        # flash a specific port
-espbridge flash --erase        # wipe the whole flash first (clears NVS / name)
-espbridge flash --firmware my.bin   # flash your own image instead
+uvx --from "python-esp-bridge[flash]" flash   # zero-install via uv
+# or install once:  uv tool install "python-esp-bridge[flash]"  /  pip install "python-esp-bridge[flash]"
+flash                # list ports and choose (also: espbridge flash)
+flash -p COM5        # flash a specific port
+flash --erase        # wipe the whole flash first (clears NVS / name)
+flash --firmware my.bin   # flash your own image instead
 ```
 
 The bundled image is a **classic-ESP32 Huge APP** build (no OTA — for cable-free

library.properties

@@ -1,5 +1,5 @@
 name=python esp bridge
-version=0.12.0
+version=0.12.1
 author=Hamza Yesilmen <resmiyslmn@gmail.com>
 maintainer=Hamza Yesilmen <resmiyslmn@gmail.com>
 sentence=Flash-once ESP32 firmware that exposes every peripheral to Python over USB serial or Bluetooth.

python/espbridge/__init__.py

@@ -56,7 +56,7 @@ def __getattr__(name):
         return AsyncBridge
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-__version__ = "0.12.0"
+__version__ = "0.12.1"
 
 __all__ = [
     "Bridge",

python/espbridge/flash.py

@@ -21,6 +21,7 @@
 """
 from __future__ import annotations
 
+import sys
 from importlib import resources
 from pathlib import Path
 
@@ -70,20 +71,23 @@ def _all_serial_ports() -> list[PortInfo]:
 
 
 def _choose_port(ports: list[PortInfo]) -> str:
-    """Print a numbered menu and read the operator's choice."""
+    """Print a numbered menu and read the operator's choice (Enter picks #1)."""
     print("Available serial ports:")
     for i, p in enumerate(ports, 1):
         chip = f"  [{p.usb_chip}]" if p.usb_chip else ""
         desc = f"  {p.description}" if p.description else ""
         print(f"  {i}) {p.device}{chip}{desc}")
+    prompt = f"Select a port [1-{len(ports)}, Enter = 1, q = cancel]: "
     while True:
         try:
-            raw = input(f"Select a port [1-{len(ports)}] (q to cancel): ").strip()
+            raw = input(prompt).strip()
         except EOFError:
             raise BridgeError("no port selected (no interactive console; "
                               "pass -p PORT explicitly)")
         if raw.lower() in ("q", "quit"):
             raise BridgeError("cancelled")
+        if raw == "":  # bare Enter → the first (most likely) port
+            return ports[0].device
         if raw.isdigit() and 1 <= int(raw) <= len(ports):
             return ports[int(raw) - 1].device
         for p in ports:  # also accept typing the port name directly
@@ -93,16 +97,22 @@ def _choose_port(ports: list[PortInfo]) -> str:
 
 
 def select_port(port: str | None = None) -> str:
-    """Resolve a port: honour an explicit one, else auto-pick or prompt."""
+    """Resolve a port: honour an explicit one, else show the menu (or, with no
+    interactive console, auto-pick a lone port)."""
     if port:
         return port
     ports = find_ports() or _all_serial_ports()
     if not ports:
         raise BridgeError("no serial ports found — plug the ESP32 in over USB, "
                           "or pass -p PORT")
-    if len(ports) == 1:
-        log.info(f"using the only serial port found: {ports[0].device}")
-        return ports[0].device
+    interactive = bool(getattr(sys.stdin, "isatty", lambda: False)())
+    if not interactive:  # piped/CI: can't prompt, so a lone port or bust
+        if len(ports) == 1:
+            log.info(f"using the only serial port found: {ports[0].device}")
+            return ports[0].device
+        names = ", ".join(p.device for p in ports)
+        raise BridgeError(f"several serial ports ({names}); pass -p PORT "
+                          "(no interactive console to choose from)")
     return _choose_port(ports)
 
 
@@ -131,8 +141,16 @@ def flash_firmware(port: str | None = None, *,
 
     port = select_port(port)
 
+    # esptool v5 renamed `write_flash` → `write-flash` (the underscore form
+    # still works but prints a deprecation warning); pick by version so we stay
+    # quiet on v5 and keep working on an older v4.
+    try:
+        major = int(esptool.__version__.split(".")[0])
+    except (AttributeError, ValueError):
+        major = 5
+    write_cmd = "write-flash" if major >= 5 else "write_flash"
     argv = ["--chip", chip, "--port", port, "--baud", str(baud),
-            "--before", "default-reset", "--after", "hard-reset", "write_flash"]
+            "--before", "default-reset", "--after", "hard-reset", write_cmd]
     if erase:
         argv.append("--erase-all")
     argv += ["--flash-size", "keep", FIRMWARE_OFFSET, str(fw)]
@@ -150,3 +168,41 @@ def flash_firmware(port: str | None = None, *,
         raise BridgeError(f"flash failed: {e}")
     log.info("done — the board will reboot into the bridge firmware "
              "(connect with `espbridge info`)")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the standalone `flash` command, so the one-off is just
+
+        uvx --from "python-esp-bridge[flash]" flash
+
+    `espbridge flash` runs the same thing through the main CLI.
+    """
+    import argparse
+
+    from . import __version__
+    from .cli import _force_utf8_output
+
+    _force_utf8_output()
+    ap = argparse.ArgumentParser(
+        prog="flash",
+        description="Flash the bundled bridge firmware to an ESP32 over USB.")
+    ap.add_argument("--version", action="version", version=f"espbridge {__version__}")
+    ap.add_argument("-p", "--port", help="serial port to flash (default: list ports and choose)")
+    ap.add_argument("--baud", type=int, default=DEFAULT_BAUD,
+                    help=f"flash baud rate (default: {DEFAULT_BAUD})")
+    ap.add_argument("--erase", action="store_true",
+                    help="erase the whole flash before writing (clears NVS / stored name)")
+    ap.add_argument("--firmware", help="flash this .bin instead of the bundled image")
+    ap.add_argument("--chip", default=FIRMWARE_CHIP, help=f"target chip (default: {FIRMWARE_CHIP})")
+    args = ap.parse_args(argv)
+    try:
+        flash_firmware(args.port, baud=args.baud, erase=args.erase,
+                       firmware=args.firmware, chip=args.chip)
+    except BridgeError as e:
+        log.error(str(e))
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-esp-bridge"
-version = "0.12.0"
+version = "0.12.1"
 description = "Control every ESP32 peripheral from Python over USB serial or Bluetooth — GPIO, ADC, DAC, PWM, touch, I2C, SPI, UART, Wi-Fi sockets, BLE, ESP-NOW, RMT, 1-Wire, CAN, I2S, files, NVS, OTA"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -15,7 +15,7 @@ dependencies = [
 oled = ["pillow>=10"]  # espbridge.oled: PIL drawing for SSD1306/SH1106 displays
 ble = ["bleak>=0.22"]  # kept for back-compat; bleak now ships by default (BLE is the default transport)
 mcp = ["fastmcp>=2.3"]  # espbridge.mcp: MCP server exposing the bridge as tools
-flash = ["esptool>=4.8"]  # espbridge flash: write the bundled firmware over USB serial
+flash = ["esptool>=5"]  # espbridge flash / `flash`: write the bundled firmware over USB serial
 all = ["python-esp-bridge[oled,ble,mcp,flash]"]  # every optional feature at once
 
 [project.urls]
@@ -24,6 +24,7 @@ Homepage = "https://github.com/HamzaYslmn/python-esp-bridge"
 [project.scripts]
 espbridge = "espbridge.cli:main"
 espbridge-mcp = "espbridge.mcp.server:main"
+flash = "espbridge.flash:main"  # `uvx --from "python-esp-bridge[flash]" flash`
 
 # Third-party device drivers: a package advertises its driver classes in this
 # group and they become available as esp.<name>(...) on every bridge, with no

python/uv.lock

@@ -11,7 +11,7 @@
 // tests/test_contract_sync.py enforces the lockstep.
 #define FW_VERSION_MAJOR 0
 #define FW_VERSION_MINOR 12
-#define FW_VERSION_PATCH 0
+#define FW_VERSION_PATCH 1
 
 // Frame (logical, pre-COBS):
 //   flags u8 | seq u8 | cmd u16 BE | payload .. | crc16 BE