grafito-canstepper 0.1.0__tar.gz

grafito_canstepper-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: grafito-canstepper
+Version: 0.1.0
+Summary: Host library for Grafito CANStepper boards (GCSP v1): multi-node CAN stepper control with encoders, homing, groups and coordinated motion
+Author-email: Grafito Innovations <grafito.innovations@gmail.com>
+License: Apache-2.0
+Project-URL: Documentation, https://docs.grafito.in
+Project-URL: Homepage, https://docs.grafito.in
+Project-URL: Source, https://github.com/Grafito-Innovations/Grafito-Edge-Services/tree/main/can_stepper
+Project-URL: Issues, https://github.com/Grafito-Innovations/Grafito-Edge-Services/issues
+Keywords: stepper,CAN,motion-control,esp32,tmc2209,encoder
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.4
+Provides-Extra: toml
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "toml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Dynamic: requires-python
+
+# Grafito CANStepper
+
+Closed-loop stepper motor control over CAN. Each board carries an ESP32-C3,
+a TMC2209 driver, an MT6701 14-bit magnetic encoder and a CAN transceiver;
+up to 31 boards daisy-chain on one 1 Mbps bus and are driven from Python
+through the USB port of any board on the chain.
+
+```
+can_stepper/
+├── firmware/GrafitoCANStepper_C3/   # node firmware (GCSP v1)
+├── canstepper/                      # Python package (grafito-canstepper)
+├── examples/                        # runnable examples + machine.toml
+├── tests/                           # pytest suite (runs on a software sim)
+└── docs/
+    ├── PRD.md                       # product requirements
+    ├── protocol.md                  # GCSP v1 wire protocol reference
+    └── quickstart.md                # unboxing -> moving motor
+```
+
+## Highlights
+
+- **Layered Python API** — raw frames → `StepperNode` → `NodeGroup` →
+  `Axis` (mm units via `rotation_distance`) → `DualMotorAxis` / `CoreXY` /
+  `MotionGroup` → declarative `machine.toml`.
+- **Safety scopes** — `node.estop()`, `group.estop()`, `bus.estop_all()`
+  (single broadcast frame); e-stop is latched until re-enabled.
+- **Homing** — physical endstop on IO8, sensorless (StallGuard), or
+  set-zero; configurable current, backoff and timeout.
+- **Closed loop** — firmware ≥1.2 plans a rest-to-rest **trapezoidal**
+  trajectory with **velocity feedforward** and a light tracking PID on the
+  MT6701 encoder (settle + stall watchdog). All motion limits are
+  *configurable defaults*, never hard clamps.
+- **On-bus leader/follower** — dual-motor gantries stay coupled with no
+  host in the loop.
+- **Simulator included** — `canstepper.sim.SimNetwork` implements the whole
+  protocol in software; the test suite and the examples run without hardware.
+
+## Install & first spin
+
+The package is **`grafito-canstepper`** on the index; you `import canstepper`.
+
+```bash
+# Works today (GitHub monorepo subdirectory — not yet on PyPI):
+pip install "git+https://github.com/Grafito-Innovations/Grafito-Edge-Services.git#subdirectory=can_stepper"
+
+# Development (from this directory):
+pip install -U pip setuptools && pip install -e ".[dev]"
+
+# After publishing to PyPI:
+# pip install grafito-canstepper
+```
+
+Docs: **https://docs.grafito.in**
+
+```python
+from canstepper import CANStepperBus
+
+with CANStepperBus.serial("/dev/ttyACM0") as bus:
+    print(bus.discover())
+    node = bus.node(1)
+    node.set_run_current(40).enable()
+    node.move_to(360.0, blocking=True)
+```
+
+Continue with:
+
+- [docs/quickstart.md](docs/quickstart.md) — first motion
+- [docs/closed_loop_tuning.md](docs/closed_loop_tuning.md) — trapezoid + v_ff,
+  hardware matrix + 10 min soak on **PR42HS40-1204AF-02** (NEMA 17 1.2 A)
+- [docs/protocol.md](docs/protocol.md) — GCSP v1 wire protocol
+
+## Development
+
+```bash
+cd can_stepper
+python3 -m pytest            # simulator suite
+python3 tools/cl_speed_validate.py /dev/ttyACM0 1 70 8   # hardware OL vs CL
+```
+
+Firmware builds with Arduino IDE or `arduino-cli` (ESP32C3 Dev Module, USB
+CDC On Boot = Enabled; libraries: FastAccelStepper, TMC2209 janelia-arduino):
+
+```bash
+arduino-cli compile --fqbn esp32:esp32:esp32c3:CDCOnBoot=cdc \
+  firmware/GrafitoCANStepper_C3
+arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:esp32c3:CDCOnBoot=cdc \
+  firmware/GrafitoCANStepper_C3
+```
+
+## Legacy note
+
+`CANStepperNode_C3/` and `canbus.py` are the earlier bring-up firmware and
+host script based on a third-party protocol. They are superseded by the
+clean-room GCSP v1 stack above and kept only for reference during migration.

