bsworld 1.1.3__py3-none-any.whl

bsworld/__init__.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Xiaomi Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Deterministic simulation test framework for Bluetooth LE Applications."""
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+# bsworld loads bscontroller from its source in this repository.
+_BSCONTROLLER_SRC = Path(__file__).parents[2] / "components" / "bscontroller" / "src"
+if _BSCONTROLLER_SRC.is_dir():
+    sys.path.insert(0, str(_BSCONTROLLER_SRC))
+
+try:
+    __version__ = version("bsworld")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

bsworld/backends/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Xiaomi Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#

bsworld/backends/babblesim.py

@@ -0,0 +1,461 @@
+# Copyright 2026 Xiaomi Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""BabbleSim backend: PHY, independent Controllers, firmware and interference.
+
+Application command factories receive an AppSlot and select their native
+arguments for joining the PHY. Processes are registered once; Host and complete
+firmware slots are derived from their final attachments when the layout freezes.
+
+Bring-up shape:
+    1. verify configured BabbleSim artifacts.
+    2. prepare: kill stragglers for this sim_id, remove stale HCI
+       socket files.
+    3. plan_devices: freeze one DeviceLayout covering Virtual Controllers,
+       Host processes, complete firmware, the framework clock, then interference.
+    4. spawn phy (-D = num_devs).
+    5. spawn Virtual Controllers and interference devices. Firmware processes
+       are started by topology.
+    6. connect the in-process pytest clock after external participants start.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..deps import check_babblesim_ready
+from ..devices.bscontroller import BSController
+from ..devices.controller import Controller
+from ..devices.layout import DeviceLayout, build_device_layout
+from ..env import Env
+from ..interference import (
+    BurstInterference,
+    ChannelAttenuation,
+    InterferenceSource,
+    PlaybackInterference,
+    StaticAttenuation,
+    TimedAttenuation,
+    WlanInterference,
+)
+from ..log import log, warn
+from ..runtime.proc import ProcessManager
+from ..runtime.scheduler import BsimClock
+from ..runtime.wait import wait_for_path, wait_for_paths, wait_for_paths_async
+from .ellisys import convert_tx_csv
+
+if TYPE_CHECKING:
+    from ..devices.instance import ProcessInstance
+
+_RESIDUAL_PATTERNS = (
+    "bs_2G4_phy_v1",
+    "bt_virt_controller",
+    "bs_device_2G4_",
+)
+
+_PHY_ID = "2G4"
+_DEFAULT_MODEM = "BLE_simple"
+
+
+@dataclass
+class BabbleSimBackend:
+    env: Env
+    sim_id: str
+    controllers: list[Controller] = field(default_factory=list)
+    channel_attenuation: ChannelAttenuation | None = None
+    interference_sources: list[InterferenceSource] = field(default_factory=list)
+    _processes: list[ProcessInstance] = field(
+        default_factory=list, init=False, repr=False
+    )
+    _layout: DeviceLayout | None = field(default=None, init=False, repr=False)
+    _started: bool = False
+    clock: BsimClock | None = None
+
+    @property
+    def processes(self) -> tuple[ProcessInstance, ...]:
+        """Registered processes, read-only; register through register_process()."""
+        return tuple(self._processes)
+
+    def _ensure_layout_mutable(self) -> None:
+        """Reject registrations once PHY identities have been published.
+
+        start() freezes the layout first, so this also covers a started backend.
+        """
+        if self._layout is not None:
+            raise RuntimeError("cannot change participants after the layout is frozen")
+
+    def add_controller(
+        self,
+        *,
+        controller_type: type[Controller] = BSController,
+        public_address: str | None = None,
+        snoop_dir: Path | None = None,
+        **options,
+    ) -> Controller:
+        self._ensure_layout_mutable()
+        dev_id = len(self.controllers)
+        ctl = controller_type(
+            controller_dev_id=dev_id,
+            sim_id=self.sim_id,
+            phy_id=_PHY_ID,
+            socket_dir=self.env.sim_dir(self.sim_id),
+            public_address=public_address,
+            **options,
+        )
+        # Decided once, here: every Controller knows where its capture goes
+        # before it starts, so no implementation needs a fallback path.
+        ctl.hci_snoop_file = (
+            (snoop_dir or self.env.log_dir / "controllers") / f"hci{dev_id}.snoop"
+        ).resolve()
+        self.controllers.append(ctl)
+        return ctl
+
+    def validate_attachment(
+        self, process: ProcessInstance, controller: Controller
+    ) -> None:
+        """Check that a Controller can be attached, without changing any state."""
+        self._ensure_layout_mutable()
+        if not any(candidate is controller for candidate in self.controllers):
+            raise ValueError("Controller does not belong to this BabbleSim backend")
+        if any(
+            other is not process and other.controller is controller
+            for other in self._processes
+        ):
+            raise ValueError(
+                "a Virtual Controller can only be attached to one Application process"
+            )
+
+    def register_process(self, process: ProcessInstance) -> None:
+        """Record a process once; its final attachment is read when ids are frozen."""
+        if any(existing is process for existing in self._processes):
+            raise ValueError("process is already registered with this backend")
+        if process.controller is None:
+            self._ensure_layout_mutable()
+        else:
+            self.validate_attachment(process, process.controller)
+        self._processes.append(process)
+
+    def add_interference_source(self, source: InterferenceSource) -> int:
+        """Record an interference device and return its index."""
+        self._ensure_layout_mutable()
+        self.interference_sources.append(source)
+        return len(self.interference_sources) - 1
+
+    def set_snoop_dir(self, controller: Controller, snoop_dir: Path) -> None:
+        """Relocate a Controller's capture before it starts."""
+        if self._started:
+            raise RuntimeError("cannot move an HCI capture after BabbleSim has started")
+        if not any(candidate is controller for candidate in self.controllers):
+            raise ValueError("Controller does not belong to this BabbleSim backend")
+        controller.hci_snoop_file = (
+            snoop_dir / f"hci{controller.controller_dev_id}.snoop"
+        ).resolve()
+
+    def plan_devices(self) -> DeviceLayout:
+        """Freeze the device id assignment for the registered topology.
+
+        Device ids are derived from the registered participants, so the first
+        caller after registration fixes the layout for the whole simulation.
+        """
+        if self._layout is None:
+            self._layout = build_device_layout(
+                phy_id=_PHY_ID,
+                sim_id=self.sim_id,
+                controllers=self.controllers,
+                processes=self._processes,
+                interference_count=len(self.interference_sources),
+            )
+        return self._layout
+
+    def check_deps_ready(self) -> None:
+        check_babblesim_ready(self.env)
+
+    def prepare(self) -> None:
+        log(f"preparing bsim sim_id={self.sim_id}")
+        sim_dir = self.env.sim_dir(self.sim_id)
+        sim_dir.mkdir(parents=True, exist_ok=True)
+        for pat in _RESIDUAL_PATTERNS:
+            subprocess.run(
+                ["pkill", "-9", "-f", f"{pat}.*-s={self.sim_id}"],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        subprocess.run(
+            ["pkill", "-9", "-f", "--", f"--sim-bsim-sid={self.sim_id}"],
+            check=False,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        for ctl in self.controllers:
+            if ctl.hci_sock.exists():
+                log(f"removing stale {ctl.hci_sock}")
+                ctl.hci_sock.unlink()
+
+    async def start(
+        self,
+        pm: ProcessManager,
+        *,
+        log_dir: Path | None = None,
+        ready_timeout: float = 30.0,
+    ) -> None:
+        log_dir = log_dir or self.env.log_dir
+        bsim_log_dir = log_dir / "babblesim"
+        if self._started:
+            return
+        if not self.controllers and not self._processes:
+            raise RuntimeError(
+                "a BabbleSim simulation requires at least one Virtual Controller "
+                "or complete firmware"
+            )
+        self.check_deps_ready()
+        self.prepare()
+
+        layout = self.plan_devices()
+        num_devs = layout.device_count
+
+        # Spawn phy.
+        phy_bin = self.env.bsim_bin_dir / f"bs_{_PHY_ID}_phy_v1"
+        phy_argv: list = [
+            phy_bin,
+            f"-s={self.sim_id}",
+            f"-D={num_devs}",
+            f"-defmodem={_DEFAULT_MODEM}",
+        ]
+        if self.channel_attenuation is not None:
+            ca = self.channel_attenuation
+            matrix_file = ca.matrix_file
+            if ca.static_paths or ca.timed_paths:
+                matrix_file = _write_attenuation_matrix(
+                    static_paths=ca.static_paths,
+                    timed_paths=ca.timed_paths,
+                    out_dir=bsim_log_dir,
+                )
+            phy_argv += [
+                "-channel=multiatt",
+                "-argschannel",
+                f"-at={ca.default_attenuation_db}",
+            ]
+            if ca.extra_attenuation_db:
+                phy_argv.append(f"-atextra={ca.extra_attenuation_db}")
+            if matrix_file is not None:
+                phy_argv.append(f"-file={matrix_file}")
+            # switch back to main phy args so subsequent flags (-dump etc.) are
+            # not consumed by the channel plugin
+            phy_argv.append("-argsmain")
+        phy_argv.extend(["-dump", "-dump_imm"])
+        phy_process = pm.spawn(
+            "bs_2G4_phy_v1",
+            phy_argv,
+            cwd=self.env.bsim_bin_dir,
+            log_dir=bsim_log_dir,
+        )
+        sim_dir = self.env.sim_dir(self.sim_id)
+        wait_for_path(sim_dir / "2G4.phy.lock", timeout=ready_timeout)
+        log("phy ready")
+
+        self.clock = BsimClock(
+            sim_dir=sim_dir,
+            phy_id=_PHY_ID,
+            dev_id=layout.clock_dev_id,
+            phy_alive=phy_process.alive,
+        )
+
+        for ctl in self.controllers:
+            await ctl.start(pm, self.env, log_dir=log_dir)
+
+        for i, src in enumerate(self.interference_sources):
+            dev_id = layout.interference_dev_id(i)
+            argv = _build_interf_argv(
+                src, sim_id=self.sim_id, dev_id=dev_id, bin_dir=self.env.bsim_bin_dir
+            )
+            pm.spawn(
+                f"interf_{dev_id}",
+                argv,
+                cwd=self.env.bsim_bin_dir,
+                log_dir=bsim_log_dir,
+            )
+        self._started = True
+
+    async def stop_controllers(self) -> None:
+        """Release Controller runtimes before terminating the shared PHY."""
+        results = await asyncio.gather(
+            *(ctl.stop() for ctl in self.controllers), return_exceptions=True
+        )
+        for result in results:
+            if isinstance(result, BaseException):
+                raise result
+
+    def device_lock_paths(self) -> list[Path]:
+        return self.plan_devices().lock_paths(self.env.sim_dir(self.sim_id))
+
+    def wait_for_devices_registered(self, *, timeout: float = 30.0) -> None:
+        locks = self.device_lock_paths()
+        log(f"waiting for {len(locks)} BabbleSim device lock(s)")
+        if self.clock is not None:
+            self.clock.connect(timeout=timeout)
+        wait_for_paths(locks, timeout=timeout)
+        log("all devices registered to phy")
+
+    async def wait_for_hci_sockets(self, *, timeout: float = 30.0) -> None:
+        socks = [ctl.hci_sock for ctl in self.controllers]
+        if not socks:
+            return
+        log(f"waiting for {len(socks)} hci socket(s)")
+        await wait_for_paths_async(socks, timeout=timeout)
+        log("hci socket(s) bound")
+
+    def finish(self, *, log_dir: Path | None = None) -> None:
+        """Release the clock and archive artifacts, including after a failed start."""
+        if self.clock is not None:
+            try:
+                self.clock.close()
+            except Exception as exc:
+                warn(f"simulation clock close failed: {exc}")
+            finally:
+                self.clock = None
+        try:
+            self.convert_ellisys(log_dir=log_dir)
+        finally:
+            self.cleanup_sim_artifacts()
+
+    def convert_ellisys(self, *, log_dir: Path | None = None) -> None:
+        if self.env.bsim_dir is None:
+            return
+        results_dir = self.env.bsim_dir / "results" / self.sim_id
+        tx_files = sorted(results_dir.glob("d_2G4*.Tx.csv"))
+        if not tx_files:
+            warn(f"no BabbleSim Tx CSV dumps found under {results_dir}")
+            return
+
+        out_dir = (log_dir or self.env.log_dir) / "babblesim"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / "ellisys.bttrp"
+        log(f"converting BabbleSim dump to Ellisys: {out_path}")
+        try:
+            with out_path.open("w") as out:
+                convert_tx_csv(tx_files, out)
+        except (OSError, ValueError) as exc:
+            warn(f"Ellisys conversion failed for {self.sim_id}: {exc}")
+
+    def cleanup_sim_artifacts(self) -> None:
+        sim_state_dir = self.env.sim_dir(self.sim_id)
+        if sim_state_dir.exists():
+            log(f"removing sim state {sim_state_dir}")
+            shutil.rmtree(sim_state_dir, ignore_errors=True)
+
+        results_dir = (
+            self.env.bsim_dir / "results" / self.sim_id if self.env.bsim_dir else None
+        )
+        if results_dir is not None and results_dir.exists():
+            log(f"removing bsim results {results_dir}")
+            shutil.rmtree(results_dir, ignore_errors=True)
+
+        for ctl in self.controllers:
+            ctl.hci_sock.unlink(missing_ok=True)
+
+
+def _write_attenuation_matrix(
+    *,
+    static_paths: list[StaticAttenuation],
+    timed_paths: list[TimedAttenuation],
+    out_dir: Path,
+) -> Path:
+    """Write per-path static/timed attenuation files + matrix_file into out_dir.
+
+    Files are placed in the test log directory so they survive cleanup and are
+    available for post-mortem inspection alongside bsworld.log and HCI snoops.
+    Returns the path to the generated matrix file ready for -file=<path>.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    matrix_lines = [
+        f"{path.tx} {path.rx} : {path.attenuation_db}" for path in static_paths
+    ]
+    for i, tp in enumerate(timed_paths):
+        timed_file = out_dir / f"timed_att_{tp.tx}_{tp.rx}_{i}.txt"
+        with open(timed_file, "w") as fh:
+            for t, att in zip(tp.times_us, tp.attenuation_db):
+                fh.write(f"{t}    {att}\n")
+        matrix_lines.append(f'{tp.tx} {tp.rx} : "{timed_file}"')
+
+    matrix_file = out_dir / "att_matrix.txt"
+    with open(matrix_file, "w") as fh:
+        fh.write("\n".join(matrix_lines) + "\n")
+    return matrix_file
+
+
+def _build_interf_argv(
+    src: InterferenceSource,
+    *,
+    sim_id: str,
+    dev_id: int,
+    bin_dir: Path,
+) -> list:
+    common = [f"-s={sim_id}", f"-d={dev_id}"]
+
+    if isinstance(src, BurstInterference):
+        argv: list = [bin_dir / "bs_device_2G4_burst_interf"] + common
+        argv += [
+            f"-centerfreq={src.center_freq_mhz}",
+            f"-power={src.power_dbm}",
+            f"-type={src.interf_type}",
+        ]
+        if src.rand_seed is not None:
+            argv.append(f"-rs={src.rand_seed}")
+        _append_windows(argv, src.windows)
+        return argv
+
+    if isinstance(src, WlanInterference):
+        argv = [bin_dir / "bs_device_2G4_WLAN_actmod"] + common
+        if src.channel is not None:
+            argv.append(f"-channel={src.channel}")
+        else:
+            argv.append(f"-centerfreq={src.center_freq_mhz}")
+        argv += [
+            f"-power={src.power_dbm}",
+            f"-mod={src.mod_type}",
+            f"-ConfigSet={src.config_set}",
+        ]
+        if src.rand_seed is not None:
+            argv.append(f"-rs={src.rand_seed}")
+        _append_windows(argv, src.windows)
+        return argv
+
+    if isinstance(src, PlaybackInterference):
+        argv = [bin_dir / "bs_device_2G4_playbackv2"] + common
+        argv.append(f"-inputf={src.input_file}")
+        if not src.tx:
+            argv.append("-txoff")
+        if not src.rx:
+            argv.append("-rxoff")
+        if not src.rssi:
+            argv.append("-rssioff")
+        if not src.cca:
+            argv.append("-ccaoff")
+        return argv
+
+    raise TypeError(f"unknown interference source type: {type(src)}")
+
+
+def _append_windows(argv: list, windows: list[tuple[int, int]]) -> None:
+    if not windows:
+        return
+    argv.append("-timestart")
+    argv.extend(str(start) for start, _ in windows)
+    argv.append("-timeend")
+    argv.extend(str(end) for _, end in windows)

bsworld/backends/ellisys.py

@@ -0,0 +1,66 @@
+# Copyright 2018 Oticon A/S
+# Copyright 2026 Xiaomi Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""Convert BabbleSim Tx CSV dumps to the Ellisys Bluetooth import format.
+
+Port of ext_2G4_phy_v1/dump_post_process/convert_results_to_ellisysv2.sh.
+Keep its header, fixed RSSI, Coded segment handling and numeric/lexical sort
+order so existing traces remain identical, including duplicate records.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import TextIO
+
+_HEADER = (
+    "FileFormat:Bluetooth\n                version=1.0\n\nItemFormat:LE version=1.1\n"
+)
+
+
+def convert_tx_csv(tx_files: Iterable[Path], output: TextIO) -> None:
+    """Merge dumps in input order and write a time-sorted .bttrp trace."""
+    records: list[tuple[int, str]] = []
+    timestamp = "0"
+    address = ""
+    channel = 0
+    rssi = 0
+    ci = ""
+    for path in tx_files:
+        with path.open() as source:
+            next(source, None)  # Each device dump has its own CSV header.
+            for line in source:
+                fields = line.removesuffix("\n").split(",")
+                if len(fields) != 10 or not fields[9]:
+                    continue
+                packet = fields[9]
+                modulation = int(fields[4])
+                if modulation == 80 and int(fields[8]) > 4:
+                    # FEC2 inherits the FEC1 timestamp, address, channel and CI.
+                    phy = f"Coded coding=Coded{8 if ci == '00' else 2}"
+                else:
+                    # Match awk's double arithmetic and %.0f timestamp format.
+                    timestamp = f"{float(fields[0]) * 1000:.0f}"
+                    channel = int((float(fields[2]) - 2) / 2)
+                    address = fields[3]
+                    rssi = -40
+                    if len(packet) >= 2:
+                        ci = packet[:2]
+                    if modulation == 16:
+                        phy = "1Mbps"
+                    elif modulation in (32, 33):
+                        phy = "2Mbps"
+                    else:
+                        continue
+                record = (
+                    f'{timestamp} aa={address} rssi={rssi} rfchannel={channel} '
+                    f'phy={phy} rawdata="{packet.rstrip()}"'
+                )
+                records.append((int(timestamp), record))
+
+    output.write(_HEADER)
+    # GNU sort -g breaks numeric ties by comparing the entire line.
+    for _, record in sorted(records):
+        output.write(f"Item time={record}\n")

bsworld/deps.py

@@ -0,0 +1,100 @@
+# Copyright 2026 Xiaomi Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Validate the externally built artifacts a simulation depends on.
+
+Nothing here compiles: BabbleSim, the Virtual Controller and every Host are
+built outside pytest and selected through environment variables. These checks
+run before a topology starts so a missing artifact is reported once, with the
+setup guide, instead of surfacing as a failed process spawn.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .env import Env
+
+_BABBLESIM_OUTPUTS = (
+    "bin/bs_2G4_phy_v1",
+    "bin/bs_device_2G4_burst_interf",
+    "bin/bs_device_2G4_WLAN_actmod",
+    "lib/lib_2G4Channel_NtNcable.so",
+    "lib/lib_2G4Channel_multiatt.so",
+    "lib/lib_2G4Modem_BLE_simple.so",
+    # Real AES for the nRF HW models (-RealEncryption=1).
+    "lib/libCryptov1.so",
+)
+
+_CONTROLLER_HINT = (
+    "Build the Virtual Controller and export BSWORLD_BT_VIRT_CONTROLLER_BIN "
+    "as the path to zephyr.exe. See docs/controllers.md."
+)
+
+
+class BSWorldSetupError(RuntimeError):
+    """A required artifact is missing or not configured.
+
+    Raised before a topology starts, so pytest reports it as an ordinary
+    failure against the test that needed the artifact.
+    """
+
+
+def check_babblesim_ready(env: Env) -> None:
+    """Validate the selected BabbleSim runtime outputs."""
+    if env.bsim_dir is None:
+        raise BSWorldSetupError(
+            (
+                "Set BSIM_OUT_PATH to the BabbleSim output directory containing bin/ "
+                "and lib/. See README.md."
+            )
+        )
+    missing = [
+        str(env.bsim_dir / rel)
+        for rel in _BABBLESIM_OUTPUTS
+        if not (env.bsim_dir / rel).is_file()
+        or (rel.startswith("bin/") and not os.access(env.bsim_dir / rel, os.X_OK))
+    ]
+    if missing:
+        raise BSWorldSetupError(
+            "BabbleSim build outputs are missing.\nMissing:\n    "
+            + "\n    ".join(missing)
+            + "\nFollow the repo-based BabbleSim setup in README.md#build-and-test, "
+            "then set BSIM_OUT_PATH to the build output directory "
+            f"containing bin/ and lib/ (currently {env.bsim_dir})."
+        )
+
+
+def check_controller_ready(env: Env) -> None:
+    """Validate the native Virtual Controller executable."""
+    binary = env.hci_virt_bin
+    if binary is None or not binary.is_file() or not os.access(binary, os.X_OK):
+        raise BSWorldSetupError(
+            f"Virtual Controller executable unavailable: {binary}\n{_CONTROLLER_HINT}"
+        )
+
+
+def controller_bin(env: Env) -> Path:
+    """Return the validated Virtual Controller launcher path."""
+    check_controller_ready(env)
+    return env.hci_virt_bin
+
+
+__all__ = [
+    "BSWorldSetupError",
+    "check_babblesim_ready",
+    "check_controller_ready",
+    "controller_bin",
+]