wakemypc 1.0.0__py3-none-any.whl

wakemypc/flash.py

@@ -0,0 +1,230 @@
+"""
+flash.py -- Flash MicroPython firmware (.uf2) onto a Raspberry Pi Pico
+======================================================================
+
+WHAT IS FIRMWARE?
+-----------------
+"Firmware" is the base software that runs on a microcontroller. Think of it like
+the operating system on your computer. Without firmware, the Pico is a blank chip
+that cannot do anything.
+
+We use MicroPython as our firmware. MicroPython is a tiny version of Python that
+runs directly on microcontrollers. Once MicroPython is installed, you can write
+Python scripts and the Pico will execute them.
+
+WHAT IS A .uf2 FILE?
+---------------------
+UF2 stands for "USB Flashing Format". It is a special file format designed by
+Microsoft for flashing microcontrollers. The key insight is:
+
+  A .uf2 file can be flashed by simply copying it to a USB drive.
+
+No special programmer hardware needed. No complex flashing software. Just drag
+and drop (or cp on the command line).
+
+HOW BOOTSEL MODE WORKS
+-----------------------
+BOOTSEL = "Boot Select". The Pico has a physical button labeled BOOTSEL on the board.
+
+  1. Unplug the Pico from USB.
+  2. Hold down the BOOTSEL button (it is a small white button on the board).
+  3. While holding BOOTSEL, plug the USB cable back in.
+  4. Release the BOOTSEL button.
+
+Now the Pico appears as a USB mass storage device -- just like a flash drive!
+It will show up as a drive called "RPI-RP2" (for original Pico) or "RP2350"
+(for Pico 2 / Pico W 2).
+
+The drive is tiny (only a few hundred KB) and contains two files:
+  - INFO_UF2.TXT  (information about the bootloader)
+  - INDEX.HTM     (a redirect to the Raspberry Pi documentation)
+
+To flash new firmware, you just copy a .uf2 file onto this drive. The Pico
+detects the new file, writes it to its internal flash memory, and automatically
+reboots. After reboot, the Pico is no longer a USB drive -- it is now running
+whatever firmware was in the .uf2 file.
+
+AFTER FLASHING
+--------------
+Once MicroPython is flashed, the Pico reboots and appears as a USB serial device.
+You can then connect to it via serial port (e.g. /dev/ttyACM0) and type Python
+commands interactively, or upload .py files for it to run.
+"""
+
+import platform
+import shutil
+import time
+from pathlib import Path
+
+
+# Known mount point names for Pico in BOOTSEL mode.
+# These are the "drive names" that appear when the Pico is in BOOTSEL.
+BOOTSEL_DRIVE_NAMES = {"RPI-RP2", "RP2350"}
+
+
+def find_bootsel_drive():
+    """
+    Look for a Pico in BOOTSEL mode by searching for its USB mass storage mount point.
+
+    On Linux:   typically mounted at /media/<username>/RPI-RP2 or /run/media/...
+    On macOS:   typically mounted at /Volumes/RPI-RP2
+    On Windows: appears as a new drive letter like E:\\
+
+    Returns the path to the mounted drive, or None if not found.
+    """
+    system = platform.system()
+
+    if system == "Linux":
+        # On Linux, removable drives are usually auto-mounted under /media/<user>/
+        # or /run/media/<user>/ depending on the desktop environment.
+        search_dirs = []
+
+        # Check /media/<username>/
+        media_path = Path("/media")
+        if media_path.exists():
+            for user_dir in media_path.iterdir():
+                if user_dir.is_dir():
+                    search_dirs.append(user_dir)
+
+        # Check /run/media/<username>/
+        run_media_path = Path("/run/media")
+        if run_media_path.exists():
+            for user_dir in run_media_path.iterdir():
+                if user_dir.is_dir():
+                    search_dirs.append(user_dir)
+
+        for search_dir in search_dirs:
+            for drive_name in BOOTSEL_DRIVE_NAMES:
+                candidate = search_dir / drive_name
+                if candidate.is_dir() and (candidate / "INFO_UF2.TXT").exists():
+                    return str(candidate)
+
+    elif system == "Darwin":
+        # macOS mounts volumes under /Volumes/
+        for drive_name in BOOTSEL_DRIVE_NAMES:
+            candidate = Path("/Volumes") / drive_name
+            if candidate.is_dir() and (candidate / "INFO_UF2.TXT").exists():
+                return str(candidate)
+
+    elif system == "Windows":
+        # On Windows, check all drive letters for the BOOTSEL drive.
+        # The drive will have INFO_UF2.TXT in its root.
+        import string
+
+        for letter in string.ascii_uppercase:
+            candidate = Path(f"{letter}:\\")
+            if candidate.exists() and (candidate / "INFO_UF2.TXT").exists():
+                return str(candidate)
+
+    return None
+
+
+def read_bootsel_info(drive_path):
+    """
+    Read the INFO_UF2.TXT file on the BOOTSEL drive to get board information.
+
+    This file contains lines like:
+      UF2 Bootloader v1.0
+      Model: Raspberry Pi RP2350
+      Board-ID: RPI-RP2350
+    """
+    info_file = Path(drive_path) / "INFO_UF2.TXT"
+    if info_file.exists():
+        return info_file.read_text()
+    return "INFO_UF2.TXT not found"
+
+
+def flash_uf2(uf2_path, drive_path=None):
+    """
+    Flash a .uf2 firmware file to a Pico in BOOTSEL mode.
+
+    This is literally just copying a file to a USB drive. That is all flashing is!
+    The Pico's bootloader detects the .uf2 file, writes it to internal flash,
+    and reboots automatically.
+
+    Parameters:
+        uf2_path:   Path to the .uf2 firmware file (e.g. "micropython-pico-w2.uf2")
+        drive_path: Path to the BOOTSEL drive. If None, auto-detect.
+
+    Returns:
+        True on success, raises on failure.
+    """
+    uf2_path = Path(uf2_path)
+
+    # Validate the .uf2 file exists
+    if not uf2_path.exists():
+        raise FileNotFoundError(
+            f"UF2 file not found: {uf2_path}\n"
+            f"\n"
+            f"You need to download the MicroPython firmware for your Pico variant.\n"
+            f"Get it from: https://micropython.org/download/\n"
+            f"  - For Pico W 2: look for 'RPI_PICO2_W' or 'PICO2-W'\n"
+            f"  - The file will be named something like: RPI_PICO2_W-v1.xx.x.uf2"
+        )
+
+    if not uf2_path.suffix.lower() == ".uf2":
+        raise ValueError(
+            f"File does not have .uf2 extension: {uf2_path}\n"
+            f"Make sure you downloaded the correct firmware file."
+        )
+
+    # Find the BOOTSEL drive
+    if drive_path is None:
+        drive_path = find_bootsel_drive()
+        if drive_path is None:
+            raise RuntimeError(
+                "No Pico in BOOTSEL mode detected.\n"
+                "\n"
+                "To put the Pico in BOOTSEL mode:\n"
+                "  1. Unplug the Pico from USB.\n"
+                "  2. Hold down the BOOTSEL button (small white button on the board).\n"
+                "  3. While holding BOOTSEL, plug the USB cable back in.\n"
+                "  4. Release the BOOTSEL button.\n"
+                "\n"
+                "The Pico should appear as a USB drive named 'RPI-RP2' or 'RP2350'.\n"
+                "If it does not appear, try a different USB cable -- some cables are\n"
+                "charge-only and do not carry data."
+            )
+
+    # Read board info before flashing (for display purposes)
+    board_info = read_bootsel_info(drive_path)
+
+    # The actual flash: copy the .uf2 file to the BOOTSEL drive.
+    # shutil.copy2 preserves file metadata. The Pico's bootloader will
+    # detect the new file and start writing it to flash memory.
+    dest = Path(drive_path) / uf2_path.name
+    shutil.copy2(str(uf2_path), str(dest))
+
+    # After the copy completes, the Pico will automatically reboot.
+    # The BOOTSEL drive will disappear (unmount) as the Pico restarts.
+    # Give it a moment to start the reboot process.
+    return {
+        "uf2_file": str(uf2_path),
+        "drive_path": drive_path,
+        "board_info": board_info,
+    }
+
+
+def wait_for_serial_after_flash(timeout=15):
+    """
+    After flashing, wait for the Pico to reboot and appear as a serial device.
+
+    The typical sequence after flashing MicroPython:
+      1. .uf2 is copied to BOOTSEL drive (~2 seconds)
+      2. Pico writes firmware to flash memory (~3 seconds)
+      3. Pico reboots (~1 second)
+      4. MicroPython starts and USB serial device appears (~2 seconds)
+
+    Total: about 5-10 seconds.
+    """
+    # Import here to avoid circular imports
+    from .serial_detect import list_pico_serial_ports
+
+    start = time.time()
+    while time.time() - start < timeout:
+        picos = list_pico_serial_ports()
+        if picos:
+            return picos[0]["port"]
+        time.sleep(1)
+
+    return None

