microcmm 0.1.0__py3-none-any.whl

microcmm/__init__.py

@@ -0,0 +1,17 @@
+from .arm import Arm, NotHomedError, Pose, UnsupportedDeviceError
+from .device import MicroScribe
+from .hci import HCI, DeviceInfo, HCIError, HCITimeout, Maxes, Packet
+
+__all__ = [
+    "HCI",
+    "Arm",
+    "DeviceInfo",
+    "HCIError",
+    "HCITimeout",
+    "Maxes",
+    "MicroScribe",
+    "NotHomedError",
+    "Packet",
+    "Pose",
+    "UnsupportedDeviceError",
+]

microcmm/arm.py

@@ -0,0 +1,229 @@
+"""forward kinematics for the microscribe arm.
+
+transcribed from the 1996 immersion sdk's arm.c: the arm never computes xyz
+itself -- it reports raw encoder counts, and the host fetches the
+denavit-hartenberg parameters ("Format DH0.5") stored in the arm's eeprom
+and does the kinematics. joint 2 has a beta-corrected matrix (a mechanism
+in the standard sdk for all arms, not something unit-specific); beta is 0
+unless the arm's comment string contains "Beta", in which case
+GET_EXT_PARAMS supplies the value from eeprom.
+
+units are millimeters throughout (the eeprom stores thousandths of an inch;
+converted once at parameter load).
+
+homing: this arm calibrates by being in its exact home pose (stylus seated
+and vertical, counterweight pressed against the stylus holder) either at
+power-on or when HOME_POS is sent. the device cannot report whether that
+was done correctly, so this class refuses to compute positions until the
+caller has either called home() (arm physically in the home pose) or
+explicitly accepted responsibility via assume_homed().
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from .hci import HCI, DeviceInfo, HCIError, Maxes, Packet
+
+NUM_DOF = 6
+MM_PER_INCH = 25.4
+
+# the only hardware this library has ever been tested against.
+TESTED_PRODUCTS = {("MicroScribe3D", "D")}
+
+
+class NotHomedError(HCIError):
+    pass
+
+
+class UnsupportedDeviceError(HCIError):
+    pass
+
+
+@dataclass
+class Pose:
+    x: float
+    y: float
+    z: float
+    # stylus direction, XYZ_FIXED convention (arm_calc_stylus_dir), radians
+    roll: float
+    pitch: float
+    yaw: float
+    joints_rad: list[float]
+    buttons: int
+    encoders: list[int]
+
+
+class Arm:
+    """wraps an HCI session with the arm's calibration constants. mm."""
+
+    def __init__(self, hci: HCI):
+        self.hci = hci
+        self.info: DeviceInfo | None = None
+        self.maxes: Maxes | None = None
+        self.alpha = [0.0] * NUM_DOF
+        self.a = [0.0] * NUM_DOF
+        self.d = [0.0] * NUM_DOF
+        self.beta = 0.0
+        self.radians_factor = [0.0] * NUM_DOF
+        self._homed = False
+
+    def initialize(self, allow_untested_models: bool = False) -> None:
+        """fetch strings, maxes and DH params (arm_get_constants)."""
+        if self.hci.product_id and "MSCR" not in self.hci.product_id:
+            # the sdk manual says to check this: other immersion devices
+            # share the same handshake
+            raise UnsupportedDeviceError(
+                f"device identifies as {self.hci.product_id!r}, not a "
+                "microscribe ('MSCR')"
+            )
+        self.info = self.hci.get_info()
+
+        key = (self.info.product_name, self.info.model_name)
+        if key not in TESTED_PRODUCTS and not allow_untested_models:
+            raise UnsupportedDeviceError(
+                f"device reports product {self.info.product_name!r} model "
+                f"{self.info.model_name!r}; this library has only been tested "
+                f"against {sorted(TESTED_PRODUCTS)}. pass "
+                "allow_untested_models=True to try anyway, and please report "
+                "the result."
+            )
+
+        self.maxes = self.hci.get_maxes()
+        self.radians_factor = [2.0 * math.pi / (m + 1) for m in self.maxes.max_encoder]
+
+        if self.info.param_format != "Format DH0.5":
+            raise UnsupportedDeviceError(
+                f"unsupported parameter format {self.info.param_format!r} "
+                "(only 'Format DH0.5' is implemented)"
+            )
+        block = self.hci.get_params()
+        if len(block) != 36:
+            raise HCIError(f"GET_PARAMS returned {len(block)} bytes, expected 36")
+        self._convert_params(block)
+
+        if "Beta" in self.info.comment:
+            ext = self.hci.get_ext_params()
+            if len(ext) >= 2:
+                raw = _int16(ext[0], ext[1])
+                self.beta = raw / 32768.0 * math.pi
+
+    def _convert_params(self, pb: bytes) -> None:
+        # arm_params_DH0_5: 6 x alpha, 6 x A, 6 x D as signed int16 BE.
+        # alpha in raw/32768*pi radians; A and D in thousandths of an inch.
+        for i in range(6):
+            self.alpha[i] = _int16(pb[2 * i], pb[2 * i + 1]) / 32768.0 * math.pi
+        for i in range(6):
+            j = 12 + 2 * i
+            self.a[i] = _int16(pb[j], pb[j + 1]) / 1000.0 * MM_PER_INCH
+        for i in range(6):
+            j = 24 + 2 * i
+            self.d[i] = _int16(pb[j], pb[j + 1]) / 1000.0 * MM_PER_INCH
+
+    # ----- homing -----
+
+    @property
+    def homed(self) -> bool:
+        return self._homed
+
+    def home(self) -> None:
+        """re-zero the arm. the arm MUST physically be in its home pose:
+        stylus seated in the holder and vertical, counterweight pressed up
+        against the bottom of the stylus holder."""
+        self.hci.go_home_pos()
+        self._homed = True
+
+    def assume_homed(self) -> None:
+        """declare that the arm is already homed (it was powered on while in
+        its home pose, or home() was run earlier this power cycle)."""
+        self._homed = True
+
+    def _require_homed(self) -> None:
+        if not self._homed:
+            raise NotHomedError(
+                "arm not homed: positions would be garbage. put the arm in "
+                "its home pose and call home(), or call assume_homed() if it "
+                "was powered on in the home pose."
+            )
+
+    # ----- sampling -----
+
+    def joints_rad(self, packet: Packet) -> list[float]:
+        self._require_homed()
+        assert self.maxes is not None
+        out = []
+        for i in range(min(NUM_DOF, len(packet.encoders))):
+            # counts keep increasing past one revolution ("winding number");
+            # the mask assumes max_encoder+1 is a power of two, true for all
+            # values seen on real hardware (16384/8192/4096 cpr)
+            count = packet.encoders[i] & self.maxes.max_encoder[i]
+            out.append(self.radians_factor[i] * count)
+        while len(out) < NUM_DOF:
+            out.append(0.0)
+        return out
+
+    def pose(self, packet: Packet) -> Pose:
+        joints = self.joints_rad(packet)
+        t = self._calc_t(joints)
+        # XYZ_FIXED / ZYX_EULER stylus direction (arm_calc_stylus_dir)
+        roll = math.atan2(t[2][1], t[2][2])
+        pitch = math.atan2(-t[2][0], math.hypot(t[0][0], t[1][0]))
+        yaw = math.atan2(t[1][0], t[0][0])
+        return Pose(
+            x=t[0][3],
+            y=t[1][3],
+            z=t[2][3],
+            roll=roll,
+            pitch=pitch,
+            yaw=yaw,
+            joints_rad=joints,
+            buttons=packet.buttons,
+            encoders=packet.encoders,
+        )
+
+    def sample_pose(self, timer: bool = False) -> Pose:
+        self._require_homed()
+        return self.pose(self.hci.sample(encoders=6, timer=timer))
+
+    # ----- kinematics (arm_calc_M / arm_calc_T) -----
+
+    def _calc_m(self, i: int, theta: float) -> list[list[float]]:
+        c, s = math.cos(theta), math.sin(theta)
+        ca, sa = math.cos(self.alpha[i]), math.sin(self.alpha[i])
+        a, d = self.a[i], self.d[i]
+        if i != 2:
+            return [
+                [c, -s, 0.0, a],
+                [s * ca, c * ca, -sa, -sa * d],
+                [s * sa, c * sa, ca, ca * d],
+                [0.0, 0.0, 0.0, 1.0],
+            ]
+        cb, sb = math.cos(self.beta), math.sin(self.beta)
+        return [
+            [c * cb, -s * cb, sb, sb * d + a],
+            [s * ca + sa * sb * c, c * ca - sa * sb * s, -sa * cb, -sa * cb * d],
+            [s * sa - ca * sb * c, c * sa + s * sb * ca, ca * cb, cb * ca * d],
+            [0.0, 0.0, 0.0, 1.0],
+        ]
+
+    def _calc_t(self, joints: list[float]) -> list[list[float]]:
+        t = self._calc_m(0, joints[0])
+        for i in range(1, NUM_DOF):
+            t = _mul_4x4(t, self._calc_m(i, joints[i]))
+        return t
+
+
+def _int16(hi: int, lo: int) -> int:
+    v = (hi << 8) | lo
+    return v - 0x10000 if v >= 0x8000 else v
+
+
+def _mul_4x4(m1: list[list[float]], m2: list[list[float]]) -> list[list[float]]:
+    out = [[0.0] * 4 for _ in range(4)]
+    for r in range(3):
+        for c in range(4):
+            out[r][c] = m1[r][0] * m2[0][c] + m1[r][1] * m2[1][c] + m1[r][2] * m2[2][c]
+        out[r][3] += m1[r][3]
+    out[3][3] = 1.0
+    return out

