micropython-microbit-fs 0.1.0__py3-none-any.whl

micropython_microbit_fs/__init__.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""
+micropython-microbit-fs: Inject and extract files from MicroPython Intel Hex files.
+
+This library provides a simple API for working with MicroPython filesystem
+embedded in Intel Hex files for the BBC micro:bit.
+
+Main functions:
+    - add_files: Add files to a MicroPython hex file
+    - get_files: Read files from a MicroPython hex file
+    - get_device_info: Get device memory information from a hex file
+    - get_bundled_hex: Get a bundled MicroPython hex file
+    - list_bundled_versions: List available bundled hex versions
+"""
+
+from micropython_microbit_fs.api import (
+    add_files,
+    get_device_info,
+    get_files,
+)
+from micropython_microbit_fs.device_info import DeviceInfo, DeviceVersion
+from micropython_microbit_fs.exceptions import (
+    FilesystemError,
+    HexNotFoundError,
+    InvalidFileError,
+    InvalidHexError,
+    NotMicroPythonError,
+    StorageFullError,
+)
+from micropython_microbit_fs.file import File
+from micropython_microbit_fs.hexes import (
+    MicroPythonHex,
+    get_bundled_hex,
+    list_bundled_versions,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main API functions
+    "add_files",
+    "get_files",
+    "get_device_info",
+    # Bundled hex functions
+    "MicroPythonHex",
+    "get_bundled_hex",
+    "list_bundled_versions",
+    # Data classes
+    "File",
+    "DeviceInfo",
+    "DeviceVersion",
+    # Exceptions
+    "FilesystemError",
+    "InvalidHexError",
+    "NotMicroPythonError",
+    "InvalidFileError",
+    "StorageFullError",
+    "HexNotFoundError",
+]

micropython_microbit_fs/api.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+Main public API for micropython-microbit-fs.
+
+This module provides the main functions for working with micro:bit MicroPython
+filesystems in Intel Hex files.
+"""
+
+from micropython_microbit_fs.device_info import DeviceInfo, get_device_info_ih
+from micropython_microbit_fs.exceptions import InvalidFileError, InvalidHexError
+from micropython_microbit_fs.file import File
+from micropython_microbit_fs.filesystem import (
+    add_files_to_hex,
+    read_files_from_hex,
+)
+from micropython_microbit_fs.hex_utils import hex_to_string, load_hex
+
+
+def add_files(
+    hex_data: str,
+    files: list[File],
+) -> str:
+    """
+    Add files to a micro:bit MicroPython Intel Hex file.
+
+    Takes a micro:bit MicroPython hex file and a list of files to add,
+    returning a new hex file with the files encoded in the filesystem region.
+
+    :param hex_data: Intel Hex file content as a string.
+    :param files: List of File objects to inject into the filesystem.
+    :returns: New Intel Hex file content with the files injected.
+
+    :raises InvalidHexError: If the hex data is invalid.
+    :raises NotMicroPythonError: If the hex does not contain MicroPython.
+    :raises InvalidFileError: If a file has invalid name or content.
+    :raises StorageFullError: If the files don't fit in the filesystem.
+
+    Example::
+
+        >>> import micropython_microbit_fs as micropython
+        >>> files = [micropython.File.from_text("main.py", "print('Hello!')")]
+        >>> new_hex = micropython.add_files(micropython_hex, files)
+    """
+    try:
+        ih = load_hex(hex_data)
+    except Exception as e:
+        raise InvalidHexError(f"Failed to parse Intel Hex data: {e}") from e
+    device_info = get_device_info_ih(ih)
+
+    files_dict = {}
+    for file in files:
+        if file.name in files_dict:
+            raise InvalidFileError(f"Duplicate file name: {file.name}")
+        files_dict[file.name] = file.content
+    add_files_to_hex(ih, device_info, files_dict)
+
+    return hex_to_string(ih)
+
+
+def get_files(hex_data: str) -> list[File]:
+    """
+    Get files from a micro:bit MicroPython Intel Hex file.
+
+    Reads a micro:bit MicroPython hex file and returns all files found in the
+    filesystem region.
+
+    :param hex_data: Intel Hex file content as a string.
+    :returns: List of File objects found in the filesystem.
+
+    :raises InvalidHexError: If the hex data is invalid.
+    :raises NotMicroPythonError: If the hex does not contain MicroPython.
+    :raises FilesystemError: If the filesystem structure is corrupted.
+
+    Example::
+
+        >>> import micropython_microbit_fs as micropython
+        >>> files = micropython.get_files(hex_with_files)
+        >>> for f in files:
+        ...     print(f"{f.name}: {f.size} bytes")
+    """
+    try:
+        ih = load_hex(hex_data)
+    except Exception as e:
+        raise InvalidHexError(f"Failed to parse Intel Hex data: {e}") from e
+    device_info = get_device_info_ih(ih)
+    files_dict = read_files_from_hex(ih, device_info)
+    return [File(name=name, content=content) for name, content in files_dict.items()]
+
+
+def get_device_info(hex_data: str) -> DeviceInfo:
+    """
+    Get device memory information from a MicroPython Intel Hex file.
+
+    Extracts information about the flash memory layout, including
+    filesystem boundaries and MicroPython version.
+
+    :param hex_data: Intel Hex file content as a string.
+    :returns: DeviceInfo containing memory layout information.
+
+    :raises InvalidHexError: If the hex data is invalid.
+    :raises NotMicroPythonError: If the hex does not contain MicroPython.
+
+    Example::
+
+        >>> import micropython_microbit_fs as micropython
+        >>> info = micropython.get_device_info(micropython_hex)
+        >>> print(f"FS Size: {info.fs_size} bytes")
+        >>> print(f"MicroPython: {info.micropython_version}")
+    """
+    try:
+        ih = load_hex(hex_data)
+    except Exception as e:
+        raise InvalidHexError(f"Failed to parse Intel Hex data: {e}") from e
+    return get_device_info_ih(ih)

