opentrons 8.6.0a1__py3-none-any.whl

opentrons/hardware_control/simulator_setup.py

@@ -0,0 +1,260 @@
+import asyncio
+from typing import Dict, Optional, Any, List, Union
+from typing_extensions import Literal
+from dataclasses import dataclass, asdict, field, replace
+import json
+from pathlib import Path
+from warnings import warn
+
+from opentrons.config import robot_configs
+from opentrons.config.types import RobotConfig, OT3Config
+from opentrons.types import Mount
+from opentrons.hardware_control import API, HardwareControlAPI, ThreadManager
+from opentrons.hardware_control.types import OT3Mount, HardwareFeatureFlags
+from opentrons.hardware_control.modules import SimulatingModule
+
+
+# Name and kwargs for a module function
+@dataclass(frozen=True)
+class ModuleCall:
+    function_name: str
+    args: List[Any] = field(default_factory=list)
+    kwargs: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModuleItem:
+    serial_number: str
+    model: str
+    calls: List[ModuleCall] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class OT2SimulatorSetup:
+    machine: Literal["OT-2 Standard"] = "OT-2 Standard"
+    attached_instruments: Dict[Mount, Dict[str, Optional[str]]] = field(
+        default_factory=dict
+    )
+    attached_modules: Dict[str, List[ModuleItem]] = field(default_factory=dict)
+    config: Optional[RobotConfig] = None
+    strict_attached_instruments: bool = True
+
+
+@dataclass(frozen=True)
+class OT3SimulatorSetup:
+    machine: Literal["OT-3 Standard"] = "OT-3 Standard"
+    attached_instruments: Dict[OT3Mount, Dict[str, Optional[str]]] = field(
+        default_factory=dict
+    )
+    attached_modules: Dict[str, List[ModuleItem]] = field(default_factory=dict)
+    config: Optional[OT3Config] = None
+    strict_attached_instruments: bool = True
+
+
+SimulatorSetup = Union[OT2SimulatorSetup, OT3SimulatorSetup]
+
+
+async def _simulator_for_setup(
+    setup: SimulatorSetup, loop: Optional[asyncio.AbstractEventLoop]
+) -> HardwareControlAPI:
+    if setup.machine == "OT-2 Standard":
+        return await API.build_hardware_simulator(
+            attached_instruments=setup.attached_instruments,
+            attached_modules={
+                k: [
+                    SimulatingModule(serial_number=m.serial_number, model=m.model)
+                    for m in v
+                ]
+                for k, v in setup.attached_modules.items()
+            },
+            config=setup.config,
+            strict_attached_instruments=setup.strict_attached_instruments,
+            loop=loop,
+            feature_flags=HardwareFeatureFlags.build_from_ff(),
+        )
+    else:
+        from opentrons.hardware_control.ot3api import OT3API
+
+        return await OT3API.build_hardware_simulator(
+            attached_instruments=setup.attached_instruments,
+            attached_modules={
+                k: [
+                    SimulatingModule(serial_number=m.serial_number, model=m.model)
+                    for m in v
+                ]
+                for k, v in setup.attached_modules.items()
+            },
+            config=setup.config,
+            strict_attached_instruments=setup.strict_attached_instruments,
+            loop=loop,
+            feature_flags=HardwareFeatureFlags.build_from_ff(),
+        )
+
+
+async def create_simulator(
+    setup: SimulatorSetup, loop: Optional[asyncio.AbstractEventLoop] = None
+) -> HardwareControlAPI:
+    """Create a simulator"""
+    simulator = await _simulator_for_setup(setup, loop)
+    for attached_module in simulator.attached_modules:
+        modules = setup.attached_modules[attached_module.name()]
+        for module in modules:
+            if module.serial_number == attached_module.device_info.get("serial"):
+                for call in module.calls:
+                    f = getattr(attached_module, call.function_name)
+                    await f(*call.args, **call.kwargs)
+
+    return simulator
+
+
+async def load_simulator(
+    path: Path, loop: Optional[asyncio.AbstractEventLoop] = None
+) -> HardwareControlAPI:
+    """Create a simulator from a JSON file."""
+    return await create_simulator(setup=load_simulator_setup(path), loop=loop)
+
+
+def _thread_manager_for_setup(
+    setup: SimulatorSetup,
+) -> ThreadManager[HardwareControlAPI]:
+    if setup.machine == "OT-2 Standard":
+        return ThreadManager(
+            API.build_hardware_simulator,
+            attached_instruments=setup.attached_instruments,
+            attached_modules={
+                k: [
+                    SimulatingModule(serial_number=m.serial_number, model=m.model)
+                    for m in v
+                ]
+                for k, v in setup.attached_modules.items()
+            },
+            config=setup.config,
+            strict_attached_instruments=setup.strict_attached_instruments,
+            feature_flags=HardwareFeatureFlags.build_from_ff(),
+        )
+    else:
+        from opentrons.hardware_control.ot3api import OT3API
+
+        return ThreadManager(
+            OT3API.build_hardware_simulator,
+            attached_instruments=setup.attached_instruments,
+            attached_modules={
+                k: [
+                    SimulatingModule(serial_number=m.serial_number, model=m.model)
+                    for m in v
+                ]
+                for k, v in setup.attached_modules.items()
+            },
+            config=setup.config,
+            strict_attached_instruments=setup.strict_attached_instruments,
+            feature_flags=HardwareFeatureFlags.build_from_ff(),
+        )
+
+
+async def create_simulator_thread_manager(
+    setup: SimulatorSetup,
+) -> ThreadManager[HardwareControlAPI]:
+    """Create a simulator thread manager from a loaded config."""
+    thread_manager = _thread_manager_for_setup(setup)
+    await thread_manager.managed_thread_ready_async()
+
+    for attached_module in thread_manager.wrapped().attached_modules:
+        modules = setup.attached_modules[attached_module.name()]
+        for module in modules:
+            for call in module.calls:
+                f = getattr(attached_module, call.function_name)
+                await f(*call.args, **call.kwargs)
+
+    return thread_manager
+
+
+async def load_simulator_thread_manager(
+    path: Path,
+) -> ThreadManager[HardwareControlAPI]:
+    """Create a simulator wrapped in a ThreadManager from a JSON file."""
+    return await create_simulator_thread_manager(load_simulator_setup(path))
+
+
+def save_simulator_setup(simulator_setup: SimulatorSetup, path: Path) -> None:
+    """Write a simulator setup to a file."""
+    no_config = replace(simulator_setup, config=None)
+    as_dict = asdict(no_config)
+
+    as_dict["config"] = (
+        robot_configs.config_to_save(simulator_setup.config)
+        if simulator_setup.config
+        else None
+    )
+
+    if as_dict.get("attached_instruments", None):
+        as_dict["attached_instruments"] = {
+            mount.name.lower(): data
+            for mount, data in as_dict["attached_instruments"].items()
+        }
+
+    with path.open("w") as f:
+        json.dump(as_dict, f)
+
+
+def load_simulator_setup(path: Path) -> SimulatorSetup:
+    """Load a simulator setup from a file."""
+    with path.open() as f:
+        obj = json.load(f)
+
+    if "machine" not in obj:
+        warn(
+            "Simulator configuration does not name a machine, defaulting to OT-2 Standard"
+        )
+    machine_type = obj.get("machine", "OT-2 Standard")
+    if machine_type == "OT-2 Standard":
+        return OT2SimulatorSetup(
+            **{k: _prepare_for_simulator_setup(k, v) for (k, v) in obj.items()}
+        )
+    else:
+        return OT3SimulatorSetup(
+            **{k: _prepare_for_ot3_simulator_setup(k, v) for (k, v) in obj.items()}
+        )
+
+
+def _prepare_for_simulator_setup(key: str, value: Dict[str, Any]) -> Any:
+    """Convert value to a SimulatorSetup"""
+    if key == "attached_instruments" and value:
+        return {Mount[mount.upper()]: data for (mount, data) in value.items()}
+    if key == "config" and value:
+        return robot_configs.build_config_ot2(value)
+    if key == "attached_modules" and value:
+        attached_modules: Dict[str, List[ModuleItem]] = {}
+        for key, item in value.items():
+            for obj in item:
+                attached_modules.setdefault(key, []).append(
+                    ModuleItem(
+                        serial_number=obj["serial_number"],
+                        model=obj["model"],
+                        calls=[ModuleCall(**data) for data in obj["calls"]],
+                    )
+                )
+
+        return attached_modules
+
+    return value
+
+
+def _prepare_for_ot3_simulator_setup(key: str, value: Dict[str, Any]) -> Any:
+    if key == "attached_instruments" and value:
+        return {OT3Mount[mount.upper()]: data for (mount, data) in value.items()}
+    if key == "config" and value:
+        return robot_configs.build_config_ot3(value)
+    if key == "attached_modules" and value:
+        attached_modules: Dict[str, List[ModuleItem]] = {}
+        for key, item in value.items():
+            for obj in item:
+                attached_modules.setdefault(key, []).append(
+                    ModuleItem(
+                        serial_number=obj["serial_number"],
+                        model=obj["model"],
+                        calls=[ModuleCall(**data) for data in obj["calls"]],
+                    )
+                )
+
+        return attached_modules
+    return value

