armbuilderx 0.1.1__tar.gz

armbuilderx-0.1.1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: armbuilderx
+Version: 0.1.1
+Summary: CMake-based build, flash and serial-monitor tooling for Arm Cortex-M Keil/MDK projects, built on CMSIS-Toolbox and pyOCD
+Author: ArmBuilderX
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: pyocd>=0.36
+Requires-Dist: pyserial>=3.5
+Requires-Dist: requests>=2.31
+Requires-Dist: tqdm>=4.66
+Requires-Dist: PyYAML>=6.0
+
+# ArmBuilderX
+
+Cross-platform CLI that turns a Keil/MDK Arm Cortex-M project into a
+CMake project, builds it with the Arm GNU Toolchain, flashes it with
+pyOCD, and streams the DAPLink/CMSIS-DAP virtual COM port log.
+
+It is built on top of official tooling rather than a custom project
+parser:
+
+- **[CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/devtools)**
+  (`csolution` / `cbuild` / `cbuild2cmake` / `cpackget`) resolves the
+  CMSIS-Pack device data (CPU, FPU, memory map, startup/linker files)
+  and generates the actual `CMakeLists.txt`.
+- **[pyOCD](https://github.com/pyocd/pyOCD)** flashes the target over
+  CMSIS-DAP/DAPLink and can also list/open the debug probe's serial
+  port.
+- **CMake + Arm GNU Toolchain (`arm-none-eabi-gcc`)** builds the
+  generated CMake project. `ninja` is used as the CMake generator.
+
+## Install
+
+```bash
+pip install armbuilderx
+```
+
+## Usage
+
+```bash
+# One-time: point ArmBuilderX at the vendor pack(s) that describe your device.
+armbuilderx init --pack path/to/Vendor.PackName.x.y.z.pack
+
+# Generate (or refresh) the GCC/CMake project for one example, from its
+# existing MDK project.
+armbuilderx generate examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Build it (adds arm-none-eabi-gcc/cmake/ninja/git to ~/.armbuilderx/tools
+# automatically if they are missing from PATH).
+armbuilderx build examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Flash the built ELF over CMSIS-DAP/DAPLink with pyOCD.
+# (the build step also emits matching .hex and .bin images alongside the .elf)
+armbuilderx flash examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Open the DAPLink virtual COM port and stream log output.
+armbuilderx monitor
+
+# All of the above, in one shot.
+armbuilderx run examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+```
+
+## SDK adapters
+
+ArmBuilderX keeps vendor-specific SDK rules behind SDK adapters. The current
+`ns800rt5xxx` adapter contains the NS800 project-layout detection, GCC startup
+file replacement, linker-script selection, and NS800-only compiler defines.
+The command layer remains independent of those details and can select an
+adapter explicitly when needed:
+
+```bash
+armbuilderx generate <example-dir> --sdk ns800rt5xxx
+```
+
+Without `--sdk`, ArmBuilderX detects the adapter from the example layout. To
+add another SDK such as GR551x, implement a new adapter under
+`src/armbuilderx/sdk/` and register it in `sdk/registry.py`; do not add its
+directory rules to the NS800 adapter or the generic generator.
+
+### GR551x
+
+The `gr551x` adapter supports Goodix GR551x projects that ship a `GCC/`
+CMSIS-Toolbox project. It verifies the `Goodix::GR5xxx_DFP@1.0.0` pack and
+`Goodix::GR551x` device, preserves the SDK's source groups and BLE library,
+and resolves the selected GCC toolchain's Cortex-M4 softfp runtime libraries.
+
+```bash
+armbuilderx init --pack ../GR551x_SDK_V2.1.1/Goodix.GR5xxx_DFP.1.0.0.pack
+armbuilderx build ../GR551x_SDK_V2.1.1/projects/peripheral/gpio/app_gpio --sdk gr551x --clean
+```
+
+Each project keeps its generated CMake project under a `GCC/` folder
+next to the existing `MDK/`/`IAR/` folders, matching the SDK's own
+convention.

armbuilderx-0.1.1/README.md

@@ -0,0 +1,82 @@
+# ArmBuilderX
+
+Cross-platform CLI that turns a Keil/MDK Arm Cortex-M project into a
+CMake project, builds it with the Arm GNU Toolchain, flashes it with
+pyOCD, and streams the DAPLink/CMSIS-DAP virtual COM port log.
+
+It is built on top of official tooling rather than a custom project
+parser:
+
+- **[CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/devtools)**
+  (`csolution` / `cbuild` / `cbuild2cmake` / `cpackget`) resolves the
+  CMSIS-Pack device data (CPU, FPU, memory map, startup/linker files)
+  and generates the actual `CMakeLists.txt`.
+- **[pyOCD](https://github.com/pyocd/pyOCD)** flashes the target over
+  CMSIS-DAP/DAPLink and can also list/open the debug probe's serial
+  port.
+- **CMake + Arm GNU Toolchain (`arm-none-eabi-gcc`)** builds the
+  generated CMake project. `ninja` is used as the CMake generator.
+
+## Install
+
+```bash
+pip install armbuilderx
+```
+
+## Usage
+
+```bash
+# One-time: point ArmBuilderX at the vendor pack(s) that describe your device.
+armbuilderx init --pack path/to/Vendor.PackName.x.y.z.pack
+
+# Generate (or refresh) the GCC/CMake project for one example, from its
+# existing MDK project.
+armbuilderx generate examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Build it (adds arm-none-eabi-gcc/cmake/ninja/git to ~/.armbuilderx/tools
+# automatically if they are missing from PATH).
+armbuilderx build examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Flash the built ELF over CMSIS-DAP/DAPLink with pyOCD.
+# (the build step also emits matching .hex and .bin images alongside the .elf)
+armbuilderx flash examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+
+# Open the DAPLink virtual COM port and stream log output.
+armbuilderx monitor
+
+# All of the above, in one shot.
+armbuilderx run examples/device_support/ns800rt5xxx/examples/gpio/gpio_ex2_output
+```
+
+## SDK adapters
+
+ArmBuilderX keeps vendor-specific SDK rules behind SDK adapters. The current
+`ns800rt5xxx` adapter contains the NS800 project-layout detection, GCC startup
+file replacement, linker-script selection, and NS800-only compiler defines.
+The command layer remains independent of those details and can select an
+adapter explicitly when needed:
+
+```bash
+armbuilderx generate <example-dir> --sdk ns800rt5xxx
+```
+
+Without `--sdk`, ArmBuilderX detects the adapter from the example layout. To
+add another SDK such as GR551x, implement a new adapter under
+`src/armbuilderx/sdk/` and register it in `sdk/registry.py`; do not add its
+directory rules to the NS800 adapter or the generic generator.
+
+### GR551x
+
+The `gr551x` adapter supports Goodix GR551x projects that ship a `GCC/`
+CMSIS-Toolbox project. It verifies the `Goodix::GR5xxx_DFP@1.0.0` pack and
+`Goodix::GR551x` device, preserves the SDK's source groups and BLE library,
+and resolves the selected GCC toolchain's Cortex-M4 softfp runtime libraries.
+
+```bash
+armbuilderx init --pack ../GR551x_SDK_V2.1.1/Goodix.GR5xxx_DFP.1.0.0.pack
+armbuilderx build ../GR551x_SDK_V2.1.1/projects/peripheral/gpio/app_gpio --sdk gr551x --clean
+```
+
+Each project keeps its generated CMake project under a `GCC/` folder
+next to the existing `MDK/`/`IAR/` folders, matching the SDK's own
+convention.

armbuilderx-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "armbuilderx"
+version = "0.1.1"
+description = "CMake-based build, flash and serial-monitor tooling for Arm Cortex-M Keil/MDK projects, built on CMSIS-Toolbox and pyOCD"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "ArmBuilderX" }]
+dependencies = [
+    "click>=8.1",
+    "pyocd>=0.36",
+    "pyserial>=3.5",
+    "requests>=2.31",
+    "tqdm>=4.66",
+    "PyYAML>=6.0",
+]
+
+[project.scripts]
+armbuilderx = "armbuilderx.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