micropython_microbit_fs/cli.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Command-line interface for micropython-microbit-fs.
+
+This module provides CLI commands for working with micro:bit MicroPython
+filesystems in Intel Hex files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+from cyclopts import App, Parameter
+
+import micropython_microbit_fs as upyfs
+from micropython_microbit_fs.exceptions import HexNotFoundError
+from micropython_microbit_fs.hexes import (
+    get_bundled_hex,
+    list_bundled_versions,
+)
+
+app = App(
+    name="microbit-fs",
+    help="Inject and extract files from MicroPython Hex files for micro:bit.",
+    version=upyfs.__version__,
+)
+
+
+@app.command
+def info(hex_file: Path) -> None:
+    """Display device and filesystem information from a MicroPython hex file.
+
+    :param hex_file: Path to the Intel Hex file.
+    """
+    hex_data = hex_file.read_text()
+    device_info = upyfs.get_device_info(hex_data)
+
+    print(f"Device: micro:bit {device_info.device_version.value}")
+    print(f"MicroPython version: {device_info.micropython_version}")
+    print(f"Flash page size: {device_info.flash_page_size} bytes")
+    print(f"Filesystem size: {device_info.fs_size} bytes")
+    print(f"Filesystem start: 0x{device_info.fs_start_address:08X}")
+    print(f"Filesystem end: 0x{device_info.fs_end_address:08X}")
+
+
+@app.command(name="list")
+def list_files(hex_file: Path) -> None:
+    """List files stored in a MicroPython hex file.
+
+    :param hex_file: Path to the Intel Hex file.
+    """
+    hex_data = hex_file.read_text()
+    files = upyfs.get_files(hex_data)
+
+    if not files:
+        print("No files found in filesystem.")
+        return
+
+    total_size = sum(file.size for file in files)
+    name_col_width = 40
+    size_col_width = 12
+
+    print(f"\n{'File':<{name_col_width}} {'Size':>{size_col_width}}")
+    print(f"{'─' * name_col_width} {'─' * size_col_width}")
+    for file in files:
+        size_str = f"{file.size} bytes"
+        print(f"{file.name:<{name_col_width}} {size_str:>{size_col_width}}")
+
+    print(f"{'─' * name_col_width} {'─' * size_col_width}")
+    total_str = f"{total_size} bytes"
+    print(
+        f"{'Total (' + str(len(files)) + ' files)':<{name_col_width}} {total_str:>{size_col_width}}"
+    )
+
+
+@app.command
+def get(
+    hex_file: Path,
+    output_dir: Path = Path("."),
+    filename: Optional[str] = None,
+    force: bool = False,
+) -> None:
+    """Extract files from a MicroPython hex file.
+
+    :param hex_file: Path to the Intel Hex file.
+    :param output_dir: Directory to extract files to (default: current directory).
+    :param filename: Extract only this specific file (default: extract all).
+    :param force: Overwrite existing files without prompting (default: False).
+    """
+    hex_data = hex_file.read_text()
+    files = upyfs.get_files(hex_data)
+
+    if not files:
+        print("No files found in filesystem.")
+        return
+
+    # Filter files if a specific filename was requested
+    files_to_extract = files
+    if filename is not None:
+        files_to_extract = [f for f in files if f.name == filename]
+        if not files_to_extract:
+            raise SystemExit(f"Error: File not found in hex: {filename}")
+
+    # Check for existing files before extracting (unless --force is used)
+    if not force:
+        existing_files = []
+        for file in files_to_extract:
+            output_path = output_dir / file.name
+            if output_path.exists():
+                existing_files.append(file.name)
+        if existing_files:
+            raise SystemExit(
+                f"Error: Files already exist: {', '.join(existing_files)}\n"
+                "Use --force to overwrite."
+            )
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    for file in files_to_extract:
+        output_path = output_dir / file.name
+        output_path.write_bytes(file.content)
+        print(f"Extracted: {file.name} ({file.size} bytes)")
+
+
+@app.command
+def add(
+    files: list[Path],
+    hex_file: Annotated[
+        Optional[Path],
+        Parameter(
+            name="--hex-file",
+            help="Path to input Intel Hex file. Required if --v1 or --v2 is not used.",
+        ),
+    ] = None,
+    output: Optional[Path] = None,
+    v1: Annotated[
+        Optional[str],
+        Parameter(
+            help=(
+                "Use bundled micro:bit V1 MicroPython hex. "
+                "Specify a version (e.g., --v1=1.1) or 'latest' for the newest."
+            ),
+        ),
+    ] = None,
+    v2: Annotated[
+        Optional[str],
+        Parameter(
+            help=(
+                "Use bundled micro:bit V2 MicroPython hex. "
+                "Specify a version (e.g., --v2=1.2) or 'latest' for the newest."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Inject files into a MicroPython hex file.
+
+    You must provide either --hex-file OR --v1/--v2 to specify the base hex file.
+
+    **Examples:**
+
+    - microbit-fs add main.py --v1=latest
+    - microbit-fs add main.py --v2=1.2 --output my_program.hex
+    - microbit-fs add main.py --hex-file micropython.hex
+    - microbit-fs add main.py helper.py --hex-file micropython.hex --output output.hex
+
+    :param files: One or more files to add to the filesystem.
+    :param hex_file: Path to the input Intel Hex file.
+    :param output: Output hex file path (default: <input_name>_output.hex).
+    :param v1: Use bundled micro:bit V1 hex with specified version or 'latest'.
+    :param v2: Use bundled micro:bit V2 hex with specified version or 'latest'.
+    """
+    has_hex_file = hex_file is not None
+    has_v1 = v1 is not None
+    has_v2 = v2 is not None
+    if sum([has_hex_file, has_v1, has_v2]) == 0:
+        raise SystemExit(
+            "Error: You must provide a hex file or use --v1/--v2 for a bundled hex."
+        )
+    if sum([has_hex_file, has_v1, has_v2]) > 1:
+        raise SystemExit(
+            "Error: Cannot combine hex_file with --v1 or --v2, or use both --v1 and --v2."
+        )
+
+    hex_content: str
+    try:
+        # "latest" means use None to get the newest version
+        if has_v1:
+            version = None if v1.lower() == "latest" else v1  # type: ignore
+            bundled_hex = get_bundled_hex(1, version)
+            hex_content = bundled_hex.content
+            resolved_version = version or bundled_hex.version
+            hex_path = bundled_hex.file_path
+            print(f"Using bundled micro:bit V1 MicroPython v{resolved_version}")
+        elif has_v2:
+            version = None if v2.lower() == "latest" else v2  # type: ignore
+            bundled_hex = get_bundled_hex(2, version)
+            hex_content = bundled_hex.content
+            resolved_version = version or bundled_hex.version
+            hex_path = bundled_hex.file_path
+            print(f"Using bundled micro:bit V2 MicroPython v{resolved_version}")
+        elif has_hex_file:
+            hex_content = hex_file.read_text()  # type: ignore
+            hex_path = hex_file  # type: ignore
+    except HexNotFoundError as e:
+        raise SystemExit(f"Error: {e}") from None
+
+    file_objects = []
+    for file_path in files:
+        upy_file = upyfs.File(name=file_path.name, content=file_path.read_bytes())
+        file_objects.append(upy_file)
+        print(f"Adding: {file_path.name} ({upy_file.size_fs} bytes)")
+
+    new_hex = upyfs.add_files(hex_content, file_objects)
+
+    # Generate default output in cwd, filename: <name>_output.hex
+    output_path = output if output else Path(f"{hex_path.stem}_output.hex")
+    output_path.write_text(new_hex)
+    print(f"Written to: {output_path.absolute().relative_to(Path.cwd())}")
+
+
+@app.command
+def versions() -> None:
+    """List available bundled MicroPython hex versions.
+
+    Shows all MicroPython versions bundled with this tool for both
+    micro:bit V1 and V2.
+    """
+    versions_by_device = list_bundled_versions()
+
+    print("Bundled MicroPython hex files:")
+    for device_version in sorted(versions_by_device.keys()):
+        print(f"\nmicro:bit V{device_version}:")
+        for version in versions_by_device[device_version]:
+            print(f"  - {version}")
+        if len(versions_by_device[device_version]) == 0:
+            print("  (none available)")
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

micropython_microbit_fs/device_info.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Device memory information data structures."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class DeviceVersion(Enum):
+    """micro:bit hardware version."""
+
+    V1 = "V1"  # micro:bit V1 (nRF51822)
+    V2 = "V2"  # micro:bit V2 (nRF52833)
+
+
+@dataclass(frozen=True)
+class DeviceSpec:
+    """Hardware specification for a micro:bit version."""
+
+    device_version: DeviceVersion
+    uicr_magic: int
+    page_size: int
+    flash_start_address: int
+    flash_size: int
+    fs_end_address: int
+
+
+DEVICE_SPECS = {
+    DeviceVersion.V1: DeviceSpec(
+        device_version=DeviceVersion.V1,
+        uicr_magic=0x17EEB07C,
+        page_size=1024,
+        flash_start_address=0,
+        flash_size=256 * 1024,
+        fs_end_address=256 * 1024,
+    ),
+    DeviceVersion.V2: DeviceSpec(
+        device_version=DeviceVersion.V2,
+        uicr_magic=0x47EEB07C,
+        page_size=4096,
+        flash_start_address=0,
+        flash_size=512 * 1024,
+        fs_end_address=0x73000,
+    ),
+}
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    """
+    Device information extracted from a MicroPython hex file.
+
+    This contains information about the flash memory layout including
+    where the MicroPython runtime and filesystem are located.
+    """
+
+    flash_page_size: int
+    """Size of a flash page in bytes (V1: 1024, V2: 4096)."""
+
+    flash_size: int
+    """Total flash size in bytes (V1: 256KB, V2: 512KB)."""
+
+    flash_start_address: int
+    """Start address of flash memory (always 0)."""
+
+    flash_end_address: int
+    """End address of flash memory."""
+
+    runtime_start_address: int
+    """Start address of the MicroPython runtime."""
+
+    runtime_end_address: int
+    """End address of the MicroPython runtime."""
+
+    fs_start_address: int
+    """Start address of the filesystem region."""
+
+    fs_end_address: int
+    """End address of the filesystem region."""
+
+    micropython_version: str
+    """MicroPython version string."""
+
+    device_version: DeviceVersion
+    """micro:bit hardware version (V1 or V2)."""
+
+    @property
+    def fs_size(self) -> int:
+        """Total filesystem size in bytes."""
+        # One page is used as scratch, so exclude it from the size
+        return self.fs_end_address - self.fs_start_address - self.flash_page_size
+
+
+def get_device_info_ih(ih: Any) -> DeviceInfo:
+    """
+    Internal function to get device info from an already-loaded IntelHex.
+
+    :param ih: IntelHex object.
+    :returns: DeviceInfo containing memory layout information.
+
+    :raises NotMicroPythonError: If the hex does not contain MicroPython.
+    """
+    # Delayed imports to avoid circular dependency
+    from micropython_microbit_fs.exceptions import NotMicroPythonError
+    from micropython_microbit_fs.flash_regions import get_device_info_from_flash_regions
+    from micropython_microbit_fs.uicr import get_device_info_from_uicr
+
+    # First try Flash Regions Table detection, as it's more likely to be a V2
+    device_info = get_device_info_from_flash_regions(ih)
+    if device_info is not None:
+        return device_info
+
+    # Try UICR detection next (works for V1 and pre-release V2)
+    device_info = get_device_info_from_uicr(ih)
+    if device_info is not None:
+        return device_info
+
+    raise NotMicroPythonError(
+        "Could not detect MicroPython in hex file. "
+        "The hex file may not contain MicroPython or may be corrupted."
+    )

micropython_microbit_fs/exceptions.py

@@ -0,0 +1,37 @@
+"""Custom exceptions for the micropython-microbit-fs library."""
+
+
+class FilesystemError(Exception):
+    """Base exception for filesystem-related errors."""
+
+    pass
+
+
+class InvalidHexError(FilesystemError):
+    """Raised when the Intel Hex data is invalid or malformed."""
+
+    pass
+
+
+class NotMicroPythonError(FilesystemError):
+    """Raised when the hex file does not contain MicroPython."""
+
+    pass
+
+
+class InvalidFileError(FilesystemError):
+    """Raised when a file has invalid name or content."""
+
+    pass
+
+
+class StorageFullError(FilesystemError):
+    """Raised when there is not enough space in the filesystem."""
+
+    pass
+
+
+class HexNotFoundError(Exception):
+    """Raised when a requested hex file is not found."""
+
+    pass

micropython_microbit_fs/file.py

@@ -0,0 +1,62 @@
+"""File representation for the MicroPython filesystem."""
+
+from dataclasses import dataclass
+
+from micropython_microbit_fs.exceptions import InvalidFileError
+from micropython_microbit_fs.filesystem import calculate_file_size
+
+
+@dataclass
+class File:
+    """
+    Represents a file to be stored in the MicroPython filesystem.
+
+    Attributes:
+        name: The filename (max 120 characters, no path separators).
+        content: The file content as bytes.
+    """
+
+    name: str
+    content: bytes
+
+    def __post_init__(self) -> None:
+        """Validate file name and content."""
+        if not self.name:
+            raise InvalidFileError("Filename cannot be empty")
+        if len(self.name) > 120:
+            raise InvalidFileError(
+                f"Filename too long: {len(self.name)} > 120 characters"
+            )
+        if not self.content:
+            raise InvalidFileError("File content cannot be empty")
+
+    @classmethod
+    def from_text(cls, name: str, text: str, encoding: str = "utf-8") -> "File":
+        """
+        Create a File from text content.
+
+        :param name: The filename.
+        :param text: The text content.
+        :param encoding: Text encoding (default: utf-8).
+        :returns: A new File instance.
+        """
+        return cls(name=name, content=text.encode(encoding))
+
+    def get_text(self, encoding: str = "utf-8") -> str:
+        """
+        Get the file content as text.
+
+        :param encoding: Text encoding (default: utf-8).
+        :returns: The file content as a string.
+        """
+        return self.content.decode(encoding)
+
+    @property
+    def size(self) -> int:
+        """Return the size of the file content in bytes."""
+        return len(self.content)
+
+    @property
+    def size_fs(self) -> int:
+        """Return the total size the file consumes in the filesystem storage."""
+        return calculate_file_size(self.name, self.content)