grafito_canstepper-0.1.0/README.md

@@ -0,0 +1,94 @@
+# Grafito CANStepper
+
+Closed-loop stepper motor control over CAN. Each board carries an ESP32-C3,
+a TMC2209 driver, an MT6701 14-bit magnetic encoder and a CAN transceiver;
+up to 31 boards daisy-chain on one 1 Mbps bus and are driven from Python
+through the USB port of any board on the chain.
+
+```
+can_stepper/
+├── firmware/GrafitoCANStepper_C3/   # node firmware (GCSP v1)
+├── canstepper/                      # Python package (grafito-canstepper)
+├── examples/                        # runnable examples + machine.toml
+├── tests/                           # pytest suite (runs on a software sim)
+└── docs/
+    ├── PRD.md                       # product requirements
+    ├── protocol.md                  # GCSP v1 wire protocol reference
+    └── quickstart.md                # unboxing -> moving motor
+```
+
+## Highlights
+
+- **Layered Python API** — raw frames → `StepperNode` → `NodeGroup` →
+  `Axis` (mm units via `rotation_distance`) → `DualMotorAxis` / `CoreXY` /
+  `MotionGroup` → declarative `machine.toml`.
+- **Safety scopes** — `node.estop()`, `group.estop()`, `bus.estop_all()`
+  (single broadcast frame); e-stop is latched until re-enabled.
+- **Homing** — physical endstop on IO8, sensorless (StallGuard), or
+  set-zero; configurable current, backoff and timeout.
+- **Closed loop** — firmware ≥1.2 plans a rest-to-rest **trapezoidal**
+  trajectory with **velocity feedforward** and a light tracking PID on the
+  MT6701 encoder (settle + stall watchdog). All motion limits are
+  *configurable defaults*, never hard clamps.
+- **On-bus leader/follower** — dual-motor gantries stay coupled with no
+  host in the loop.
+- **Simulator included** — `canstepper.sim.SimNetwork` implements the whole
+  protocol in software; the test suite and the examples run without hardware.
+
+## Install & first spin
+
+The package is **`grafito-canstepper`** on the index; you `import canstepper`.
+
+```bash
+# Works today (GitHub monorepo subdirectory — not yet on PyPI):
+pip install "git+https://github.com/Grafito-Innovations/Grafito-Edge-Services.git#subdirectory=can_stepper"
+
+# Development (from this directory):
+pip install -U pip setuptools && pip install -e ".[dev]"
+
+# After publishing to PyPI:
+# pip install grafito-canstepper
+```
+
+Docs: **https://docs.grafito.in**
+
+```python
+from canstepper import CANStepperBus
+
+with CANStepperBus.serial("/dev/ttyACM0") as bus:
+    print(bus.discover())
+    node = bus.node(1)
+    node.set_run_current(40).enable()
+    node.move_to(360.0, blocking=True)
+```
+
+Continue with:
+
+- [docs/quickstart.md](docs/quickstart.md) — first motion
+- [docs/closed_loop_tuning.md](docs/closed_loop_tuning.md) — trapezoid + v_ff,
+  hardware matrix + 10 min soak on **PR42HS40-1204AF-02** (NEMA 17 1.2 A)
+- [docs/protocol.md](docs/protocol.md) — GCSP v1 wire protocol
+
+## Development
+
+```bash
+cd can_stepper
+python3 -m pytest            # simulator suite
+python3 tools/cl_speed_validate.py /dev/ttyACM0 1 70 8   # hardware OL vs CL
+```
+
+Firmware builds with Arduino IDE or `arduino-cli` (ESP32C3 Dev Module, USB
+CDC On Boot = Enabled; libraries: FastAccelStepper, TMC2209 janelia-arduino):
+
+```bash
+arduino-cli compile --fqbn esp32:esp32:esp32c3:CDCOnBoot=cdc \
+  firmware/GrafitoCANStepper_C3
+arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:esp32c3:CDCOnBoot=cdc \
+  firmware/GrafitoCANStepper_C3
+```
+
+## Legacy note
+
+`CANStepperNode_C3/` and `canbus.py` are the earlier bring-up firmware and
+host script based on a third-party protocol. They are superseded by the
+clean-room GCSP v1 stack above and kept only for reference during migration.

grafito_canstepper-0.1.0/canstepper/__init__.py