armbuilderx-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

armbuilderx-0.1.1/src/armbuilderx/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

armbuilderx-0.1.1/src/armbuilderx/cli.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+import click
+
+from armbuilderx.cmsis import csolution, generator, mdk_project, toolbox
+from armbuilderx.cmsis.csolution import CSolutionError
+from armbuilderx.cmsis.mdk_project import MdkProjectError
+from armbuilderx.paths import pack_root_dir
+from armbuilderx.sdk import available_sdk_ids, get_sdk_adapter
+from armbuilderx.toolchain.ensure import ensure_toolchain
+
+
+def _echo(msg: str) -> None:
+    click.echo(msg)
+
+
+@click.group()
+def main() -> None:
+    """ArmBuilderX: build, flash and monitor Keil/MDK Arm projects with
+    CMake, CMSIS-Toolbox and pyOCD."""
+
+
+@main.command()
+@click.option("--pack", "pack_files", multiple=True, type=click.Path(exists=True, path_type=Path),
+              help="Vendor .pack file to install into ArmBuilderX's managed pack root. "
+                   "Repeat for multiple packs.")
+def init(pack_files: tuple[Path, ...]) -> None:
+    """Install CMSIS-Pack(s) needed to resolve device data."""
+    if not pack_files:
+        _echo(f"pack root: {pack_root_dir()}")
+        _echo("Nothing to do. Pass --pack <file> to install a vendor pack.")
+        return
+    for pack_file in pack_files:
+        _echo(f"installing {pack_file} ...")
+        toolbox.add_pack(pack_file)
+    _echo("done.")
+
+
+@main.command()
+@click.argument("project_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--sdk", type=click.Choice(available_sdk_ids()),
+              help="SDK adapter to use. Defaults to automatic project-layout detection.")
+def generate(project_dir: Path, sdk: str | None) -> None:
+    """Generate/refresh GCC/*.csolution.yml + *.cproject.yml for PROJECT_DIR
+    from its existing MDK project."""
+    try:
+        result = generator.generate(project_dir, sdk=sdk)
+    except (MdkProjectError, generator.GenerateError) as exc:
+        raise click.ClickException(str(exc))
+    _echo(f"generated {result.csolution_yml}")
+    _echo(f"generated {result.cproject_yml}")
+
+
+def _resolve_pyocd_exe() -> str:
+    """pyocd is installed as a console script in the same environment as
+    armbuilderx (it's a pip dependency), so look next to the running
+    interpreter first; fall back to PATH for the rare case of a
+    non-standard install layout.
+    """
+    exe_dir = Path(sys.executable).parent
+    for name in ("pyocd", "pyocd.exe"):
+        candidate = exe_dir / name
+        if candidate.is_file():
+            return str(candidate)
+    found = shutil.which("pyocd")
+    if found:
+        return found
+    raise click.ClickException(
+        "pyocd not found. It is a pip dependency of armbuilderx; reinstall with "
+        "'pip install armbuilderx'."
+    )
+
+
+def _ensure_generated(project_dir: Path, sdk: str | None = None) -> Path:
+    gcc_dir = project_dir / "GCC"
+    selected_sdk = sdk
+    if selected_sdk is None:
+        try:
+            # SDK adapters own generated configuration such as startup files,
+            # ABI flags, and vendor linker inputs. Refresh it on every build;
+            # merely finding an existing csolution file must not retain stale
+            # adapter output from an earlier ArmBuilderX version.
+            selected_sdk = get_sdk_adapter(project_dir).sdk_id
+        except generator.GenerateError:
+            pass
+
+    if selected_sdk is not None:
+        _echo(f"refreshing project files with SDK adapter '{selected_sdk}'...")
+        generator.generate(project_dir, sdk=selected_sdk)
+    elif not list(gcc_dir.glob("*.csolution.yml")):
+        _echo("no GCC/*.csolution.yml found yet, generating it first...")
+        generator.generate(project_dir, sdk=sdk)
+    return gcc_dir
+
+
+@main.command()
+@click.argument("project_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--build-type", default="Debug", show_default=True, type=click.Choice(["Debug", "Release"]))
+@click.option("--clean", is_flag=True, help="Remove intermediate/output directories before building.")
+@click.option("--sdk", type=click.Choice(available_sdk_ids()),
+              help="SDK adapter to use if generation is needed.")
+def build(project_dir: Path, build_type: str, clean: bool, sdk: str | None) -> None:
+    """Ensure the toolchain is available, then build PROJECT_DIR/GCC."""
+    project_dir = project_dir.resolve()
+    try:
+        gcc_dir = _ensure_generated(project_dir, sdk)
+    except (MdkProjectError, generator.GenerateError) as exc:
+        raise click.ClickException(str(exc))
+
+    csolution_files = list(gcc_dir.glob("*.csolution.yml"))
+    if not csolution_files:
+        raise click.ClickException(f"no *.csolution.yml found under {gcc_dir}")
+    csolution_yml = csolution_files[0]
+
+    tc_env = ensure_toolchain(notify=_echo)
+    env = tc_env.as_environ()
+    env["CMSIS_PACK_ROOT"] = str(pack_root_dir())
+
+    args = [str(csolution_yml), "--toolchain", "GCC", "--packs"]
+    # *.cproject.yml -> project name (strip the ".cproject.yml" suffix, not just ".yml")
+    contexts = [c.name[: -len(".cproject.yml")] for c in gcc_dir.glob("*.cproject.yml")]
+    for context in contexts:
+        args += ["-c", f"{context}.{build_type}"]
+    if clean:
+        args.append("--rebuild")
+
+    _echo(f"building {csolution_yml.name} ({build_type}) ...")
+    result = toolbox.run(toolbox.cbuild_exe(), args, cwd=gcc_dir, env=env)
+    click.echo(result.stdout)
+    if result.returncode != 0:
+        click.echo(result.stderr, err=True)
+        raise click.ClickException("build failed")
+    _echo("build succeeded.")
+
+
+@main.command()
+@click.argument("project_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--build-type", default="Debug", show_default=True, type=click.Choice(["Debug", "Release"]))
+@click.option("--pack", "pack_file", type=click.Path(exists=True, path_type=Path),
+              help="Vendor .pack file pyOCD should use to resolve the target device.")
+@click.option(
+    "--target",
+    help="pyOCD target type name (defaults to the device declared by the MDK or CMSIS solution project).",
+)
+@click.option("--unique-id", help="pyOCD probe unique ID, when multiple probes are attached.")
+@click.option("--frequency", help="SWD/JTAG clock frequency, for example 100k or 1m.")
+@click.option("--connect", "connect_mode", type=click.Choice(["halt", "pre-reset", "under-reset", "attach"]),
+              help="pyOCD target connection mode.")
+def flash(project_dir: Path, build_type: str, pack_file, target, unique_id, frequency, connect_mode) -> None:
+    """Flash the ELF built for PROJECT_DIR onto the target with pyOCD."""
+    from armbuilderx import flash as flash_mod
+
+    project_dir = project_dir.resolve()
+    gcc_dir = project_dir / "GCC"
+    elf_path = flash_mod.find_elf(gcc_dir, build_type)
+
+    if pack_file is None or target is None:
+        try:
+            uvprojx = mdk_project.find_uvprojx(project_dir)
+            mdk = mdk_project.parse_uvprojx(uvprojx)
+            if target is None:
+                target = mdk.device.lower()
+        except MdkProjectError:
+            if target is None:
+                try:
+                    target = csolution.pyocd_target_from_csolution(project_dir)
+                except CSolutionError:
+                    pass
+
+    # Goodix links GR551x applications at 0x01002000, while its CMSIS-Pack
+    # .FLM file exposes a 0x00200000 flash range to pyOCD.  The Goodix
+    # downloader performs target-specific initialisation/address mapping that
+    # pyOCD cannot infer from this Pack, so do not risk a misleading partial
+    # programming attempt through the generic pyOCD backend.
+    if target == "gr551x":
+        raise click.ClickException(
+            "GR551x flashing is not supported by the pyOCD backend: the Goodix Pack flash "
+            "address does not match the SDK ELF address. Use Goodix GProgrammer with a J-Link, "
+            "or add a verified GR551x J-Link/GProgrammer backend."
+        )
+
+    pyocd_exe = _resolve_pyocd_exe()
+
+    _echo(f"flashing {elf_path} ...")
+    try:
+        flash_mod.flash(
+            elf_path,
+            pack_file=pack_file,
+            target=target,
+            unique_id=unique_id,
+            frequency=frequency,
+            connect_mode=connect_mode,
+            pyocd_exe=pyocd_exe,
+        )
+    except flash_mod.FlashError as exc:
+        raise click.ClickException(str(exc))
+    _echo("flash succeeded.")
+
+
+@main.command()
+@click.option("--port", help="Serial device to open (skips auto-detect).")
+@click.option("--unique-id", help="pyOCD probe unique ID to match against a serial port's serial number.")
+@click.option("--baud", default=115200, show_default=True)
+def monitor(port, unique_id, baud) -> None:
+    """Stream the DAPLink/CMSIS-DAP virtual COM port log."""
+    from armbuilderx.serial import monitor as monitor_mod
+
+    if port is None:
+        try:
+            if unique_id:
+                info = monitor_mod.find_port_for_probe(unique_id)
+            else:
+                info = monitor_mod.find_single_daplink_port()
+        except monitor_mod.SerialPortNotFoundError as exc:
+            raise click.ClickException(str(exc))
+        port = info.device
+        _echo(f"using serial port {port} ({info.description})")
+
+    _echo(f"streaming {port} @ {baud} baud, Ctrl+C to stop")
+    try:
+        for chunk in monitor_mod.stream(port, baudrate=baud):
+            sys.stdout.buffer.write(chunk)
+            sys.stdout.buffer.flush()
+    except KeyboardInterrupt:
+        _echo("\nstopped.")
+
+
+@main.command()
+@click.argument("project_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--build-type", default="Debug", show_default=True, type=click.Choice(["Debug", "Release"]))
+@click.option("--skip-monitor", is_flag=True, help="Build and flash only; do not open the serial monitor.")
+@click.option("--sdk", type=click.Choice(available_sdk_ids()),
+              help="SDK adapter to use if generation is needed.")
+@click.pass_context
+def run(ctx: click.Context, project_dir: Path, build_type: str, skip_monitor: bool,
+        sdk: str | None) -> None:
+    """Generate, build, flash, then stream the serial log — all in one shot."""
+    ctx.invoke(build, project_dir=project_dir, build_type=build_type, clean=False, sdk=sdk)
+    ctx.invoke(
+        flash,
+        project_dir=project_dir,
+        build_type=build_type,
+        pack_file=None,
+        target=None,
+        unique_id=None,
+        frequency=None,
+        connect_mode=None,
+    )
+    if not skip_monitor:
+        ctx.invoke(monitor, port=None, unique_id=None, baud=115200)
+
+
+if __name__ == "__main__":
+    main()

