koebelt-dash-scripts 1.3.0b1__py3-none-any.whl

koebelt_dash_scripts/__init__.py

@@ -0,0 +1,17 @@
+"""koebelt-dash-scripts: control devices connected in koebelt/dash from Python.
+
+    from koebelt_dash_scripts import connect, every
+    dev = connect()
+    for _ in every(0.05):
+        dev.sticks(throttle=0.3)
+"""
+
+__version__ = "1.3.0b1"
+
+from .camera import Camera, CameraError, decode_jpeg  # noqa: E402
+from .client import Device, Released, ScriptError, Setting, Telemetry, connect, every, wait  # noqa: E402
+from .tools import angle_diff, bearing, clamp, distance, geo_bearing, geo_distance, lowpass, pid, rate_limit  # noqa: E402
+
+__all__ = ["connect", "every", "wait", "Device", "Telemetry", "Setting", "ScriptError", "Released", "Camera", "CameraError", "decode_jpeg",
+           "pid", "lowpass", "rate_limit", "clamp", "distance", "bearing", "angle_diff", "geo_distance", "geo_bearing",
+           "__version__"]

koebelt_dash_scripts/__main__.py

@@ -0,0 +1,4 @@
+"""python -m koebelt_dash_scripts host"""
+from .host import cli
+
+cli()

koebelt_dash_scripts/camera.py

@@ -0,0 +1,214 @@
+"""A device's camera, as numpy images for OpenCV, PyTorch, YOLO…
+
+The stream is read straight from the device (MJPEG, or a still JPEG polled),
+on a background thread that keeps only the newest picture: a slow model
+always gets the latest frame, never a backlog.
+"""
+from __future__ import annotations
+
+import io
+import threading
+import time
+import urllib.request
+from typing import Any, Dict, Iterator, Optional
+
+
+class CameraError(RuntimeError):
+    pass
+
+
+def decode_jpeg(data: bytes):
+    """Image bytes (JPEG, PNG) → H×W×3 numpy array, BGR (OpenCV's order), with OpenCV or Pillow."""
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        cv2 = None
+    if cv2 is not None:
+        img = cv2.imdecode(np.frombuffer(data, np.uint8), cv2.IMREAD_COLOR)
+        if img is None:
+            raise CameraError("could not decode a camera frame")
+        return img
+    try:
+        import numpy as np
+        from PIL import Image
+    except ImportError:
+        raise CameraError("camera frames need numpy and OpenCV (pip install opencv-python) or Pillow (pip install pillow)") from None
+    return np.asarray(Image.open(io.BytesIO(data)).convert("RGB"))[:, :, ::-1].copy()
+
+
+class Camera:
+    """One of the device's cameras. ``frame()`` is the newest picture;
+    ``for img in camera.frames():`` yields each new one."""
+
+    def __init__(self, info: Dict[str, Any]):
+        self.id: str = info.get("id", "cam")
+        self.label: str = info.get("label") or self.id
+        self.url: Optional[str] = info.get("url")
+        self.fmt: str = info.get("fmt", "mjpeg")
+        self._jpeg: Optional[bytes] = None
+        self._count = 0
+        self._cond = threading.Condition()
+        self._thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self.error: Optional[str] = None
+        self.fps = 0.0
+
+    def __repr__(self):
+        return f"Camera({self.label!r}, {self.url!r})"
+
+    def _start(self) -> None:
+        if self._thread is not None:
+            return
+        if not self.url:
+            raise CameraError(f"camera {self.label} is not reachable from this computer")
+        self._thread = threading.Thread(target=self._read, daemon=True, name=f"koebelt-dash-camera-{self.id}")
+        self._thread.start()
+
+    def _publish(self, jpeg: bytes) -> None:
+        with self._cond:
+            self._jpeg = jpeg
+            self._count += 1
+            self._cond.notify_all()
+
+    def _read(self) -> None:
+        while not self._stop.is_set():
+            try:
+                with urllib.request.urlopen(self.url, timeout=5) as r:
+                    ctype = r.headers.get("Content-Type", "")
+                    if self.fmt == "jpeg" or not ctype.startswith("multipart/"):
+                        self._publish(r.read())
+                        self._stop.wait(0.1)
+                        continue
+                    boundary = ctype.split("boundary=", 1)[-1].strip().strip('"').encode()
+                    self._parts(r, b"--" + boundary.lstrip(b"-") if boundary else b"")
+                self.error = None
+            except Exception as e:
+                self.error = str(e)
+                self._stop.wait(1.0)
+
+    def _parts(self, r, boundary: bytes) -> None:
+        """Reads multipart/x-mixed-replace parts: headers, then Content-Length
+        bytes (or, without a length, up to the next boundary)."""
+        rd = _Buffered(r)
+        last = time.monotonic()
+        while not self._stop.is_set():
+            line = rd.readline()
+            if line is None:
+                return
+            if not line.strip().startswith(b"--"):
+                continue
+            length = None
+            while True:
+                h = rd.readline()
+                if h is None:
+                    return
+                if not h.strip():
+                    break
+                k, _, v = h.decode("latin-1").partition(":")
+                if k.strip().lower() == "content-length":
+                    length = int(v.strip())
+            data = rd.read(length) if length is not None else rd.until(b"\r\n" + boundary)
+            if data is None:
+                return
+            self._publish(data)
+            now = time.monotonic()
+            self.fps = self.fps * 0.9 + (1 / max(now - last, 1e-3)) * 0.1
+            last = now
+
+    def jpeg(self, timeout: float = 5.0) -> bytes:
+        """The newest frame as the camera sends it (JPEG, or PNG for simulated cameras)."""
+        self._start()
+        with self._cond:
+            if not self._cond.wait_for(lambda: self._jpeg is not None, timeout=timeout):
+                raise CameraError(f"no picture from camera {self.label} within {timeout} s" + (f": {self.error}" if self.error else ""))
+            return self._jpeg  # type: ignore[return-value]
+
+    def frame(self, timeout: float = 5.0):
+        """The newest frame, H×W×3 BGR numpy array."""
+        return decode_jpeg(self.jpeg(timeout))
+
+    def frames(self, timeout: float = 5.0) -> Iterator[Any]:
+        """Each new frame, newest first: frames the loop was too slow for are skipped."""
+        self._start()
+        seen = -1
+        while True:
+            with self._cond:
+                if not self._cond.wait_for(lambda: self._count != seen and self._jpeg is not None, timeout=timeout):
+                    raise CameraError(f"no picture from camera {self.label} within {timeout} s" + (f": {self.error}" if self.error else ""))
+                seen, data = self._count, self._jpeg
+            yield decode_jpeg(data)  # type: ignore[arg-type]
+
+    def close(self) -> None:
+        self._stop.set()
+
+
+class _Buffered:
+    """Line, length and marker reads over a live HTTP body, returning what has
+    arrived without waiting for more than it needs."""
+
+    def __init__(self, r):
+        self.r = r
+        self.buf = b""
+
+    def _more(self) -> bool:
+        chunk = self.r.read1(65536) if hasattr(self.r, "read1") else self.r.read(4096)
+        if not chunk:
+            return False
+        self.buf += chunk
+        if len(self.buf) > 32_000_000:
+            raise CameraError("camera stream without frame boundaries")
+        return True
+
+    def readline(self) -> Optional[bytes]:
+        while b"\n" not in self.buf:
+            if not self._more():
+                return None
+        line, _, self.buf = self.buf.partition(b"\n")
+        return line + b"\n"
+
+    def read(self, n: int) -> Optional[bytes]:
+        while len(self.buf) < n:
+            if not self._more():
+                return None
+        data, self.buf = self.buf[:n], self.buf[n:]
+        return data
+
+    def until(self, marker: bytes) -> Optional[bytes]:
+        """The bytes before marker; the marker stays for the next part."""
+        while marker not in self.buf:
+            if not self._more():
+                return None
+        i = self.buf.index(marker)
+        data, self.buf = self.buf[:i], self.buf[i + 2:]
+        return data
+
+
+def boxes_of(items: Any, width: Optional[float] = None, height: Optional[float] = None) -> list:
+    """Boxes for dev.overlay(): from (x, y, w, h[, label]) tuples, normalised
+    or in pixels (with width and height), or straight from an ultralytics
+    result (``model(frame)[0]``) or its ``.boxes``."""
+    names = getattr(items, "names", None)
+    if hasattr(items, "boxes") and not hasattr(items, "xyxyn"):
+        items = items.boxes
+    if hasattr(items, "xyxyn"):
+        xyxy = items.xyxyn.tolist()
+        cls = items.cls.tolist() if hasattr(items, "cls") else [None] * len(xyxy)
+        conf = items.conf.tolist() if hasattr(items, "conf") else [None] * len(xyxy)
+        out = []
+        for (x1, y1, x2, y2), c, p in zip(xyxy, cls, conf):
+            label = "" if c is None else (names.get(int(c), str(int(c))) if isinstance(names, dict) else str(int(c)))
+            if p is not None:
+                label = f"{label} {p:.2f}".strip()
+            out.append([x1, y1, x2 - x1, y2 - y1, label])
+        return out
+    out = []
+    for b in items:
+        if hasattr(b, "xyxyn"):
+            out.extend(boxes_of(b))
+            continue
+        x, y, w, h = (float(v) for v in b[:4])
+        if width and height:
+            x, y, w, h = x / width, y / height, w / width, h / height
+        out.append([x, y, w, h, str(b[4]) if len(b) > 4 else ""])
+    return out

