armbuilderx 0.1.1__py3-none-any.whl

armbuilderx/__init__.py

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

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/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/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/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()

armbuilderx/cmsis/toolbox.py

@@ -0,0 +1,69 @@
+"""Locate and invoke the CMSIS-Toolbox executables (csolution, cbuild,
+cpackget). ArmBuilderX never re-implements pack parsing or CMake
+generation itself; it only shells out to these official binaries.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from armbuilderx.paths import cmsis_toolbox_bin_dir, pack_root_dir
+
+
+class CmsisToolboxNotFoundError(RuntimeError):
+    pass
+
+
+def _resolve(exe_name: str) -> Path:
+    bin_dir = cmsis_toolbox_bin_dir()
+    if bin_dir and bin_dir.is_dir():
+        candidate = bin_dir / exe_name
+        candidate_exe = bin_dir / f"{exe_name}.exe"
+        if candidate.is_file():
+            return candidate
+        if candidate_exe.is_file():
+            return candidate_exe
+    found = shutil.which(exe_name)
+    if found:
+        return Path(found)
+    raise CmsisToolboxNotFoundError(
+        f"'{exe_name}' not found. Install CMSIS-Toolbox and either put it on "
+        f"PATH or set ARMBUILDERX_CMSIS_TOOLBOX_BIN to its bin directory."
+    )
+
+
+def csolution_exe() -> Path:
+    return _resolve("csolution")
+
+
+def cbuild_exe() -> Path:
+    return _resolve("cbuild")
+
+
+def cpackget_exe() -> Path:
+    return _resolve("cpackget")
+
+
+def run(exe: Path, args: list[str], cwd: Optional[Path] = None, env: Optional[dict] = None):
+    return subprocess.run(
+        [str(exe), *args],
+        cwd=str(cwd) if cwd else None,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+
+
+def add_pack(pack_file: Path, env: Optional[dict] = None) -> None:
+    """Install a local .pack file into the managed pack root (idempotent)."""
+    pack_root_dir().mkdir(parents=True, exist_ok=True)
+    full_env = dict(env or {})
+    full_env.setdefault("CMSIS_PACK_ROOT", str(pack_root_dir()))
+    result = run(cpackget_exe(), ["add", str(pack_file)], env=full_env)
+    if result.returncode != 0 and "already installed" not in (result.stderr + result.stdout):
+        raise RuntimeError(
+            f"cpackget add failed for {pack_file}:\n{result.stdout}\n{result.stderr}"
+        )

armbuilderx/cmsis/types.py

@@ -0,0 +1,17 @@
+"""SDK-independent generation result and errors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class GenerateError(RuntimeError):
+    """Raised when a project cannot be generated for the selected SDK."""
+
+
+@dataclass(frozen=True)
+class GeneratedProject:
+    gcc_dir: Path
+    csolution_yml: Path
+    cproject_yml: Path

armbuilderx/flash.py

@@ -0,0 +1,54 @@
+"""Flash a built ELF onto the target over CMSIS-DAP/DAPLink, using pyOCD.
+
+ArmBuilderX shells out to the `pyocd` CLI (rather than re-implementing
+flashing against pyOCD's Python API) so behavior always matches pyOCD's
+own, well-tested command-line contract.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+class FlashError(RuntimeError):
+    pass
+
+
+def find_elf(gcc_dir: Path, build_type: str = "Debug") -> Path:
+    """Locate the most recently built .elf under GCC/out/**/<build_type>/."""
+    candidates = sorted(
+        gcc_dir.glob(f"out/*/*/{build_type}/*.elf"), key=lambda p: p.stat().st_mtime, reverse=True
+    )
+    if not candidates:
+        raise FlashError(
+            f"no .elf found under {gcc_dir / 'out'} ({build_type}); build the project first"
+        )
+    return candidates[0]
+
+
+def flash(
+    elf_path: Path,
+    pack_file: Optional[Path] = None,
+    target: Optional[str] = None,
+    unique_id: Optional[str] = None,
+    frequency: Optional[str] = None,
+    connect_mode: Optional[str] = None,
+    pyocd_exe: str = "pyocd",
+) -> None:
+    args = [pyocd_exe, "load", str(elf_path)]
+    if pack_file:
+        args += ["--pack", str(pack_file)]
+    if target:
+        args += ["-t", target]
+    if unique_id:
+        args += ["-u", unique_id]
+    if frequency:
+        args += ["-f", frequency]
+    if connect_mode:
+        args += ["--connect", connect_mode]
+
+    result = subprocess.run(args, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise FlashError(f"pyocd load failed:\n{result.stdout}\n{result.stderr}")

armbuilderx/paths.py

@@ -0,0 +1,66 @@
+"""Well-known directories used by ArmBuilderX."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def home_dir() -> Path:
+    """Root directory ArmBuilderX uses for its own cache/state."""
+    override = os.environ.get("ARMBUILDERX_HOME")
+    if override:
+        return Path(override)
+    return Path.home() / ".armbuilderx"
+
+
+def tools_dir() -> Path:
+    """Directory where auto-downloaded toolchains are installed."""
+    return home_dir() / "tools"
+
+
+def pack_root_dir() -> Path:
+    """CMSIS_PACK_ROOT used by cpackget/csolution/cbuild."""
+    override = os.environ.get("ARMBUILDERX_PACK_ROOT")
+    if override:
+        return Path(override)
+    return home_dir() / "packs"
+
+
+def cmsis_toolbox_bin_dir() -> Path:
+    """Bundled or user-provided CMSIS-Toolbox bin directory.
+
+    Resolution order:
+    1. ARMBUILDERX_CMSIS_TOOLBOX_BIN environment variable.
+    2. A `cmsis-toolbox-<platform>/bin` directory bundled next to the
+       installed package (used for local/dev checkouts).
+    3. `csolution`/`cbuild` already on PATH.
+    """
+    override = os.environ.get("ARMBUILDERX_CMSIS_TOOLBOX_BIN")
+    if override:
+        return Path(override)
+
+    candidates = []
+    if sys.platform == "darwin":
+        candidates.append("cmsis-toolbox-darwin-arm64")
+        candidates.append("cmsis-toolbox-darwin-x64")
+    elif sys.platform.startswith("linux"):
+        candidates.append("cmsis-toolbox-linux-x64")
+        candidates.append("cmsis-toolbox-linux-arm64")
+    elif sys.platform.startswith("win"):
+        candidates.append("cmsis-toolbox-windows-x64")
+
+    here = Path(__file__).resolve()
+    for parent in [here.parent, *here.parents]:
+        for name in candidates:
+            bin_dir = parent / name / "bin"
+            if bin_dir.is_dir():
+                return bin_dir
+        # also look one level up from a repo checkout (ArmBuilderX/<name>/bin)
+        for name in candidates:
+            bin_dir = parent.parent / name / "bin"
+            if bin_dir.is_dir():
+                return bin_dir
+
+    return Path()  # empty -> caller falls back to PATH lookup

armbuilderx/sdk/__init__.py

@@ -0,0 +1,10 @@
+"""SDK-specific project-generation adapters.
+
+The command layer and CMSIS-Toolbox integration stay SDK agnostic.  Each
+vendor SDK contributes one adapter that understands only that SDK's layout
+and build conventions.
+"""
+
+from armbuilderx.sdk.registry import available_sdk_ids, get_sdk_adapter
+
+__all__ = ["available_sdk_ids", "get_sdk_adapter"]