microcmm/cli.py

@@ -0,0 +1,288 @@
+"""cli for the microscribe digitizer arm. all lengths in mm."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import csv
+import glob
+import math
+import select
+import sys
+import termios
+import time
+import tty
+from collections.abc import Iterator
+from typing import Any, Protocol
+
+from .arm import Pose
+from .device import MicroScribe
+from .hci import HCIError
+
+HOME_POSE_HELP = (
+    "home pose: stylus seated in its holder and vertical, counterweight "
+    "pressed up against the bottom of the stylus holder (user guide fig 9)"
+)
+
+
+class _RowWriter(Protocol):
+    def writerow(self, row: list[Any]) -> Any: ...
+
+
+def find_port(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    candidates = sorted(glob.glob("/dev/cu.usbserial*"))
+    if not candidates:
+        sys.exit("no /dev/cu.usbserial* port found; pass --port")
+    if len(candidates) > 1:
+        sys.exit(f"multiple serial ports found, pass --port: {candidates}")
+    return candidates[0]
+
+
+def open_device(args: argparse.Namespace) -> MicroScribe:
+    port = find_port(args.port)
+    ms = MicroScribe(port, baud=args.baud, debug=args.debug, timeout=args.timeout)
+    ms.connect()
+    return ms
+
+
+def _assume_homed(ms: MicroScribe) -> None:
+    print(
+        "note: assuming the arm is homed (powered on in its home pose, or "
+        "`microcmm home` run this power cycle). if positions look wrong, "
+        "re-home."
+    )
+    ms.assume_homed()
+
+
+def fmt_pose(pose: Pose, joints: bool = False) -> str:
+    s = f"{pose.x:9.3f} {pose.y:9.3f} {pose.z:9.3f}"
+    s += (
+        f"   rpy {math.degrees(pose.roll):7.2f} "
+        f"{math.degrees(pose.pitch):7.2f} {math.degrees(pose.yaw):7.2f}"
+    )
+    if joints:
+        s += "   j " + " ".join(f"{math.degrees(j):7.2f}" for j in pose.joints_rad)
+    return s
+
+
+def cmd_ports(_args: argparse.Namespace) -> None:
+    for p in sorted(glob.glob("/dev/cu.*")):
+        print(p)
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    ms = open_device(args)
+    try:
+        for name, val in ms.info.fields.items():
+            print(f"{name:14s} {val}")
+        print(f"{'max encoder':14s} {ms.maxes.max_encoder}")
+        arm = ms.arm
+        print(
+            f"{'alpha (deg)':14s} "
+            + " ".join(f"{math.degrees(v):8.3f}" for v in arm.alpha)
+        )
+        print(f"{'a (mm)':14s} " + " ".join(f"{v:8.3f}" for v in arm.a))
+        print(f"{'d (mm)':14s} " + " ".join(f"{v:8.3f}" for v in arm.d))
+        print(f"{'beta (deg)':14s} {math.degrees(arm.beta):.4f}")
+    finally:
+        ms.disconnect()
+
+
+def cmd_home(args: argparse.Namespace) -> None:
+    print(f"{HOME_POSE_HELP}.")
+    print("hold it there, then press enter (ctrl-c to abort)")
+    input()
+    ms = open_device(args)
+    try:
+        ms.home()
+        print("home position set (until the arm is next power cycled)")
+    finally:
+        ms.disconnect()
+
+
+def cmd_point(args: argparse.Namespace) -> None:
+    ms = open_device(args)
+    try:
+        _assume_homed(ms)
+        pose = ms.pose()
+        if args.raw:
+            print(f"buttons {pose.buttons:#04x}  encoders {pose.encoders}")
+        print(fmt_pose(pose, joints=args.joints))
+    finally:
+        ms.disconnect()
+
+
+def cmd_stream(args: argparse.Namespace) -> None:
+    ms = open_device(args)
+    period = 1.0 / args.hz
+    try:
+        _assume_homed(ms)
+        while True:
+            t0 = time.monotonic()
+            print(fmt_pose(ms.pose(), joints=args.joints), flush=True)
+            dt = period - (time.monotonic() - t0)
+            if dt > 0:
+                time.sleep(dt)
+    except KeyboardInterrupt:
+        print()
+    finally:
+        ms.disconnect()
+
+
+def _capture_events(hz: float, ms: MicroScribe) -> Iterator[Pose]:
+    """poll the arm, yielding a pose each time the user presses space or
+    enter. 'q' or ctrl-c ends the stream."""
+    print("space or enter: capture point. q: quit.")
+    stdin_fd = None
+    old_attrs = None
+    if sys.stdin.isatty():
+        stdin_fd = sys.stdin.fileno()
+        old_attrs = termios.tcgetattr(stdin_fd)
+        tty.setcbreak(stdin_fd)
+    try:
+        while True:
+            pose = ms.pose()
+            keys = ""
+            if stdin_fd is not None:
+                while select.select([sys.stdin], [], [], 0)[0]:
+                    keys += sys.stdin.read(1)
+            for _ in range(sum(1 for k in keys if k in (" ", "\n", "\r"))):
+                yield pose
+            if "q" in keys:
+                return
+            time.sleep(1.0 / hz)
+    except KeyboardInterrupt:
+        print()
+    finally:
+        if stdin_fd is not None and old_attrs is not None:
+            termios.tcsetattr(stdin_fd, termios.TCSADRAIN, old_attrs)
+
+
+def cmd_capture(args: argparse.Namespace) -> None:
+    ms = open_device(args)
+    _assume_homed(ms)
+    with contextlib.ExitStack() as stack:
+        writer: _RowWriter | None = None
+        if args.output:
+            outfile = stack.enter_context(open(args.output, "w", newline=""))
+            writer = csv.writer(outfile)
+            writer.writerow(
+                ["n", "x", "y", "z", "roll_deg", "pitch_deg", "yaw_deg"]
+                + [f"j{i}_deg" for i in range(6)]
+                + [f"enc{i}" for i in range(6)]
+            )
+        n = 0
+        try:
+            for pose in _capture_events(args.hz, ms):
+                n += 1
+                print(f"{n:4d}  {fmt_pose(pose, joints=args.joints)}")
+                if writer:
+                    writer.writerow(
+                        [
+                            n,
+                            f"{pose.x:.4f}",
+                            f"{pose.y:.4f}",
+                            f"{pose.z:.4f}",
+                            f"{math.degrees(pose.roll):.3f}",
+                            f"{math.degrees(pose.pitch):.3f}",
+                            f"{math.degrees(pose.yaw):.3f}",
+                        ]
+                        + [f"{math.degrees(j):.4f}" for j in pose.joints_rad]
+                        + [str(e) for e in pose.encoders]
+                    )
+        finally:
+            ms.disconnect()
+            if writer:
+                print(f"{n} points written to {args.output}")
+
+
+def cmd_dist(args: argparse.Namespace) -> None:
+    ms = open_device(args)
+    _assume_homed(ms)
+    print(
+        "measure point pairs: capture A, then B -> distance."
+        " repeat pairs (same divots, different arm poses) for stats."
+    )
+    pending: Pose | None = None
+    dists: list[float] = []
+    try:
+        for pose in _capture_events(args.hz, ms):
+            if pending is None:
+                pending = pose
+                print(f"  A  {pose.x:9.3f} {pose.y:9.3f} {pose.z:9.3f}")
+            else:
+                dx = pose.x - pending.x
+                dy = pose.y - pending.y
+                dz = pose.z - pending.z
+                d = math.sqrt(dx * dx + dy * dy + dz * dz)
+                dists.append(d)
+                print(f"  B  {pose.x:9.3f} {pose.y:9.3f} {pose.z:9.3f}")
+                print(f"  -> {d:9.3f} mm   (dx {dx:8.3f}  dy {dy:8.3f}  dz {dz:8.3f})")
+                pending = None
+    finally:
+        ms.disconnect()
+        if len(dists) > 1:
+            mean = sum(dists) / len(dists)
+            spread = max(dists) - min(dists)
+            rms = math.sqrt(sum((d - mean) ** 2 for d in dists) / len(dists))
+            print(
+                f"{len(dists)} pairs: mean {mean:.3f} mm, "
+                f"spread {spread:.3f}, rms dev {rms:.3f}"
+            )
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="microcmm",
+        description="read positions from a microscribe-3d digitizer arm (mm)",
+    )
+    ap.add_argument(
+        "--port", help="serial device (default: the single /dev/cu.usbserial*)"
+    )
+    ap.add_argument("--baud", type=int, default=115200)
+    ap.add_argument(
+        "--timeout", type=float, default=5.0, help="handshake timeout seconds"
+    )
+    ap.add_argument("--debug", action="store_true", help="hex-dump serial i/o")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("ports", help="list serial ports")
+    sub.add_parser("info", help="identify the arm and dump its calibration")
+    sub.add_parser("home", help=f"set home position ({HOME_POSE_HELP})")
+
+    p = sub.add_parser("point", help="read one stylus position")
+    p.add_argument("--joints", action="store_true", help="also print joint angles")
+    p.add_argument("--raw", action="store_true", help="also print raw encoders")
+
+    p = sub.add_parser("stream", help="continuously print stylus position")
+    p.add_argument("--hz", type=float, default=20.0)
+    p.add_argument("--joints", action="store_true")
+
+    p = sub.add_parser("capture", help="capture points on keypress")
+    p.add_argument("-o", "--output", help="write points to a csv file")
+    p.add_argument("--hz", type=float, default=60.0, help="poll rate")
+    p.add_argument("--joints", action="store_true")
+
+    p = sub.add_parser("dist", help="measure distance between captured point pairs")
+    p.add_argument("--hz", type=float, default=60.0, help="poll rate")
+
+    args = ap.parse_args()
+    handlers = {
+        "ports": cmd_ports,
+        "info": cmd_info,
+        "home": cmd_home,
+        "point": cmd_point,
+        "stream": cmd_stream,
+        "capture": cmd_capture,
+        "dist": cmd_dist,
+    }
+    try:
+        handlers[args.command](args)
+    except HCIError as e:
+        sys.exit(f"error: {e}")
+
+
+if __name__ == "__main__":
+    main()

microcmm/device.py

@@ -0,0 +1,100 @@
+"""high-level entry point.
+
+from microcmm import MicroScribe
+
+with MicroScribe("/dev/cu.usbserial-XXXX") as ms:
+    # you should be homing right now: arm in its home pose (stylus seated
+    # in the holder and vertical, counterweight against the stylus holder)
+    ms.home()
+    # (advanced: ms.assume_homed() instead, if the arm is already homed
+    # this power cycle and you know it)
+    print(ms.info.serial_number)
+    p = ms.pose()
+    print(p.x, p.y, p.z)       # mm
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Self
+
+import serial
+
+from .arm import Arm, Pose
+from .hci import HCI, DeviceInfo, Maxes
+
+
+class MicroScribe:
+    def __init__(
+        self,
+        port: str | serial.SerialBase,
+        baud: int = 115200,
+        debug: bool = False,
+        allow_untested_models: bool = False,
+        timeout: float = 5.0,
+    ):
+        self._hci = HCI(port, baud=baud, debug=debug)
+        self._arm = Arm(self._hci)
+        self._allow_untested = allow_untested_models
+        self._timeout = timeout
+
+    def connect(self) -> DeviceInfo:
+        self._hci.connect(timeout=self._timeout)
+        self._arm.initialize(allow_untested_models=self._allow_untested)
+        assert self._arm.info is not None
+        return self._arm.info
+
+    def disconnect(self) -> None:
+        self._hci.disconnect()
+
+    def __enter__(self) -> Self:
+        self.connect()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.disconnect()
+
+    # ----- homing -----
+
+    def home(self) -> None:
+        """re-zero. the arm must physically be in its home pose (stylus
+        seated and vertical, counterweight against the stylus holder)."""
+        self._arm.home()
+
+    def assume_homed(self) -> None:
+        self._arm.assume_homed()
+
+    @property
+    def homed(self) -> bool:
+        return self._arm.homed
+
+    # ----- data -----
+
+    @property
+    def info(self) -> DeviceInfo:
+        assert self._arm.info is not None, "not connected"
+        return self._arm.info
+
+    @property
+    def maxes(self) -> Maxes:
+        assert self._arm.maxes is not None, "not connected"
+        return self._arm.maxes
+
+    @property
+    def arm(self) -> Arm:
+        """the underlying kinematics layer (dh parameters etc.)."""
+        return self._arm
+
+    @property
+    def hci(self) -> HCI:
+        """the underlying protocol layer."""
+        return self._hci
+
+    def pose(self) -> Pose:
+        """one stylus pose: x/y/z in mm, roll/pitch/yaw in radians."""
+        return self._arm.sample_pose()

