openmhp 0.3.0__py3-none-any.whl

openmhp/__init__.py

@@ -0,0 +1,9 @@
+"""OpenMHP - reference implementation of the Open Model Hardware Protocol (MHP).
+
+MHP is to physical devices what MCP is to software tools: a small JSON-RPC
+protocol through which an AI agent discovers a device, learns how to use it
+safely, reads from it, writes to it, and runs long-running actions on it.
+"""
+
+PROTOCOL_VERSION = "2026-09-09"
+__version__ = "0.3.0"

openmhp/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Adapters: put hardware already controlled by another layer behind MHP.
+
+    from openmhp.adapters import BoundDriver, Signal, Setting, Action   # any Python callable
+    from openmhp.adapters.sila2 import sila_device                      # SiLA 2 servers
+    from openmhp.adapters.pylabrobot import plr_device                  # PyLabRobot machines
+    from openmhp.adapters.madsci import madsci_node                     # MADSci nodes
+    from openmhp.adapters.opcua import opcua_device                     # OPC UA servers / PLCs
+    from openmhp.adapters.ros2 import ros2_device                       # ROS 2 nodes
+
+Each returns a Driver; serve it with `mhp serve`, register it in a Directory,
+or expose it through `mhp-mcp` like any native MHP device.
+"""
+from .base import Action, BoundDriver, Setting, Signal, params_from_signature
+
+__all__ = ["Action", "BoundDriver", "Setting", "Signal", "params_from_signature"]

openmhp/adapters/base.py

@@ -0,0 +1,140 @@
+"""Bindings: the few-lines way to put any controllable thing behind MHP.
+
+An adapter author describes a device as three small lists of *bindings*, each
+pairing an MHP name with a callable into the underlying control layer. The
+BoundDriver turns them into a full MHP driver with every safety gate, the
+detail tiers, jobs and notifications inherited from Driver.
+
+    dev = BoundDriver(
+        device={"id": "hotplate-01", "class": "hotplate", "notes": "Fume hood 2."},
+        signals=[Signal("plate_temperature", read=lambda: plc.read(0x10), unit="degC")],
+        settings=[Setting("target_temperature", write=lambda v: plc.write(0x20, v),
+                          unit="degC", limits={"min": 20, "max": 300})],
+        actions=[Action("shutdown", run=lambda job, p: plc.write(0x21, 0), approval="confirm")],
+        estop=lambda: plc.write(0x21, 0),
+    )
+
+Ecosystem adapters (sila2, pylabrobot, madsci, opcua, ros2) are just functions
+that build these bindings by introspecting their layer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from ..driver import Driver, Job
+
+
+@dataclass
+class Signal:
+    name: str
+    read: Callable[[], Any]
+    type: str = "number"
+    unit: str | None = None
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "type": self.type, "unit": self.unit, "notes": self.notes})
+
+
+@dataclass
+class Setting:
+    name: str
+    write: Callable[[Any], None]
+    read: Callable[[], Any] | None = None
+    type: str = "number"
+    unit: str | None = None
+    limits: dict | None = None
+    approval: str = "auto"
+    interlocks: list[str] = field(default_factory=list)
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "type": self.type, "unit": self.unit, "limits": self.limits,
+                       "approval": self.approval, "interlocks": self.interlocks or None, "notes": self.notes})
+
+
+@dataclass
+class Action:
+    name: str
+    run: Callable[[Job, dict], Any]          # run(job, params) -> result; may call driver.progress(job, x)
+    duration: str = "short"
+    approval: str = "auto"
+    interlocks: list[str] = field(default_factory=list)
+    params: dict | None = None
+    limits: dict | None = None
+    examples: list[dict] | None = None
+    concurrent: bool = False
+    notes: str | None = None
+
+    def spec(self) -> dict:
+        return _clean({"name": self.name, "duration": self.duration, "approval": self.approval,
+                       "interlocks": self.interlocks or None, "params": self.params, "limits": self.limits,
+                       "examples": self.examples, "concurrent": self.concurrent or None, "notes": self.notes})
+
+
+def _clean(d: dict) -> dict:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class BoundDriver(Driver):
+    """A Driver assembled from bindings. Works with every transport and the directory."""
+
+    def __init__(self, device: dict, signals: list[Signal] = (), settings: list[Setting] = (),
+                 actions: list[Action] = (), *, physical: dict | None = None, safety: dict | None = None,
+                 estop: Callable[[], None] | None = None, setup: Callable[[], None] | None = None,
+                 extra: dict | None = None):
+        self._signals = {s.name: s for s in signals}
+        self._settings = {s.name: s for s in settings}
+        self._actions = {a.name: a for a in actions}
+        self._estop_fn, self._setup_fn = estop, setup
+        interlocks = sorted({i for b in [*settings, *actions] for i in b.interlocks})
+        self.descriptor = {
+            "device": device,
+            "physical": physical or {},
+            "signals": [s.spec() for s in signals],
+            "settings": [s.spec() for s in settings],
+            "actions": [a.spec() for a in actions],
+            "safety": {"estop": estop is not None, "interlocks": interlocks, **(safety or {})},
+            **(extra or {}),
+        }
+        super().__init__()
+
+    def setup(self):
+        if self._setup_fn:
+            self._setup_fn()
+
+    def on_read(self, name):
+        if name in self._signals:
+            return self._signals[name].read()
+        s = self._settings.get(name)
+        if s and s.read:
+            return s.read()
+        raise KeyError(name)
+
+    def on_write(self, name, value):
+        self._settings[name].write(value)
+
+    def on_invoke(self, job: Job):
+        return self._actions[job.action].run(job, job.params)
+
+    def on_estop(self):
+        if self._estop_fn:
+            self._estop_fn()
+
+
+def params_from_signature(fn: Callable, skip: tuple[str, ...] = ("self",)) -> dict:
+    """Best-effort MHP `params` doc from a Python signature."""
+    import inspect
+    out = {}
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return out
+    for n, p in sig.parameters.items():
+        if n in skip or p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+            continue
+        ann = "" if p.annotation is inspect._empty else getattr(p.annotation, "__name__", str(p.annotation))
+        dflt = "" if p.default is inspect._empty else f" (default {p.default!r})"
+        out[n] = (ann + dflt).strip() or "any"
+    return out

