fbuild 1.2.8__py3-none-any.whl

fbuild/deploy/deployer_esp32.py

@@ -0,0 +1,310 @@
+"""
+Firmware deployment module for uploading to embedded devices.
+
+This module handles flashing firmware to ESP32 devices using esptool.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+from fbuild.config import PlatformIOConfig
+from fbuild.packages import Cache
+
+from .deployer import DeploymentError, DeploymentResult, IDeployer
+
+
+class ESP32Deployer(IDeployer):
+    """Handles firmware deployment to embedded devices."""
+
+    def __init__(self, verbose: bool = False):
+        """Initialize deployer.
+
+        Args:
+            verbose: Whether to show verbose output
+        """
+        self.verbose = verbose
+
+    def deploy(
+        self,
+        project_dir: Path,
+        env_name: str,
+        port: Optional[str] = None,
+    ) -> DeploymentResult:
+        """Deploy firmware to a device.
+
+        Args:
+            project_dir: Path to project directory
+            env_name: Environment name to deploy
+            port: Serial port to use (auto-detect if None)
+
+        Returns:
+            DeploymentResult with success status and message
+        """
+        try:
+            # Load platformio.ini
+            ini_path = project_dir / "platformio.ini"
+            if not ini_path.exists():
+                raise DeploymentError(f"platformio.ini not found in {project_dir}")
+
+            config = PlatformIOConfig(ini_path)
+            env_config = config.get_env_config(env_name)
+
+            # Get board and platform
+            board_id = env_config.get("board")
+            platform_url = env_config.get("platform")
+
+            if not board_id or not platform_url:
+                raise DeploymentError("Board or platform not specified in platformio.ini")
+
+            # Determine platform type
+            if "espressif32" in platform_url or board_id.startswith("esp32"):
+                return self._deploy_esp32(project_dir, env_name, board_id, port, platform_url)
+            else:
+                raise DeploymentError(f"Deployment not supported for board: {board_id}")
+
+        except DeploymentError as e:
+            return DeploymentResult(success=False, message=str(e))
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            return DeploymentResult(success=False, message=f"Unexpected deployment error: {e}")
+
+    def _deploy_esp32(
+        self,
+        project_dir: Path,
+        env_name: str,
+        board_id: str,
+        port: Optional[str],
+        platform_url: str,
+    ) -> DeploymentResult:
+        """Deploy firmware to ESP32 device.
+
+        Args:
+            project_dir: Path to project directory
+            env_name: Environment name
+            board_id: Board identifier
+            port: Serial port (auto-detect if None)
+            platform_url: Platform package URL
+
+        Returns:
+            DeploymentResult with success status
+        """
+        # Get build directory
+        build_dir = project_dir / ".fbuild" / "build" / env_name
+        firmware_bin = (build_dir / "firmware.bin").absolute()
+        bootloader_bin = (build_dir / "bootloader.bin").absolute()
+        partitions_bin = (build_dir / "partitions.bin").absolute()
+
+        if not firmware_bin.exists():
+            raise DeploymentError(f"Firmware not found at {firmware_bin}. Run 'fbuild build' first.")
+
+        # Get cache and ensure platform/toolchain packages
+        cache = Cache(project_dir)
+
+        # Import ESP32 packages
+        from fbuild.packages.framework_esp32 import FrameworkESP32
+        from fbuild.packages.platform_esp32 import PlatformESP32
+
+        # Ensure platform is downloaded first (needed to get board JSON)
+        platform = PlatformESP32(cache, platform_url, show_progress=self.verbose)
+        platform.ensure_platform()
+
+        # Get board JSON to determine MCU and required packages
+        board_json = platform.get_board_json(board_id)
+        mcu = board_json.get("build", {}).get("mcu", "esp32")
+        packages = platform.get_required_packages(mcu)
+
+        # Initialize framework
+        framework_url = packages.get("framework-arduinoespressif32")
+        libs_url = packages.get("framework-arduinoespressif32-libs")
+        if not framework_url or not libs_url:
+            raise DeploymentError("Framework URLs not found in platform package")
+
+        framework = FrameworkESP32(cache, framework_url, libs_url, show_progress=self.verbose)
+        framework.ensure_framework()
+
+        # Auto-detect port if not specified
+        if not port:
+            port = self._detect_serial_port()
+            if not port:
+                raise DeploymentError("No serial port specified and auto-detection failed. " + "Use --port to specify a port.")
+
+        if self.verbose:
+            print(f"Using port: {port}")
+
+        # Determine chip type and flash parameters from board JSON
+        chip = self._get_chip_type(mcu)
+        flash_mode = board_json.get("build", {}).get("flash_mode", "dio")
+
+        # Get flash frequency and convert to esptool format
+        f_flash = board_json.get("build", {}).get("f_flash", "80000000L")
+        if isinstance(f_flash, str) and f_flash.endswith("L"):
+            freq_value = int(f_flash.rstrip("L"))
+            flash_freq = f"{freq_value // 1000000}m"
+        elif isinstance(f_flash, (int, float)):
+            flash_freq = f"{int(f_flash // 1000000)}m"
+        else:
+            flash_freq = "80m"
+
+        flash_size = "detect"
+
+        # CRITICAL FIX: ESP32-C6/C3/C2/H2 ROM bootloader can only load the second-stage
+        # bootloader in DIO mode. Must use DIO for flashing even if app uses QIO.
+        # See: https://github.com/espressif/arduino-esp32/discussions/10418
+        if mcu in ["esp32c6", "esp32c3", "esp32c2", "esp32h2"]:
+            flash_mode = "dio"
+
+        # Determine bootloader offset based on MCU
+        # ESP32/ESP32-S2: 0x1000, ESP32-P4: 0x2000, others: 0x0
+        if mcu in ["esp32", "esp32s2"]:
+            bootloader_offset = "0x1000"
+        elif mcu == "esp32p4":
+            bootloader_offset = "0x2000"
+        else:
+            bootloader_offset = "0x0"
+
+        # Find boot_app0.bin in framework tools
+        boot_app0_bin = framework.framework_path / "tools" / "partitions" / "boot_app0.bin"
+
+        # Build esptool command to flash multiple binaries at different offsets
+        # Flash layout: bootloader @ offset, partition table @ 0x8000, boot_app0 @ 0xe000, app @ 0x10000
+        cmd = [
+            sys.executable,
+            "-m",
+            "esptool",
+            "--chip",
+            chip,
+            "--port",
+            port,
+            "--baud",
+            "460800",
+            "write_flash",
+            "-z",  # Compress
+            "--flash-mode",
+            flash_mode,
+            "--flash-freq",
+            flash_freq,
+            "--flash-size",
+            flash_size,
+        ]
+
+        # Add bootloader if it exists
+        if bootloader_bin.exists():
+            cmd.extend([bootloader_offset, str(bootloader_bin)])
+        else:
+            if self.verbose:
+                print("Warning: bootloader.bin not found, skipping")
+
+        # Add partition table if it exists
+        if partitions_bin.exists():
+            cmd.extend(["0x8000", str(partitions_bin)])
+        else:
+            if self.verbose:
+                print("Warning: partitions.bin not found, skipping")
+
+        # Add boot_app0.bin if it exists
+        if boot_app0_bin.exists():
+            cmd.extend(["0xe000", str(boot_app0_bin)])
+        else:
+            if self.verbose:
+                print("Warning: boot_app0.bin not found, skipping")
+
+        # Add application firmware at 0x10000
+        cmd.extend(["0x10000", str(firmware_bin)])
+
+        if self.verbose:
+            print("Flashing firmware to device...")
+            print(f"  Bootloader: {bootloader_offset}")
+            print("  Partition table: 0x8000")
+            print("  Boot app: 0xe000")
+            print("  Application: 0x10000")
+            print(f"Running: {' '.join(cmd)}")
+
+        # Execute esptool - must use cmd.exe for ESP32 on Windows
+        if sys.platform == "win32":
+            # Run via cmd.exe to avoid msys issues
+            env = os.environ.copy()
+            # Strip MSYS paths that cause issues
+            if "PATH" in env:
+                paths = env["PATH"].split(os.pathsep)
+                filtered_paths = [p for p in paths if "msys" not in p.lower()]
+                env["PATH"] = os.pathsep.join(filtered_paths)
+
+            result = subprocess.run(
+                cmd,
+                cwd=project_dir,
+                capture_output=not self.verbose,
+                text=False,  # Don't decode as text - esptool may output binary data
+                env=env,
+                shell=False,
+            )
+        else:
+            result = subprocess.run(
+                cmd,
+                cwd=project_dir,
+                capture_output=not self.verbose,
+                text=False,  # Don't decode as text - esptool may output binary data
+            )
+
+        if result.returncode != 0:
+            error_msg = "Upload failed"
+            if result.stderr:
+                error_msg = result.stderr.decode("utf-8", errors="replace")
+            return DeploymentResult(success=False, message=f"Deployment failed: {error_msg}", port=port)
+
+        return DeploymentResult(success=True, message="Firmware uploaded successfully", port=port)
+
+    def _get_chip_type(self, mcu: str) -> str:
+        """Get chip type string for esptool from MCU name.
+
+        Args:
+            mcu: MCU type (e.g., "esp32c6", "esp32s3")
+
+        Returns:
+            Chip type for esptool (e.g., "esp32c6", "esp32s3")
+        """
+        # Map MCU names to esptool chip types
+        return mcu  # Usually they match directly
+
+    def _detect_serial_port(self) -> Optional[str]:
+        """Auto-detect serial port for device.
+
+        Returns:
+            Serial port name or None if not found
+        """
+        try:
+            import serial.tools.list_ports
+
+            ports = list(serial.tools.list_ports.comports())
+
+            # Look for ESP32 or USB-SERIAL devices
+            for port in ports:
+                description = (port.description or "").lower()
+                manufacturer = (port.manufacturer or "").lower()
+
+                if any(x in description or x in manufacturer for x in ["cp210", "ch340", "usb-serial", "uart", "esp32"]):
+                    return port.device
+
+            # If no specific match, return first port
+            if ports:
+                return ports[0].device
+
+        except ImportError:
+            if self.verbose:
+                print("pyserial not installed. Cannot auto-detect port.")
+        except KeyboardInterrupt as ke:
+            from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+            handle_keyboard_interrupt_properly(ke)
+            raise  # Never reached, but satisfies type checker
+        except Exception as e:
+            if self.verbose:
+                print(f"Port detection failed: {e}")
+
+        return None

fbuild/deploy/docker_utils.py

@@ -0,0 +1,315 @@
+"""
+Docker utilities for QEMU deployment.
+
+This module provides utilities for managing Docker containers for ESP32 QEMU emulation,
+including automatic Docker daemon startup detection and image management.
+"""
+
+import os
+import platform
+import subprocess
+import sys
+import time
+from typing import Optional
+
+from fbuild.interrupt_utils import handle_keyboard_interrupt_properly
+
+
+def get_docker_env() -> dict[str, str]:
+    """Get environment for Docker commands, handling Git Bash/MSYS2 path conversion."""
+    env = os.environ.copy()
+    # Set UTF-8 encoding environment variables for Windows
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["PYTHONUTF8"] = "1"
+    # Only set MSYS_NO_PATHCONV if we're in a Git Bash/MSYS2 environment
+    if "MSYSTEM" in os.environ or os.environ.get("TERM") == "xterm" or "bash.exe" in os.environ.get("SHELL", ""):
+        env["MSYS_NO_PATHCONV"] = "1"
+    return env
+
+
+def check_docker_daemon_running() -> bool:
+    """Check if Docker daemon is running.
+
+    Returns:
+        True if Docker daemon is running, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+            env=get_docker_env(),
+        )
+        return result.returncode == 0
+    except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def check_docker_installed() -> bool:
+    """Check if Docker is installed.
+
+    Returns:
+        True if Docker is installed, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "--version"],
+            capture_output=True,
+            timeout=5,
+            env=get_docker_env(),
+        )
+        return result.returncode == 0
+    except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def get_docker_desktop_path() -> Optional[str]:
+    """Get the path to Docker Desktop executable.
+
+    Returns:
+        Path to Docker Desktop or None if not found
+    """
+    system = platform.system()
+
+    if system == "Windows":
+        # Common locations for Docker Desktop on Windows
+        paths = [
+            r"C:\Program Files\Docker\Docker\Docker Desktop.exe",
+            r"C:\Program Files (x86)\Docker\Docker\Docker Desktop.exe",
+            os.path.expandvars(r"%ProgramFiles%\Docker\Docker\Docker Desktop.exe"),
+            os.path.expandvars(r"%LocalAppData%\Programs\Docker\Docker\Docker Desktop.exe"),
+        ]
+        for path in paths:
+            if os.path.exists(path):
+                return path
+
+    elif system == "Darwin":  # macOS
+        paths = [
+            "/Applications/Docker.app/Contents/MacOS/Docker Desktop",
+            "/Applications/Docker.app",
+        ]
+        for path in paths:
+            if os.path.exists(path):
+                return path
+
+    elif system == "Linux":
+        # On Linux, Docker usually runs as a service, not a desktop app
+        return None
+
+    return None
+
+
+def start_docker_daemon() -> bool:
+    """Attempt to start the Docker daemon.
+
+    This function tries to start Docker Desktop on Windows/macOS
+    or the Docker service on Linux.
+
+    Returns:
+        True if Docker daemon started successfully, False otherwise
+    """
+    system = platform.system()
+
+    if check_docker_daemon_running():
+        return True
+
+    print("Docker daemon is not running. Attempting to start...")
+
+    if system == "Windows":
+        docker_path = get_docker_desktop_path()
+        if docker_path:
+            try:
+                # Start Docker Desktop without waiting
+                subprocess.Popen(
+                    [docker_path],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NO_WINDOW,
+                )
+                return _wait_for_docker_daemon()
+            except KeyboardInterrupt as ke:
+                handle_keyboard_interrupt_properly(ke)
+            except Exception as e:
+                print(f"Failed to start Docker Desktop: {e}")
+                return False
+        else:
+            print("Docker Desktop not found. Please start Docker Desktop manually.")
+            return False
+
+    elif system == "Darwin":
+        docker_path = get_docker_desktop_path()
+        if docker_path:
+            try:
+                subprocess.Popen(
+                    ["open", "-a", "Docker"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+                return _wait_for_docker_daemon()
+            except KeyboardInterrupt as ke:
+                handle_keyboard_interrupt_properly(ke)
+            except Exception as e:
+                print(f"Failed to start Docker Desktop: {e}")
+                return False
+        else:
+            print("Docker Desktop not found. Please install Docker Desktop.")
+            return False
+
+    elif system == "Linux":
+        try:
+            # Try to start the Docker service using systemctl
+            result = subprocess.run(
+                ["sudo", "systemctl", "start", "docker"],
+                capture_output=True,
+                timeout=30,
+            )
+            if result.returncode == 0:
+                return _wait_for_docker_daemon()
+            else:
+                # Try without sudo (if user has permissions)
+                result = subprocess.run(
+                    ["systemctl", "start", "docker"],
+                    capture_output=True,
+                    timeout=30,
+                )
+                if result.returncode == 0:
+                    return _wait_for_docker_daemon()
+        except KeyboardInterrupt as ke:
+            handle_keyboard_interrupt_properly(ke)
+        except Exception as e:
+            print(f"Failed to start Docker service: {e}")
+
+        print("Failed to start Docker service. Try running: sudo systemctl start docker")
+        return False
+
+    return False
+
+
+def _wait_for_docker_daemon(timeout: int = 60) -> bool:
+    """Wait for Docker daemon to become available.
+
+    Args:
+        timeout: Maximum time to wait in seconds
+
+    Returns:
+        True if Docker daemon is now running, False if timeout
+    """
+    print(f"Waiting for Docker daemon to start (timeout: {timeout}s)...")
+    start_time = time.time()
+
+    while (time.time() - start_time) < timeout:
+        if check_docker_daemon_running():
+            print("Docker daemon is now running!")
+            return True
+        time.sleep(2)
+        sys.stdout.write(".")
+        sys.stdout.flush()
+
+    print("\nTimeout waiting for Docker daemon to start.")
+    return False
+
+
+def ensure_docker_available() -> bool:
+    """Ensure Docker is available, starting daemon if necessary.
+
+    Returns:
+        True if Docker is available, False otherwise
+    """
+    if not check_docker_installed():
+        print("Docker is not installed.")
+        print()
+        print("Install Docker:")
+        print("  - Windows/Mac: https://www.docker.com/products/docker-desktop")
+        print("  - Linux: https://docs.docker.com/engine/install/")
+        return False
+
+    if check_docker_daemon_running():
+        return True
+
+    return start_docker_daemon()
+
+
+def check_docker_image_exists(image_name: str) -> bool:
+    """Check if a Docker image exists locally.
+
+    Args:
+        image_name: Name of the Docker image to check
+
+    Returns:
+        True if image exists, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "images", "-q", image_name],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            env=get_docker_env(),
+        )
+        return bool(result.stdout.strip())
+    except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def pull_docker_image(image_name: str, timeout: int = 600) -> bool:
+    """Pull a Docker image.
+
+    Args:
+        image_name: Name of the Docker image to pull
+        timeout: Timeout in seconds (default 10 minutes)
+
+    Returns:
+        True if image was pulled successfully, False otherwise
+    """
+    print(f"Pulling Docker image: {image_name}")
+    print("This may take a few minutes on first run...")
+
+    try:
+        result = subprocess.run(
+            ["docker", "pull", image_name],
+            timeout=timeout,
+            env=get_docker_env(),
+        )
+        if result.returncode == 0:
+            print(f"Successfully pulled {image_name}")
+            return True
+        else:
+            print(f"Failed to pull {image_name}")
+            return False
+    except KeyboardInterrupt as ke:
+        handle_keyboard_interrupt_properly(ke)
+    except subprocess.TimeoutExpired:
+        print(f"Timeout pulling {image_name}")
+        return False
+    except Exception as e:
+        print(f"Error pulling {image_name}: {e}")
+        return False
+
+
+def ensure_docker_image(image_name: str, fallback_images: Optional[list[str]] = None) -> bool:
+    """Ensure a Docker image is available, pulling if necessary.
+
+    Args:
+        image_name: Name of the Docker image to ensure
+        fallback_images: Optional list of fallback images to try if primary fails
+
+    Returns:
+        True if image is available, False otherwise
+    """
+    if check_docker_image_exists(image_name):
+        print(f"Image {image_name} already available locally")
+        return True
+
+    if pull_docker_image(image_name):
+        return True
+
+    # Try fallback images
+    if fallback_images:
+        for fallback in fallback_images:
+            print(f"Trying fallback image: {fallback}")
+            if check_docker_image_exists(fallback):
+                return True
+            if pull_docker_image(fallback):
+                return True
+
+    return False