wakemypc/identify.py

@@ -0,0 +1,212 @@
+"""
+identify.py -- Blink the Pico's LED for physical identification
+================================================================
+
+WHY YOU NEED THIS
+-----------------
+Imagine you have 5 Picos plugged into a USB hub, and your computer shows them as:
+    /dev/ttyACM0
+    /dev/ttyACM1
+    /dev/ttyACM2
+    /dev/ttyACM3
+    /dev/ttyACM4
+
+Which physical Pico is /dev/ttyACM2? They all look the same! You cannot tell
+just by looking at them.
+
+The "identify" command solves this: it tells a specific Pico to blink its LED
+rapidly. Now you can look at your pile of Picos and see which one is blinking.
+Then you can label it with a sticker or note its position.
+
+HOW IT WORKS
+------------
+We send a small Python script to the Pico via the serial REPL (the interactive
+Python prompt accessible over USB). The script:
+
+  1. Imports the 'machine' module (MicroPython's hardware control library).
+  2. Gets a reference to the onboard LED pin.
+     - On Pico W / Pico W 2, the LED is connected to the WiFi chip, so we
+       use the string "LED" instead of a pin number.
+  3. Toggles the LED on and off rapidly in a loop.
+
+The Pico W 2's onboard LED is a small green LED next to the USB connector.
+It is not super bright, but it is visible enough to identify the device.
+
+SERIAL REPL COMMUNICATION
+--------------------------
+The serial REPL is like having a Python terminal running on the Pico. When you
+open a serial connection (like we do here), you can type Python code and the
+Pico executes it immediately. This is the same thing that happens when you use
+tools like Thonny, PuTTY, or 'screen' to talk to the Pico.
+
+We use "raw REPL" mode (entered with Ctrl+A) for sending multi-line scripts.
+In raw mode, there is no echo or prompt, making it easier for programs (vs humans)
+to communicate with the Pico.
+"""
+
+import time
+
+import serial
+
+
+# The MicroPython script that runs ON THE PICO (not on your computer!).
+# This script is sent over USB serial and executed by the Pico's MicroPython
+# interpreter.
+#
+# Note: This code uses MicroPython APIs (machine.Pin, time.sleep) which are
+# different from regular Python. These only work on the Pico, not on your computer.
+BLINK_SCRIPT = """\
+import machine
+import time
+
+# On Pico W and Pico W 2, the onboard LED is controlled via the WiFi chip,
+# so we reference it by the string "LED" rather than a GPIO pin number.
+# On the original Pico (non-W), the LED is on GPIO 25: machine.Pin(25, machine.Pin.OUT)
+led = machine.Pin("LED", machine.Pin.OUT)
+
+# Blink rapidly 20 times (takes about 4 seconds total).
+# Each cycle: 100ms on + 100ms off = 200ms per blink.
+for i in range(20):
+    led.on()
+    time.sleep(0.1)
+    led.off()
+    time.sleep(0.1)
+
+# Leave the LED off when done
+led.off()
+print("IDENTIFY_DONE")
+"""
+
+
+def blink_led(port, duration_seconds=4, baudrate=115200):
+    """
+    Make a Pico's onboard LED blink rapidly for physical identification.
+
+    Parameters:
+        port:             Serial port path, e.g. "/dev/ttyACM0"
+        duration_seconds: Approximate duration of blinking (not precise)
+        baudrate:         Serial speed (115200 is standard for MicroPython)
+
+    How it works:
+        1. Open a serial connection to the Pico.
+        2. Enter raw REPL mode (Ctrl+A) for clean script execution.
+        3. Send the blink script.
+        4. Wait for the script to finish.
+        5. Return to normal REPL mode (Ctrl+B).
+
+    The raw REPL protocol:
+        - Ctrl+A (0x01): Enter raw REPL mode. Pico responds with "raw REPL; CTRL-B to exit"
+        - Send Python code as plain text.
+        - Ctrl+D (0x04): Execute the code. Pico responds with "OK" then output then Ctrl+D.
+        - Ctrl+B (0x02): Exit raw REPL, return to normal interactive mode.
+    """
+    try:
+        ser = serial.Serial(port, baudrate, timeout=2)
+    except serial.SerialException as e:
+        raise RuntimeError(
+            f"Could not open serial port {port}: {e}\n"
+            f"\n"
+            f"Make sure:\n"
+            f"  - The Pico is plugged in and has MicroPython installed\n"
+            f"  - No other program (Thonny, screen, etc.) is using the port\n"
+            f"  - You have permission to access the port (Linux: add yourself to 'dialout' group)"
+        )
+
+    time.sleep(0.5)
+
+    # Interrupt any currently running program on the Pico.
+    # Sending Ctrl+C (0x03) twice is the standard way to get back to the REPL
+    # prompt, even if a program is in the middle of a time.sleep() or a loop.
+    ser.write(b"\r\x03\x03")
+    time.sleep(0.5)
+    ser.read(ser.in_waiting)  # Discard any buffered output
+
+    # Enter raw REPL mode.
+    # Normal REPL: echoes what you type, has ">>> " prompt, auto-indents.
+    # Raw REPL: no echo, no prompt, executes code blocks terminated by Ctrl+D.
+    # Raw mode is better for programmatic use because we do not have to parse prompts.
+    ser.write(b"\x01")  # Ctrl+A = enter raw REPL
+    time.sleep(0.3)
+    ser.read(ser.in_waiting)  # Read and discard the "raw REPL" banner
+
+    # Calculate blink count based on desired duration.
+    # Each blink cycle is ~200ms (100ms on + 100ms off).
+    blink_count = max(5, int(duration_seconds / 0.2))
+
+    # Build the script with the custom blink count
+    script = (
+        "import machine\n"
+        "import time\n"
+        'led = machine.Pin("LED", machine.Pin.OUT)\n'
+        f"for i in range({blink_count}):\n"
+        "    led.on()\n"
+        "    time.sleep(0.1)\n"
+        "    led.off()\n"
+        "    time.sleep(0.1)\n"
+        "led.off()\n"
+        'print("IDENTIFY_DONE")\n'
+    )
+
+    # Send the script and execute it
+    ser.write(script.encode())
+    ser.write(b"\x04")  # Ctrl+D = execute the code
+
+    # Wait for the blinking to finish.
+    # The script takes approximately `duration_seconds` to complete.
+    timeout = duration_seconds + 5  # Extra buffer for slow serial
+    start = time.time()
+    response = b""
+
+    while time.time() - start < timeout:
+        if ser.in_waiting:
+            response += ser.read(ser.in_waiting)
+            if b"IDENTIFY_DONE" in response:
+                break
+        time.sleep(0.1)
+
+    # Exit raw REPL mode and return to normal mode
+    ser.write(b"\x02")  # Ctrl+B = exit raw REPL
+    time.sleep(0.2)
+    ser.close()
+
+    success = b"IDENTIFY_DONE" in response
+    return {
+        "port": port,
+        "success": success,
+        "duration": duration_seconds,
+        "message": (
+            f"LED on {port} blinked for ~{duration_seconds} seconds."
+            if success
+            else f"Blink command was sent to {port} but completion was not confirmed."
+        ),
+    }
+
+
+def read_device_id_and_blink(port, baudrate=115200):
+    """
+    Read the device ID AND blink the LED, so the user can match ID to physical device.
+
+    This is a convenience function that:
+      1. Reads the Pico's unique hardware ID.
+      2. Blinks the LED so you can see which physical Pico it is.
+      3. Returns both the device ID and the port, so you can label the device.
+
+    Typical usage:
+        "I have 3 Picos. Let me identify each one."
+        For each port, call this function. It will tell you:
+        "Port /dev/ttyACM0 has device ID e660583883724a32 -- that's the one blinking now."
+    """
+    from .provision import read_device_id
+
+    device_id = read_device_id(port)
+    blink_result = blink_led(port)
+
+    return {
+        "port": port,
+        "device_id": device_id,
+        "blink_success": blink_result["success"],
+        "message": (
+            f"Device on {port} has ID: {device_id}\n"
+            f"The LED is blinking now -- look for the flashing green light!"
+        ),
+    }