@@ -0,0 +1,95 @@
+"""grafito-canstepper — host library for Grafito CANStepper boards (GCSP v1).
+
+Quick start::
+
+    from canstepper import CANStepperBus
+
+    bus = CANStepperBus.serial("/dev/ttyACM0")
+    print(bus.discover())
+
+    node = bus.node(1)
+    node.set_run_current(40).set_microsteps(16).enable()
+    node.move_to(180.0, blocking=True)
+
+    bus.estop_all()   # single broadcast frame stops every node
+"""
+
+from .axis import Axis
+from .bus import CANStepperBus
+from .config import Machine
+from .exceptions import (
+    CANStepperError,
+    ConfigError,
+    EStopActive,
+    HomingFailed,
+    LimitViolation,
+    NodeFault,
+    NotHomed,
+    ParamRejected,
+    RequestTimeout,
+    TransportError,
+    UnknownParam,
+)
+from .group import NodeGroup
+from .kinematics import CoreXY, DualMotorAxis, MotionGroup
+from .node import SpeedLimits, StepperNode
+from .protocol import (
+    BROADCAST,
+    PROTOCOL_VERSION,
+    Cmd,
+    EndstopAction,
+    Event,
+    Fault,
+    Frame,
+    HomeMethod,
+    Mode,
+    Param,
+    StandstillMode,
+    Tel,
+)
+from .telemetry import CanHealth, FollowStatus, NodeState, NodeStatus, PidStatus
+from .transport import SerialBridgeTransport, Transport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Axis",
+    "BROADCAST",
+    "CANStepperBus",
+    "CANStepperError",
+    "CanHealth",
+    "Cmd",
+    "ConfigError",
+    "CoreXY",
+    "DualMotorAxis",
+    "EndstopAction",
+    "EStopActive",
+    "Event",
+    "Fault",
+    "FollowStatus",
+    "Frame",
+    "HomeMethod",
+    "HomingFailed",
+    "LimitViolation",
+    "Machine",
+    "Mode",
+    "MotionGroup",
+    "NodeFault",
+    "NodeGroup",
+    "NodeState",
+    "NodeStatus",
+    "NotHomed",
+    "Param",
+    "ParamRejected",
+    "PidStatus",
+    "PROTOCOL_VERSION",
+    "RequestTimeout",
+    "SerialBridgeTransport",
+    "SpeedLimits",
+    "StandstillMode",
+    "StepperNode",
+    "Tel",
+    "Transport",
+    "TransportError",
+    "UnknownParam",
+]

grafito_canstepper-0.1.0/canstepper/axis.py

