servomotor-mcp 0.1.0__tar.gz

servomotor_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+# Builds and publishes servomotor-mcp to PyPI on a version tag (e.g. v0.1.0),
+# using PyPI Trusted Publishing (OIDC) — no API token needed.
+#
+# ONE-TIME SETUP (do before the first tag):
+#   On PyPI → the servomotor-mcp project → Settings → Publishing → add a "pending publisher":
+#     Owner:        Gearotons
+#     Repository:   servomotor-mcp
+#     Workflow:     publish.yml
+#     Environment:  pypi   (matches the `environment:` below; optional but recommended)
+#   (If the existing `servomotor` project uses an API token instead, you can swap this for that
+#    method — see DEPLOY_INSTRUCTIONS.md. Trusted publishing is preferred.)
+#
+# RELEASE:  git tag v0.1.0 && git push --tags     (or run this workflow manually)
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Verify the build
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

servomotor_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

servomotor_mcp-0.1.0/LICENSE

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

servomotor_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: servomotor-mcp
+Version: 0.1.0
+Summary: MCP server to drive Gearotons M17 open-source servomotors from natural language (Claude / any MCP client) over RS-485.
+Project-URL: Homepage, https://gearotons.com
+Project-URL: Repository, https://github.com/Gearotons/servomotor-mcp
+Project-URL: Issues, https://github.com/Gearotons/servomotor-mcp/issues
+Project-URL: Documentation, https://github.com/Gearotons/servomotor-mcp#readme
+Author: Gearotons
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,mcp,nema17,open-source,robotics,rs485,servomotor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: serial
+Requires-Dist: servomotor; extra == 'serial'
+Description-Content-Type: text/markdown
+
+# servomotor-mcp
+
+**Drive open-source [Gearotons M17](https://gearotons.com) servomotors from natural language.**
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the M17 — a NEMA-17
+integrated, closed-loop, RS-485 servomotor — as a small set of safe, high-level tools.
+Connect it to Claude Desktop, Claude Code, or any MCP client and control real motors by
+just *asking*:
+
+> "Home everything, then draw a square with the X and Y axes."
+
+It ships with a **mock backend**, so you can try the whole thing with **no hardware**.
+
+> The first servomotor with an official MCP server. Open hardware, open firmware, open
+> software — and now an open, AI-native control interface.
+
+---
+
+## Quickstart (no hardware, ~2 minutes)
+
+```bash
+# Run the server directly with uv (recommended):
+uvx --from servomotor-mcp servomotor-mcp
+
+# or install it:
+pip install servomotor-mcp
+servomotor-mcp
+```
+
+Then add it to **Claude Desktop** — copy the block from
+[`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) into your
+`claude_desktop_config.json`, restart Claude Desktop, and ask:
+*"What motors do you have connected?"* See [`examples/demo_prompts.md`](examples/demo_prompts.md)
+for the full scripted demo.
+
+## Drive real motors
+
+Plug an M17 (or a daisy-chain of them) into a USB↔RS-485 adapter and switch the backend:
+
+```bash
+pip install 'servomotor-mcp[serial]'   # pulls in the Gearotons servomotor library
+GEAROTONS_MOTOR_BACKEND=serial \
+GEAROTONS_SERIAL_PORT=/dev/ttyUSB0 \
+servomotor-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_motors` | Discover motors on the bus + positions (call first). |
+| `move_to` | Move a motor to an absolute angle (closed-loop). |
+| `move_relative` | Nudge a motor by a delta. |
+| `trapezoid_move` | Smooth accel/decel move (best for arms/plotters). |
+| `home` | Home one or all motors. |
+| `get_status` | Position / moving / voltage / errors. |
+| `stop` | Halt one or all motors. |
+| `reset` | Recover a motor from a latched fault (firmware system reset, ~2 s). |
+| `run_sequence` | Run a choreographed sequence ("draw a square"). |
+
+## Safety rails (in the server, not the model)
+
+The LLM can hallucinate a tool call; these make that safe — they run on every request:
+
+- **Alias allow-list** — only configured motors can be driven.
+- **Position limits** — absolute/relative targets are clamped to a per-motor software
+  range, so a bad command can't drive an axis into a hard stop.
+- **Speed clamp** — requested speeds are capped.
+
+Clamps are *reported back* to the model (in `safety_notes`) rather than silently applied,
+so it can see what actually happened and adjust. Configure via env:
+
+```bash
+GEAROTONS_MOTOR_ALIASES="x,y,z"
+GEAROTONS_LIMITS='{"x":{"min_deg":-180,"max_deg":180,"max_speed":300},"z":{"min_deg":0,"max_deg":90}}'
+```
+
+## How it works
+
+```
+natural language → Claude → MCP tool calls → this server → RS-485 → M17 motors
+```
+
+The server is a thin, safety-checked wrapper over the Gearotons `servomotor` Python
+library (high-level, unit-aware commands — no DIR/STEP timing). The same intents run
+against the mock backend for development and CI.
+
+## Develop / test
+
+```bash
+pip install -e '.[dev]'
+pytest                      # safety + mock-bus tests, no hardware needed
+GEAROTONS_MOCK_SIM_SECONDS=0.4 servomotor-mcp   # lifelike timing for demos
+```
+
+## Status
+
+- ✅ MCP server, full tool surface, safety rails, mock backend — done; 16 unit tests pass.
+- ✅ `SerialBus` real-hardware backend — **verified against a physical M17** (fw 0.15.0.0):
+  discovery, telemetry, closed-loop moves at **0.000° repeatability**, and a live safety
+  clamp (a 200° command on a ±90° motor stopped at 90°). See [`hardware_tests/`](hardware_tests/).
+- 🔜 Live FastMCP-over-stdio run with Claude Desktop needs a Python ≥3.10 host (tool logic
+  already hardware-verified); plus the physical demo build + video. See [demo spec](../SPEC.md).
+
+## License
+
+MIT. Hardware, firmware, and software for the M17 are open-source —
+see [github.com/tomrodinger/servomotor](https://github.com/tomrodinger/servomotor).

servomotor_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# servomotor-mcp
+
+**Drive open-source [Gearotons M17](https://gearotons.com) servomotors from natural language.**
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the M17 — a NEMA-17
+integrated, closed-loop, RS-485 servomotor — as a small set of safe, high-level tools.
+Connect it to Claude Desktop, Claude Code, or any MCP client and control real motors by
+just *asking*:
+
+> "Home everything, then draw a square with the X and Y axes."
+
+It ships with a **mock backend**, so you can try the whole thing with **no hardware**.
+
+> The first servomotor with an official MCP server. Open hardware, open firmware, open
+> software — and now an open, AI-native control interface.
+
+---
+
+## Quickstart (no hardware, ~2 minutes)
+
+```bash
+# Run the server directly with uv (recommended):
+uvx --from servomotor-mcp servomotor-mcp
+
+# or install it:
+pip install servomotor-mcp
+servomotor-mcp
+```
+
+Then add it to **Claude Desktop** — copy the block from
+[`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) into your
+`claude_desktop_config.json`, restart Claude Desktop, and ask:
+*"What motors do you have connected?"* See [`examples/demo_prompts.md`](examples/demo_prompts.md)
+for the full scripted demo.
+
+## Drive real motors
+
+Plug an M17 (or a daisy-chain of them) into a USB↔RS-485 adapter and switch the backend:
+
+```bash
+pip install 'servomotor-mcp[serial]'   # pulls in the Gearotons servomotor library
+GEAROTONS_MOTOR_BACKEND=serial \
+GEAROTONS_SERIAL_PORT=/dev/ttyUSB0 \
+servomotor-mcp
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_motors` | Discover motors on the bus + positions (call first). |
+| `move_to` | Move a motor to an absolute angle (closed-loop). |
+| `move_relative` | Nudge a motor by a delta. |
+| `trapezoid_move` | Smooth accel/decel move (best for arms/plotters). |
+| `home` | Home one or all motors. |
+| `get_status` | Position / moving / voltage / errors. |
+| `stop` | Halt one or all motors. |
+| `reset` | Recover a motor from a latched fault (firmware system reset, ~2 s). |
+| `run_sequence` | Run a choreographed sequence ("draw a square"). |
+
+## Safety rails (in the server, not the model)
+
+The LLM can hallucinate a tool call; these make that safe — they run on every request:
+
+- **Alias allow-list** — only configured motors can be driven.
+- **Position limits** — absolute/relative targets are clamped to a per-motor software
+  range, so a bad command can't drive an axis into a hard stop.
+- **Speed clamp** — requested speeds are capped.
+
+Clamps are *reported back* to the model (in `safety_notes`) rather than silently applied,
+so it can see what actually happened and adjust. Configure via env:
+
+```bash
+GEAROTONS_MOTOR_ALIASES="x,y,z"
+GEAROTONS_LIMITS='{"x":{"min_deg":-180,"max_deg":180,"max_speed":300},"z":{"min_deg":0,"max_deg":90}}'
+```
+
+## How it works
+
+```
+natural language → Claude → MCP tool calls → this server → RS-485 → M17 motors
+```
+
+The server is a thin, safety-checked wrapper over the Gearotons `servomotor` Python
+library (high-level, unit-aware commands — no DIR/STEP timing). The same intents run
+against the mock backend for development and CI.
+
+## Develop / test
+
+```bash
+pip install -e '.[dev]'
+pytest                      # safety + mock-bus tests, no hardware needed
+GEAROTONS_MOCK_SIM_SECONDS=0.4 servomotor-mcp   # lifelike timing for demos
+```
+
+## Status
+
+- ✅ MCP server, full tool surface, safety rails, mock backend — done; 16 unit tests pass.
+- ✅ `SerialBus` real-hardware backend — **verified against a physical M17** (fw 0.15.0.0):
+  discovery, telemetry, closed-loop moves at **0.000° repeatability**, and a live safety
+  clamp (a 200° command on a ±90° motor stopped at 90°). See [`hardware_tests/`](hardware_tests/).
+- 🔜 Live FastMCP-over-stdio run with Claude Desktop needs a Python ≥3.10 host (tool logic
+  already hardware-verified); plus the physical demo build + video. See [demo spec](../SPEC.md).
+
+## License
+
+MIT. Hardware, firmware, and software for the M17 are open-source —
+see [github.com/tomrodinger/servomotor](https://github.com/tomrodinger/servomotor).

servomotor_mcp-0.1.0/examples/claude_desktop_config.json

@@ -0,0 +1,18 @@
+{
+  "//": "Add this block to Claude Desktop's MCP config (claude_desktop_config.json).",
+  "//1": "macOS: ~/Library/Application Support/Claude/claude_desktop_config.json",
+  "//2": "Restart Claude Desktop after editing. Mock backend = no hardware needed.",
+  "mcpServers": {
+    "gearotons-motor": {
+      "command": "uvx",
+      "args": ["--from", "servomotor-mcp", "servomotor-mcp"],
+      "env": {
+        "GEAROTONS_MOTOR_BACKEND": "mock",
+        "GEAROTONS_MOTOR_ALIASES": "x,y,z",
+        "GEAROTONS_MOCK_SIM_SECONDS": "0.4",
+        "GEAROTONS_LIMITS": "{\"x\": {\"min_deg\": -180, \"max_deg\": 180, \"max_speed\": 300}, \"y\": {\"min_deg\": -180, \"max_deg\": 180}, \"z\": {\"min_deg\": 0, \"max_deg\": 90}}"
+      }
+    },
+    "//real-hardware": "To drive real motors, set GEAROTONS_MOTOR_BACKEND=serial and GEAROTONS_SERIAL_PORT=/dev/ttyUSB0, and install with the [serial] extra."
+  }
+}

servomotor_mcp-0.1.0/examples/demo_prompts.md

@@ -0,0 +1,35 @@
+# Demo prompts — talking to the M17 motors
+
+These are the natural-language prompts for the demo video / live demo, once the server is
+connected to Claude Desktop (or any MCP client). With the mock backend they run with no
+hardware; with the serial backend they drive real motors. The point: **no API knowledge,
+no code — just plain English.**
+
+## Warm-up (proves discovery + control)
+1. "What motors do you have connected?"
+   → calls `list_motors`, names x / y / z and their positions.
+2. "Home everything."
+   → `home` (all).
+3. "Point the X axis to 90 degrees, smoothly over 2 seconds."
+   → `trapezoid_move(x, 90, 2)`.
+4. "Where is everything right now?"
+   → `get_status`.
+
+## The headline shot — "draw a square"
+5. "Draw a square: move X and Y to trace a 90-degree box, then come back to the start."
+   → Claude composes a `run_sequence` of `move_to`/`trapezoid_move` steps. This is the
+     clip that goes in the launch posts — one sentence, real motion.
+
+## Show the safety rails (great for the technical audience / HN comments)
+6. "Spin Z to 300 degrees."
+   → Z is limited to 0–90°; the move is **clamped to 90°** and Claude reports the clamp
+     from `safety_notes` ("I limited that to 90° because Z's configured range is 0–90").
+     Demonstrates that the guardrails live in the server, not the model's goodwill.
+
+## The "talk to your hardware" moment
+7. "Wave hello with the Z axis."
+   → Claude improvises a small back-and-forth `run_sequence`. Good, human closer.
+
+> Recording notes: pen plotter reads best on camera (see SPEC.md). Keep the terminal /
+> Claude transcript on screen next to the hardware so viewers see prompt → tool call →
+> motion. ~60–90s total. End on the square.

servomotor_mcp-0.1.0/hardware_tests/README.md

@@ -0,0 +1,73 @@
+# Hardware tests — Gearotons M17 MCP server
+
+Scripts that validate the MCP server's motor backend against a **real M17** over RS-485.
+All four passed on 2026-06-08 against a physical motor (fw 0.15.0.0) — see results below and
+`../../../logs/hardware-2026-06-08.md`.
+
+## Setup
+
+`pyserial` is the only runtime dep for these (already present on the test machine). Point
+`PYTHONPATH` at the open-source `servomotor` library + the MCP package `src/`:
+
+```bash
+export SERVOMOTOR=/Users/sandbox1/servomotor/python_programs   # or: pip install servomotor
+export PKG=../src
+cd hardware_tests
+```
+
+The motor was auto-discovered on `/dev/cu.usbserial-210`, device **alias 88**. Adjust the
+port/alias args if yours differ.
+
+## The tests
+
+| Script | What it proves | Needs |
+|---|---|---|
+| `discover_motor.py` | Finds which of the connected RS-485 adapters has a motor; reports unique ID + alias. | servomotor |
+| `hw_test_basic.py` | Read-only telemetry (product/fw/status/voltage/temp/position) + one bounded ±18° move. | servomotor |
+| `hw_test_serialbus.py` | The **MCP tool code path** (SafetyPolicy clamp → `SerialBus`), incl. a live safety clamp. | servomotor + `src/` |
+| `hw_test_advanced.py` | `identify` LED blink + 12-target repeatability + a "wave" demo routine. | servomotor + `src/` |
+| `hw_test_extended.py` | PID-error readout, bounded velocity move, throughput timing, enable/disable reliability. | servomotor + `src/` |
+| `hw_test_sequence.py` | The `run_sequence` engine (the "draw"/"wave" path): a draw routine, a sequence-level clamp, and abort-on-disallowed-motor. | servomotor + `src/` |
+| `hw_test_endurance.py` | N bounded moves with temperature/voltage/error sampling — reliability + thermal data. | servomotor + `src/` |
+
+```bash
+PYTHONPATH=$SERVOMOTOR        python3 discover_motor.py
+PYTHONPATH=$SERVOMOTOR        python3 hw_test_basic.py
+PYTHONPATH=$PKG:$SERVOMOTOR   python3 hw_test_serialbus.py
+PYTHONPATH=$PKG:$SERVOMOTOR   python3 hw_test_advanced.py
+PYTHONPATH=$PKG:$SERVOMOTOR   python3 hw_test_extended.py
+PYTHONPATH=$PKG:$SERVOMOTOR   python3 hw_test_sequence.py
+```
+
+## Verified results (2026-06-08, physical M17)
+
+- **Discovery:** motor on `/dev/cu.usbserial-210`, unique_id `0x99856389A2B46555`, alias 88;
+  other three adapters empty.
+- **Telemetry:** M17, fw **0.15.0.0**, status `[0,0]` (healthy), supply **20.0 V**, **35 °C**.
+- **Bounded move:** +18° → read back 17.9999°, return → 0.000° net drift.
+- **SerialBus + safety:** absolute moves exact; **live clamp** — commanded 200° on a ±90°-
+  limited motor → physically stopped at **90.00°** with the clamp note surfaced. ✅
+- **Repeatability:** 12 random targets across ±80° → **0.000° mean & max error** (tol 0.5°).
+- **Demo routine + LED identify:** clean.
+- **Extended:** 20-move throughput 2.87 moves/s @ 0.000° worst error; 5/5 enable/disable
+  cycles clean. (Findings: `move_with_velocity` needs unit calibration before exposing a spin
+  tool; `get_max_pid_error` returned reset sentinels — read it after a move run for a real
+  number. Neither affects the 8 shipped MCP tools.)
+
+Every test force-disables the MOSFETs and closes the port in a `finally` block.
+
+## Unit tests (no hardware)
+
+The mock backend + safety rails + sequencer are covered by `../tests/` (21 tests):
+
+```bash
+PYTHONPATH=../src python3 -m pytest -q ../tests   # 21 passed
+```
+
+## Note on the live MCP-over-stdio test
+
+Running the actual FastMCP server end-to-end (MCP client → server → motor) needs the `mcp`
+SDK, which requires **Python ≥3.10**; the test machine has 3.9, so that step is deferred to
+a 3.10+ host (e.g. the dev machine). It is low-risk: `hw_test_serialbus.py` already exercises
+the identical tool logic (clamp → `SerialBus`) on hardware — only generic FastMCP transport
+plumbing is left unverified.

servomotor_mcp-0.1.0/hardware_tests/RESULTS.txt

@@ -0,0 +1,49 @@
+# Gearotons M17 MCP server — consolidated test results
+# Generated 2026-06-08 against the real motor on /dev/cu.usbserial-210 (alias 88)
+
+## Unit tests (mock + safety; no hardware, no mcp)
+................                                                         [100%]
+16 passed in 0.02s
+
+## Hardware: basic telemetry + bounded move
+  [ERR] ping (echoes 10-byte payload): SystemExit: 1
+  [ok ] product_info: ['M17     ', 3, [0, 5, 1], 1330, 11062357502496892245, 0]
+  [ok ] firmware_version: [[0, 0, 15, 0], 0]
+  [ok ] product_description: 'Servomotor\x00'
+  [ok ] status: [0, 0]
+  [ok ] supply_voltage: 20200.0
+  [ok ] temperature: 36
+  [ok ] position (deg): -14.499975585937499
+  [ok ] comprehensive_position: [-14.499975585937499, -10.693981933593749, 0.0]
+  [ok ] position after +18 deg: 3.5000244140624996
+  [ok ] position after return: -14.499975585937499
+  net displacement: +0.000 deg (expect ~0)
+MOTION TEST PASSED
+
+## Hardware: SerialBus + safety clamp (MCP tool path)
+  move_to(x, 45) -> pos=45.00° v=20.2V
+  move_to(x, 0) -> pos=0.00° v=20.2V
+  move_to(x, -30) -> pos=-30.00° v=20.2V
+--- move_relative (tool path) ---
+  move_relative(+15) -> pos=-15.00°
+--- LIVE SAFETY CLAMP: command 200° on a motor limited to 90° ---
+  move_to(x, 200) -> pos=90.00° v=20.2V  | ['target 200° clamped to 90° (range -90..90)']
+  motor stopped at 90.00° (<=90 expected) -> CLAMP WORKED ✅
+  move_to(x, 30) -> pos=30.00° v=20.2V
+  move_to(x, -30) -> pos=-30.00° v=20.2V
+  move_to(x, 0) -> pos=0.00° v=20.2V
+  homed x -> 0.00°
+SERIALBUS INTEGRATION TEST PASSED
+
+## Hardware: advanced (identify + repeatability + wave)
+--- 1. identify (LED should blink on the motor) ---
+  identify() sent — check the motor LED
+  mean error=0.000°   max error=0.000°   tolerance=0.5°
+ADVANCED TEST PASSED  (max err 0.000° vs tol 0.5°)
+
+## Hardware: extended (PID err, velocity, throughput, reliability)
+--- 1. enable + get_max_pid_error (closed-loop error, in degrees) ---
+  [ok ] max_pid_error [min,max]: [235929.5998901367, -235929.59999999998]
+  20 moves in 7.0s = 2.87 moves/s; worst position error 0.000°
+  5/5 enable+disable cycles clean
+EXTENDED TEST PASSED

servomotor_mcp-0.1.0/hardware_tests/demo_live.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Watchable demo: drive the real M17 through the MCP server's tool code path.
+
+Prints each plain-language intent + the tool it maps to, then moves the motor with a pause
+so you can watch. This is exactly what an AI assistant does via the MCP server — here a
+script plays the role of the AI so you can see the motor respond. Ends with the safety clamp.
+
+Run:
+    PYTHONPATH=../src:/Users/sandbox1/servomotor/python_programs python3 demo_live.py
+"""
+from __future__ import annotations
+
+import time
+
+from servomotor_mcp.motors import SerialBus
+from servomotor_mcp.safety import MotorLimits, SafetyPolicy
+
+NAME = "x"
+PAUSE = 1.2
+
+
+def say(intent, tool):
+    print(f'\n  🗣  "{intent}"\n      -> MCP tool: {tool}')
+
+
+def main() -> int:
+    bus = SerialBus(port="/dev/cu.usbserial-210", motor_map={NAME: 88})
+    policy = SafetyPolicy(allowed=frozenset({NAME}),
+                          limits={NAME: MotorLimits(min_deg=-90, max_deg=90, max_speed=300)})
+    m = bus._m[NAME]
+    try:
+        print("=" * 64)
+        print(" GEAROTONS M17 — live demo  (WATCH THE MOTOR)")
+        print(" A script is standing in for the AI; it calls the same MCP tools.")
+        print("=" * 64)
+
+        say("Which motor are you?  (blink so I can see you)", "identify")
+        m.identify(); print("      -> the motor's LED should be blinking now"); time.sleep(2.0)
+
+        say("Home — go to zero.", "home()")
+        bus.home(NAME); print(f"      -> position: {bus.get_status(NAME)[0].position_deg:.1f}°"); time.sleep(PAUSE)
+
+        say("Point to 60 degrees.", "move_to(x, 60)")
+        s = bus.move_to(NAME, 60); print(f"      -> position: {s.position_deg:.1f}°"); time.sleep(PAUSE)
+
+        say("Now go to minus 60 degrees.", "move_to(x, -60)")
+        s = bus.move_to(NAME, -60); print(f"      -> position: {s.position_deg:.1f}°"); time.sleep(PAUSE)
+
+        say("Wave hello.", "run_sequence([...])")
+        for deg in (25, -25, 18, -18, 0):
+            bus.move_to(NAME, deg, speed=240)
+        print(f"      -> back to {bus.get_status(NAME)[0].position_deg:.1f}°"); time.sleep(PAUSE)
+
+        print("\n" + "-" * 64)
+        print(" SAFETY DEMO — the limits live in the software, not the AI's goodwill.")
+        print(" This motor is configured with a max of 90°.")
+        say("Spin all the way to 300 degrees!", "move_to(x, 300)")
+        target, note = policy.clamp_absolute(NAME, 300)
+        s = bus.move_to(NAME, target)
+        print(f"      -> {note}")
+        print(f"      -> motor STOPPED at {s.position_deg:.1f}° (refused to exceed 90°)")
+        time.sleep(PAUSE)
+
+        say("Okay, home and rest.", "home() + stop()")
+        bus.home(NAME); bus.stop(NAME)
+        print(f"      -> position: {bus.get_status(NAME)[0].position_deg:.1f}°, motor released")
+
+        print("\n" + "=" * 64)
+        print(" Demo done. That's the MCP toolset driving your real motor.")
+        print(" With the Python-3.10 setup, Claude calls these same tools from chat.")
+        print("=" * 64)
+        return 0
+    finally:
+        bus.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

servomotor_mcp-0.1.0/hardware_tests/discover_motor.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Probe every RS-485 serial port and report which one(s) have a Gearotons motor.
+
+Tom connected ONE M17 via one of four USB-RS485 adapters; the other three are empty.
+This finds it by running the library's device detection on each port and reporting the
+unique ID + alias of whatever answers.
+
+Run:
+    PYTHONPATH=/Users/sandbox1/servomotor/python_programs python3 discover_motor.py
+"""
+from __future__ import annotations
+
+import glob
+import sys
+
+import servomotor
+from servomotor import communication
+from servomotor.device_detection import detect_devices_iteratively
+
+DEFAULT_PORTS = sorted(glob.glob("/dev/cu.usbserial-*"))
+N_DETECTIONS = 3  # consecutive successful detections the lib requires to trust a result
+
+
+def probe(port: str) -> list:
+    """Return the list of Devices found on `port` (empty if none / no answer)."""
+    communication.serial_port = port
+    # alias 255 = broadcast/ALL; detection enumerates whoever is on the bus
+    servomotor.M3(alias_or_unique_id=255, verbose=0)
+    servomotor.open_serial_port()
+    try:
+        return detect_devices_iteratively(N_DETECTIONS, verbose=False) or []
+    finally:
+        try:
+            servomotor.close_serial_port()
+        except Exception:
+            pass
+
+
+def main() -> int:
+    ports = sys.argv[1:] or DEFAULT_PORTS
+    print(f"Probing {len(ports)} port(s): {ports}\n")
+    found = {}
+    for port in ports:
+        try:
+            devices = probe(port)
+        except Exception as exc:  # empty adapter -> timeout/serial error; keep going
+            print(f"  {port:32s} -> no device ({type(exc).__name__}: {exc})")
+            continue
+        if devices:
+            for d in devices:
+                print(f"  {port:32s} -> MOTOR  unique_id=0x{d.unique_id:016X}  alias={d.alias}")
+            found[port] = devices
+        else:
+            print(f"  {port:32s} -> no device (no response)")
+
+    print()
+    if not found:
+        print("RESULT: no motor detected on any port.")
+        return 1
+    for port, devices in found.items():
+        print(f"RESULT: motor on {port} -> "
+              + ", ".join(f"uid=0x{d.unique_id:016X} alias={d.alias}" for d in devices))
+    # Emit the first found port on the last line for easy scripting/capture.
+    print(f"MOTOR_PORT={next(iter(found))}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())