koebelt_dash_scripts/client.py

@@ -0,0 +1,550 @@
+"""The connection to koebelt/dash: a device a script reads and drives.
+
+The messages are in protocol/SCRIPTS.md. A background thread receives
+telemetry and events; handlers (triggers, settings, takeover) run on a second
+thread, so a slow handler never delays telemetry, and a slow main loop (a
+model taking 200 ms per frame) never trips dash's watchdog: keep-alives go
+out from their own thread every 100 ms.
+"""
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import pathlib
+import queue
+import sys
+import threading
+import time
+import traceback
+from typing import Any, Callable, Dict, Iterator, List, Optional
+
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.client import connect as ws_connect
+
+from .camera import Camera, boxes_of
+
+API_VERSION = 1
+DISCOVERY = pathlib.Path.home() / ".koebelt" / "dash-api.json"
+
+
+class ScriptError(RuntimeError):
+    """dash refused a request; the message says why."""
+
+
+class Released(ScriptError):
+    """dash took the sticks away (watchdog, geofence, STOP…) and the operator has not resumed the script yet."""
+
+
+class Telemetry:
+    """The device's latest telemetry. Attributes are the fields dash sends
+    (``pos``, ``vel``, ``roll``, ``mode``, ``armed``, ``battery``…, see
+    protocol/SCRIPTS.md), plus ``alt``, ``gps`` and ``age``."""
+
+    def __init__(self, data: Dict[str, Any], at: float):
+        self.raw = data
+        self._at = at
+
+    @property
+    def age(self) -> float:
+        """Seconds since this telemetry arrived."""
+        return time.monotonic() - self._at
+
+    @property
+    def alt(self) -> float:
+        """Height above home, metres."""
+        return float(self.raw.get("pos", [0, 0, 0])[2])
+
+    @property
+    def gps(self):
+        """(lat, lon, alt) when the device has a GPS fix, else None."""
+        if "lat" not in self.raw:
+            return None
+        return (self.raw["lat"], self.raw["lon"], self.raw.get("galt", 0.0))
+
+    def __getattr__(self, name: str):
+        try:
+            return self.raw[name]
+        except KeyError:
+            raise AttributeError(f"this device sends no '{name}' (it sends: {', '.join(sorted(self.raw))})") from None
+
+    def __repr__(self):
+        keys = ("mode", "armed", "pos", "speed", "battery")
+        return "Telemetry(" + ", ".join(f"{k}={self.raw[k]!r}" for k in keys if k in self.raw) + ")"
+
+
+class Setting:
+    """A value the operator can change in dash while the script runs."""
+
+    def __init__(self, name: str, value: Any):
+        self.name = name
+        self.value = value
+
+    def __repr__(self):
+        return f"Setting({self.name!r}, {self.value!r})"
+
+
+class _Store(dict):
+    """A dictionary saved to disk on every change, kept between runs."""
+
+    def __init__(self, path: pathlib.Path):
+        self._path = path
+        try:
+            super().__init__(json.loads(path.read_text()))
+        except (OSError, ValueError):
+            super().__init__()
+
+    def _save(self):
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(json.dumps(self, indent=1))
+        except OSError:
+            pass
+
+    def __setitem__(self, k, v):
+        super().__setitem__(k, v)
+        self._save()
+
+    def __delitem__(self, k):
+        super().__delitem__(k)
+        self._save()
+
+    def update(self, *a, **kw):
+        super().update(*a, **kw)
+        self._save()
+
+
+class Params:
+    """The device's parameters: ``dev.params["MAX_TILT"]``. Writing needs the
+    operator's leave (Limits in dash)."""
+
+    def __init__(self, dev: "Device"):
+        self._dev = dev
+
+    def all(self) -> Dict[str, float]:
+        return dict(self._dev._call("cmd", c="params") or {})
+
+    def __getitem__(self, key: str) -> float:
+        values = self.all()
+        if key not in values:
+            raise KeyError(f"{key} (the device has: {', '.join(sorted(values))})")
+        return values[key]
+
+    def set(self, **values: float) -> None:
+        self._dev._call("cmd", c="pset", a=values)
+
+    def save(self) -> None:
+        self._dev._call("cmd", c="psave")
+
+
+def _find_dash(url: Optional[str], token: Optional[str]):
+    url = url or os.environ.get("KOEBELT_DASH_URL")
+    token = token or os.environ.get("KOEBELT_DASH_TOKEN")
+    if url and token:
+        return url, token
+    try:
+        found = json.loads(DISCOVERY.read_text())
+    except (OSError, ValueError):
+        raise ScriptError("koebelt dash is not running on this computer (no ~/.koebelt/dash-api.json). "
+                          "Start it, or pass url= and token=.") from None
+    return url or found["url"], token or found["token"]
+
+
+class Device:
+    """A device connected in koebelt dash, as a script sees it. Get one with
+    :func:`connect`."""
+
+    def __init__(self, ws, welcome: Dict[str, Any], name: str):
+        self._ws = ws
+        self._name = name
+        self._send_lock = threading.Lock()
+        self._ids = itertools.count(1)
+        self._waiting: Dict[int, "queue.Queue[Dict[str, Any]]"] = {}
+        self._tlm: Optional[Telemetry] = None
+        self._tlm_ready = threading.Condition()
+        self._events: "queue.Queue[tuple]" = queue.Queue()
+        self._settings: Dict[str, Setting] = {}
+        self._triggers: Dict[str, Callable] = {}
+        self._any_trigger: List[Callable] = []
+        self._on_stop: List[Callable] = []
+        self._on_takeover: List[Callable] = []
+        self._closed = threading.Event()
+        self._store: Optional[_Store] = None
+        self.hz: Optional[float] = None
+        self.released: Optional[str] = None
+        """Why dash took the sticks away, until the operator resumes the script."""
+        self.taken_over = False
+        """True while the operator holds the sticks."""
+        self.app = welcome.get("app")
+        self.devices = welcome.get("devices", [])
+        self.params = Params(self)
+        self.info: Dict[str, Any] = {}
+        self.cameras: List[Camera] = []
+        for target in (self._receive, self._dispatch, self._keepalive):
+            threading.Thread(target=target, daemon=True, name=f"koebelt-dash-{target.__name__}").start()
+
+    # ------------------------------------------------------------------ plumbing
+    def _send(self, msg: Dict[str, Any]) -> None:
+        with self._send_lock:
+            self._ws.send(json.dumps(msg))
+
+    def _call(self, t: str, timeout: float = 5, **fields) -> Any:
+        if self._closed.is_set():
+            raise ScriptError("the connection to koebelt dash is closed")
+        i = next(self._ids)
+        box: "queue.Queue[Dict[str, Any]]" = queue.Queue(1)
+        self._waiting[i] = box
+        try:
+            self._send({"t": t, "id": i, **fields})
+            try:
+                res = box.get(timeout=timeout)
+            except queue.Empty:
+                raise ScriptError(f"koebelt dash did not answer '{t}' within {timeout} s") from None
+        finally:
+            self._waiting.pop(i, None)
+        if res.get("closed"):
+            raise ScriptError("the connection to koebelt dash closed")
+        if not res.get("ok"):
+            err = res.get("err") or "refused"
+            raise (Released if self.released and "resume" in err else ScriptError)(err)
+        return res.get("value")
+
+    def _receive(self) -> None:
+        try:
+            for raw in self._ws:
+                m = json.loads(raw)
+                t = m.get("t")
+                if t == "res":
+                    box = self._waiting.get(m.get("id"))
+                    if box is not None:
+                        box.put(m)
+                elif t == "tlm":
+                    with self._tlm_ready:
+                        self._tlm = Telemetry(m["d"], time.monotonic())
+                        self._tlm_ready.notify_all()
+                elif t == "setting":
+                    s = self._settings.get(m["name"])
+                    if s is not None:
+                        s.value = m["value"]
+                elif t == "fire":
+                    self._events.put(("fire", m["name"], m.get("value")))
+                elif t == "takeover":
+                    self.taken_over = bool(m.get("on"))
+                    self._events.put(("takeover", self.taken_over))
+                elif t == "released":
+                    self.released = m.get("why") or "released"
+                    print(f"koebelt dash: {self.released}", file=sys.stderr)
+                    self._events.put(("stop", self.released))
+                elif t == "resumed":
+                    self.released = None
+                elif t == "stop":
+                    self._events.put(("stop", "STOP"))
+        except ConnectionClosed:
+            pass
+        finally:
+            self._closed.set()
+            for box in list(self._waiting.values()):
+                box.put({"ok": False, "closed": True})
+            self._events.put(("closed",))
+
+    def _dispatch(self) -> None:
+        while True:
+            ev = self._events.get()
+            kind = ev[0]
+            if kind == "closed":
+                return
+            handlers: List[Callable] = []
+            args: tuple = ()
+            if kind == "fire":
+                _, name, value = ev
+                h = self._triggers.get(name)
+                if h is not None:
+                    handlers, args = [h], (() if value is None else (value,))
+                elif self._any_trigger:
+                    handlers, args = self._any_trigger, (name, value)
+                else:
+                    print(f"koebelt dash: trigger '{name}' has no handler (add @dev.on_trigger)", file=sys.stderr)
+            elif kind == "takeover":
+                handlers, args = self._on_takeover, (ev[1],)
+            elif kind == "stop":
+                handlers, args = self._on_stop, ()
+            for h in handlers:
+                try:
+                    h(*args)
+                except Exception:
+                    traceback.print_exc()
+
+    def _keepalive(self) -> None:
+        while not self._closed.wait(0.1):
+            try:
+                self._send({"t": "ka", **({"hz": round(self.hz, 2)} if self.hz else {})})
+            except Exception:
+                return
+
+    def _use(self, device: Optional[str]) -> None:
+        self.info = self._call("use", device=device)
+        self.cameras = [Camera(c) for c in self.info.get("cameras", [])]
+        with self._tlm_ready:
+            self._tlm_ready.wait_for(lambda: self._tlm is not None, timeout=3)
+
+    # ------------------------------------------------------------------ reading
+    @property
+    def name(self) -> str:
+        return self.info.get("name", "")
+
+    @property
+    def kind(self) -> str:
+        """drone, rover, arm, bench, rocket or generic."""
+        return self.info.get("kind", "generic")
+
+    @property
+    def simulated(self) -> bool:
+        return bool(self.info.get("sim"))
+
+    @property
+    def tlm(self) -> Telemetry:
+        """The latest telemetry (20 Hz)."""
+        if self._tlm is None:
+            raise ScriptError("no telemetry from the device yet")
+        return self._tlm
+
+    def next_tlm(self, timeout: float = 1.0) -> Telemetry:
+        """Waits for the next telemetry message and returns it."""
+        with self._tlm_ready:
+            before = self._tlm
+            if not self._tlm_ready.wait_for(lambda: self._tlm is not before, timeout=timeout):
+                raise ScriptError(f"no telemetry for {timeout} s")
+            return self._tlm  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------ acting
+    def sticks(self, **axes: float) -> None:
+        """Sets the sticks, −1…1, until changed. Drones: ``throttle``, ``yaw``,
+        ``pitch``, ``roll``; rovers: ``throttle``, ``steer``; any device:
+        ``lx``, ``ly``, ``rx``, ``ry``. dash scales them to the script's speed
+        limit, and the operator's sticks win."""
+        self._call("sticks", a=axes)
+
+    def release(self) -> None:
+        """Hands the sticks back; the device holds."""
+        self._call("release")
+
+    def mode(self, mode: str) -> None:
+        self._call("cmd", c="mode", a={"m": mode})
+
+    def arm(self) -> None:
+        """Needs the operator's leave (Limits in dash)."""
+        self._call("cmd", c="arm")
+
+    def disarm(self) -> None:
+        self._call("cmd", c="disarm")
+
+    def speed_limit(self, v: float) -> None:
+        """The device's speed limit, 0.1–1, capped by the script's."""
+        self._call("cmd", c="speed", a={"v": v})
+
+    def cmd(self, name: str, **args: Any) -> None:
+        """A command of this kind of device: ``dev.cmd("release")``, ``dev.cmd("countdown", s=10)``…"""
+        self._call("cmd", c=name, a=args)
+
+    def stop(self) -> None:
+        """STOP: every device, at once, as the STOP button."""
+        self._call("cmd", c="stop")
+
+    # ------------------------------------------------------------------ steps
+    def _step(self, step: str, wait: bool, **args: Any) -> None:
+        self._call("cmd", timeout=3600 if wait else 5, c="step", a={"type": step, "wait": wait, **args})
+
+    def takeoff(self, alt: float = 6, *, wait: bool = True) -> None:
+        """Drones: arms and climbs to ``alt`` metres (needs leave in Limits). Returns once there."""
+        self._step("takeoff", wait, alt=alt)
+
+    def goto(self, x: float, y: float, z: Optional[float] = None, *, wait: bool = True) -> None:
+        """Goes to x metres east, y north of home (and z up, drones). Returns once there."""
+        self._step("goto", wait, x=x, y=y, **({} if z is None else {"z": z}))
+
+    def land(self, *, wait: bool = True) -> None:
+        self._step("land", wait)
+
+    def rth(self, *, wait: bool = True) -> None:
+        """Drones: returns home and lands."""
+        self._step("rth", wait)
+
+    def pose(self, *joints: float, wait: bool = True) -> None:
+        """Arms: moves to joint angles, degrees (J1, J2…)."""
+        self._step("pose", wait, **{f"j{i + 1}": float(v) for i, v in enumerate(joints)})
+
+    def gripper(self, open_pct: float, *, wait: bool = True) -> None:
+        """Arms: 0 (closed) to 100 % open."""
+        self._step("gripper", wait, open=open_pct)
+
+    def home(self, *, wait: bool = True) -> None:
+        """Arms: the home pose."""
+        self._step("home", wait)
+
+    def throttle(self, pct: float, seconds: float, *, wait: bool = True) -> None:
+        """Test benches: holds a throttle for some seconds."""
+        self._step("throttle", wait, pct=pct, s=seconds)
+
+    def ramp(self, start: float, end: float, seconds: float, *, wait: bool = True) -> None:
+        """Test benches: ramps the throttle from one percentage to another."""
+        self._step("ramp", wait, **{"from": start, "to": end, "s": seconds})
+
+    def run_program(self, name: str, *, wait: bool = True) -> None:
+        """Runs a program from dash's Program screen (on the device when it can
+        store it: it keeps going if the link drops)."""
+        self._call("cmd", timeout=24 * 3600 if wait else 5, c="program", a={"name": name, "wait": wait})
+
+    def pause_program(self) -> None:
+        self._call("cmd", c="seqctl", a={"c": "pause"})
+
+    def resume_program(self) -> None:
+        self._call("cmd", c="seqctl", a={"c": "resume"})
+
+    def stop_program(self) -> None:
+        self._call("cmd", c="seqctl", a={"c": "stop"})
+
+    # ------------------------------------------------------------------ camera
+    @property
+    def camera(self) -> Camera:
+        """The device's first camera."""
+        if not self.cameras:
+            raise ScriptError(f"{self.name} has no camera")
+        return self.cameras[0]
+
+    def overlay(self, boxes: Any, width: Optional[float] = None, height: Optional[float] = None) -> None:
+        """Draws boxes over the camera picture in dash: (x, y, w, h[, label])
+        tuples, normalised 0–1 (or in pixels with width and height), or an
+        ultralytics result. They fade a second after the last call."""
+        self._send({"t": "overlay", "boxes": boxes_of(boxes, width, height)})
+
+    # ------------------------------------------------------------------ dash
+    def setting(self, name: str, default: Any, *, min: Optional[float] = None, max: Optional[float] = None,
+                label: Optional[str] = None) -> Setting:
+        """A slider (numbers) or switch (True/False) in dash. Read ``.value``;
+        the operator's last value is kept between runs."""
+        value = self._call("setting", name=name, value=default, min=min, max=max, label=label)
+        s = self._settings[name] = Setting(name, value)
+        return s
+
+    def trigger(self, name: str, kind: str = "button", *, key: Optional[str] = None, gamepad: Optional[str] = None,
+                min: Optional[float] = None, max: Optional[float] = None):
+        """Decorator: runs the function when the trigger fires. ``kind``:
+        ``button`` (no argument), ``switch`` (True/False) or ``value`` (a
+        number). ``key`` and ``gamepad`` suggest bindings; the operator can
+        change them."""
+        def register(fn: Callable) -> Callable:
+            self._triggers[name] = fn
+            self._call("trigger", name=name, kind=kind, key=key, gamepad=gamepad, min=min, max=max)
+            return fn
+        return register
+
+    def on_trigger(self, fn: Callable) -> Callable:
+        """Decorator: ``fn(name, value)`` for triggers without their own handler."""
+        self._any_trigger.append(fn)
+        return fn
+
+    def on_stop(self, fn: Callable) -> Callable:
+        """Decorator: called when dash takes the sticks away or STOP is pressed."""
+        self._on_stop.append(fn)
+        return fn
+
+    def on_takeover(self, fn: Callable) -> Callable:
+        """Decorator: ``fn(True)`` when the operator takes the sticks, ``fn(False)`` when they give them back."""
+        self._on_takeover.append(fn)
+        return fn
+
+    def plot(self, name: str, value: float) -> None:
+        """Shows a value in dash (channel ``script:<name>``) and records it."""
+        self._send({"t": "plot", "name": name, "v": float(value)})
+
+    def mark(self, text: str) -> None:
+        """An event on the recording's timeline."""
+        self._call("mark", text=text)
+
+    def notify(self, text: str, level: str = "info") -> None:
+        """A message to the operator in dash (``info``, ``warn``, ``err``)."""
+        self._call("notify", text=text, level=level)
+
+    @property
+    def store(self) -> dict:
+        """A dictionary kept between runs of this script."""
+        if self._store is None:
+            safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in self._name)
+            self._store = _Store(DISCOVERY.parent / "script-store" / f"{safe}.json")
+        return self._store
+
+    def run(self) -> None:
+        """Waits until dash closes the connection: for scripts that only react to triggers."""
+        try:
+            self._closed.wait()
+        except KeyboardInterrupt:
+            pass
+
+    def close(self) -> None:
+        for c in self.cameras:
+            c.close()
+        try:
+            self._ws.close()
+        finally:
+            self._closed.set()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def __repr__(self):
+        return f"Device({self.name!r}, {self.kind}{', simulated' if self.simulated else ''})"
+
+
+_current: Optional[Device] = None
+
+
+def connect(device: Optional[str] = None, *, url: Optional[str] = None, token: Optional[str] = None,
+            name: Optional[str] = None) -> Device:
+    """Connects to koebelt dash and returns a device: the one selected in dash,
+    or the one called ``device``. dash on this computer is found by itself."""
+    global _current
+    url, token = _find_dash(url, token)
+    name = name or os.path.basename(sys.argv[0] or "") or "python"
+    try:
+        # Entering the context opens it, in every websockets version from 12 on.
+        ws = ws_connect(url, open_timeout=5, max_size=None).__enter__()
+    except OSError as e:
+        raise ScriptError(f"cannot reach koebelt dash at {url}: {e}") from None
+    ws.send(json.dumps({"t": "hello", "v": API_VERSION, "token": token, "name": name, "pid": os.getpid()}))
+    welcome = json.loads(ws.recv(timeout=5))
+    if welcome.get("t") != "welcome":
+        ws.close()
+        raise ScriptError(welcome.get("why") or "koebelt dash refused the connection")
+    dev = Device(ws, welcome, name)
+    dev._use(device)
+    _current = dev
+    return dev
+
+
+def every(seconds: float) -> Iterator[int]:
+    """A steady loop: ``for i in every(0.05): ...`` runs the body every 50 ms
+    (or as fast as it can), and reports the real rate to dash."""
+    period = float(seconds)
+    nxt = time.monotonic()
+    window, count = nxt, 0
+    for i in itertools.count():
+        yield i
+        now = time.monotonic()
+        # The rate over each second, not single intervals.
+        count += 1
+        if now - window >= 1.0 and _current is not None:
+            _current.hz = count / (now - window)
+            window, count = now, 0
+        nxt += period
+        delay = nxt - time.monotonic()
+        if delay > 0:
+            time.sleep(delay)
+        else:
+            nxt = time.monotonic()
+
+
+def wait(seconds: float) -> None:
+    time.sleep(seconds)

