pandora-sdk 0.4.1__py3-none-any.whl

pandora_sdk/__init__.py

@@ -0,0 +1,32 @@
+"""Hands from the 01 Glove in a few lines of Python.
+
+    import pandora_sdk
+
+    with pandora_sdk.connect() as gloves:              # through the running app
+        gloves.subscribe(hands=["right"], rate_hz=50, bones=False)
+        for hand in gloves.frames():
+            print(hand.angles_deg)
+
+connect() reads through the app, which must be running with its Protocol
+adapter switched on. open_receiver() reads the receiver itself, with no app,
+from the profiles the `pandora calibrate` command writes
+(pandora_sdk/calibrate.py). Both give the same Frame, Raw and Debug, take the
+same commands for a glove (haptics, Hall range) and give its Calibration;
+what they hold is in PROTOCOL.md (attached to each release of pandora-sdk).
+"""
+from pandora_core_rs.glove import Profile
+from pandora_core_rs.protocol import (DEFAULT_PORT, Calibration, Debug, Device, Frame,
+                                      ProtocolError, Raw, Subscription)
+from pandora_core_rs.receiver import ReceiverPort
+
+from pandora_sdk.client import Client, Server, connect
+from pandora_sdk.local import (Local, default_profiles_dir, list_receivers, load_profiles,
+                               open_link, open_receiver, save_profile)
+from pandora_sdk.source import (CONNECTION_FAILED_CODES, DISCONNECTED_CODES, ConnectionFailed,
+                                Disconnected, PandoraError, ServerError, Source)
+
+__all__ = ["CONNECTION_FAILED_CODES", "DEFAULT_PORT", "DISCONNECTED_CODES", "Calibration",
+           "Client", "ConnectionFailed", "Debug", "Device", "Disconnected", "Frame", "Local",
+           "PandoraError", "Profile", "ProtocolError", "Raw", "ReceiverPort", "Server",
+           "ServerError", "Source", "Subscription", "connect", "default_profiles_dir",
+           "list_receivers", "load_profiles", "open_link", "open_receiver", "save_profile"]

pandora_sdk/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from pandora_sdk.cli import main
+
+sys.exit(main())

pandora_sdk/calibrate.py