microcmm/hci.py

@@ -0,0 +1,386 @@
+"""immersion hci serial protocol for microscribe digitizer arms.
+
+transcribed from the original immersion sdk (reference/original-sdk/HCI.C,
+HCI.H, SDK1-2a, 1996). the arm autobauds: host repeats "IMMC" until the
+device echoes it back, host flushes, sends "BEGIN", device replies with a
+null-terminated product id string. after that it's a binary request/response
+protocol: host sends one command byte, device echoes it with bit7 set,
+followed by a fixed-size payload.
+
+standard (non-config) packets carry 7-bit payload bytes; only the echoed
+command byte has bit7 set, which is the resync mechanism. config command
+payloads (0xC0+) are plain 8-bit.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+import serial
+
+SIGNON = b"IMMC"
+BEGIN = b"BEGIN"
+
+# config commands (HCI.H)
+GET_PARAMS = 0xC0
+GET_HOME_REF = 0xC1
+HOME_POS = 0xC2
+SET_HOME = 0xC3
+SET_BAUD = 0xC4
+END_SESSION = 0xC5
+GET_MAXES = 0xC6
+SET_PARAMS = 0xC7
+GET_PROD_NAME = 0xC8
+GET_PROD_ID = 0xC9
+GET_MODEL_NAME = 0xCA
+GET_SERNUM = 0xCB
+GET_COMMENT = 0xCC
+GET_PRM_FORMAT = 0xCD
+GET_VERSION = 0xCE
+REPORT_MOTION = 0xCF
+SET_HOME_REF = 0xD0
+RESTORE_FACTORY = 0xD1
+INSERT_MARKER = 0xD2
+GET_EXT_PARAMS = 0xD3
+
+# standard command byte bits (HCI.H)
+TIMER_BIT = 0x20
+# bits1-0 select encoder count: 01 = 5 encoders, 10 = 7, 11 = 6
+_ENCODER_BITS = {0: 0x00, 5: 0x01, 6: 0x03, 7: 0x02}
+
+SIGNON_PAUSE = 0.015  # SIGNON_PAUSE in HCI.H
+END_PAUSE = 0.015
+
+
+class HCIError(Exception):
+    pass
+
+
+class HCITimeout(HCIError):
+    pass
+
+
+@dataclass
+class Packet:
+    # buttons is the raw pedal/button state byte from the arm. per the sdk,
+    # bit0 = single/right pedal, bit1 = left pedal. left as raw data here
+    # because we have no pedal hardware to test the semantics against.
+    buttons: int
+    encoders: list[int]
+    timer: int | None = None
+
+
+@dataclass
+class Maxes:
+    buttons_supported: int
+    max_timer: int
+    max_analog: list[int]
+    max_encoder: list[int]  # 6 values; pulses/rev - 1
+
+
+@dataclass
+class DeviceInfo:
+    product_name: str = ""
+    product_id: str = ""
+    model_name: str = ""
+    serial_number: str = ""
+    comment: str = ""
+    param_format: str = ""
+    version: str = ""
+    fields: dict[str, str] = field(default_factory=dict)
+
+
+class HCI:
+    """low-level protocol session.
+
+    port is a serial device path (e.g. /dev/cu.usbserial-XXXX). an already-
+    opened pyserial-compatible object may be passed instead, mainly for tests.
+    """
+
+    def __init__(
+        self,
+        port: str | serial.SerialBase,
+        baud: int = 115200,
+        debug: bool = False,
+    ):
+        self.port_name = port if isinstance(port, str) else ""
+        self._injected = None if isinstance(port, str) else port
+        self.baud = baud
+        self.debug = debug
+        self.ser: serial.SerialBase | None = None
+        self.product_id = ""
+
+    # ----- transport -----
+
+    def _log(self, msg: str) -> None:
+        if self.debug:
+            print(f"[hci] {msg}")
+
+    def _write(self, data: bytes) -> None:
+        assert self.ser is not None
+        self._log(f"tx {data.hex(' ')}")
+        self.ser.write(data)
+
+    def _read_exact(self, n: int, timeout: float) -> bytes:
+        assert self.ser is not None
+        self.ser.timeout = timeout
+        data = self.ser.read(n)
+        self._log(f"rx {data.hex(' ')}")
+        if len(data) != n:
+            raise HCITimeout(f"wanted {n} bytes, got {len(data)}")
+        return bytes(data)
+
+    def _drain(self, quiet: float = 0.05) -> bytes:
+        """read and discard until the line is quiet for `quiet` seconds."""
+        assert self.ser is not None
+        self.ser.timeout = quiet
+        drained = b""
+        while True:
+            b = self.ser.read(1)
+            if not b:
+                break
+            drained += b
+        if drained:
+            self._log(f"drained {drained.hex(' ')}")
+        return drained
+
+    # ----- session -----
+
+    def connect(self, timeout: float = 5.0) -> str:
+        """autobaud handshake (hci_autosynch + hci_begin). returns product id."""
+        if self._injected is not None:
+            self.ser = self._injected
+        else:
+            self.ser = serial.Serial(
+                self.port_name,
+                self.baud,
+                bytesize=serial.EIGHTBITS,
+                parity=serial.PARITY_NONE,
+                stopbits=serial.STOPBITS_ONE,
+                timeout=0.05,
+            )
+        self.ser.reset_input_buffer()
+
+        deadline = time.monotonic() + timeout
+        match = 0
+        signed_on = False
+        while not signed_on and time.monotonic() < deadline:
+            # END_SESSION first so a previously-live session re-enters autobaud
+            self._write(bytes([END_SESSION]) + SIGNON)
+            time.sleep(SIGNON_PAUSE)
+            self.ser.timeout = 0
+            while True:
+                b = self.ser.read(1)
+                if not b:
+                    break
+                if b[0] == SIGNON[match]:
+                    match += 1
+                    if match == len(SIGNON):
+                        signed_on = True
+                        break
+                else:
+                    match = 1 if b[0] == SIGNON[0] else 0
+        if not signed_on:
+            self.ser.close()
+            self.ser = None
+            raise HCITimeout(
+                f"no IMMC echo from {self.port_name} at {self.baud} baud "
+                f"within {timeout:.1f}s (is the arm powered on?)"
+            )
+        # discard leftover signon echoes still in flight, then begin
+        self._drain(quiet=0.1)
+        self._write(BEGIN)
+        self.product_id = self._read_string(timeout=1.0)
+        return self.product_id
+
+    def end(self) -> None:
+        if self.ser is not None:
+            self._write(bytes([END_SESSION]))
+            time.sleep(END_PAUSE)
+
+    def disconnect(self) -> None:
+        if self.ser is not None:
+            try:
+                self._drain(quiet=0.02)
+                self.end()
+            finally:
+                self.ser.close()
+                self.ser = None
+
+    # ----- low-level helpers -----
+
+    def _read_string(self, timeout: float = 1.0) -> str:
+        """read a null-terminated ascii string."""
+        assert self.ser is not None
+        deadline = time.monotonic() + timeout
+        out = bytearray()
+        self.ser.timeout = 0.05
+        while time.monotonic() < deadline:
+            b = self.ser.read(1)
+            if not b:
+                continue
+            if b[0] == 0:
+                s = out.decode("ascii", errors="replace")
+                self._log(f"rx string {s!r}")
+                return s
+            out += b
+        raise HCITimeout(f"string read timed out (got {bytes(out)!r})")
+
+    def _wait_echo(self, cmd: int, timeout: float = 1.0) -> None:
+        """discard bytes until the echoed command byte arrives."""
+        assert self.ser is not None
+        deadline = time.monotonic() + timeout
+        self.ser.timeout = 0.05
+        while time.monotonic() < deadline:
+            b = self.ser.read(1)
+            if b:
+                if b[0] == cmd:
+                    return
+                self._log(f"discard {b.hex()} (waiting for {cmd:02x})")
+        raise HCITimeout(f"no echo for command {cmd:02x}")
+
+    # ----- config commands -----
+
+    def get_string(self, cmd: int) -> str:
+        self._write(bytes([cmd]))
+        self._wait_echo(cmd)
+        return self._read_string()
+
+    def get_info(self) -> DeviceInfo:
+        info = DeviceInfo()
+        for name, cmd in [
+            ("product_name", GET_PROD_NAME),
+            ("product_id", GET_PROD_ID),
+            ("model_name", GET_MODEL_NAME),
+            ("serial_number", GET_SERNUM),
+            ("comment", GET_COMMENT),
+            ("param_format", GET_PRM_FORMAT),
+            ("version", GET_VERSION),
+        ]:
+            val = self.get_string(cmd)
+            setattr(info, name, val)
+            info.fields[name] = val
+        return info
+
+    def get_maxes(self) -> Maxes:
+        """GET_MAXES: 24 payload bytes.
+
+        note: the sdk's parser reads 7 encoder maxes (26 bytes) from a
+        24-byte buffer -- the 7th overruns. on the wire it is 24 bytes,
+        i.e. 6 encoder maxes, which is what we parse.
+        """
+        self._write(bytes([GET_MAXES]))
+        self._wait_echo(GET_MAXES)
+        d = self._read_exact(24, timeout=1.0)
+        max_analog = [d[3 + i] << 1 for i in range(8)]
+        extra = d[11]
+        for i in range(7):
+            max_analog[i] |= 1 if extra & (0x40 >> i) else 0
+        max_encoder = [(d[12 + 2 * i] << 8) | d[13 + 2 * i] for i in range(6)]
+        return Maxes(
+            buttons_supported=d[0],
+            max_timer=(d[1] << 8) | d[2],
+            max_analog=max_analog,
+            max_encoder=max_encoder,
+        )
+
+    def get_params(self) -> bytes:
+        """GET_PARAMS: echo, then a length byte, then that many bytes."""
+        self._write(bytes([GET_PARAMS]))
+        self._wait_echo(GET_PARAMS)
+        n = self._read_exact(1, timeout=2.0)[0]
+        return self._read_exact(n, timeout=2.0)
+
+    def get_ext_params(self) -> bytes:
+        """GET_EXT_PARAMS (only valid if the comment string contains "Beta")."""
+        self._write(bytes([GET_EXT_PARAMS]))
+        self._wait_echo(GET_EXT_PARAMS)
+        n = self._read_exact(1, timeout=2.0)[0]
+        return self._read_exact(n, timeout=2.0)
+
+    def go_home_pos(self) -> None:
+        """HOME_POS: re-zero angle registers. stylus MUST be in its cradle."""
+        self._write(bytes([HOME_POS]))
+        self._wait_echo(HOME_POS)
+
+    # ----- standard sampling -----
+
+    def sample(
+        self, encoders: int = 6, timer: bool = False, timeout: float = 1.0
+    ) -> Packet:
+        """send one standard command and read the response packet."""
+        cmd = _ENCODER_BITS[encoders] | (TIMER_BIT if timer else 0)
+        self._write(bytes([cmd]))
+        return self.read_packet(cmd, timeout=timeout)
+
+    def read_packet(self, cmd: int, timeout: float = 1.0) -> Packet:
+        """read one standard response packet for command byte `cmd`."""
+        assert self.ser is not None
+        echo = cmd | 0x80
+        deadline = time.monotonic() + timeout
+        self.ser.timeout = 0.05
+        while time.monotonic() < deadline:
+            b = self.ser.read(1)
+            if not b:
+                continue
+            if b[0] == echo:
+                break
+            self._log(f"discard {b.hex()} (waiting for {echo:02x})")
+        else:
+            raise HCITimeout(f"no response packet (cmd {cmd:02x})")
+
+        n_enc = {0x01: 5, 0x03: 6, 0x02: 7}.get(cmd & 0x03, 0)
+        size = 1 + (2 if cmd & TIMER_BIT else 0) + 2 * n_enc
+        d = self._read_exact(size, timeout=timeout)
+        if any(b & 0x80 for b in d):
+            # only the header byte of a standard packet may have bit 7 set;
+            # a set bit inside the payload means corruption (doc ch. 4)
+            self._drain()
+            raise HCIError("corrupt packet (bit 7 set in payload byte)")
+        pos = 0
+        buttons = d[pos]
+        pos += 1
+        tm = None
+        if cmd & TIMER_BIT:
+            tm = (d[pos] << 7) | d[pos + 1]
+            pos += 2
+        enc = []
+        for _ in range(n_enc):
+            enc.append((d[pos] << 7) | d[pos + 1])
+            pos += 2
+        return Packet(buttons=buttons, encoders=enc, timer=tm)
+
+    def start_motion(
+        self,
+        encoders: int = 6,
+        timer: bool = False,
+        delay_ms: int = 0,
+        active_buttons: int = 0,
+        encoder_deltas: list[int] | None = None,
+    ) -> int:
+        """REPORT_MOTION: arm streams packets on its own. returns the std
+        command byte whose echoes to expect. cancel with end_motion()."""
+        if encoders > 6:
+            raise ValueError("start_motion supports up to 6 encoders")
+        cmd = _ENCODER_BITS[encoders] | (TIMER_BIT if timer else 0)
+        deltas = encoder_deltas or [0] * 6
+        msg = bytearray(
+            [
+                REPORT_MOTION,
+                (delay_ms >> 8) & 0xFF,
+                delay_ms & 0xFF,
+                cmd,
+                active_buttons,
+            ]
+        )
+        msg += bytes(8)  # analog deltas, unused
+        for dlt in deltas[:6]:
+            msg += bytes([(dlt >> 8) & 0xFF, dlt & 0xFF])
+        self._write(bytes(msg))
+        return cmd
+
+    def end_motion(self) -> None:
+        self._write(bytes([0x00]))
+        time.sleep(0.05)
+        self._drain()

microcmm-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: microcmm
+Version: 0.1.0
+Summary: Python library + CLI for MicroScribe-3D digitizer arms (RS-232, no Windows DLL)
+Project-URL: Repository, https://github.com/Revise-Robotics/microcmm
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pyserial>=3.5
+Description-Content-Type: text/markdown
+
+# microcmm
+
+Python library + CLI for reading positions from a MicroScribe-3D digitizer arm
+over its RS-232 serial port. Speaks the Immersion HCI protocol directly (no
+Windows DLL) and does the forward kinematics on the host using the arm's own
+EEPROM calibration. Millimeters everywhere.
+
+## Install
+
+```
+pip install microcmm
+# or
+uv add microcmm
+```
+
+## Usage
+
+```python
+from microcmm import MicroScribe
+
+with MicroScribe("/dev/cu.usbserial-XXXX") as ms:
+    # You should be homing right now: arm in its home pose (stylus seated
+    # in the holder and vertical, counterweight against the stylus holder).
+    ms.home()
+    # (Advanced: ms.assume_homed() if the arm is already homed this power cycle.)
+    print(ms.info.serial_number)
+    p = ms.pose()
+    print(p.x, p.y, p.z)
+```
+
+## CLI
+
+```
+microcmm <command>
+```
+
+- `info` - identify the arm, dump its calibration constants
+- `point` - read one stylus position
+- `stream` - continuously print positions
+- `capture -o points.csv` - capture points on keypress, write CSV
+- `dist` - measure distances between captured point pairs
+- `home` - set the home position (arm must be in its home pose)
+- `ports` - list serial ports
+
+## Notes
+
+- **Homing is mandatory.** The arm only reads correctly if it was in its home
+  pose (stylus seated in the holder and vertical, counterweight pressed
+  against the bottom of the stylus holder) at power-on or when `home` was
+  sent. This is lost at every power cycle. The library refuses to return
+  positions until you call `home()` or explicitly `assume_homed()` - an
+  unhomed arm produces garbage that looks plausible.
+- **Only tested on a MicroScribe-3D model D (5-DOF).** The library refuses
+  other models by precaution, not because they can't work - if you have one,
+  run with `allow_untested_models=True` and report back, we'll add it.
+- **Pedals are not implemented** because we don't have one. The raw button
+  byte is exposed on every packet if you want to try.
+- 5-DOF arms have no roll about the stylus axis; the reported orientation
+  (XYZ-fixed roll/pitch/yaw) reflects that.
+- Accuracy validated with a 45-point single-divot pivot test: 0.66 mm RMS.
+  Avoid poses with the stylus aligned with the forearm (singularity).
+- Not implemented, on purpose: analog channels, baud switching, EEPROM
+  writes (SET_PARAMS / SET_HOME / RESTORE_FACTORY), motion-report streaming,
+  custom tip offsets (MSTIP.DAT). Ask if you need one.
+
+## Dev
+
+Install dependencies with `uv sync`, then:
+
+```
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```
+
+Tests run without hardware: the kinematics is checked against golden
+joint-angles-to-XYZ values captured from a real arm.

microcmm-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+microcmm/__init__.py,sha256=LCxXk_8QCNlg5p00j6dR2aiB58kG75-lin1QZzfUt0M,366
+microcmm/arm.py,sha256=iUwsaMoZLkKpWhXc1cBw55cvjj19Nx_sU1Vh2TVSVsY,8298
+microcmm/cli.py,sha256=fUxSbdZez54yrPiRrVlfUhRrrEGi2U-PSLZ2BGEA61w,9477
+microcmm/device.py,sha256=CR4n52YKNZhxwYGNcs7zsipw3Ve82az9d_6WGNTwS98,2676
+microcmm/hci.py,sha256=NCyJscWRv_c1sYaaYygRiSXFsUu8PuX12c4M4uOMFE0,12460
+microcmm-0.1.0.dist-info/METADATA,sha256=6J89ul8epPAaJw4FfFFc7Lvi-burhn52F2aiY2KrK_E,3025
+microcmm-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+microcmm-0.1.0.dist-info/entry_points.txt,sha256=yOrNisK5Cru16bNk38YmbJQVSXRoA8sSCox7E7O-Bgs,47
+microcmm-0.1.0.dist-info/licenses/LICENSE,sha256=09e-X6HyXyR4pimE6NbZMk5L-fd3PX12bCYFKooCr8U,1070
+microcmm-0.1.0.dist-info/RECORD,,

microcmm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

microcmm-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+microcmm = microcmm.cli:main

microcmm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Sadetsky
+
+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.