openmhp/adapters/madsci.py

@@ -0,0 +1,111 @@
+"""MADSci node -> MHP.
+
+    from openmhp.adapters.madsci import madsci_node
+    dev = madsci_node("http://192.168.1.40:2000",
+                      device={"id": "pf400-01", "class": "robot_arm", "location": "bay 2",
+                              "notes": "MADSci-managed PF400."})
+
+MADSci nodes already speak REST with an action vocabulary, so the adapter
+reads the node's own description and needs no hand-written bindings:
+
+    GET  {url}/info          node info incl. actions and their args   -> MHP actions
+    GET  {url}/state         node state dict                          -> MHP signals (one per key)
+    GET  {url}/status        node status (busy, errored, ...)         -> MHP state
+    POST {url}/action        {"action_name", "args"}                  <- actions/invoke
+    GET  {url}/action/{id}   action result / status                    -> jobs/progress
+    POST {url}/admin/{cmd}   safety_stop, reset                        <- safety/estop, safety/reset
+
+Path names are class attributes so a lab can adjust them if its MADSci
+version differs. `http` may be injected (any object with get/post returning
+JSON-able dicts) for tests.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+
+from .base import Action, BoundDriver, Signal
+
+
+class _Http:
+    def __init__(self, base: str, timeout: float = 30):
+        self.base, self.timeout = base.rstrip("/"), timeout
+
+    def _req(self, method, path, body=None):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base + path, data=data, method=method,
+                                     headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=self.timeout) as r:
+            raw = r.read()
+            return json.loads(raw) if raw else {}
+
+    def get(self, path):        return self._req("GET", path)
+    def post(self, path, body=None): return self._req("POST", path, body or {})
+
+
+class MadsciPaths:
+    info, state, status, action, action_result, admin = "/info", "/state", "/status", "/action", "/action/{id}", "/admin/{cmd}"
+
+
+def madsci_node(url: str, *, device: dict, http=None, paths: type = MadsciPaths, poll_s: float = 0.5,
+                approval: dict | None = None, physical: dict | None = None) -> BoundDriver:
+    http = http or _Http(url)
+    info = http.get(paths.info)
+    approval = approval or {}
+    node_actions = info.get("actions") or {}
+    if isinstance(node_actions, list):                     # some versions return a list of {name, args, description}
+        node_actions = {a["name"]: a for a in node_actions}
+
+    state_keys = list((http.get(paths.state) or {}).keys())
+
+    def sig(key):
+        return Signal(key, read=lambda: (http.get(paths.state) or {}).get(key), type="string")
+
+    def action(name, meta):
+        def run(job, params):
+            res = http.post(paths.action, {"action_name": name, "args": params})
+            aid = res.get("action_id") or res.get("id")
+            status = res.get("status")
+            while aid and status not in ("succeeded", "failed", "cancelled", None):
+                time.sleep(poll_s)
+                res = http.get(paths.action_result.format(id=aid))
+                status = res.get("status")
+                if job.cancel_requested:
+                    break
+            if status == "failed":
+                raise RuntimeError(res.get("errors") or res.get("error") or "MADSci action failed")
+            return res
+        args = meta.get("args") or {}
+        params = {k: (v.get("description") or v.get("type") or "any") if isinstance(v, dict) else str(v) for k, v in args.items()} or None
+        return Action(name, run=run, duration="long", params=params, approval=approval.get(name, "auto"),
+                      notes=meta.get("description"))
+
+    dev = dict(device)
+    dev.setdefault("make", "MADSci")
+    dev.setdefault("model", info.get("node_type") or info.get("module_name") or "node")
+
+    driver = BoundDriver(
+        device=dev, physical=physical,
+        signals=[sig(k) for k in state_keys],
+        actions=[action(n, m if isinstance(m, dict) else {}) for n, m in node_actions.items()],
+        estop=lambda: http.post(paths.admin.format(cmd="safety_stop")),
+        extra={"madsci": {"url": url, "node_id": info.get("node_id")}},
+    )
+
+    # MADSci also knows whether it is busy: fold that into the MHP state on ping.
+    _ping = driver.rpc_ping
+
+    def rpc_ping(p, client):
+        out = _ping(p, client)
+        try:
+            st = http.get(paths.status) or {}
+            if st.get("errored"):
+                out["madsci"] = "errored"
+            elif st.get("busy") and out["state"] == "idle":
+                out["state"] = "busy"
+        except Exception:                                    # noqa: BLE001
+            pass
+        return out
+    driver.rpc_ping = rpc_ping
+    return driver

openmhp/adapters/opcua.py

@@ -0,0 +1,72 @@
+"""OPC UA -> MHP.  (Also the pattern for Modbus and other register-style layers.)
+
+    from openmhp.adapters.opcua import opcua_device
+    dev = opcua_device("opc.tcp://furnace-plc:4840",
+        device={"id": "furnace-02", "class": "oven", "location": "line 4",
+                "notes": "Sintering furnace. Door interlock is hardwired; MHP mirrors it."},
+        signals={"zone1_temperature": ("ns=2;s=Furnace.Zone1.PV", "degC"),
+                 "door_closed": ("ns=2;s=Furnace.DoorClosed", "boolean")},
+        settings={"zone1_setpoint": ("ns=2;s=Furnace.Zone1.SP", {"min": 20, "max": 1400}, "degC")},
+        actions={"start_program": ("ns=2;s=Furnace", "ns=2;s=Furnace.Start",
+                                   {"interlocks": ["door_closed"], "approval": "confirm"})},
+        estop=("ns=2;s=Furnace", "ns=2;s=Furnace.Abort"))
+
+Mapping
+  Variable node (read)      -> signal   (nodeid, unit?)
+  Variable node (write)     -> setting  (nodeid, limits?, unit?)
+  Method node               -> action   (object nodeid, method nodeid, opts?); params are passed
+                                        positionally in the order of the `params` doc you give
+  Alarms & conditions       -> not mapped in 0.2; poll a signal instead
+
+Uses python-opcua (`opcua.Client`) or asyncua's sync wrapper
+(`asyncua.sync.Client`); pass `client=` to inject either, or a fake for tests
+(needs get_node(id) -> node with get_value/set_value, and call_method).
+"""
+from __future__ import annotations
+
+from .base import Action, BoundDriver, Setting, Signal
+
+
+def _connect(url: str):
+    try:
+        from asyncua.sync import Client
+    except ImportError:
+        from opcua import Client
+    c = Client(url)
+    c.connect()
+    return c
+
+
+def opcua_device(url: str = "", *, device: dict, signals: dict | None = None, settings: dict | None = None,
+                 actions: dict | None = None, estop: tuple | None = None, physical: dict | None = None,
+                 client=None) -> BoundDriver:
+    client = client or _connect(url)
+    node = client.get_node
+
+    def sig(name, spec):
+        nid, unit = (spec, None) if isinstance(spec, str) else (spec[0], spec[1] if len(spec) > 1 else None)
+        typ = "boolean" if unit == "boolean" else "number"
+        return Signal(name, read=lambda: node(nid).get_value(), unit=None if typ == "boolean" else unit, type=typ)
+
+    def setting(name, spec):
+        nid, limits, unit = (spec, None, None) if isinstance(spec, str) else (spec + (None, None))[:3]
+        return Setting(name, write=lambda v: node(nid).set_value(v), read=lambda: node(nid).get_value(),
+                       limits=limits, unit=unit)
+
+    def action(name, spec):
+        obj, meth, opts = (spec + ({},))[:3]
+        order = list((opts.get("params") or {}).keys())
+
+        def run(job, params):
+            args = [params[k] for k in order] if order else list(params.values())
+            return node(obj).call_method(meth, *args)
+        return Action(name, run=run, **opts)
+
+    return BoundDriver(
+        device=device, physical=physical,
+        signals=[sig(n, s) for n, s in (signals or {}).items()],
+        settings=[setting(n, s) for n, s in (settings or {}).items()],
+        actions=[action(n, s) for n, s in (actions or {}).items()],
+        estop=(lambda: node(estop[0]).call_method(estop[1])) if estop else None,
+        extra={"opcua": {"url": url}},
+    )

openmhp/adapters/pylabrobot.py

@@ -0,0 +1,77 @@
+"""PyLabRobot -> MHP.
+
+    from pylabrobot.liquid_handling import LiquidHandler
+    from pylabrobot.liquid_handling.backends import STAR
+    from pylabrobot.resources import STARLetDeck
+    from openmhp.adapters.pylabrobot import plr_device
+
+    lh = LiquidHandler(backend=STAR(), deck=STARLetDeck())
+    dev = plr_device(lh, device={"id": "star-01", "class": "liquid_handler", "location": "bay 1",
+                                 "notes": "Hamilton STARlet. Keep the deck clear of loose tips."},
+                     actions=["pick_up_tips", "drop_tips", "aspirate", "dispense", "move_plate"],
+                     limits={"aspirate": {"vols": [0, 1000]}})
+
+Every public coroutine on the machine becomes an MHP action (or only the ones
+you name), with `params` documented from its Python signature. setup()/stop()
+are wired to the driver's lifecycle and e-stop. Coroutines run on a private
+event loop thread so the synchronous MHP driver can call them.
+
+Works with any pylabrobot Machine (LiquidHandler, PlateReader, Centrifuge,
+Incubator, ...). `machine` may be a fake with async methods for testing.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+
+from .base import Action, BoundDriver, Signal, params_from_signature
+
+_SKIP = {"setup", "stop", "serialize", "deserialize", "save", "load", "assign_child_resource",
+         "unassign_child_resource", "get_resource"}
+
+
+class _Loop:
+    def __init__(self):
+        self.loop = asyncio.new_event_loop()
+        threading.Thread(target=self.loop.run_forever, daemon=True).start()
+
+    def run(self, coro, timeout=None):
+        return asyncio.run_coroutine_threadsafe(coro, self.loop).result(timeout)
+
+
+def plr_device(machine, *, device: dict, actions: list[str] | None = None, signals: dict | None = None,
+               limits: dict | None = None, approval: dict | None = None, physical: dict | None = None,
+               setup: bool = True, action_timeout_s: float = 3600) -> BoundDriver:
+    loop = _Loop()
+    limits, approval = limits or {}, approval or {}
+
+    names = actions or [n for n, m in inspect.getmembers(machine, inspect.iscoroutinefunction)
+                        if not n.startswith("_") and n not in _SKIP]
+
+    def make_action(name):
+        fn = getattr(machine, name)
+
+        def run(job, params):
+            res = loop.run(fn(**params), timeout=action_timeout_s)
+            return res if isinstance(res, (dict, list, str, int, float, bool, type(None))) else str(res)
+        return Action(name, run=run, duration="long", params=params_from_signature(fn) or None,
+                      limits=limits.get(name), approval=approval.get(name, "auto"),
+                      notes=(inspect.getdoc(fn) or "").split("\n")[0] or None)
+
+    sigs = [Signal("setup_finished", read=lambda: bool(getattr(machine, "setup_finished", False)), type="boolean")]
+    for n, fn in (signals or {}).items():
+        sigs.append(Signal(n, read=fn))
+
+    def do_setup():
+        if setup and hasattr(machine, "setup"):
+            loop.run(machine.setup())
+
+    def do_stop():
+        if hasattr(machine, "stop"):
+            loop.run(machine.stop(), timeout=30)
+
+    return BoundDriver(device=device, physical=physical, signals=sigs,
+                       actions=[make_action(n) for n in names], estop=do_stop, setup=do_setup,
+                       extra={"pylabrobot": {"machine": type(machine).__name__,
+                                             "backend": type(getattr(machine, "backend", None)).__name__}})