@@ -0,0 +1,253 @@
+"""`pandora calibrate`: calibrate one glove read straight from the receiver,
+with no app, and write the profile open_receiver() reads.
+
+    link = open_link()
+    outcome = calibrate(link, hand="right")
+    print(outcome.path)
+
+The run itself is pandora-core-rs's (CalibrationSession, driven over the glove's
+packets by calibrate_packets): which steps there are, what each captures and
+how it went. This adds what a person at a terminal needs around it: which
+glove, each step and its countdown as text, a buzz on the back of the hand
+when a step starts, and the file at the end.
+
+The clock is the glove's own (its packets' timestamps), so a countdown stops
+while the glove is out of range and nothing is captured from old data.
+
+A profile is good for one Hall range, and open_receiver() sends a glove
+nothing unless asked, so the range it will meet is the one a glove powers up
+in. The run
+therefore starts by resetting every Hall sensor to its power-up settings, and
+the profile records that range. The glove does not report back, so this is
+what it was told, not what it confirmed.
+"""
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Tuple, Union
+
+from pandora_core_rs import commands
+from pandora_core_rs.calibration_session import CalibrationSession, Run, Step, calibrate_packets
+from pandora_core_rs.glove import Glove, Profile
+from pandora_core_rs.packet_decoder import GlovePacket
+from pandora_core_rs.packet_layout import (
+    HALL_DEFAULT_FILTER, HALL_DEFAULT_ODR, HALL_DEFAULT_OSR, HALL_DEFAULT_RANGE, HALL_TARGET_ALL,
+    HAPTIC_BACKHAND_MOTOR, HAPTIC_MOTOR_COUNT,
+)
+from pandora_core_rs.tuning import Tuning
+
+from pandora_sdk.local import (default_profiles_dir, link_failure, link_failure_code,
+                               link_packets, load_profiles, save_profile, send_command)
+from pandora_sdk.source import Disconnected, PandoraError
+
+# The cue: the back-of-hand motor at full drive (pandora_core_rs commands.haptic_rtp
+# takes 1 to 127), for this long when a step starts and when the run is over.
+CUE_AMPLITUDE = 127
+CUE_MS = 150
+DONE_MS = 500
+
+Packets = Iterator[Optional[GlovePacket]]
+
+
+@dataclass
+class Outcome:
+    """How a run went."""
+    device: str
+    hand: str
+    # The run's heading and one (good, text) line per result, as the session
+    # gives them.
+    title: str
+    lines: List[Tuple[bool, str]]
+    # The profile written; None when the run stored nothing.
+    path: Optional[Path]
+
+    @property
+    def ok(self) -> bool:
+        """A profile was written and no part of the run failed."""
+        return self.path is not None and all(good for good, _text in self.lines)
+
+
+def calibrate(link: Any, *, hand: Optional[str] = None, device: Optional[str] = None,
+              out: Union[str, Path, None] = None, run: Run = Run.FULL, hold_s: float = 3.0,
+              ready_s: float = 3.0, haptics: bool = True, name: Optional[str] = None,
+              listen_s: float = 1.0, wait_s: float = 10.0,
+              say: Callable[[str], None] = print,
+              tuning: Union[Tuning, Mapping[str, Any], None] = None,
+              defaults: Optional[Mapping[str, Any]] = None) -> Outcome:
+    """Calibrate one glove sending on *link* (an open receiver port,
+    local.open_link) and write its profile into *out*, a folder
+    (default_profiles_dir() when left out).
+
+    The glove is *device*, or the only one heard in the first *listen_s*
+    seconds. *hand* is "left" or "right"; it can be left out for a glove that
+    already has a profile in the folder, which the run then starts from, so
+    what it does not measure is kept. *run* and *hold_s* are the session's:
+    what to calibrate and how long each still pose is held. The first step
+    starts *ready_s* seconds after the glove is picked. *name* is a label for
+    the glove, kept in the profile. With *haptics* the back of the hand
+    buzzes when a step starts and when the run is over.
+
+    Every line for the person goes to *say*. PandoraError when no run could
+    be made: no glove heard for *wait_s* seconds, two heard and none named, a
+    hand that is not known, a glove that stopped part way. Nothing is written
+    then.
+    """
+    folder = default_profiles_dir() if out is None else Path(out)
+    feed = _packets(link)
+    glove_id = _pick(feed, device, listen_s, wait_s)
+    profile = _starting_profile(folder, glove_id, hand, name, say)
+    say(f"Glove {glove_id}, {profile.hand} hand.")
+    send_command(link, commands.hall_config(
+        glove_id, reset=True, range_val=HALL_DEFAULT_RANGE, osr=HALL_DEFAULT_OSR,
+        odr=HALL_DEFAULT_ODR, filter_val=HALL_DEFAULT_FILTER, target=HALL_TARGET_ALL))
+    say(f"First step in {ready_s:g} s."
+        + (" The back of the hand buzzes when a step starts." if haptics else ""))
+
+    def cue(ms: int = CUE_MS) -> None:
+        if haptics:
+            _buzz(link, glove_id, ms)
+
+    mine = _from(feed, glove_id, wait_s)
+    with Glove(profile, tuning, defaults) as glove:
+        _settle(glove, mine, ready_s)
+        session = calibrate_packets(glove, mine, run, hold_s, watch=_Screen(say, cue))
+        path = (save_profile(folder, glove_id, glove.export_profile())
+                if session.changed else None)
+    if session.steps:
+        cue(DONE_MS)
+    say("")
+    say(session.title)
+    for good, text in session.lines:
+        say(f"  {'ok  ' if good else 'FAIL'}  {text}")
+    say(f"Profile written: {path}" if path is not None else "No profile was written.")
+    return Outcome(glove_id, profile.hand, session.title, list(session.lines), path)
+
+
+# ── which glove, and what it starts from ─────────────────────────────────────
+
+def _pick(feed: Packets, device: Optional[str], listen_s: float, wait_s: float) -> str:
+    """The glove to calibrate: *device* once it is heard; with none named,
+    the only one heard by the time the first has sent for *listen_s* seconds
+    of its own clock."""
+    heard: Dict[str, int] = {}
+    started = time.monotonic()
+    for packet in feed:
+        if packet is not None:
+            first_ms = heard.setdefault(packet.device_id, packet.timestamp)
+            if packet.device_id == device:
+                return packet.device_id
+            if device is None and packet.device_id == next(iter(heard)) \
+                    and packet.timestamp - first_ms >= listen_s * 1000:
+                break
+        if time.monotonic() - started > wait_s:
+            break
+    sending = ", ".join(sorted(heard))
+    if device is not None:
+        raise PandoraError(f"{device} was not heard in {wait_s:g} s. "
+                           + (f"Sending now: {sending}." if heard else "No glove is sending."))
+    if not heard:
+        raise PandoraError(f"no glove is sending (waited {wait_s:g} s). Switch the glove on "
+                           "and keep it near the receiver.")
+    if len(heard) > 1:
+        raise PandoraError(f"more than one glove is sending ({sending}); "
+                           "say which with --device")
+    return next(iter(heard))
+
+
+def _starting_profile(folder: Path, device: str, hand: Optional[str], name: Optional[str],
+                      say: Callable[[str], None]) -> Profile:
+    """What the run starts from: the glove's profile in *folder* when it has
+    one for this hand, else an empty one. On the power-up Hall range either
+    way, so a calibration kept from another range is rescaled to it."""
+    try:
+        earlier = load_profiles(folder).get(device)
+    except (ValueError, TypeError, OSError) as unreadable:
+        raise PandoraError(f"a profile in {folder} cannot be read ({unreadable}). "
+                           "Move it away, or name another folder with --out.") from None
+    if earlier is not None and hand not in (None, earlier.hand):
+        say(f"{device} was calibrated as the {earlier.hand} hand; starting again as the "
+            f"{hand} hand.")
+        earlier = None
+    if earlier is None:
+        if hand is None:
+            raise PandoraError(f"{device} has no profile in {folder} yet: say which hand it "
+                               "is worn on with --hand left or --hand right")
+        earlier = Profile(hand)
+    return replace(earlier, range=HALL_DEFAULT_RANGE, sensor_ranges={},
+                   name=earlier.name if name is None else name)
+
+
+# ── the glove's packets ──────────────────────────────────────────────────────
+
+def _packets(link: Any) -> Packets:
+    """link_packets, with a port that fails reported as the SDK reports it."""
+    try:
+        yield from link_packets(link)
+    except OSError as failed:
+        raise Disconnected(link_failure(failed), link_failure_code(failed)) from failed
+
+
+def _from(feed: Packets, device: str, wait_s: float) -> Iterator[GlovePacket]:
+    """*device*'s packets out of *feed*, until it has sent none for *wait_s*
+    seconds."""
+    heard = time.monotonic()
+    for packet in feed:
+        if packet is not None and packet.device_id == device:
+            heard = time.monotonic()
+            yield packet
+        elif time.monotonic() - heard > wait_s:
+            raise PandoraError(f"{device} stopped sending: nothing from it for {wait_s:g} s. "
+                               "No profile was written.")
+
+
+def _settle(glove: Glove, packets: Iterator[GlovePacket], ready_s: float) -> None:
+    """Run *glove*'s pipeline for *ready_s* seconds of its own clock: time
+    for the wearer to get ready, for the sensors to settle on their range and
+    for the pipeline's filters to fill."""
+    if ready_s <= 0:
+        return
+    started_ms: Optional[int] = None
+    for packet in packets:
+        glove.push_decoded(packet)
+        started_ms = packet.timestamp if started_ms is None else started_ms
+        if packet.timestamp - started_ms >= ready_s * 1000:
+            return
+
+
+# ── what the person sees and feels ───────────────────────────────────────────
+
+class _Screen:
+    """calibrate_packets' watch: says each step when it starts, with a cue,
+    then a line for each second left, with the session's warning on it when
+    it has one. It is called for every packet; it speaks once a second."""
+
+    def __init__(self, say: Callable[[str], None], cue: Callable[[], None]) -> None:
+        self._say, self._cue = say, cue
+        self._step: Optional[Step] = None
+        self._left = 0
+
+    def __call__(self, session: CalibrationSession) -> None:
+        step = session.step
+        if step is None:
+            return
+        if step is not self._step:
+            self._step, self._left = step, 0
+            self._say("")
+            self._say(f"Step {session.index + 1} of {len(session.steps)}: {step.title}")
+            self._say(f"  {step.detail}")
+            self._cue()
+        left = math.ceil(session.remaining_s - 1e-6)
+        if left != self._left and left > 0:
+            self._left = left
+            warned = [text for good, text in session.prompt if not good]
+            self._say(f"  {left}" + (f"    ! {'; '.join(warned)}" if warned else ""))
+
+
+def _buzz(link: Any, device: str, ms: int) -> None:
+    amplitudes, durations = [0] * HAPTIC_MOTOR_COUNT, [0] * HAPTIC_MOTOR_COUNT
+    amplitudes[HAPTIC_BACKHAND_MOTOR], durations[HAPTIC_BACKHAND_MOTOR] = CUE_AMPLITUDE, ms
+    send_command(link, commands.haptic_rtp(device, amplitudes, durations))
+

