motor-python 0.0.8__tar.gz → 0.0.10__tar.gz

{motor_python-0.0.8 → motor_python-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: motor_python
-Version: 0.0.8
+Version: 0.0.10
 Summary: CubeMars motor module for Aries exosuits.
 Project-URL: homepage, https://github.com/TUM-Aries-Lab/motor-module
 Author-email: Tsmorz <tony.smoragiewicz@tum.de>, Hannes Nguyen <hannes.nguyen@tum.de>
@@ -149,10 +149,10 @@ from motor_python.cube_mars_motor import CubeMarsAK606v3
 | Method | Purpose |
 | --- | --- |
 | `set_position(position_degrees)` | MIT-backed position command |
-| `set_velocity(velocity_erpm, allow_low_speed=False)` | MIT-backed velocity command |
+| `set_velocity(velocity_erpm)` | MIT-backed velocity command. Zero releases the motor via `stop()` |
 | `set_current(current_amps)` | Interpreted as MIT torque feedforward |
 | `set_mit_mode(pos_rad, vel_rad_s, kp, kd, torque_ff_nm)` | Direct MIT command |
-| `stop()` | Neutral MIT command and disable |
+| `stop()` | Neutral MIT command, disable MIT mode, release the motor |
 
 ## Useful Bench Scripts
 

{motor_python-0.0.8 → motor_python-0.0.10}/README.md

@@ -135,10 +135,10 @@ from motor_python.cube_mars_motor import CubeMarsAK606v3
 | Method | Purpose |
 | --- | --- |
 | `set_position(position_degrees)` | MIT-backed position command |
-| `set_velocity(velocity_erpm, allow_low_speed=False)` | MIT-backed velocity command |
+| `set_velocity(velocity_erpm)` | MIT-backed velocity command. Zero releases the motor via `stop()` |
 | `set_current(current_amps)` | Interpreted as MIT torque feedforward |
 | `set_mit_mode(pos_rad, vel_rad_s, kp, kd, torque_ff_nm)` | Direct MIT command |
-| `stop()` | Neutral MIT command and disable |
+| `stop()` | Neutral MIT command, disable MIT mode, release the motor |
 
 ## Useful Bench Scripts
 

{motor_python-0.0.8 → motor_python-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "motor_python"
-version = "0.0.8"
+version = "0.0.10"
 description = "CubeMars motor module for Aries exosuits."
 readme = "README.md"
 authors = [{ name = "Tsmorz", email = "tony.smoragiewicz@tum.de"},{ name = "Hannes Nguyen", email = "hannes.nguyen@tum.de" }]

{motor_python-0.0.8 → motor_python-0.0.10}/src/motor_python/__init__.py

@@ -5,7 +5,7 @@ Legacy UART interface: CubeMarsAK606v3.
 Base class: BaseMotor (for shared interface & safety logic).
 """
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"
 
 from typing import Literal
 

{motor_python-0.0.8 → motor_python-0.0.10}/src/motor_python/cube_mars_motor_can.py

@@ -1282,10 +1282,17 @@ class CubeMarsBaseCAN(BaseMotor):
         return None
 
     def send_neutral_command(self) -> None:
-        """Return latest parsed motor telemetry.
+        """Send the enter-motor-mode frame.
 
-        Per CubeMars manual AK80-6 (Page 41): re-sending the enter MIT command
-        returns current state in a stateless manner.
+        The name and the docstring this replaced were both wrong -- it was
+        described as returning telemetry, copied from get_status(). What it
+        sends is FF..FC, the MIT enter-motor-mode helper, which is why calling
+        it was the difference between a motor that produced torque and one
+        that accepted every command and produced none.
+
+        Nothing here is neutral. Prefer enable_mit_mode(), which sends the
+        same frame and reports whether the motor answered; this remains for
+        callers that want the frame alone.
         """
         if not self.connected:
             return
@@ -1412,13 +1419,13 @@ class CubeMarsBaseCAN(BaseMotor):
 
         self._mit_enabled = False
         neutral = self._mit_neutral_payload()
-        feedback_before = self._last_feedback_monotonic
-        sent = self._send_mit_payload(neutral, capture_response=True)
-        if sent and self._last_feedback_monotonic > feedback_before:
-            self._mit_enabled = True
-            logger.info("MIT mode ready via direct MIT command handshake")
-            return
 
+        # The helper frame is what actually enters motor mode. It is sent
+        # first, not as a fallback, because fresh feedback cannot tell an
+        # enabled motor from a disabled one: the motor answers an MIT-format
+        # frame either way. Concluding from that alone reported success
+        # against a motor that then produced no torque -- commands accepted,
+        # position and speed reported, torque frozen at one value.
         helper_frames: list[tuple[str, bytes]] = []
         if self._helper_policy in {"fcfd", "legacy"}:
             helper_frames.append(("FF..FC", self._CAN_HELPER_ENABLE))
@@ -1427,10 +1434,14 @@ class CubeMarsBaseCAN(BaseMotor):
 
         for label, frame in helper_frames:
             logger.debug(f"Attempting MIT handshake with helper frame {label}")
+            # No response captured: the helper is a fire-and-forget command
+            # and proves nothing by replying. The MIT payload below is what
+            # the enable is verified against, so demanding a reply here would
+            # only add a second thing to go wrong.
             helper_sent = self._send_raw(
                 arbitration_id=self.motor_can_id,
                 data=frame,
-                capture_response=True,
+                capture_response=False,
             )
             if not helper_sent:
                 continue
@@ -1442,6 +1453,22 @@ class CubeMarsBaseCAN(BaseMotor):
                 logger.info(f"MIT mode ready after helper frame {label}")
                 return
 
+        # No helper frame is available under the strict policy, and under the
+        # others none got through. Falling back to the direct handshake keeps
+        # those callers working, but it proves only that the motor is
+        # answering -- so say so rather than logging readiness.
+        feedback_before = self._last_feedback_monotonic
+        sent = self._send_mit_payload(neutral, capture_response=True)
+        if sent and self._last_feedback_monotonic > feedback_before:
+            self._mit_enabled = True
+            logger.warning(
+                "MIT mode assumed ready from a direct command handshake: the "
+                "motor is answering, but nothing confirms it entered motor "
+                "mode, and a disabled motor answers identically. Expect "
+                "commands to be accepted and produce no torque if it did not."
+            )
+            return
+
         can_state = self._read_can_state(force=True)
         raise RuntimeError(
             "Failed to enable MIT mode: no fresh feedback observed after MIT handshake "
@@ -1503,7 +1530,26 @@ class CubeMarsBaseCAN(BaseMotor):
         - Extended ID: ``(0x08 << 8) | motor_id``
         - Payload order: ``KP, KD, Position, Speed, Torque`` bit-packed in 8 bytes.
         - Limits are taken from the currently selected motor profile.
+
+        Gains are not defaulted to anything torque-producing on purpose: a
+        caller asking for a pure feed-forward torque needs ``kd`` to stay at
+        zero, and changing that would alter the torque every correct caller
+        already gets. A velocity commanded with ``kd`` at zero cannot act
+        though -- see the warning below -- so that case is reported rather
+        than silently absorbed.
         """
+        if vel_rad_s != 0.0 and kd == 0.0:
+            # tau = t_ff + kp * pos_err + kd * vel_err, so with kd at zero the
+            # velocity term contributes nothing and the command cannot make
+            # the motor turn. Nothing else reports this: the frame is valid,
+            # the motor answers normally, and the shaft simply does not move.
+            logger.warning(
+                f"MIT command carries {vel_rad_s:.3f} rad/s with kd=0, so the "
+                f"velocity term produces no torque and the motor will not "
+                f"follow it. Pass kd explicitly (this motor's profile value is "
+                f"{self._mit_velocity_kd}) or call set_velocity()."
+            )
+
         if not self.connected:
             logger.warning("Cannot send MIT command - CAN bus not connected")
             return