armbuilderx-0.1.1/src/armbuilderx/cmsis/csolution.py

@@ -0,0 +1,46 @@
+"""Read the target identity declared by a CMSIS Solution file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+class CSolutionError(RuntimeError):
+    """A CMSIS Solution file cannot provide an unambiguous target."""
+
+
+def find_csolution(project_dir: Path) -> Path:
+    """Return the sole GCC solution file for *project_dir*."""
+    candidates = sorted((project_dir / "GCC").glob("*.csolution.yml"))
+    if len(candidates) != 1:
+        raise CSolutionError(
+            f"expected exactly one GCC/*.csolution.yml under {project_dir}, "
+            f"found {len(candidates)}"
+        )
+    return candidates[0]
+
+
+def pyocd_target_from_csolution(project_dir: Path) -> str:
+    """Return pyOCD's lowercase target name from ``target-types[0].device``.
+
+    CMSIS uses a qualified device name such as ``Goodix::GR551x`` while pyOCD
+    registers the same Pack target as ``gr551x``.  The device declaration is
+    intentionally read from the project rather than maintained in a vendor
+    specific flash table.
+    """
+    path = find_csolution(project_dir)
+    try:
+        with path.open() as source:
+            data = yaml.safe_load(source)
+    except (OSError, yaml.YAMLError) as exc:
+        raise CSolutionError(f"could not read {path}: {exc}") from exc
+
+    try:
+        device = data["solution"]["target-types"][0]["device"]
+    except (KeyError, IndexError, TypeError) as exc:
+        raise CSolutionError(f"missing solution.target-types[0].device in {path}") from exc
+    if not isinstance(device, str) or not device.strip():
+        raise CSolutionError(f"invalid solution.target-types[0].device in {path}")
+    return device.rsplit("::", 1)[-1].lower()

armbuilderx-0.1.1/src/armbuilderx/cmsis/generator.py

@@ -0,0 +1,21 @@
+"""SDK-agnostic façade for CMSIS-Toolbox project generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping
+
+from armbuilderx.cmsis.types import GenerateError, GeneratedProject
+from armbuilderx.sdk.registry import get_sdk_adapter
+
+__all__ = ["GenerateError", "GeneratedProject", "generate"]
+
+
+def generate(
+    project_dir: Path,
+    pack_env: Mapping[str, str] | None = None,
+    sdk: str | None = None,
+) -> GeneratedProject:
+    """Generate a project through the explicitly selected or detected SDK adapter."""
+    project_dir = project_dir.resolve()
+    return get_sdk_adapter(project_dir, sdk).generate(project_dir, pack_env)

