Class ESP32FlashImageBuilder

ci/compiler/esp32_artifacts.py:146–202

Builds merged flash images for ESP32 QEMU.

class ESP32FlashImageBuilder:
    """Builds merged flash images for ESP32 QEMU."""

    def __init__(self, board_name: str, artifacts: ArtifactSet):
        self.board_name = board_name
        self.artifacts = artifacts
        self.bootloader_offset = get_bootloader_offset(board_name)

    def create_merged_image(self, output_path: Path, flash_size_mb: int = 4) -> bool:
        """Create a merged flash image from individual artifacts."""
        if flash_size_mb not in VALID_FLASH_SIZES:
            raise ValueError(
                f"Invalid flash size: {flash_size_mb}MB. Must be in {VALID_FLASH_SIZES}"
            )

        if not self.artifacts.required_files_present:
            raise ValueError(
                f"Missing required files: {self.artifacts.missing_files()}"
            )

        flash_size = flash_size_mb * 1024 * 1024
        flash_data = bytearray(b"\xff" * flash_size)

        # Merge files at their offsets
        self._write_at_offset(
            flash_data, self.artifacts.bootloader, self.bootloader_offset
        )
        self._write_at_offset(
            flash_data, self.artifacts.partitions_bin, FLASH_OFFSETS.PARTITIONS
        )
        self._write_at_offset(
            flash_data, self.artifacts.boot_app0, FLASH_OFFSETS.BOOT_APP0
        )
        self._write_at_offset(
            flash_data, self.artifacts.firmware, FLASH_OFFSETS.FIRMWARE
        )

        # Optional: SPIFFS if present (board-specific offset)
        # Note: SPIFFS typically starts after firmware, offset varies by partition table

        output_path.write_bytes(flash_data)
        return True

    def _write_at_offset(
        self, flash_data: bytearray, file_path: Optional[Path], offset: int
    ) -> None:
        """Write file contents at specified offset."""
        if not file_path or not file_path.exists():
            return

        file_data = file_path.read_bytes()
        if offset + len(file_data) > len(flash_data):
            raise ValueError(
                f"File {file_path.name} at offset 0x{offset:x} exceeds flash size"
            )

        flash_data[offset : offset + len(file_data)] = file_data