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

micropython_microbit_fs/hexes.py

@@ -0,0 +1,166 @@
+"""
+Bundled MicroPython hex files for micro:bit.
+
+This module provides access to the bundled MicroPython Intel Hex files
+for micro:bit V1 and V2. The hex files are organised in the `hexes/` directory
+using the following folder structure:
+
+    hexes/
+        microbitv1/
+            v{semver}/
+                filename-v{semver}.hex
+        microbitv2/
+            v{semver}/
+                filename-v{semver}.hex
+
+The micro:bit version and MicroPython version are determined by the folder path,
+not the filename.
+
+Example paths:
+    - hexes/microbitv1/v1.1.1/micropython-microbit-v1.1.1.hex
+    - hexes/microbitv2/v2.1.2/micropython-microbit-v2.1.2.hex
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Optional
+
+from packaging.version import Version
+
+from micropython_microbit_fs.exceptions import HexNotFoundError
+
+# Regex patterns for device/version folders
+DEVICE_FOLDER_PATTERN = re.compile(r"^microbitv(\d+)$")
+VERSION_FOLDER_PATTERN = re.compile(r"^v(\d+\.\d+\.\d+)$")
+
+
+@dataclass(frozen=True)
+class MicroPythonHex:
+    """Metadata and contents for a bundled MicroPython hex file."""
+
+    file_path: Path
+    version: str
+    device_version: int
+    content: str
+
+
+def _get_hexes_dir() -> Path:
+    """Get the path to the bundled hexes directory."""
+    # Use importlib.resources to access package data
+    return Path(str(resources.files("micropython_microbit_fs") / "hexes"))
+
+
+def list_bundled_versions(device_version: Optional[int] = None) -> dict[int, list[str]]:
+    """List available MicroPython versions.
+
+    Example::
+        >>> list_bundled_versions()
+        {1: ['1.1.1'], 2: ['2.1.2']}
+        >>> list_bundled_versions(1)
+        {1: ['1.1.1']}
+
+    :param device_version: The micro:bit device version (1 or 2). ``None`` lists all.
+    :return: Mapping of device version to sorted versions (newest first).
+    """
+    hexes_dir = _get_hexes_dir()
+
+    # Determine which device folders to inspect
+    target_devices: list[int]
+    if device_version is None:
+        target_devices = []
+        for entry in hexes_dir.iterdir():
+            if not entry.is_dir():
+                continue
+            match = DEVICE_FOLDER_PATTERN.match(entry.name)
+            if match:
+                target_devices.append(int(match.group(1)))
+    else:
+        target_devices = [device_version]
+
+    versions_by_device: dict[int, list[str]] = {}
+
+    for target in target_devices:
+        device_dir = hexes_dir / f"microbitv{target}"
+        versions: list[str] = []
+
+        if device_dir.exists():
+            for version_folder in device_dir.iterdir():
+                if not version_folder.is_dir():
+                    continue
+                match = VERSION_FOLDER_PATTERN.match(version_folder.name)
+                if match:
+                    semver = match.group(1)
+                    # Hex filename is not important, but ensure exactly one exists
+                    hex_files = [
+                        p
+                        for p in version_folder.iterdir()
+                        if p.suffix.lower() == ".hex"
+                    ]
+                    if len(hex_files) != 1:
+                        raise HexNotFoundError(
+                            f"Unexpected number of hex files found in path {version_folder} (should be exactly 1)."
+                        )
+                    versions.append(semver)
+
+        versions.sort(key=lambda v: Version(v), reverse=True)
+        versions_by_device[target] = versions
+
+    return versions_by_device
+
+
+def get_bundled_hex(
+    device_version: int, version: Optional[str] = None
+) -> MicroPythonHex:
+    """Get a bundled MicroPython hex file and metadata.
+
+    :param device_version: The micro:bit device version (1 or 2).
+    :param version: Optional MicroPython version string (e.g., "1.1.0").
+        If not provided, returns the latest available version.
+    :return: A frozen dataclass with filename, version string, and file contents.
+    :raises HexNotFoundError: If no hex file is found for the specified
+        device/version.
+
+    Example::
+
+        >>> hex_file = get_bundled_hex(1)  # Get latest V1 hex
+        >>> hex_file.file_path.name
+        'micropython-microbit-v1.1.1.hex'
+        >>> hex_file.version
+        '1.1.1'
+        >>> hex_file.device_version
+        1
+        >>> hex_file.content[:2]
+        '::'
+    """
+    available_versions_map = list_bundled_versions(device_version)
+    available_versions = available_versions_map.get(device_version, [])
+    if not available_versions:
+        raise HexNotFoundError(
+            f"No bundled MicroPython hex files found for micro:bit V{device_version}."
+        )
+
+    if version is None:
+        # Use the latest version (first in the sorted list)
+        selected_version = available_versions[0]
+    else:
+        if version not in available_versions:
+            raise HexNotFoundError(
+                f"MicroPython version '{version}' not found for micro:bit V{device_version}. "
+                f"Available versions: {', '.join(available_versions)}"
+            )
+        selected_version = version
+
+    # list_bundled_versions() ensures a single hex file exists in the version folder
+    hex_path = _get_hexes_dir() / f"microbitv{device_version}" / f"v{selected_version}"
+    hex_files = [p for p in hex_path.iterdir() if p.suffix.lower() == ".hex"]
+    hex_file = hex_files[0]
+    return MicroPythonHex(
+        file_path=hex_file,
+        version=selected_version,
+        device_version=device_version,
+        content=hex_file.read_text(),
+    )

micropython_microbit_fs/uicr.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+Parse UICR data from micro:bit MicroPython hex files.
+
+The UICR (User Information Configuration Registers) contains MicroPython
+specific data including:
+- Magic value to identify MicroPython
+- Flash page size
+- Runtime start/end pages
+- Version string location
+
+For more info:
+https://microbit-micropython.readthedocs.io/en/latest/devguide/hexformat.html
+"""
+
+from __future__ import annotations
+
+from intelhex import IntelHex
+
+from micropython_microbit_fs.device_info import DEVICE_SPECS, DeviceInfo
+from micropython_microbit_fs.hex_utils import (
+    read_string,
+    read_uint16,
+    read_uint32,
+)
+
+# UICR addresses
+UICR_START = 0x10001000
+UICR_CUSTOMER_OFFSET = 0x80
+UICR_CUSTOMER_UPY_OFFSET = 0x40
+UICR_UPY_START = UICR_START + UICR_CUSTOMER_OFFSET + UICR_CUSTOMER_UPY_OFFSET
+
+# UICR field addresses
+UicrAddress = {
+    "MAGIC": UICR_UPY_START + 0,  # 4 bytes - Magic value,
+    "END_MARKER": UICR_UPY_START + 4,  # 4 bytes - End marker
+    "PAGE_SIZE": UICR_UPY_START + 8,  # 4 bytes - Page size (log2)
+    "START_PAGE": UICR_UPY_START + 12,  # 2 bytes - Start page number
+    "PAGES_USED": UICR_UPY_START + 14,  # 2 bytes - Number of pages used
+    "DELIMITER": UICR_UPY_START + 16,  # 4 bytes - Delimiter
+    "VERSION_LOC": UICR_UPY_START + 20,  # 4 bytes - Address of version string
+    "REG_TERMINATOR": UICR_UPY_START + 24,  # 4 bytes - Flash regions terminator
+}
+
+
+def get_device_info_from_uicr(ih: IntelHex) -> DeviceInfo | None:
+    """
+    Extract DeviceInfo from UICR data in an IntelHex object.
+
+    :param ih: IntelHex object containing the hex data.
+    :returns: DeviceInfo if valid MicroPython UICR data is found, None otherwise.
+    """
+    magic = read_uint32(ih, UicrAddress["MAGIC"])
+    page_size_log2 = read_uint32(ih, UicrAddress["PAGE_SIZE"])
+    start_page = read_uint16(ih, UicrAddress["START_PAGE"])
+    pages_used = read_uint16(ih, UicrAddress["PAGES_USED"])
+    version_address = read_uint32(ih, UicrAddress["VERSION_LOC"])
+
+    for device in DEVICE_SPECS.values():
+        if device.uicr_magic == magic:
+            device_spec = device
+            break
+    else:
+        # Unknown magic value
+        return None
+
+    page_size = 2**page_size_log2
+    flash_size = device_spec.flash_size
+    flash_start = start_page * page_size
+    flash_end = flash_start + device_spec.flash_size
+    runtime_start = flash_start
+    runtime_end = pages_used * page_size
+    fs_start = runtime_end
+    fs_end = device_spec.fs_end_address
+    version = read_string(ih, version_address)
+    device_version = device_spec.device_version
+
+    return DeviceInfo(
+        flash_page_size=page_size,
+        flash_size=flash_size,
+        flash_start_address=flash_start,
+        flash_end_address=flash_end,
+        runtime_start_address=runtime_start,
+        runtime_end_address=runtime_end,
+        fs_start_address=fs_start,
+        fs_end_address=fs_end,
+        micropython_version=version,
+        device_version=device_version,
+    )