armbuilderx-0.1.1/src/armbuilderx/cmsis/mdk_project.py

@@ -0,0 +1,130 @@
+"""Parse a Keil MDK (.uvprojx) project just enough to drive CMSIS-Toolbox:
+device/vendor/pack identity, preprocessor defines, and the list of
+source file groups. CMSIS-Toolbox (csolution/cbuild/cbuild2cmake) does
+all of the real work of turning that into a CMake project; this module
+only extracts what already exists in the Keil project file.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class SourceFile:
+    path: Path  # absolute path
+    is_source: bool  # True for .c/.cpp/.s/.S that must be compiled; False for headers
+
+
+@dataclass
+class SourceGroup:
+    name: str
+    files: list[SourceFile] = field(default_factory=list)
+
+
+@dataclass
+class MdkTarget:
+    target_name: str
+    device: str
+    vendor: str
+    pack_id: str  # e.g. "NOVOSENSE.NS800RT5XXX.1.3.0"
+    output_name: str
+    defines: list[str]
+    include_paths: list[Path]
+    groups: list[SourceGroup]
+
+
+class MdkProjectError(RuntimeError):
+    pass
+
+
+# File types compiled from source (Keil's <FileType>): 1=C, 2=Asm, 8=C++.
+_COMPILABLE_FILE_TYPES = {"1", "2", "8"}
+
+
+def find_uvprojx(project_dir: Path) -> Path:
+    mdk_dir = project_dir / "MDK"
+    if not mdk_dir.is_dir():
+        raise MdkProjectError(f"no MDK/ folder found under {project_dir}")
+    candidates = sorted(mdk_dir.glob("*.uvprojx"))
+    if not candidates:
+        raise MdkProjectError(f"no .uvprojx file found under {mdk_dir}")
+    return candidates[0]
+
+
+def parse_pack_id(pack_id: str) -> tuple[str, str, str]:
+    """'NOVOSENSE.NS800RT5XXX.1.3.0' -> ('NOVOSENSE', 'NS800RT5XXX', '1.3.0')."""
+    parts = pack_id.split(".")
+    if len(parts) < 4:
+        raise MdkProjectError(f"unexpected PackID format: {pack_id!r}")
+    vendor, name = parts[0], parts[1]
+    version = ".".join(parts[2:])
+    return vendor, name, version
+
+
+def parse_uvprojx(uvprojx_path: Path) -> MdkTarget:
+    tree = ET.parse(uvprojx_path)
+    root = tree.getroot()
+
+    target_el = root.find("./Targets/Target")
+    if target_el is None:
+        raise MdkProjectError(f"no <Target> found in {uvprojx_path}")
+
+    target_name = _text(target_el, "TargetName")
+    common = target_el.find("./TargetOption/TargetCommonOption")
+    if common is None:
+        raise MdkProjectError(f"no TargetCommonOption in {uvprojx_path}")
+
+    device = _text(common, "Device")
+    vendor = _text(common, "Vendor")
+    pack_id = _text(common, "PackID")
+    output_name = _text(common, "OutputName") or target_name
+
+    cads = target_el.find("./TargetOption/TargetArmAds/Cads/VariousControls")
+    defines: list[str] = []
+    include_paths: list[Path] = []
+    if cads is not None:
+        define_text = _text(cads, "Define")
+        defines = [d for d in define_text.split() if d]
+        include_text = _text(cads, "IncludePath")
+        project_dir = uvprojx_path.parent  # .../MDK
+        for raw in include_text.split(";"):
+            raw = raw.strip()
+            if not raw:
+                continue
+            include_paths.append((project_dir / raw.replace("\\", "/")).resolve())
+
+    groups: list[SourceGroup] = []
+    project_dir = uvprojx_path.parent
+    for group_el in target_el.findall("./Groups/Group"):
+        group_name = _text(group_el, "GroupName") or "group"
+        files: list[SourceFile] = []
+        for file_el in group_el.findall("./Files/File"):
+            file_type = _text(file_el, "FileType")
+            file_path = _text(file_el, "FilePath")
+            if not file_path:
+                continue
+            abs_path = (project_dir / file_path.replace("\\", "/")).resolve()
+            files.append(SourceFile(path=abs_path, is_source=file_type in _COMPILABLE_FILE_TYPES))
+        groups.append(SourceGroup(name=group_name, files=files))
+
+    return MdkTarget(
+        target_name=target_name,
+        device=device,
+        vendor=vendor,
+        pack_id=pack_id,
+        output_name=output_name,
+        defines=defines,
+        include_paths=include_paths,
+        groups=groups,
+    )
+
+
+def _text(parent: ET.Element, tag: str) -> str:
+    el = parent.find(tag)
+    if el is None or el.text is None:
+        return ""
+    return el.text.strip()