@@ -0,0 +1,198 @@
+"""Axis — a stepper node dressed in real-world linear units.
+
+Klipper-style ``rotation_distance``: the distance the axis travels for one
+full motor revolution (e.g. an 8 mm-lead leadscrew -> 8.0, a GT2-20T belt
+-> 40.0). All Axis positions/speeds are in those units ("mm" below).
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from .exceptions import LimitViolation, NotHomed
+from .node import StepperNode
+from .protocol import HomeMethod, Param
+
+
+class Axis:
+    """Linear (or geared rotary) axis on one node.
+
+    Args:
+        node:               the StepperNode driving the axis
+        rotation_distance:  units of travel per motor revolution
+        gear_ratio:         motor revs per output rev (e.g. 5.0 for a 5:1 box)
+        min_pos / max_pos:  optional host-side soft travel limits (units)
+        max_speed:          optional host-side speed limit (units/s)
+        require_homing:     refuse moves until the axis was homed
+    """
+
+    def __init__(
+        self,
+        node: StepperNode,
+        rotation_distance: float,
+        gear_ratio: float = 1.0,
+        min_pos: Optional[float] = None,
+        max_pos: Optional[float] = None,
+        max_speed: Optional[float] = None,
+        require_homing: bool = False,
+        name: str = "",
+    ):
+        if rotation_distance <= 0:
+            raise ValueError("rotation_distance must be positive")
+        if gear_ratio <= 0:
+            raise ValueError("gear_ratio must be positive")
+        self.node = node
+        self.rotation_distance = float(rotation_distance)
+        self.gear_ratio = float(gear_ratio)
+        self.min_pos = min_pos
+        self.max_pos = max_pos
+        self.max_speed = max_speed
+        self.require_homing = require_homing
+        self.name = name or f"axis{node.node_id}"
+        self._homed = False
+
+    # -- unit conversion ---------------------------------------------------------
+
+    def units_to_deg(self, units: float) -> float:
+        return units / self.rotation_distance * 360.0 * self.gear_ratio
+
+    def deg_to_units(self, deg: float) -> float:
+        return deg / 360.0 / self.gear_ratio * self.rotation_distance
+
+    # -- state ---------------------------------------------------------------------
+
+    @property
+    def position(self) -> Optional[float]:
+        """Last-known position in axis units (cached telemetry)."""
+        deg = self.node.state.position_deg
+        return None if deg is None else self.deg_to_units(deg)
+
+    def get_position(self) -> float:
+        """Round-trip read of the position in axis units."""
+        return self.deg_to_units(self.node.get_position())
+
+    @property
+    def homed(self) -> bool:
+        status = self.node.state.status
+        if status is not None:
+            return status.homed or self._homed
+        return self._homed
+
+    # -- motion ---------------------------------------------------------------------
+
+    def move_to(
+        self,
+        pos: float,
+        speed: Optional[float] = None,
+        blocking: bool = False,
+        timeout: float = 60.0,
+    ) -> "Axis":
+        """Absolute move in axis units; ``speed`` (units/s) sets the node's
+        move speed for this and subsequent moves."""
+        self._check_motion_allowed(pos, speed)
+        if speed is not None:
+            self.node.set_max_speed(self.units_to_deg(speed))
+        self.node.move_to(self.units_to_deg(pos), blocking=blocking, timeout=timeout)
+        return self
+
+    def move_by(
+        self,
+        delta: float,
+        speed: Optional[float] = None,
+        blocking: bool = False,
+        timeout: float = 60.0,
+    ) -> "Axis":
+        target = None
+        if self.min_pos is not None or self.max_pos is not None:
+            current = self.position
+            if current is not None:
+                target = current + delta
+        self._check_motion_allowed(target, speed)
+        if speed is not None:
+            self.node.set_max_speed(self.units_to_deg(speed))
+        self.node.move_by(self.units_to_deg(delta), blocking=blocking, timeout=timeout)
+        return self
+
+    def run(self, speed: float) -> "Axis":
+        """Continuous motion at signed ``speed`` (units/s)."""
+        if self.max_speed is not None and abs(speed) > self.max_speed:
+            raise LimitViolation(
+                f"{self.name}: {abs(speed):.3f} exceeds max_speed {self.max_speed:.3f}"
+            )
+        self.node.run(self.units_to_deg(speed))
+        return self
+
+    def stop(self) -> "Axis":
+        self.node.stop()
+        return self
+
+    def estop(self) -> "Axis":
+        self.node.estop()
+        return self
+
+    # -- homing ---------------------------------------------------------------------
+
+    def home(
+        self,
+        method: Union[str, HomeMethod] = HomeMethod.ENDSTOP,
+        direction: int = -1,
+        speed: float = 10.0,
+        current_percent: Optional[int] = None,
+        backoff: Optional[float] = None,
+        timeout: float = 60.0,
+    ) -> "Axis":
+        """Home the axis. ``speed`` and ``backoff`` are in axis units.
+
+        For ``"stallguard"`` homing, tune ``node.set_stall_threshold()`` and
+        use a reduced ``current_percent`` so the crash into the hard stop
+        stays gentle.
+        """
+        if current_percent is not None:
+            self.node.set_param(Param.HOMING_CURRENT, current_percent)
+        if backoff is not None:
+            self.node.set_param(Param.HOMING_BACKOFF, self.units_to_deg(backoff))
+        self.node.home(
+            method=method,
+            direction=direction,
+            speed_deg_s=self.units_to_deg(speed),
+            blocking=True,
+            timeout=timeout,
+        )
+        self._homed = True
+        return self
+
+    def set_zero(self) -> "Axis":
+        self.node.set_zero()
+        self._homed = True
+        return self
+
+    def wait_settled(self, timeout: float = 30.0) -> "Axis":
+        self.node.wait_settled(timeout=timeout)
+        return self
+
+    # -- internals ---------------------------------------------------------------------
+
+    def _check_motion_allowed(
+        self, target: Optional[float], speed: Optional[float]
+    ) -> None:
+        if self.require_homing and not self.homed:
+            raise NotHomed(f"{self.name}: home the axis before moving it")
+        if speed is not None and self.max_speed is not None and abs(speed) > self.max_speed:
+            raise LimitViolation(
+                f"{self.name}: {abs(speed):.3f} exceeds max_speed {self.max_speed:.3f}"
+            )
+        if target is not None:
+            if self.min_pos is not None and target < self.min_pos:
+                raise LimitViolation(
+                    f"{self.name}: target {target:.3f} below min_pos {self.min_pos:.3f}"
+                )
+            if self.max_pos is not None and target > self.max_pos:
+                raise LimitViolation(
+                    f"{self.name}: target {target:.3f} above max_pos {self.max_pos:.3f}"
+                )
+
+    def __repr__(self) -> str:
+        return (
+            f"<Axis {self.name!r} node={self.node.node_id} "
+            f"rotation_distance={self.rotation_distance}>"
+        )