micropython_microbit_fs-0.1.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: micropython-microbit-fs
+Version: 0.1.0
+Summary: Library and cli app to add and extract files from MicroPython Hex files for micro:bit
+Keywords: microbit,micropython,filesystem,intel-hex,embedded
+Author: Carlos Pereira Atencio
+Author-email: Carlos Pereira Atencio <carlosperate@embeddedlog.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Dist: cyclopts>=3.24.0
+Requires-Dist: intelhex>=2.3.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'dev'
+Requires-Dist: pytest-sugar>=1.0.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0.0 ; extra == 'dev'
+Requires-Dist: mini-racer>=0.12.4 ; extra == 'dev'
+Requires-Python: >=3.9
+Project-URL: Changelog, https://github.com/carlosperate/python-microbit-fs/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/carlosperate/python-microbit-fs
+Project-URL: Issues, https://github.com/carlosperate/python-microbit-fs/issues
+Project-URL: Repository, https://github.com/carlosperate/python-microbit-fs.git
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# micropython-microbit-fs
+
+[![Test](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml/badge.svg)](https://github.com/carlosperate/python-microbit-fs/actions/workflows/test.yml)
+[![PyPI versions](https://img.shields.io/pypi/pyversions/micropython-microbit-fs.svg)](https://pypi.org/project/micropython-microbit-fs/)
+[![PyPI - License](https://img.shields.io/pypi/l/micropython-microbit-fs.svg)](LICENSE)
+
+A Python library and command line tool to inject and extract files from
+[MicroPython](https://microbit-micropython.readthedocs.io)
+Intel Hex file for the [BBC micro:bit](https://microbit.org).
+
+## Features
+
+- **Inject files** into a MicroPython hex file for flashing to micro:bit.
+- **Extract files** from an existing micro:bit MicroPython hex file.
+- **Get device info** from hex, including filesystem size and MicroPython version.
+- **Command-line interface** for easy scripting and automation.
+- Includes the latest MicroPython releases for micro:bit V1 and V2 boards.
+
+## Installation
+
+To install this terminal tool we recommend using [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install micropython-microbit-fs
+```
+
+It can also be installed via pip as a normal Python package:
+
+```bash
+pip install micropython-microbit-fs
+```
+
+## Command Line Interface
+
+The package includes a `microbit-fs` command for working with hex files from
+the terminal.
+
+### Usage
+
+Display device information:
+
+```bash
+$ microbit-fs info micropython.hex
+
+Device: micro:bit V2
+MicroPython version: micro:bit v2.1.2+0697c6d on 2023-10-30; MicroPython v1.18 on 2023-10-30
+Flash page size: 4096 bytes
+Filesystem size: 20480 bytes
+Filesystem start: 0x0006D000
+Filesystem end: 0x00073000
+```
+
+List files in a hex file:
+
+```bash
+$ microbit-fs list micropython_with_files.hex
+
+File                                             Size
+──────────────────────────────────────── ────────────
+main.py                                     183 bytes
+──────────────────────────────────────── ────────────
+Total (1 files)                             183 bytes
+```
+
+Add files to a hex file:
+
+```bash
+# Add a single file using an existing MicroPython hex
+microbit-fs add main.py --hex-file micropython.hex
+
+# Add multiple files with a custom output file
+microbit-fs add main.py helper.py --hex-file micropython.hex --output output.hex
+
+# Use bundled micro:bit V1 MicroPython hex (latest version)
+microbit-fs add main.py --v1=latest
+
+# Use bundled micro:bit V2 MicroPython hex (latest version)
+microbit-fs add main.py --v2=latest --output my_program.hex
+
+# Use a specific MicroPython version
+microbit-fs add main.py --v1=1.1.1 --output output.hex
+microbit-fs add main.py --v2=2.1.2 --output output.hex
+```
+
+List available bundled MicroPython versions:
+
+```bash
+$ microbit-fs versions
+Bundled MicroPython hex files:
+
+micro:bit V1:
+  - 1.1.1
+
+micro:bit V2:
+  - 2.1.2
+```
+
+Extract files from a hex file:
+
+```bash
+# Extract all files to the current directory
+microbit-fs get micropython_with_files.hex
+
+# Extract all files to a specific directory
+microbit-fs get micropython_with_files.hex --output-dir ./extracted
+
+# Extract a specific file
+microbit-fs get micropython_with_files.hex --filename main.py
+
+# Overwrite existing files without prompting
+microbit-fs get micropython_with_files.hex --force
+```
+
+
+## Library Quick Start
+
+### Add files to a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read your MicroPython hex file
+with open("micropython.hex") as f:
+    micropython_hex = f.read()
+
+# Create files to add
+files = [
+    microbit_fs.File.from_text("main.py", "from microbit import *\ndisplay.scroll('Hello!')"),
+    microbit_fs.File.from_text("helper.py", "def greet(name):\n    return f'Hello {name}'"),
+]
+
+# Add files and get new hex string
+new_hex = microbit_fs.add_files(micropython_hex, files)
+
+with open("micropython_with_files.hex", "w") as f:
+    f.write(new_hex)
+```
+
+### Get files from a MicroPython hex
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# Read hex file with embedded files
+with open("micropython_with_files.hex") as f:
+    hex_data = f.read()
+
+# Get all files
+files = microbit_fs.get_files(hex_data)
+
+for file in files:
+    print(f"{file.name}: {file.size} bytes")
+    print(file.get_text())
+```
+
+### Get device information
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+with open("micropython.hex") as f:
+    hex_data = f.read()
+
+info = microbit_fs.get_device_info(hex_data)
+print(f"Device: micro:bit {info.device_version.value}")
+print(f"MicroPython: {info.micropython_version}")
+print(f"Filesystem size: {info.fs_size} bytes")
+print(f"Flash page size: {info.flash_page_size} bytes")
+```
+
+### Use bundled MicroPython hex files
+
+```python
+import micropython_microbit_fs as microbit_fs
+
+# List available bundled versions (dict keyed by device)
+versions = microbit_fs.list_bundled_versions()
+# {1: ['1.1.1'], 2: ['2.1.2']}
+v1_versions = versions[1]
+v2_versions = versions[2]
+
+# Get the latest bundled hex for micro:bit V1
+hex_data = microbit_fs.get_bundled_hex(1)
+
+# Get a specific version
+hex_data = microbit_fs.get_bundled_hex(2, "2.1.2")
+
+# Add files to the bundled hex
+files = [microbit_fs.File.from_text("main.py", "from microbit import *")]
+new_hex = microbit_fs.add_files(hex_data, files)
+
+with open("my_program.hex", "w") as f:
+    f.write(new_hex)
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for project management.
+
+### Setup
+
+```bash
+git clone https://github.com/carlosperate/python-microbit-fs.git
+cd python-microbit-fs
+uv sync --all-extras --dev
+```
+
+### Development Commands
+
+This project includes a `make.py` script to automate common development tasks.
+
+```bash
+# Run all checks (lint, typecheck, format check, test with coverage)
+uv run python make.py check
+
+# Format code (ruff check --fix + ruff format)
+uv run python make.py format
+
+# Show all available commands
+uv run python make.py help
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- This project has been ported (AI assisted) from the original
+  [microbit-fs](https://github.com/microbit-foundation/microbit-fs)
+  TypeScript library.
+- This project packs the files inside a micro:bit MicroPython hex, which
+  can then be flashed to a micro:bit.
+  Alternatively, to read and write files from a running micro:bit device over
+  USB, the [microFs](https://github.com/ntoll/microfs) CLI tool can be used.

micropython_microbit_fs-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+micropython_microbit_fs/.DS_Store,sha256=sJCJ1a9O1Gae_hIXRjG1O_vwKIo7gz_2gRFe-0tvTmw,6148
+micropython_microbit_fs/__init__.py,sha256=fr5PcF8Yv13scWSb737QXMUORxCv1sZISapi5rJNU1I,1528
+micropython_microbit_fs/api.py,sha256=tnpPp5rRa4lXNCIig1q4254ejnHfwyodspZ7sgR7wMw,4026
+micropython_microbit_fs/cli.py,sha256=WlkVV0BshX_9Ez6-gJcy8AI_rIyde5ixEogByk18c6Y,8305
+micropython_microbit_fs/device_info.py,sha256=cSJ5VILQ0lE0d2Gh6gOPQhvqH80-pb9esYno4Y3UXNo,3438
+micropython_microbit_fs/exceptions.py,sha256=ELDQb8zyQphL51-WPmBddPu9MKXsDVMLHxt9GPP5K-c,741
+micropython_microbit_fs/file.py,sha256=ryNgCFf4eQ3vK2z7lZeWrRFmfTk3Pe4STxoiQcSr8H4,1907
+micropython_microbit_fs/filesystem.py,sha256=VhstR88kNpIG9yqPIwuDTaOJPLD4soiFxpwMFLTEkJ4,15783
+micropython_microbit_fs/flash_regions.py,sha256=fRtqjg-6cvlXPbLN87brMUSOOWDNiXrgy_FRFXY7lrQ,8772
+micropython_microbit_fs/hex_utils.py,sha256=KyVavsO4ARGUbj9Ixh3uIu6BBbT1its4737-u7HRTYE,3888
+micropython_microbit_fs/hexes/.DS_Store,sha256=dooJkRPNrvjXmcN3kxtEXnz7U6RBQ5dxWA_IPYpAMQs,6148
+micropython_microbit_fs/hexes/microbitv1/.DS_Store,sha256=QI4ST-RRzHM2695mYD0wlbtVEM4CuRtKNovB7RB2mH0,6148
+micropython_microbit_fs/hexes/microbitv1/v1.1.1/micropython-microbit-v1.1.1.hex,sha256=02huZpZ31Fbs6dIGpEuKy-c933PhoyEf-JuTlyuVMVI,635792
+micropython_microbit_fs/hexes/microbitv2/.DS_Store,sha256=wlzvdw6KFHiXLk4kW0I_V6q_ODxODr601kFDiuh8Ecw,6148
+micropython_microbit_fs/hexes/microbitv2/v2.1.2/micropython-microbit-v2.1.2.hex,sha256=Zvrge3F3fp46a1EionkwskzAvlACq5pn6SSUxUoWRe8,1239726
+micropython_microbit_fs/hexes.py,sha256=SVE9_mlDHvrEVT3ueIGaKcX0PndeucK8DFYpFj4cOY0,5624
+micropython_microbit_fs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+micropython_microbit_fs/uicr.py,sha256=utcSo8MhaoUbIkBomBS759z2mxUP8N8VVrIkXq8MarY,2983
+micropython_microbit_fs-0.1.0.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
+micropython_microbit_fs-0.1.0.dist-info/entry_points.txt,sha256=ezUl-Ghp4t_RPLWhdQXToinaV3hA3dfd_NYnybFMm3w,66
+micropython_microbit_fs-0.1.0.dist-info/METADATA,sha256=uqqy8tdUQnQdHxwcvKtLs0xWfbPMvSwIJ6G8rKKqBQU,8371
+micropython_microbit_fs-0.1.0.dist-info/RECORD,,

micropython_microbit_fs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.21
+Root-Is-Purelib: true
+Tag: py3-none-any

micropython_microbit_fs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+microbit-fs = micropython_microbit_fs.cli:main
+