pandora_sdk/cli.py

@@ -0,0 +1,246 @@
+"""The `pandora` command: look at hands, calibrate a glove and update
+firmware, without writing code.
+
+    pandora devices                      the gloves the app knows
+    pandora watch --hand right           hands as they arrive, ten a second
+    pandora watch --raw --rate 0         every raw packet
+    pandora watch --raw --cancelled      raw counts after earth-field cancellation
+    pandora calibrate --hand right       calibrate a glove with no app running
+    pandora watch --local                hands straight from the receiver
+    pandora update-firmware glove IMAGE  flash a glove (or the receiver)
+
+`devices` and `watch` read through the running app. `calibrate`,
+`watch --local` and `update-firmware` open the receiver themselves, so the app
+must not be running.
+"""
+from __future__ import annotations
+
+import argparse
+import io
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence, Set
+
+from pandora_core_rs.calibration_session import RUNS, Run
+from pandora_core_rs.protocol import DEFAULT_PORT, HANDS, Frame, ProtocolError, Raw
+
+from pandora_sdk import firmware
+from pandora_sdk.calibrate import calibrate
+from pandora_sdk.client import connect
+from pandora_sdk.local import (Local, default_profiles_dir, load_profiles, open_link,
+                               open_receiver)
+from pandora_sdk.source import PandoraError, Source
+
+# The hand `watch --local --raw` reads a glove with no profile as.
+UNPROFILED_HAND = "right"
+
+
+def _frame_line(hand: Frame) -> str:
+    curl = " ".join(f"{finger[0]:.2f}" for finger in hand.curl)
+    splay = " ".join(f"{value:+.2f}" for value in hand.splay)
+    wrist = "-" if hand.wrist_deg is None else " ".join(f"{a:.0f}" for a in hand.wrist_deg)
+    return (f"{hand.hand:<5}  {hand.device}  #{hand.seq}  curl {curl}  splay {splay}  "
+            f"wrist {wrist}")
+
+
+def _proximal(hall: Sequence[Sequence[Sequence[float]]]) -> str:
+    """Each finger's proximal sensor, x,y,z."""
+    return "  ".join(",".join(f"{axis:.0f}" for axis in finger[0]) for finger in hall)
+
+
+def _raw_line(reading: Raw, cancelled: bool = False) -> str:
+    if not cancelled:
+        counts = f"hall {_proximal(reading.hall)}"
+    elif reading.hall_cancelled is None:
+        counts = "cancelled -"
+    else:
+        what = "earth cancelled" if reading.earth_cancelled else "nothing cancelled"
+        counts = f"cancelled {_proximal(reading.hall_cancelled)}  {what}"
+    return (f"{reading.hand:<5}  {reading.device}  #{reading.seq}  {counts}  "
+            f"battery {reading.battery_pct}%")
+
+
+def _devices(gloves: Source) -> int:
+    for device in gloves.devices():
+        state = "connected" if device.connected else "silent"
+        print(f"{device.id}  {device.hand:<5}  {state}  {device.name}".rstrip())
+    return 0
+
+
+def _watch(gloves: Source, args: argparse.Namespace) -> int:
+    stream = "raw" if args.raw else "frames"
+    granted = gloves.subscribe(stream, devices=args.device, hands=args.hand or HANDS,
+                               rate_hz=args.rate, bones=False, cancelled=args.cancelled)
+    if args.cancelled and not granted.cancelled:
+        print("pandora: the app sends no cancelled counts (it is older than them)",
+              file=sys.stderr)
+    printed = 0
+    named: Set[str] = set()
+    while not args.count or printed < args.count:
+        try:
+            message = gloves.read(stream, timeout=1.0)
+        except TimeoutError:
+            message = None
+        if isinstance(gloves, Local):
+            for device in sorted(gloves.unprofiled - named):
+                named.add(device)
+                print(f"pandora: {_unprofiled(device, args)}. Make one with: pandora calibrate "
+                      f"--device {device} --hand left|right", file=sys.stderr)
+        if message is None:
+            continue
+        print(_raw_line(message, args.cancelled) if args.raw else _frame_line(message),
+              flush=True)
+        printed += 1
+    return 0
+
+
+def _unprofiled(device: str, args: argparse.Namespace) -> str:
+    """What `watch --local` does with a glove that has no profile."""
+    if not args.raw:
+        # Left out, which looks like silence.
+        return (f"{device} is sending but is left out of the frames: a frame needs the "
+                "glove's profile, and it has none (--raw shows its raw readings without one)")
+    return (f"{device} has no profile, so its raw readings are shown as the {UNPROFILED_HAND} "
+            "hand's (a packet does not say which hand it is)"
+            + (", with no cancelled counts" if args.cancelled else ""))
+
+
+def _local(args: argparse.Namespace) -> Local:
+    folder = args.profiles or default_profiles_dir()
+    profiles = load_profiles(folder)
+    if not profiles and not args.raw:
+        raise PandoraError(f"no profile in {folder}, and frames need one. Make one with: "
+                           "pandora calibrate --hand left|right, or watch raw readings, which "
+                           "need none, with --raw")
+    return open_receiver(profiles, port=args.receiver, default_hand=UNPROFILED_HAND)
+
+
+def _calibrate(args: argparse.Namespace) -> int:
+    link = open_link(args.receiver)
+    try:
+        outcome = calibrate(
+            link, hand=args.hand, device=args.device, out=args.out,
+            run=getattr(Run, args.run.upper()), hold_s=args.hold, ready_s=args.ready,
+            haptics=not args.no_haptics, name=args.name,
+            say=lambda text: print(text, flush=True))
+    except KeyboardInterrupt:
+        print("\nStopped. No profile was written.", flush=True)
+        return 1
+    finally:
+        link.close()
+    if outcome.path is not None:
+        where = "" if args.out is None else f" --profiles {args.out}"
+        print(f"Look at the hand with: pandora watch --local{where}", flush=True)
+    return 0 if outcome.ok else 1
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    app = argparse.ArgumentParser(add_help=False)
+    app.add_argument("--host", default="127.0.0.1")
+    app.add_argument("--port", type=int, default=DEFAULT_PORT)
+    app.add_argument("--timeout", type=float, default=5.0, help="seconds to wait for the app")
+    port = argparse.ArgumentParser(add_help=False)
+    port.add_argument("--receiver", metavar="PORT",
+                      help="the receiver's serial port (COM7, /dev/ttyACM0) when more than "
+                           "one is plugged in")
+
+    parser = argparse.ArgumentParser(
+        prog="pandora",
+        description="Look at the 01 Glove's hands, through the app or straight from the "
+                    "receiver, and calibrate a glove with no app.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("devices", parents=[app], help="list the gloves the app knows")
+
+    watch = commands.add_parser("watch", parents=[app, port],
+                                help="print hands as they arrive")
+    watch.add_argument("--raw", action="store_true",
+                       help="the gloves' raw readings instead of finished hands")
+    watch.add_argument("--cancelled", action="store_true",
+                       help="with --raw: each finger's counts after earth-field cancellation "
+                            "instead of as the glove sent them")
+    watch.add_argument("--hand", action="append", choices=HANDS, help="only this hand")
+    watch.add_argument("--device", action="append", help="only this glove id (repeatable)")
+    watch.add_argument("--rate", type=float, default=10.0,
+                       help="lines a second per glove at most; 0 is every message (default 10)")
+    watch.add_argument("--count", type=int, default=0, help="stop after this many lines")
+    watch.add_argument("--local", action="store_true",
+                       help="read the receiver itself, with no app, using the profiles "
+                            "`pandora calibrate` wrote (--raw needs none)")
+    watch.add_argument("--profiles", type=Path, metavar="DIR",
+                       help=f"with --local: the profiles folder (default "
+                            f"{default_profiles_dir()})")
+
+    cal = commands.add_parser(
+        "calibrate", parents=[port],
+        help="calibrate one glove read from the receiver and write its profile",
+        description="Calibrate one glove read straight from the receiver, with no app "
+                    "running, and write the profile open_receiver() and `pandora watch "
+                    "--local` need. Wear the glove and follow the steps as they are printed.")
+    cal.add_argument("--hand", choices=HANDS,
+                     help="the hand the glove is worn on; needed the first time, then taken "
+                          "from the glove's profile")
+    cal.add_argument("--device", help="the glove's id, when more than one is sending")
+    cal.add_argument("--run", choices=[run.name.lower() for run in RUNS], default="full",
+                     help="what to calibrate (default full: curl range, and the splay zero "
+                          "on a glove with finger IMUs)")
+    cal.add_argument("--hold", type=float, default=3.0,
+                     help="seconds each still pose is held (default 3)")
+    cal.add_argument("--ready", type=float, default=3.0,
+                     help="seconds before the first step (default 3)")
+    cal.add_argument("--out", type=Path, metavar="DIR",
+                     help=f"the profiles folder to write into (default {default_profiles_dir()})")
+    cal.add_argument("--name", help="a label for the glove, kept in its profile")
+    cal.add_argument("--no-haptics", action="store_true",
+                     help="no buzz on the back of the hand when a step starts")
+
+    flash = commands.add_parser(
+        "update-firmware", parents=[port],
+        help="update the receiver's or a glove's firmware over the air, with no app",
+        description="Flash a signed firmware image onto the receiver or onto a glove "
+                    "through it, with the app closed, and wait until the new image is "
+                    "confirmed. The same update as the app's Firmware tab. "
+                    "Asks before writing anything unless --yes is given.")
+    flash.add_argument("target", choices=list(firmware.TARGETS),
+                       help="what to update (dongle is the receiver)")
+    flash.add_argument("image", help="dfu_application.zip, a signed .bin, or a build folder "
+                                     "holding dfu_application.zip")
+    flash.add_argument("--device", help="the glove's id (default: the only glove sending)")
+    flash.add_argument("--yes", "-y", action="store_true",
+                       help="flash without asking first")
+    flash.add_argument("--verbose", action="store_true",
+                       help="also print every line the receiver sends")
+    args = parser.parse_args(argv)
+    if getattr(args, "cancelled", False) and not args.raw:
+        watch.error("--cancelled goes with --raw")
+
+    try:
+        if args.command == "calibrate":
+            return _calibrate(args)
+        if args.command == "update-firmware":
+            _speak_utf8()
+            return firmware.update_firmware(
+                args.target, args.image, port=args.receiver, device=args.device, yes=args.yes,
+                verbose=args.verbose, say=lambda text: print(text, flush=True))
+        if getattr(args, "local", False):
+            with _local(args) as gloves:
+                return _watch(gloves, args)
+        with connect(args.host, args.port, name="pandora-cli", timeout=args.timeout) as gloves:
+            return _devices(gloves) if args.command == "devices" else _watch(gloves, args)
+    except KeyboardInterrupt:
+        return 0
+    except (PandoraError, ProtocolError, TimeoutError) as failed:
+        print(f"pandora: {failed}", file=sys.stderr)
+        return 1
+
+
+def _speak_utf8() -> None:
+    """pandora-core-rs's firmware update prints emoji, from threads of its own,
+    which a Windows console's code page cannot always show: replace what it
+    cannot, rather than let the print fail."""
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+if __name__ == "__main__":
+    sys.exit(main())