opentrons/hardware_control/thread_manager.py

@@ -0,0 +1,431 @@
+"""Manager for the :py:class:`.hardware_control.API` thread."""
+import functools
+import threading
+import logging
+import asyncio
+import inspect
+import weakref
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    Optional,
+    TypeVar,
+    cast,
+    Sequence,
+    Mapping,
+    AsyncGenerator,
+    Union,
+    Type,
+    ParamSpec,
+)
+from .adapters import SynchronousAdapter
+from .modules.mod_abc import AbstractModule
+from .protocols import (
+    AsyncioConfigurable,
+)
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+class ThreadManagerException(Exception):
+    pass
+
+
+WrappedReturn = TypeVar("WrappedReturn", contravariant=True)
+WrappedYield = TypeVar("WrappedYield", contravariant=True)
+P = ParamSpec("P")
+
+
+async def call_coroutine_threadsafe(
+    loop: asyncio.AbstractEventLoop,
+    coro: Callable[P, Awaitable[WrappedReturn]],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> WrappedReturn:
+    fut = cast(
+        "asyncio.Future[WrappedReturn]",
+        asyncio.run_coroutine_threadsafe(coro(*args, **kwargs), loop),
+    )
+    wrapped = asyncio.wrap_future(fut)
+    return await wrapped
+
+
+async def execute_asyncgen_threadsafe(
+    loop: asyncio.AbstractEventLoop,
+    agenfunc: Callable[P, AsyncGenerator[WrappedYield, None]],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> AsyncGenerator[WrappedYield, None]:
+
+    # This function should bridge an async generator function between two asyncio
+    # loops running in different threads. There are several stages to this because
+    # there are several stages to generator execution.
+
+    # These clues will help us later
+    class _DoneSingleton:
+        pass
+
+    async def _build_queue() -> "asyncio.Queue[Union[WrappedYield, _DoneSingleton]]":
+        return asyncio.Queue(maxsize=1)
+
+    yield_queue = await asyncio.wrap_future(
+        cast(
+            "asyncio.Future[asyncio.Queue[Union[WrappedYield, _DoneSingleton]]]",
+            asyncio.run_coroutine_threadsafe(_build_queue(), loop),
+        )
+    )
+
+    # the async generator function needs to run on the target loop. it is not a coroutine
+    # and cannot be run with run_coroutine_threadsafe in the same way. however, we can
+    # make a coroutine that _can_, and that exhausts the async generator and puts what
+    # the generator yields into a queue. since something later will have to combine
+    # awaiting yield results and the function finishing, we can now use the _DoneSingleton
+    # to short circuit the caller waiting for a yield result when the function is done.
+    # in addition, the queue being 1 element max should give us similar "backpressure"
+    # behavior as an async for.
+    async def _inner_agen_wrap() -> None:
+        item: WrappedYield
+        try:
+            async for item in agenfunc(*args, **kwargs):
+                await yield_queue.put(item)
+        finally:
+            await yield_queue.put(_DoneSingleton())
+
+    # as promised, we can run our coroutine pretty easily now. note that this coroutine
+    # returns None, because it is handling the generator yields internally.
+    fut = cast(
+        "asyncio.Future[None]",
+        asyncio.run_coroutine_threadsafe(_inner_agen_wrap(), loop),
+    )
+
+    # now we have to bridge the output of the generator to the calling loop. this is
+    # fun because this uses an asyncio queue which isn't thread safe. so we also need
+    # to pull stuff out of the asyncio queue via the other loop
+    while not fut.done():
+        getter = cast(
+            "asyncio.Future[Union[WrappedYield, _DoneSingleton]]",
+            asyncio.run_coroutine_threadsafe(yield_queue.get(), loop),
+        )
+        asyncio_getter = asyncio.wrap_future(getter)
+        item = await asyncio_getter
+        if isinstance(item, _DoneSingleton):
+            break
+        yield item
+    # if there was an exception then this should re-raise it in the calling loop
+    _ = fut.result()
+
+
+WrappedObj = TypeVar("WrappedObj", bound=AsyncioConfigurable, covariant=True)
+
+
+class CallBridger(Generic[WrappedObj]):
+    def __init__(
+        self, wrapped_obj: WrappedObj, loop: asyncio.AbstractEventLoop
+    ) -> None:
+        self.wrapped_obj = wrapped_obj
+        self._loop = loop
+
+    def __getattribute__(self, attr_name: str) -> Any:
+        # Almost every attribute retrieved from us will be for people actually
+        # looking for an attribute of the managed object, so check there first.
+        managed_obj = object.__getattribute__(self, "wrapped_obj")
+        loop = object.__getattribute__(self, "_loop")
+        try:
+            attr = getattr(managed_obj, attr_name)
+        except AttributeError:
+            # Maybe this actually was for us? Let’s find it
+            return object.__getattribute__(self, attr_name)
+
+        if asyncio.iscoroutinefunction(attr):
+            # Return coroutine result of async function
+            # executed in managed thread to calling thread
+
+            @functools.wraps(attr)
+            async def wrapper(
+                *args: Sequence[Any], **kwargs: Mapping[str, Any]
+            ) -> WrappedReturn:
+                return await call_coroutine_threadsafe(loop, attr, *args, **kwargs)
+
+            return wrapper
+
+        elif asyncio.iscoroutine(attr):
+            # Return awaitable coroutine properties run in managed thread/loop
+            fut = asyncio.run_coroutine_threadsafe(attr, loop)
+            wrapped = asyncio.wrap_future(fut)
+            return wrapped
+
+        elif inspect.isasyncgenfunction(attr):
+            # Return a wrapper that will exectue the resulting async generator
+            # in managed thread loop
+
+            @functools.wraps(attr)
+            async def wrapper(
+                *args: Sequence[Any], **kwargs: Mapping[str, Any]
+            ) -> AsyncGenerator[WrappedYield, None]:
+                item: WrappedYield
+                async for item in execute_asyncgen_threadsafe(
+                    loop, attr, *args, **kwargs
+                ):
+                    yield item
+
+            return wrapper
+
+        return attr
+
+
+# TODO: BC 2020-02-25 instead of overwriting __get_attribute__ in this class
+# use inspect.getmembers to iterate over appropriate members of adapted
+# instance and setattr on the outer instance with the proper threadsafe
+# resolution logic injected. This approach avoids requiring calls to
+# object.__get_attribute__(self,...) to opt out of the overwritten
+# functionality. It is more readable and protected from
+# unintentional recursion.
+class ThreadManager(Generic[WrappedObj]):
+    """A wrapper to make every call into :py:class:`.hardware_control.API`
+    execute within the same thread.
+
+    This class spawns a worker thread and starts an event loop within.
+    It then calls the async builder parameter within that worker thread's
+    event loop passing thru all args and kwargs and injecting the worker
+    thread's loop as a kwarg to the builder. The resulting built object
+    is stored as a member of the class, and a synchronous interface to
+    the managed object's members is also exposed for convenience.
+
+    If you want to wait for the managed object's creation separately
+    (with managed_thread_ready_blocking or managed_thread_ready_async)
+     use the nonblocking_builder static method to add an attribute to the builder
+    function, i.e.
+
+    thread_manager = ThreadManager(ThreadManager.nonblocking_builder(builder), ...)
+
+    Example
+    -------
+    .. code-block::
+    >>> from opentrons.hardware_control import API, ThreadManager
+    >>> api_single_thread = ThreadManager(API.build_hardware_simulator)
+    >>> await api_single_thread.home() # call as awaitable async
+    >>> api_single_thread.sync.home() # call as blocking sync
+    """
+
+    Builder = ParamSpec("Builder")
+    Built = TypeVar("Built")
+
+    @staticmethod
+    def nonblocking_builder(
+        builder: Callable[Builder, Awaitable[Built]]
+    ) -> Callable[Builder, Awaitable[Built]]:
+        """Wrap an instance of a builder function to make initializes that use it nonblocking.
+
+        For instance, you can build a ThreadManager like this:
+
+        thread_manager = ThreadManager(ThreadManager.nonblocking_builder(API.build_hardware_controller), ...)
+
+        to make the initialize call return immediately so you can later wait on it via
+        managed_thread_ready_blocking or managed_thread_ready_async
+        """
+
+        @functools.wraps(builder)
+        async def wrapper(
+            *args: ThreadManager.Builder.args, **kwargs: ThreadManager.Builder.kwargs
+        ) -> ThreadManager.Built:
+            return await builder(*args, **kwargs)
+
+        setattr(wrapper, "nonblocking", True)
+        return wrapper
+
+    def __init__(
+        self,
+        builder: Callable[Builder, Awaitable[WrappedObj]],
+        *args: Builder.args,
+        **kwargs: Builder.kwargs,
+    ) -> None:
+        """Build the ThreadManager.
+
+        builder: The api function to use to build the instance.
+
+        The args and kwargs will be forwarded to the builder function.
+
+        Note: by default, this function will block until the managed thread is ready and the hardware controller
+        has been built. To make this function return immediately you can wrap its builder argument in
+        ThreadManager.nonblocking_builder(), like this:
+
+        thread_manager = ThreadManager(ThreadManager.nonblocking_builder(API.build_hardware_controller), ...)
+
+        Afterwards, you'll need to call ThreadManager.managed_thread_ready_blocking or its async variant before
+        you can actually use thei nstance.
+        """
+
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self.managed_obj: Optional[WrappedObj] = None
+        self.bridged_obj: Optional[CallBridger[WrappedObj]] = None
+        self._sync_managed_obj: Optional[SynchronousAdapter[WrappedObj]] = None
+        is_running = threading.Event()
+        self._is_running = is_running
+        self._cached_modules: weakref.WeakKeyDictionary[
+            AbstractModule, CallBridger[AbstractModule]
+        ] = weakref.WeakKeyDictionary()
+        # TODO: remove this if we switch to python 3.8
+        # https://docs.python.org/3/library/asyncio-subprocess.html#subprocess-and-threads
+        # On windows, the event loop and system interface is different and
+        # this won't work.
+        try:
+            asyncio.get_child_watcher()
+        except NotImplementedError:
+            pass
+        blocking = not getattr(builder, "nonblocking", False)
+        target = object.__getattribute__(self, "_build_and_start_loop")
+        thread = threading.Thread(
+            target=target,
+            name="ManagedThread",
+            args=(builder, *args),
+            kwargs=kwargs,
+            daemon=True,
+        )
+        self._thread = thread
+        thread.start()
+        if blocking:
+            object.__getattribute__(self, "managed_thread_ready_blocking")()
+
+    def managed_thread_ready_blocking(self) -> None:
+        object.__getattribute__(self, "_is_running").wait()
+        if not object.__getattribute__(self, "managed_obj"):
+            raise ThreadManagerException("Failed to create Managed Object")
+
+    async def managed_thread_ready_async(self) -> None:
+        is_running = object.__getattribute__(self, "_is_running")
+        while not is_running.is_set():
+            await asyncio.sleep(0.1)
+        # Thread initialization is done.
+        if not object.__getattribute__(self, "managed_obj"):
+            raise ThreadManagerException("Failed to create Managed Object")
+
+    def _build_and_start_loop(
+        self,
+        builder: Callable[..., Awaitable[WrappedObj]],
+        *args: Sequence[Any],
+        **kwargs: Mapping[str, Any],
+    ) -> None:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        self._loop = loop
+        try:
+            managed_obj = loop.run_until_complete(builder(*args, loop=loop, **kwargs))
+            self.managed_obj = managed_obj
+            self.bridged_obj = CallBridger(managed_obj, loop)
+            self._sync_managed_obj = SynchronousAdapter(managed_obj)
+        except Exception:
+            MODULE_LOG.exception("Exception in Thread Manager build")
+        finally:
+            object.__getattribute__(self, "_is_running").set()
+            loop.run_forever()
+            loop.close()
+
+    @property
+    def sync(self) -> SynchronousAdapter[WrappedObj]:
+        # Why the ignore?
+        # While self._sync_managed_obj is initialized None, a failure to build
+        # the managed_obj and _sync_managed_obj is a catastrophic failure.
+        # All callers of this property assume it to be valid.
+        return self._sync_managed_obj  # type: ignore
+
+    def __repr__(self) -> str:
+        return "<ThreadManager>"
+
+    def clean_up_tm(self) -> None:
+        try:
+            loop = object.__getattribute__(self, "_loop")
+            loop.call_soon_threadsafe(loop.stop)
+        except Exception:
+            pass
+        object.__setattr__(self, "_cached_modules", weakref.WeakKeyDictionary({}))
+        object.__getattribute__(self, "_thread").join()
+
+    def wrap_module(self, module: AbstractModule) -> CallBridger[AbstractModule]:
+        """Return the module object wrapped in a CallBridger and cache it.
+
+        The wrapped module objects are cached in `self._cached_modules` so they can be
+        re-used throughout the module object's life, as creating a wrapper is expensive.
+        We use a WeakKeyDictionary for caching so that module objects can be
+        garbage collected when modules are detached (since entries in WeakKeyDictionary
+        get discarded when there is no longer a strong reference to the key).
+        """
+        wrapper_cache = object.__getattribute__(self, "_cached_modules")
+        this_module_wrapper = wrapper_cache.get(module)
+
+        if this_module_wrapper is None:
+            this_module_wrapper = CallBridger(
+                module, object.__getattribute__(self, "_loop")
+            )
+            wrapper_cache.update({module: this_module_wrapper})
+
+        return this_module_wrapper  # type: ignore
+
+    def __getattribute__(self, attr_name: str) -> Any:
+        # hardware_control.api.API.attached_modules is the only hardware
+        # API method that returns something other than data. The module
+        # objects it returns have associated methods that can be called.
+        # That means they need the same wrapping treatment as the API
+        # itself.
+        if attr_name == "attached_modules":
+            wrap = object.__getattribute__(self, "wrap_module")
+            managed = object.__getattribute__(self, "managed_obj")
+            attr = getattr(managed, attr_name)
+            return [wrap(mod) for mod in attr]
+        elif attr_name == "clean_up":
+            # the wrapped object probably has this attr as well as us, and we
+            # want to call both, with the wrapped one first
+
+            # we only want to call cleanup once, and then only if the loop
+            # is running
+            wrapped_loop = object.__getattribute__(self, "_loop")
+            if not wrapped_loop.is_running():
+                return lambda: None
+
+            wrapped_cleanup = getattr(
+                object.__getattribute__(self, "bridged_obj"), "clean_up"
+            )
+            our_cleanup = object.__getattribute__(self, "clean_up_tm")
+
+            def call_both() -> None:
+                # the wrapped cleanup wants to happen in the managed thread,
+                # started from the managed loop. our cleanup wants to happen
+                # in the current thread, _after_ the wrapped cleanup is done
+                # so cancelled tasks can have a chance to complete.
+                async def clean_and_notify() -> None:
+                    await wrapped_cleanup()
+                    # this sleep allows the wrapped loop to spin to clean up the
+                    # tasks we just cancelled.
+                    await asyncio.sleep(0)
+
+                fut = asyncio.run_coroutine_threadsafe(clean_and_notify(), wrapped_loop)
+                fut.result()
+                our_cleanup()
+
+            return call_both
+
+        else:
+            try:
+                return getattr(object.__getattribute__(self, "bridged_obj"), attr_name)
+            except AttributeError:
+                return object.__getattribute__(self, attr_name)
+
+    def wrapped(self) -> WrappedObj:
+        """Expose the type of the underlying wrapped object.
+
+        This isn't a method that does anything (it just returns self again) but the cast
+        means that the type of self will be what the threadmanager's generic wrapped
+        object is. You can therefore use this to get typechecking when using
+        ThreadManagers.
+
+        While the generic type is what you say it is when you annotate the instance
+        variable containing a ThreadManager, if you restrict yourself to annotating
+         those instances using a protocol from hardware_api.protocols, things will more
+        or less work out through the rest of the system. Not perfect, but ok.
+        """
+        return cast(WrappedObj, self)
+
+    def wraps_instance(self, of_type: Type[Any]) -> bool:
+        """Do isinstance() on the wrapped object."""
+        return isinstance(object.__getattribute__(self, "managed_obj"), of_type)