openmhp/adapters/ros2.py

@@ -0,0 +1,116 @@
+"""ROS 2 -> MHP.
+
+    from openmhp.adapters.ros2 import ros2_device
+    dev = ros2_device("mhp_ur5e",
+        device={"id": "ur5e-01", "class": "robot_arm", "location": "cell 7",
+                "notes": "UR5e on the assembly cell. 5 kg payload."},
+        signals={"joint_positions": ("/joint_states", "sensor_msgs/msg/JointState", "position"),
+                 "estop_clear": ("/safety/estop_clear", "std_msgs/msg/Bool", "data")},
+        settings={"speed_scale": ("/speed_scaling", "std_msgs/msg/Float64", "data", {"min": 0.05, "max": 1.0})},
+        actions={"move_to_joints": ("/follow_joint_trajectory",
+                                    "control_msgs/action/FollowJointTrajectory",
+                                    {"interlocks": ["estop_clear"], "duration": "long"})},
+        estop=("/ur_hardware_interface/dashboard/stop", "std_srvs/srv/Trigger"))
+
+Mapping
+  topic (subscribe)   -> signal   (topic, msg_type, field path)   last message cached
+  topic (publish)     -> setting  (topic, msg_type, field, limits?)
+  action server       -> action   (name, action_type, opts); goal built from params,
+                                  feedback -> jobs/progress if it has a `progress` field,
+                                  cancel_requested -> cancel_goal
+  service (Trigger)   -> estop    (name, srv_type)
+
+Needs rclpy and the message packages on the PYTHONPATH (source your ROS 2
+workspace first). The node spins on a background thread.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+from .base import Action, BoundDriver, Setting, Signal
+
+
+def _field(msg, path: str):
+    for part in path.split("."):
+        msg = getattr(msg, part)
+    return list(msg) if hasattr(msg, "__iter__") and not isinstance(msg, (str, bytes)) else msg
+
+
+def ros2_device(node_name: str, *, device: dict, signals: dict | None = None, settings: dict | None = None,
+                actions: dict | None = None, estop: tuple | None = None, physical: dict | None = None,
+                spin: bool = True) -> BoundDriver:
+    import rclpy
+    from rclpy.action import ActionClient
+    from rosidl_runtime_py.utilities import get_message, get_action, get_service
+    from rosidl_runtime_py.set_message import set_message_fields
+
+    if not rclpy.ok():
+        rclpy.init()
+    node = rclpy.create_node(node_name)
+    if spin:
+        threading.Thread(target=rclpy.spin, args=(node,), daemon=True).start()
+
+    cache: dict[str, object] = {}
+
+    def sig(name, spec):
+        topic, mtype, path = spec
+        node.create_subscription(get_message(mtype), topic, lambda m, t=topic: cache.__setitem__(t, m), 10)
+        return Signal(name, read=lambda: _field(cache[topic], path) if topic in cache else None,
+                      notes=f"{topic} ({mtype}).{path}")
+
+    def setting(name, spec):
+        topic, mtype, field, *rest = spec
+        pub = node.create_publisher(get_message(mtype), topic, 10)
+
+        def write(v):
+            msg = get_message(mtype)()
+            set_message_fields(msg, {field: v})
+            pub.publish(msg)
+        return Setting(name, write=write, limits=rest[0] if rest else None, notes=f"publishes {topic}.{field}")
+
+    def action(name, spec):
+        aname, atype, opts = (spec + ({},))[:3]
+        A = get_action(atype)
+        ac = ActionClient(node, A, aname)
+
+        def run(job, params):
+            ac.wait_for_server(timeout_sec=5.0)
+            goal = A.Goal()
+            set_message_fields(goal, params)
+            done = {}
+
+            def on_feedback(fb):
+                prog = getattr(fb.feedback, "progress", None)
+                if prog is not None:
+                    driver.progress(job, float(prog))
+            fut = ac.send_goal_async(goal, feedback_callback=on_feedback)
+            while not fut.done():
+                time.sleep(0.05)
+            handle = fut.result()
+            if not handle.accepted:
+                raise RuntimeError("goal rejected")
+            rfut = handle.get_result_async()
+            while not rfut.done():
+                if job.cancel_requested:
+                    handle.cancel_goal_async()
+                time.sleep(0.1)
+            res = rfut.result().result
+            return {f: _field(res, f) for f in res.get_fields_and_field_types()}
+        return Action(name, run=run, **{"duration": "long", **opts})
+
+    def make_estop():
+        sname, stype = estop
+        S = get_service(stype)
+        cli = node.create_client(S, sname)
+        return lambda: cli.call_async(S.Request())
+
+    driver = BoundDriver(
+        device=device, physical=physical,
+        signals=[sig(n, s) for n, s in (signals or {}).items()],
+        settings=[setting(n, s) for n, s in (settings or {}).items()],
+        actions=[action(n, s) for n, s in (actions or {}).items()],
+        estop=make_estop() if estop else None,
+        extra={"ros2": {"node": node_name}},
+    )
+    return driver

openmhp/adapters/sila2.py

@@ -0,0 +1,93 @@
+"""SiLA 2 -> MHP.
+
+    from openmhp.adapters.sila2 import sila_device
+    dev = sila_device("10.0.0.12", 50052,
+        device={"id": "arm-01", "class": "robot_arm", "location": "bay 3",
+                "notes": "PF400 plate mover. Light curtain trips SafeZoneClear."},
+        signals={"position": "RobotController.Position",
+                 "safe_zone_clear": ("SafetyController.SafeZoneClear", "boolean")},
+        settings={"speed": ("RobotController.SetSpeed.Speed", {"min": 1, "max": 100})},
+        actions={"move_to": "RobotController.MoveTo",
+                 "home": ("RobotController.Home", {"interlocks": ["safe_zone_clear"]})},
+        estop="RobotController.EmergencyStop")
+
+Mapping
+  SiLA property (observable or not)            -> signal   "Feature.Property"
+  SiLA unobservable command with one parameter -> setting  "Feature.Command.Parameter"
+  SiLA command (observable or not)             -> action   "Feature.Command"; observable ones
+                                                  report progress and honour cancel via the
+                                                  command instance
+  SiLA LockController                           -> MHP leases are enforced by the driver itself
+
+Uses the `sila2` Python package's client (pip install sila2). `client` may be
+injected for tests or for servers needing custom TLS setup.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .base import Action, BoundDriver, Setting, Signal
+
+
+def _connect(host: str, port: int, insecure: bool):
+    from sila2.client import SilaClient           # lazy: only needed for real hardware
+    return SilaClient(host, port, insecure=insecure)
+
+
+def _resolve(client, dotted: str):
+    obj = client
+    for part in dotted.split("."):
+        obj = getattr(obj, part)
+    return obj
+
+
+def sila_device(host: str = "", port: int = 50052, *, device: dict, signals: dict | None = None,
+                settings: dict | None = None, actions: dict | None = None, estop: str | None = None,
+                physical: dict | None = None, insecure: bool = True, client=None, poll_s: float = 0.25) -> BoundDriver:
+    client = client or _connect(host, port, insecure)
+
+    def sig(name, spec):
+        path, typ = (spec, "number") if isinstance(spec, str) else spec
+        return Signal(name, read=lambda: _resolve(client, path).get(), type=typ)
+
+    def setting(name, spec):
+        path, opts = (spec, {}) if isinstance(spec, str) else (spec[0], spec[1] if isinstance(spec[1], dict) and "min" not in spec[1] and "max" not in spec[1] else {"limits": spec[1]})
+        feat_cmd, param = path.rsplit(".", 1)
+        return Setting(name, write=lambda v: _resolve(client, feat_cmd)(**{param: v}), **opts)
+
+    def action(name, spec):
+        path, opts = (spec, {}) if isinstance(spec, str) else spec
+
+        def run(job, params):
+            result = _resolve(client, path)(**params)
+            if hasattr(result, "done"):                       # observable command instance
+                while not result.done:
+                    if job.cancel_requested and hasattr(result, "cancel"):
+                        result.cancel()
+                    prog = getattr(result, "progress", None)
+                    if prog is not None:
+                        driver.progress(job, float(prog))
+                    time.sleep(poll_s)
+                result = result.get_responses()
+            return _plain(result)
+        return Action(name, run=run, duration="long" if opts.pop("observable", False) else opts.pop("duration", "short"), **opts)
+
+    driver = BoundDriver(
+        device=device, physical=physical,
+        signals=[sig(n, s) for n, s in (signals or {}).items()],
+        settings=[setting(n, s) for n, s in (settings or {}).items()],
+        actions=[action(n, s) for n, s in (actions or {}).items()],
+        estop=(lambda: _resolve(client, estop)()) if estop else None,
+        extra={"sila2": {"host": host, "port": port}},
+    )
+    return driver
+
+
+def _plain(obj: Any) -> Any:
+    """SiLA response objects -> JSON-able."""
+    if hasattr(obj, "_asdict"):
+        return obj._asdict()
+    if hasattr(obj, "__dict__") and not isinstance(obj, (str, int, float, bool)):
+        return {k: v for k, v in vars(obj).items() if not k.startswith("_")}
+    return obj