pymyarm 0.0.3__tar.gz

pymyarm-0.0.3/LICENSE

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

pymyarm-0.0.3/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pymyarm
+Version: 0.0.3
+Summary: pymycobot-compatible API for Feetech STS servo-based robotic arms
+Author-email: Yunzhe Xue <yunzhexue@gmail.com>
+License-Expression: MIT
+Keywords: robot,servo,feetech,robotic-arm,sts3215
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Dynamic: license-file
+
+# pymyarm
+
+pymycobot-compatible Python API for Feetech STS servo-based robotic arms.
+
+## Installation
+
+```bash
+pip install pymyarm
+```
+
+## Quick Start
+
+```python
+from pymyarm import MyArmSTS
+
+arm = MyArmSTS(port="/dev/ttyACM0", baudrate=1000000)
+arm.connect()
+
+# Read all joint angles
+angles = arm.get_angles()
+print(angles)
+
+# Move joints
+arm.set_angles([0, 0, 0, 0, 0, 0], speed=200)
+
+# Read encoder values
+encoders = arm.get_servos_encoder()
+
+# Control gripper
+arm.set_gripper_value(50, speed=200)
+
+arm.disconnect()
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│            MyArmSTS (myarm_sts.py)      │  User API: angles, encoders, gripper
+├─────────────────────────────────────────┤
+│  STS (sts.py)      conversion.py        │  Register-level ops + unit conversion
+├─────────────────────────────────────────┤
+│          ServoController                │  Thread-safe TX/RX, retries, error cache
+│          (servo_controller.py)          │
+├─────────────────────────────────────────┤
+│  protocol.py            port.py         │  Frame encoding/decoding + serial I/O
+├─────────────────────────────────────────┤
+│  constants.py       joint_config.py     │  Protocol constants + arm mapping
+└─────────────────────────────────────────┘
+```
+
+## Features
+
+- **pymycobot-compatible API** — drop-in replacement for pymycobot with Feetech STS servos
+- **Thread-safe** — all serial communication is locked and safe for multi-threaded use
+- **Joint calibration** — offset calibration, encoder centering
+- **Dual-motor joints** — supports joints driven by two servos (e.g. shoulder)
+- **Sync read/write** — efficient batch operations for all servos
+- **Auto port detection** — finds servo controllers automatically
+
+## Requirements
+
+- Python >= 3.8
+- pyserial >= 3.5
+
+## Documentation
+
+- [API Reference (English)](API_REFERENCE_EN.md)
+- [API Reference (Chinese)](API_REFERENCE.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

pymyarm-0.0.3/README.md

@@ -0,0 +1,74 @@
+# pymyarm
+
+pymycobot-compatible Python API for Feetech STS servo-based robotic arms.
+
+## Installation
+
+```bash
+pip install pymyarm
+```
+
+## Quick Start
+
+```python
+from pymyarm import MyArmSTS
+
+arm = MyArmSTS(port="/dev/ttyACM0", baudrate=1000000)
+arm.connect()
+
+# Read all joint angles
+angles = arm.get_angles()
+print(angles)
+
+# Move joints
+arm.set_angles([0, 0, 0, 0, 0, 0], speed=200)
+
+# Read encoder values
+encoders = arm.get_servos_encoder()
+
+# Control gripper
+arm.set_gripper_value(50, speed=200)
+
+arm.disconnect()
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│            MyArmSTS (myarm_sts.py)      │  User API: angles, encoders, gripper
+├─────────────────────────────────────────┤
+│  STS (sts.py)      conversion.py        │  Register-level ops + unit conversion
+├─────────────────────────────────────────┤
+│          ServoController                │  Thread-safe TX/RX, retries, error cache
+│          (servo_controller.py)          │
+├─────────────────────────────────────────┤
+│  protocol.py            port.py         │  Frame encoding/decoding + serial I/O
+├─────────────────────────────────────────┤
+│  constants.py       joint_config.py     │  Protocol constants + arm mapping
+└─────────────────────────────────────────┘
+```
+
+## Features
+
+- **pymycobot-compatible API** — drop-in replacement for pymycobot with Feetech STS servos
+- **Thread-safe** — all serial communication is locked and safe for multi-threaded use
+- **Joint calibration** — offset calibration, encoder centering
+- **Dual-motor joints** — supports joints driven by two servos (e.g. shoulder)
+- **Sync read/write** — efficient batch operations for all servos
+- **Auto port detection** — finds servo controllers automatically
+
+## Requirements
+
+- Python >= 3.8
+- pyserial >= 3.5
+
+## Documentation
+
+- [API Reference (English)](API_REFERENCE_EN.md)
+- [API Reference (Chinese)](API_REFERENCE.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

pymyarm-0.0.3/pymyarm/__init__.py

@@ -0,0 +1,36 @@
+"""pymyarm public API."""
+
+from .conversion import angle_to_encoder, encoder_to_angle
+from .exceptions import (
+    CommunicationError,
+    ConnectionError,
+    InvalidParameterError,
+    NoResponseError,
+    NotImplementedFeatureError,
+    PyMyArmError,
+    ServoError,
+)
+from .joint_config import DEFAULT_ARM_CONFIG, ArmConfig, GripperConfig, JointConfig
+from .myarm_sts import MyArmSTS, ServoSnapshot
+from .port import find_servo_port
+
+__all__ = [
+    "MyArmSTS",
+    "ServoSnapshot",
+    "find_servo_port",
+    "ArmConfig",
+    "JointConfig",
+    "GripperConfig",
+    "DEFAULT_ARM_CONFIG",
+    "angle_to_encoder",
+    "encoder_to_angle",
+    "PyMyArmError",
+    "ConnectionError",
+    "CommunicationError",
+    "NoResponseError",
+    "InvalidParameterError",
+    "NotImplementedFeatureError",
+    "ServoError",
+]
+
+__version__ = "0.0.3"

pymyarm-0.0.3/pymyarm/constants.py

@@ -0,0 +1,89 @@
+"""Constants for Feetech STS protocol and arm defaults."""
+
+from __future__ import annotations
+
+HEADER = 0xFF
+BROADCAST_ID = 0xFE
+
+
+class Instruction:
+    """STS/SCS protocol instruction set."""
+
+    PING = 0x01
+    READ_DATA = 0x02
+    WRITE_DATA = 0x03
+    REG_WRITE = 0x04
+    ACTION = 0x05
+    RESET = 0x0A
+    POSITION_CALIBRATE = 0x0B
+    SYNC_READ = 0x82
+    SYNC_WRITE = 0x83
+
+
+class MemAddr:
+    """Common STS register addresses."""
+
+    ID = 0x05
+    BAUD_RATE = 0x06
+    PHASE = 0x12
+    OFFSET_POSITION = 0x1F
+    OPERATING_MODE = 0x21
+
+    TORQUE_ENABLE = 0x28
+    ACCELERATION = 0x29
+    GOAL_POSITION = 0x2A
+    GOAL_SPEED = 0x2E
+    LOCK_FLAG = 0x37
+
+    PRESENT_POSITION = 0x38
+    PRESENT_SPEED = 0x3A
+    PRESENT_LOAD = 0x3C
+    PRESENT_VOLTAGE = 0x3E
+    PRESENT_TEMPERATURE = 0x3F
+    STATUS = 0x41
+    MOVING_FLAG = 0x42
+    PRESENT_CURRENT = 0x45
+
+
+class TorqueEnable:
+    """Torque enable values."""
+
+    OFF = 0
+    ON = 1
+    DAMPING = 2
+    CALIBRATE_CENTER = 128
+
+
+class StatusBit:
+    """STS status bits."""
+
+    VOLTAGE_ERROR = 0x01
+    ENCODER_ERROR = 0x02
+    TEMPERATURE_ERROR = 0x04
+    CURRENT_ERROR = 0x08
+    OVERLOAD_ERROR = 0x20
+
+    # Errors that invalidate position read data.
+    # Only ENCODER_ERROR means the encoder value itself is unreliable.
+    # Other errors (voltage, temperature, current, overload) are status
+    # warnings — the encoder hardware still returns valid readings.
+    READ_INVALIDATING_ERRORS = ENCODER_ERROR
+
+
+class ServoParams:
+    """STS conversion constants."""
+
+    POSITION_MIN = 0
+    POSITION_MAX = 4095
+    POSITION_CENTER = 2048
+    POSITION_RESOLUTION_DEG = 0.087
+
+    SPEED_RESOLUTION_RPM = 0.732
+    VOLTAGE_RESOLUTION_V = 0.1
+    CURRENT_RESOLUTION_MA = 6.5
+
+
+DEFAULT_BAUDRATE = 1_000_000
+DEFAULT_TIMEOUT = 0.1
+DEFAULT_RETRIES = 2
+SYNC_READ_FRAME_BUDGET = 16

pymyarm-0.0.3/pymyarm/conversion.py

@@ -0,0 +1,56 @@
+"""Conversion helpers for encoder/angle/speed units."""
+
+from __future__ import annotations
+
+from .constants import ServoParams
+
+
+def clamp(value: float, min_value: float, max_value: float) -> float:
+    """Clamp numeric value to [min_value, max_value]."""
+    return max(min_value, min(value, max_value))
+
+
+def encoder_to_angle(
+    encoder: int, offset: int = ServoParams.POSITION_CENTER, direction: int = 1
+) -> float:
+    """Convert encoder value to joint angle in degrees."""
+    delta = encoder - offset
+    return round(delta * ServoParams.POSITION_RESOLUTION_DEG * direction, 3)
+
+
+def angle_to_encoder(
+    angle: float, offset: int = ServoParams.POSITION_CENTER, direction: int = 1
+) -> int:
+    """Convert joint angle in degrees to encoder value (0-4095)."""
+    raw = int(offset + angle / ServoParams.POSITION_RESOLUTION_DEG / direction)
+    return int(clamp(raw, ServoParams.POSITION_MIN, ServoParams.POSITION_MAX))
+
+
+def angles_to_encoders(
+    angles: list[float], offsets: list[int], directions: list[int]
+) -> list[int]:
+    """Batch angle->encoder conversion."""
+    return [
+        angle_to_encoder(angle, offset, direction)
+        for angle, offset, direction in zip(angles, offsets, directions)
+    ]
+
+
+def encoders_to_angles(
+    encoders: list[int], offsets: list[int], directions: list[int]
+) -> list[float]:
+    """Batch encoder->angle conversion."""
+    return [
+        encoder_to_angle(encoder, offset, direction)
+        for encoder, offset, direction in zip(encoders, offsets, directions)
+    ]
+
+
+def voltage_raw_to_v(raw: int) -> float:
+    """Convert raw voltage register to volts."""
+    return round(raw * ServoParams.VOLTAGE_RESOLUTION_V, 3)
+
+
+def current_raw_to_ma(raw: int) -> float:
+    """Convert raw current register to mA."""
+    return round(raw * ServoParams.CURRENT_RESOLUTION_MA, 3)

pymyarm-0.0.3/pymyarm/exceptions.py

@@ -0,0 +1,44 @@
+"""Custom exceptions for pymyarm."""
+
+
+class PyMyArmError(Exception):
+    """Base exception for pymyarm."""
+
+
+class ConnectionError(PyMyArmError):
+    """Raised when serial connection is not available."""
+
+
+class CommunicationError(PyMyArmError):
+    """Raised when protocol communication fails."""
+
+
+class NoResponseError(CommunicationError):
+    """Raised when a servo does not respond at all."""
+
+
+class TimeoutError(PyMyArmError):
+    """Raised when response timeout occurs."""
+
+
+class InvalidParameterError(PyMyArmError):
+    """Raised when user input parameter is invalid."""
+
+
+class NotImplementedFeatureError(PyMyArmError):
+    """Raised when feature is intentionally unsupported on this hardware."""
+
+    def __init__(self, feature: str) -> None:
+        super().__init__(
+            f"Feature '{feature}' is not supported on current STS implementation."
+        )
+
+
+class ServoError(PyMyArmError):
+    """Raised when servo status/error byte indicates failure."""
+
+    def __init__(self, servo_id: int, error_code: int, message: str = "") -> None:
+        detail = f"Servo {servo_id} error 0x{error_code:02X}"
+        if message:
+            detail = f"{detail}: {message}"
+        super().__init__(detail)

pymyarm-0.0.3/pymyarm/joint_config.py

@@ -0,0 +1,98 @@
+"""Arm joint and motor mapping configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class JointConfig:
+    """Single joint mapping config."""
+
+    joint_id: int
+    motor_ids: list[int]
+    is_dual_motor: bool = False
+    encoder_offset: int = 2048
+    direction: int = 1
+    min_angle: float = -180.0
+    max_angle: float = 180.0
+
+    def primary_motor_id(self) -> int:
+        """Return primary motor ID."""
+        return self.motor_ids[0]
+
+
+@dataclass
+class GripperConfig:
+    """Gripper mapping config."""
+
+    motor_id: int = 8
+    open_encoder: int = 0
+    close_encoder: int = 4095
+
+
+@dataclass
+class ArmConfig:
+    """Arm-level mapping config."""
+
+    dof: int = 6
+    joints: list[JointConfig] = field(default_factory=list)
+    gripper: GripperConfig | None = None
+
+    def get_joint(self, joint_id: int) -> JointConfig | None:
+        """Get joint config by ID."""
+        for joint in self.joints:
+            if joint.joint_id == joint_id:
+                return joint
+        return None
+
+    def all_servo_ids(self, include_gripper: bool = True) -> list[int]:
+        """Get all servo IDs in arm order."""
+        ids: list[int] = []
+        for joint in self.joints:
+            ids.extend(joint.motor_ids)
+        if include_gripper and self.gripper is not None:
+            ids.append(self.gripper.motor_id)
+        return ids
+
+    def joint_to_motor_pairs(
+        self, joint_id: int, encoder: int
+    ) -> list[tuple[int, int]]:
+        """Map joint target encoder to one/two motor target pairs."""
+        joint = self.get_joint(joint_id)
+        if joint is None:
+            raise ValueError(f"Invalid joint_id: {joint_id}")
+
+        if joint.is_dual_motor:
+            motor_a, motor_b = joint.motor_ids
+            return [(motor_a, encoder), (motor_b, 4096 - encoder)]
+        return [(joint.primary_motor_id(), encoder)]
+
+    def motor_offsets(self) -> list[int]:
+        """Return offsets for 1..dof joints."""
+        return [self.joints[i].encoder_offset for i in range(self.dof)]
+
+    def motor_directions(self) -> list[int]:
+        """Return directions for 1..dof joints."""
+        return [self.joints[i].direction for i in range(self.dof)]
+
+    def motor_id_for_joint_angle_read(self, joint_id: int) -> int:
+        """Read joint angle by primary motor ID."""
+        joint = self.get_joint(joint_id)
+        if joint is None:
+            raise ValueError(f"Invalid joint_id: {joint_id}")
+        return joint.primary_motor_id()
+
+
+DEFAULT_ARM_CONFIG = ArmConfig(
+    dof=6,
+    joints=[
+        JointConfig(1, [1], False, 2048, 1, -180.0, 180.0),
+        JointConfig(2, [2, 3], True, 2048, 1, -90.0, 90.0),
+        JointConfig(3, [4], False, 2048, 1, -150.0, 150.0),
+        JointConfig(4, [5], False, 2048, 1, -180.0, 180.0),
+        JointConfig(5, [6], False, 2048, 1, -180.0, 180.0),
+        JointConfig(6, [7], False, 2048, 1, -180.0, 180.0),
+    ],
+    gripper=GripperConfig(motor_id=8, open_encoder=0, close_encoder=4095),
+)