koebelt-dash-scripts 1.3.0b1__tar.gz

koebelt_dash_scripts-1.3.0b1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/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-1.3.0b1/koebelt_dash_scripts/__main__.py

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

koebelt_dash_scripts-1.3.0b1/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