koebelt_dash_scripts/host.py

@@ -0,0 +1,268 @@
+"""A script host: runs scripts for koebelt dash on a phone or tablet.
+
+    koebelt-dash-scripts host
+
+Phones cannot run Python with machine learning, so they send their scripts
+here. The script runs in this computer's Python and connects back to dash on
+the phone, which keeps the device link, the operator's sticks and STOP.
+
+The phone finds the host on the local network (or is given its address),
+and pairs once with the code the host prints. Messages are in
+protocol/SCRIPTS.md (Script hosts).
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import pathlib
+import secrets
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from typing import Dict, Optional
+
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.server import serve
+
+from . import __version__
+
+HOST_PORT = 47921
+DISCOVERY_PORT = 47922
+CONFIG = pathlib.Path.home() / ".koebelt" / "script-host.json"
+
+
+def _load() -> dict:
+    try:
+        return json.loads(CONFIG.read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def _save(cfg: dict) -> None:
+    CONFIG.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG.write_text(json.dumps(cfg, indent=1))
+    try:
+        CONFIG.chmod(0o600)
+    except OSError:
+        pass
+
+
+def _python_version(python: str) -> str:
+    try:
+        out = subprocess.run([python, "-c", "import sys; print(sys.version.split()[0])"], capture_output=True, text=True, timeout=10)
+        return out.stdout.strip() or "?"
+    except Exception:
+        return "?"
+
+
+class Host:
+    """Pairs phones and runs their scripts."""
+
+    def __init__(self, name: Optional[str] = None, port: int = HOST_PORT, python: Optional[str] = None,
+                 discovery: bool = True, say=print, discovery_port: int = DISCOVERY_PORT):
+        self.cfg = _load()
+        self.name = name or self.cfg.get("name") or socket.gethostname().split(".")[0]
+        self.port = port
+        self.python = python or sys.executable
+        self.version = _python_version(self.python)
+        self.discovery = discovery
+        self.discovery_port = discovery_port
+        self.say = say
+        self.ready = threading.Event()
+        self.code = self._new_code()
+        self.runs: Dict[str, "_Run"] = {}
+        self._server = None
+
+    @staticmethod
+    def _new_code() -> str:
+        alphabet = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+        return "".join(secrets.choice(alphabet) for _ in range(3)) + "-" + "".join(secrets.choice(alphabet) for _ in range(3))
+
+    @property
+    def tokens(self) -> Dict[str, str]:
+        """Paired phones: token → their name."""
+        return self.cfg.setdefault("paired", {})
+
+    def info(self) -> dict:
+        return {"t": "host", "v": 1, "name": self.name, "port": self.port, "python": self.version, "pkg": __version__}
+
+    # ------------------------------------------------------------- discovery
+    def _discovery(self) -> None:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind(("", self.discovery_port))
+        except OSError as e:
+            self.say(f"Discovery is off (port {self.discovery_port}: {e}); phones can still use this computer's address.")
+            return
+        while True:
+            try:
+                data, addr = s.recvfrom(2048)
+                if json.loads(data).get("t") == "hostdiscover":
+                    s.sendto(json.dumps(self.info()).encode(), addr)
+            except Exception:
+                continue
+
+    # ------------------------------------------------------------- sessions
+    def _handle(self, ws) -> None:
+        peer = ws.remote_address[0] if ws.remote_address else "?"
+        try:
+            hello = json.loads(ws.recv(timeout=10))
+        except Exception:
+            return
+        t = hello.get("t")
+        if t == "pair":
+            if str(hello.get("code", "")).upper().replace(" ", "") != self.code:
+                ws.send(json.dumps({"t": "bye", "why": "Wrong pairing code."}))
+                return
+            token = secrets.token_hex(16)
+            self.tokens[token] = str(hello.get("name") or peer)
+            _save(self.cfg)
+            self.code = self._new_code()
+            self.say(f"Paired with {self.tokens[token]}. Next pairing code: {self.code}")
+            ws.send(json.dumps({**self.info(), "t": "paired", "token": token}))
+            return
+        if t != "hello" or hello.get("token") not in self.tokens:
+            ws.send(json.dumps({"t": "bye", "why": "Not paired with this host: pair again with its code."}))
+            return
+        who = self.tokens[hello["token"]]
+        ws.send(json.dumps({**self.info(), "t": "welcome"}))
+        run: Optional[_Run] = None
+        try:
+            for raw in ws:
+                m = json.loads(raw)
+                if m.get("t") == "run" and run is None:
+                    run = _Run(self, ws, m, peer)
+                    self.say(f"{who}: running {m.get('name', 'a script')}")
+                    run.start()
+                elif m.get("t") == "stop" and run is not None:
+                    run.stop()
+        except ConnectionClosed:
+            pass
+        finally:
+            # The phone went away: its script cannot reach dash any more anyway.
+            if run is not None:
+                run.stop()
+
+    def serve(self) -> None:
+        if self.discovery:
+            threading.Thread(target=self._discovery, daemon=True).start()
+        with serve(self._handle, "0.0.0.0", self.port, max_size=None) as server:
+            self._server = server
+            self.port = server.socket.getsockname()[1]
+            self.ready.set()
+            server.serve_forever()
+
+    def shutdown(self) -> None:
+        if self._server is not None:
+            self._server.shutdown()
+
+
+class _Run:
+    """One script a phone runs here."""
+
+    def __init__(self, host: Host, ws, m: dict, peer: str):
+        self.host, self.ws, self.m = host, ws, m
+        self.dir = pathlib.Path(tempfile.mkdtemp(prefix="koebelt-script-"))
+        self.proc: Optional[subprocess.Popen] = None
+        self.lock = threading.Lock()
+        # dash on the phone, as this computer reaches it.
+        self.dash = f"ws://{m.get('dashHost') or peer}:{int(m['dashPort'])}/scripts"
+
+    def _send(self, msg: dict) -> None:
+        with self.lock:
+            try:
+                self.ws.send(json.dumps(msg))
+            except Exception:
+                pass
+
+    def start(self) -> None:
+        main = None
+        for rel, b64 in self.m.get("files", {}).items():
+            path = (self.dir / rel).resolve()
+            if self.dir.resolve() not in path.parents:
+                continue
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(base64.b64decode(b64))
+            if rel == self.m.get("main", "main.py"):
+                main = path
+        if main is None:
+            self._send({"t": "out", "level": "err", "text": "The script's file is missing."})
+            self._send({"t": "exit", "code": 1})
+            return
+        env = dict(os.environ, KOEBELT_DASH_URL=self.dash, KOEBELT_DASH_TOKEN=self.m["dashToken"], PYTHONUNBUFFERED="1",
+                   PYTHONIOENCODING="utf-8")
+        self.proc = subprocess.Popen([self.host.python, "-u", str(main)], cwd=self.dir, env=env, stdout=subprocess.PIPE,
+                                     stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
+        self._send({"t": "started", "pid": self.proc.pid, "python": self.host.version})
+        for stream, level in ((self.proc.stdout, "out"), (self.proc.stderr, "err")):
+            threading.Thread(target=self._pump, args=(stream, level), daemon=True).start()
+        threading.Thread(target=self._wait, daemon=True).start()
+
+    def _pump(self, stream, level: str) -> None:
+        for line in stream:
+            self._send({"t": "out", "level": level, "text": line.rstrip("\n")})
+
+    def _wait(self) -> None:
+        code = self.proc.wait()
+        time.sleep(0.2)  # let the last lines out first
+        self._send({"t": "exit", "code": code})
+        shutil.rmtree(self.dir, ignore_errors=True)
+
+    def stop(self) -> None:
+        p = self.proc
+        if p is None or p.poll() is not None:
+            return
+        p.terminate()
+        try:
+            p.wait(2)
+        except subprocess.TimeoutExpired:
+            p.kill()
+
+
+def main(argv=None) -> None:
+    ap = argparse.ArgumentParser(prog="koebelt-dash-scripts host", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--name", help="the name phones see (default: this computer's)")
+    ap.add_argument("--port", type=int, default=HOST_PORT)
+    ap.add_argument("--python", help="the Python scripts run with (default: this one)")
+    ap.add_argument("--no-discovery", action="store_true", help="do not answer phones looking for hosts")
+    ap.add_argument("--forget", action="store_true", help="unpair every phone, then exit")
+    a = ap.parse_args(argv)
+    if a.forget:
+        cfg = _load()
+        cfg["paired"] = {}
+        _save(cfg)
+        print("Every phone is unpaired.")
+        return
+    h = Host(name=a.name, port=a.port, python=a.python, discovery=not a.no_discovery)
+    if a.name:
+        h.cfg["name"] = a.name
+        _save(h.cfg)
+    print(f"koebelt dash script host “{h.name}”, port {h.port}, Python {h.version}")
+    print(f"Pairing code: {h.code}   (in koebelt dash: Scripts > Script host > Pair)")
+    print(f"Paired phones: {len(h.tokens)}. Ctrl-C to stop.", flush=True)
+    try:
+        h.serve()
+    except KeyboardInterrupt:
+        pass
+
+
+def cli(argv=None) -> None:
+    """`koebelt-dash-scripts <command>`."""
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv or argv[0] in ("-h", "--help"):
+        print("usage: koebelt-dash-scripts host [--name NAME] [--port PORT] [--python PATH] [--forget]")
+        print("       koebelt-dash-scripts --version")
+        return
+    if argv[0] == "--version":
+        print(__version__)
+        return
+    if argv[0] == "host":
+        return main(argv[1:])
+    sys.exit(f"unknown command: {argv[0]}")

koebelt_dash_scripts/tools.py

@@ -0,0 +1,112 @@
+"""Small helpers for control loops: PID, filters, limits and geometry.
+
+Local positions are metres from home, x east and y north (as dash's
+telemetry ``pos``); headings and bearings are compass degrees.
+"""
+from __future__ import annotations
+
+import math
+import time
+from typing import Optional, Sequence
+
+
+def clamp(x: float, lo: float = -1.0, hi: float = 1.0) -> float:
+    return lo if x < lo else hi if x > hi else x
+
+
+class pid:
+    """A PID controller. ``out = pid(1.2, 0.1, 0.3).update(error)``; the time
+    step is measured unless given. The output is clamped to ±limit, and the
+    integral stops growing while the output is clamped (anti-windup)."""
+
+    def __init__(self, kp: float, ki: float = 0.0, kd: float = 0.0, limit: float = 1.0):
+        self.kp, self.ki, self.kd, self.limit = kp, ki, kd, limit
+        self.reset()
+
+    def reset(self) -> None:
+        self.integral = 0.0
+        self._last_error: Optional[float] = None
+        self._last_t: Optional[float] = None
+
+    def update(self, error: float, dt: Optional[float] = None) -> float:
+        now = time.monotonic()
+        if dt is None:
+            dt = 0.0 if self._last_t is None else now - self._last_t
+        self._last_t = now
+        deriv = 0.0 if self._last_error is None or dt <= 0 else (error - self._last_error) / dt
+        self._last_error = error
+        integral = self.integral + error * dt
+        out = self.kp * error + self.ki * integral + self.kd * deriv
+        if -self.limit < out < self.limit:
+            self.integral = integral
+        return clamp(out, -self.limit, self.limit)
+
+
+class lowpass:
+    """A first-order low-pass filter with a cut-off in Hz: ``f = lowpass(2); y = f.update(x)``."""
+
+    def __init__(self, hz: float):
+        self.hz = hz
+        self.value: Optional[float] = None
+        self._last_t: Optional[float] = None
+
+    def update(self, x: float, dt: Optional[float] = None) -> float:
+        now = time.monotonic()
+        if dt is None:
+            dt = 0.0 if self._last_t is None else now - self._last_t
+        self._last_t = now
+        if self.value is None:
+            self.value = x
+        else:
+            a = 1 - math.exp(-2 * math.pi * self.hz * dt)
+            self.value += a * (x - self.value)
+        return self.value
+
+
+class rate_limit:
+    """Moves towards a target at most ``per_second`` units a second: smooth stick changes."""
+
+    def __init__(self, per_second: float, start: float = 0.0):
+        self.per_second = per_second
+        self.value = start
+        self._last_t: Optional[float] = None
+
+    def update(self, target: float, dt: Optional[float] = None) -> float:
+        now = time.monotonic()
+        if dt is None:
+            dt = 0.0 if self._last_t is None else now - self._last_t
+        self._last_t = now
+        step = self.per_second * dt
+        self.value += clamp(target - self.value, -step, step)
+        return self.value
+
+
+def distance(a: Sequence[float], b: Sequence[float] = (0, 0, 0)) -> float:
+    """Straight-line distance between two local positions (2 or 3 coordinates); from home by default."""
+    return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))
+
+
+def bearing(a: Sequence[float], b: Sequence[float]) -> float:
+    """Compass bearing from local position a to b, degrees (0 = north, 90 = east)."""
+    return math.degrees(math.atan2(b[0] - a[0], b[1] - a[1])) % 360
+
+
+def angle_diff(target: float, current: float) -> float:
+    """Shortest signed turn from one heading to another, degrees in −180…180."""
+    return (target - current + 180) % 360 - 180
+
+
+def geo_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Metres between two GPS positions."""
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp, dl = p2 - p1, math.radians(lon2 - lon1)
+    h = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * 6371000 * math.asin(math.sqrt(h))
+
+
+def geo_bearing(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Compass bearing between two GPS positions, degrees."""
+    p1, p2, dl = math.radians(lat1), math.radians(lat2), math.radians(lon2 - lon1)
+    y = math.sin(dl) * math.cos(p2)
+    x = math.cos(p1) * math.sin(p2) - math.sin(p1) * math.cos(p2) * math.cos(dl)
+    return math.degrees(math.atan2(y, x)) % 360

koebelt_dash_scripts-1.3.0b1.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: koebelt-dash-scripts
+Version: 1.3.0b1
+Summary: Control drones, robots and test rigs connected in the koebelt/dash app from Python.
+Author-email: Thomas Koebel <contact@koebelt.com>
+License-Expression: MIT
+Project-URL: Homepage, https://koebelt.com/work/koebelt-dash
+Project-URL: Source, https://github.com/koebelt/koebelt_dash/tree/main/libs/python-dash-scripts
+Project-URL: Protocol, https://github.com/koebelt/koebelt_dash/blob/main/protocol/SCRIPTS.md
+Project-URL: Issues, https://github.com/koebelt/koebelt_dash/issues
+Keywords: robotics,drone,rover,automation,computer-vision,koebelt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# koebelt-dash-scripts
+
+Control drones, robots and test rigs connected in
+[koebelt/dash](https://koebelt.com/work/koebelt-dash) from Python: read their
+telemetry, drive them, react to buttons and conditions, with any Python
+package you like (OpenCV, PyTorch, YOLO…).
+
+```sh
+pip install koebelt-dash-scripts
+```
+
+```python
+from koebelt_dash_scripts import connect, every, pid
+
+dev = connect()                      # the device selected in koebelt dash
+speed = dev.setting("speed", 0.4, min=0, max=1)   # a slider in dash
+hold = pid(1.5, 0.0, 0.2)
+
+@dev.trigger("Stop here", key="S")   # a button in dash
+def stop_here():
+    dev.mode("HOLD")
+
+dev.mode("MANUAL")
+for _ in every(0.05):                # 20 Hz
+    error = 0.0 - dev.tlm.pos[0]     # stay on the north-south line
+    dev.sticks(throttle=speed.value, steer=hold.update(error))
+```
+
+Run it from koebelt dash (Scripts), or from a terminal while dash is open on
+the same computer: it finds dash by itself.
+
+With a model on the camera:
+
+```python
+from ultralytics import YOLO
+from koebelt_dash_scripts import connect, pid
+
+model = YOLO("yolov8n.pt")
+dev = connect()
+steer = pid(1.2, 0, 0.1)
+
+for frame in dev.camera.frames():
+    result = model(frame, verbose=False)[0]
+    dev.overlay(result)                       # see what the model sees, in dash
+    people = [b for b in result.boxes if int(b.cls) == 0]
+    if not people:
+        dev.sticks(throttle=0, steer=0)
+        continue
+    x = float(people[0].xywhn[0][0]) - 0.5    # −0.5 left … 0.5 right
+    dev.sticks(throttle=0.4, steer=steer.update(-x))
+```
+
+## Script hosts: scripts for phones and tablets
+
+koebelt dash on an iPhone, iPad or Android device sends its scripts to a
+computer on the same network, which runs them with its own Python (and its
+GPU), while the phone keeps the device link, the sticks and STOP:
+
+```sh
+pip install koebelt-dash-scripts
+koebelt-dash-scripts host
+```
+
+It prints a pairing code; in dash: Scripts > Runs on > Add a script host. A
+laptop on the field, a Raspberry Pi 5 or a Jetson all work. A computer
+running koebelt dash can also be a host (Settings > Scripts).
+
+## Safety
+
+dash stays in charge, whatever the script does:
+
+- STOP stops every device and ends the script.
+- Moving the sticks in dash takes over; the script's sticks are ignored until
+  you resume it.
+- Each script has limits set in dash: maximum speed, geofence, ceiling.
+  Arming, take-off and parameter writes are refused unless you allow them.
+- If the script crashes, hangs or leaves the geofence, the device holds, and
+  the script cannot drive again until you resume it.
+
+## The API
+
+| | |
+|---|---|
+| `connect(device=None)` | The device selected in dash, or the one with that name. |
+| `dev.tlm` | Latest telemetry (20 Hz): `pos` (m from home, x east, y north), `alt`, `vel`, `speed`, `roll` `pitch` `yaw`, `heading`, `mode`, `armed`, `battery`, `gps`, `joints`… |
+| `dev.next_tlm()` | Waits for the next telemetry. |
+| `dev.sticks(...)` | −1…1, held until changed. Drones: `throttle yaw pitch roll`; rovers: `throttle steer`. |
+| `dev.mode(m)`, `dev.arm()`, `dev.disarm()`, `dev.speed_limit(v)`, `dev.cmd(name, **args)`, `dev.stop()`, `dev.release()` | Commands. |
+| `dev.takeoff(alt)`, `dev.goto(x, y, z)`, `dev.land()`, `dev.rth()`, `dev.pose(*deg)`, `dev.gripper(pct)`, `dev.home()`, `dev.throttle(pct, s)`, `dev.ramp(a, b, s)` | Program steps; they return once done (or at once with `wait=False`). |
+| `dev.run_program(name)`, `dev.pause_program()`, `dev.resume_program()`, `dev.stop_program()` | Programs from dash's Program screen. |
+| `dev.camera.frame()`, `for img in dev.camera.frames():` | The camera as numpy images (BGR, for OpenCV; needs `opencv-python` or `pillow`). The newest frame only: a slow model never falls behind. |
+| `dev.overlay(boxes)` | Boxes over the camera in dash: `(x, y, w, h, label)` tuples or an ultralytics result. |
+| `dev.params["KEY"]`, `dev.params.set(KEY=v)`, `dev.params.save()` | Parameters. |
+| `dev.setting(name, default, min, max)` | A slider or switch in dash; read `.value`. |
+| `@dev.trigger(name, kind, key, gamepad)` | A button (`button`), switch (`switch`) or number (`value`) in dash. |
+| `@dev.on_trigger`, `@dev.on_stop`, `@dev.on_takeover` | Other events. |
+| `dev.plot(name, v)`, `dev.mark(text)`, `dev.notify(text)` | Shown in dash and recorded. |
+| `dev.store` | A dictionary kept between runs. |
+| `dev.run()` | Waits, for scripts that only react to triggers. |
+| `every(seconds)`, `wait(seconds)` | Steady loops; dash shows the real rate. |
+| `pid`, `lowpass`, `rate_limit`, `clamp`, `distance`, `bearing`, `angle_diff`, `geo_distance`, `geo_bearing` | Helpers. |
+
+The messages between scripts and dash are documented in
+[protocol/SCRIPTS.md](https://github.com/koebelt/koebelt_dash/blob/main/protocol/SCRIPTS.md).
+
+MIT licence.

koebelt_dash_scripts-1.3.0b1.dist-info/RECORD

@@ -0,0 +1,13 @@
+koebelt_dash_scripts/__init__.py,sha256=SaFTxURDob1NCzP0yVpacR87uY9Y_8fmCkAWmzf7KMA,825
+koebelt_dash_scripts/__main__.py,sha256=mvh09q2N7omAyyVpFWNlZD6NEBLhJWHtErZHjnvDhx4,71
+koebelt_dash_scripts/camera.py,sha256=4bJjOUizDOeGjopl5I7tHqDqR2upaTVxe66zoyQPUkI,8325
+koebelt_dash_scripts/client.py,sha256=x60YMTZYktMoBpX89UEh0dkW8ElQ1ryjD_hhWedyuRg,21217
+koebelt_dash_scripts/host.py,sha256=Z7cEp7744JXC_QVjseCM5QLfvWTfFHVjrHqvfaDhBrw,10243
+koebelt_dash_scripts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+koebelt_dash_scripts/tools.py,sha256=AV1UvBtQq1tCTE33L6uvxHT8f-5Oipzb_iYEkGl55JQ,4311
+koebelt_dash_scripts-1.3.0b1.dist-info/licenses/LICENSE,sha256=m-y3HxYhKiD6YgEawRG_c1sL_u_6XpaXAVtEZB1EIVo,1070
+koebelt_dash_scripts-1.3.0b1.dist-info/METADATA,sha256=m79qkAaXxruU47dwZcQD6Era0INSTgwvS_pgyjaB0fc,6027
+koebelt_dash_scripts-1.3.0b1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+koebelt_dash_scripts-1.3.0b1.dist-info/entry_points.txt,sha256=Wtb84cGA602-C0JvAFceC7Gg0c8Uxz4-GKmxMlj4Mww,71
+koebelt_dash_scripts-1.3.0b1.dist-info/top_level.txt,sha256=pwU67_VGj7C5eYW4F0UGtuXejCx-wJTaAFjfeBwq4RA,21
+koebelt_dash_scripts-1.3.0b1.dist-info/RECORD,,

koebelt_dash_scripts-1.3.0b1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

koebelt_dash_scripts-1.3.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+koebelt-dash-scripts = koebelt_dash_scripts.host:cli

koebelt_dash_scripts-1.3.0b1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Koebel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

koebelt_dash_scripts-1.3.0b1.dist-info/top_level.txt

@@ -0,0 +1 @@
+koebelt_dash_scripts