motor-python 0.0.9__tar.gz → 0.0.11__tar.gz

{motor_python-0.0.9 → motor_python-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: motor_python
-Version: 0.0.9
+Version: 0.0.11
 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>

{motor_python-0.0.9 → motor_python-0.0.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "motor_python"
-version = "0.0.9"
+version = "0.0.11"
 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.9 → motor_python-0.0.11}/src/motor_python/__init__.py

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

motor_python-0.0.11/src/motor_python/can_utils.py

@@ -0,0 +1,275 @@
+"""CAN Network Utilities for Linux (Jetson).
+
+Three operations on the interface, in increasing order of violence:
+
+* :func:`get_can_state` reads the controller's error state and counters;
+* :func:`ensure_can_interface` raises the link if it is down, and leaves it
+  strictly alone if it is already up at the right bitrate;
+* :func:`reset_can_interface` reloads the kernel module, which is the only
+  thing that clears latched error counters on the Orin's mttcan controller.
+
+Reach for the lightest one that answers the problem. Reconfiguring a working
+bus is not free: taking the link down and up resets the controller and can
+drop a motor into BUS-OFF.
+"""
+
+import shutil
+import subprocess
+import time
+
+from loguru import logger
+
+from motor_python.definitions import CAN_DEFAULTS
+
+
+def get_can_state(interface: str = "can0") -> dict:
+    """Parse CAN controller state from the kernel via `ip` command.
+
+    :param interface: CAN interface name (e.g. 'can0').
+    :return: Dict with keys 'state', 'tx_err', 'rx_err'.
+    """
+    try:
+        result = subprocess.run(
+            ["ip", "-details", "-statistics", "link", "show", interface],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        output = result.stdout
+        state = "UNKNOWN"
+        tx_err = rx_err = 0
+        for line in output.splitlines():
+            if "state" in line and "berr-counter" in line:
+                for part in line.split():
+                    if part in (
+                        "ERROR-ACTIVE",
+                        "ERROR-PASSIVE",
+                        "ERROR-WARNING",
+                        "BUS-OFF",
+                    ):
+                        state = part
+                if "tx" in line:
+                    idx = line.index("tx")
+                    tx_err = int(line[idx:].split()[1])
+                if "rx" in line:
+                    idx = line.index("rx")
+                    rx_err = int(line[idx:].split()[1].rstrip(")"))
+        return {"state": state, "tx_err": tx_err, "rx_err": rx_err}
+    except Exception as e:
+        logger.debug(f"Could not read CAN state: {e}")
+        return {"state": "UNKNOWN", "tx_err": 0, "rx_err": 0}
+
+
+def reset_can_interface(interface: str = "can0", bitrate: int = 1000000) -> bool:
+    """Fully reset the CAN interface by reloading the mttcan kernel module.
+
+    ``ip link set down/up`` does NOT reset TX/RX error counters on the
+    Jetson Orin Nano mttcan controller and causes a CAN bus disruption
+    that can push the motor into BUS-OFF (completely silent).  This method
+    instead:
+
+    1. Takes the interface down.
+    2. Unloads the mttcan module — the bus is silent during unload, giving
+       the motor's CAN controller time to see the 128×11 recessive bits
+       required by the CAN spec to recover from BUS-OFF.
+    3. Reloads the module and brings the interface back up.
+
+    :param interface: CAN interface name (e.g. 'can0').
+    :param bitrate: Desired bitrate (e.g. 1000000).
+    :return: True if successful, False if the commands fail (e.g. no sudo).
+    """
+    logger.warning(
+        f"Performing full kernel-level reset of {interface} to clear error states..."
+    )
+    cmds = [
+        f"sudo ip link set {interface} down",
+        "sudo rmmod mttcan",
+        "sleep 0.5",  # Let bus stay recessive so nodes can recover
+        "sudo modprobe mttcan",
+        # Keep runtime reset behavior aligned with setup_can.sh.
+        f"sudo ip link set {interface} up type can bitrate {bitrate} berr-reporting on restart-ms 100",
+        f"sudo ip link set {interface} txqueuelen 1000",
+    ]
+    try:
+        for cmd in cmds:
+            if cmd == "sleep 0.5":
+                time.sleep(0.5)
+            else:
+                subprocess.run(cmd.split(), check=True)
+            time.sleep(0.1)
+        logger.success(f"CAN interface {interface} reset successfully.")
+        return True
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to reset CAN interface: {e}")
+        return False
+
+
+def _run(command: list[str], timeout: float) -> subprocess.CompletedProcess | None:
+    """Run a command, returning None if it could not be run at all.
+
+    :param command: Argument vector.
+    :param timeout: Seconds to wait before giving up.
+    :return: The finished process, or None if it could not run.
+    """
+    try:
+        # check=False: a non-zero exit is information here, not an exception.
+        # The caller reads returncode and reports it with the interface's name.
+        return subprocess.run(
+            command, capture_output=True, text=True, timeout=timeout, check=False
+        )
+    except (OSError, subprocess.SubprocessError) as err:
+        logger.debug(f"Could not run {' '.join(command)}: '{err}'.")
+        return None
+
+
+def read_can_interface(
+    interface: str = CAN_DEFAULTS.interface,
+) -> tuple[bool, bool, int | None]:
+    """Report what the kernel currently thinks of a CAN interface.
+
+    :param interface: CAN interface name (e.g. 'can0').
+    :return: ``(exists, is_up, bitrate)``; bitrate is None when unreadable.
+    :rtype: tuple[bool, bool, int | None]
+    """
+    result = _run(
+        ["ip", "-details", "link", "show", interface],
+        CAN_DEFAULTS.can_command_timeout_s,
+    )
+    if result is None or result.returncode != 0:
+        return False, False, None
+
+    output = result.stdout
+    # The flags live in angle brackets on the first line. "UP" also appears in
+    # "state UP" further along, but the flag is the authoritative one -- an
+    # interface can carry the UP flag while its state reads UNKNOWN, which is
+    # normal for CAN.
+    first_line = output.splitlines()[0] if output else ""
+    is_up = "UP" in first_line.split("<")[-1].split(">")[0].split(",")
+
+    bitrate = None
+    fields = output.split()
+    if "bitrate" in fields:
+        try:
+            bitrate = int(fields[fields.index("bitrate") + 1])
+        except (IndexError, ValueError):
+            bitrate = None
+    return True, is_up, bitrate
+
+
+def ensure_can_interface(
+    interface: str = CAN_DEFAULTS.interface,
+    bitrate: int = CAN_DEFAULTS.bitrate,
+) -> bool:
+    """Make sure a CAN interface is up at the given bitrate, raising it if not.
+
+    Callers otherwise have to remember ``sudo ./setup_can.sh`` after every power
+    cycle, and forgetting it presents as a motor that will not answer -- which
+    sends you to the wiring for a fault that is one command away.
+
+    **Idempotent**: an interface already up at the right bitrate is left
+    untouched. That is the point of the check rather than a shortcut through
+    it, because bringing a working link down and up resets the controller and
+    can drop a motor into BUS-OFF.
+
+    This does not reload the ``mttcan`` module; see
+    :func:`reset_can_interface` for that, which is the right tool once error
+    counters have latched and the wrong one to use unasked at startup.
+
+    :param interface: CAN interface name (e.g. 'can0').
+    :param bitrate: Desired bitrate in bits/sec.
+    :return: True if the interface is usable afterwards.
+    :rtype: bool
+    """
+    if shutil.which("ip") is None:
+        logger.debug(
+            "No 'ip' command, so this is not a Linux host. Skipping CAN setup."
+        )
+        return False
+
+    exists, is_up, current_bitrate = read_can_interface(interface)
+    if not exists:
+        logger.error(
+            f"No CAN interface '{interface}'. The mttcan kernel module is "
+            f"probably not loaded; run setup_can.sh once, which modprobes it."
+        )
+        return False
+
+    if is_up and current_bitrate == bitrate:
+        logger.info(
+            f"CAN interface '{interface}' is already up at {bitrate} bps. "
+            f"Leaving it alone."
+        )
+        return True
+
+    reason = "down" if not is_up else f"at {current_bitrate} bps rather than {bitrate}"
+    logger.warning(f"CAN interface '{interface}' is {reason}. Bringing it up.")
+    return _bring_up_can_interface(interface, bitrate)
+
+
+def _bring_up_can_interface(interface: str, bitrate: int) -> bool:
+    """Configure and raise the interface.
+
+    ``sudo -n`` throughout: a control process must not stop at a password
+    prompt, so a host without passwordless sudo fails immediately and says so
+    rather than hanging until something times out.
+
+    :param interface: CAN interface name.
+    :param bitrate: Desired bitrate in bits/sec.
+    :return: True if the interface came up at the requested bitrate.
+    :rtype: bool
+    """
+    timeout = CAN_DEFAULTS.can_command_timeout_s
+    commands = [
+        # Down first: "up type can bitrate ..." is rejected on an interface that
+        # is already up, which is the case when only the bitrate is wrong.
+        ["sudo", "-n", "ip", "link", "set", interface, "down"],
+        [
+            "sudo",
+            "-n",
+            "ip",
+            "link",
+            "set",
+            interface,
+            "up",
+            "type",
+            "can",
+            "bitrate",
+            str(bitrate),
+            "berr-reporting",
+            "on",
+            "restart-ms",
+            str(CAN_DEFAULTS.can_restart_ms),
+        ],
+        [
+            "sudo",
+            "-n",
+            "ip",
+            "link",
+            "set",
+            interface,
+            "txqueuelen",
+            str(CAN_DEFAULTS.can_tx_queue_length),
+        ],
+    ]
+
+    for command in commands:
+        result = _run(command, timeout)
+        if result is None or result.returncode != 0:
+            detail = (result.stderr or result.stdout).strip() if result else "not run"
+            logger.error(
+                f"Could not bring up '{interface}': '{detail}'. Run "
+                f"scripts/allow_can_bringup_without_password.sh once to fix this "
+                f"permanently, or setup_can.sh with sudo for just this boot."
+            )
+            return False
+
+    _, is_up, current_bitrate = read_can_interface(interface)
+    if not (is_up and current_bitrate == bitrate):
+        logger.error(
+            f"'{interface}' did not come up as asked: up={is_up}, "
+            f"bitrate={current_bitrate}."
+        )
+        return False
+
+    logger.success(f"CAN interface '{interface}' up at {bitrate} bps.")
+    return True

{motor_python-0.0.9 → motor_python-0.0.11}/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 "

{motor_python-0.0.9 → motor_python-0.0.11}/src/motor_python/definitions.py

@@ -98,6 +98,18 @@ class CANDefaults:
     retry_backoff: float = 0.01  # Base backoff time for retries (seconds)
     can_reset_pause: float = 0.1  # Small Pause after CAN bus reset (seconds)
 
+    # Link settings used when raising the interface, matching setup_can.sh.
+    # berr-reporting and restart-ms are what let the controller restart itself
+    # out of BUS-OFF -- a single unacknowledged frame is enough to cause it, and
+    # without these the interface goes permanently silent instead of recovering.
+    can_restart_ms: int = 100
+    # The kernel default of 10 is too shallow for a 100 Hz control loop driving
+    # two motors.
+    can_tx_queue_length: int = 1000
+    # Per `ip` invocation. Generous for a command that returns immediately, and
+    # short enough that a host which cannot run it does not stall startup.
+    can_command_timeout_s: float = 5.0
+
 
 @dataclass(frozen=True)
 class MITModeLimits:

motor_python-0.0.9/src/motor_python/can_utils.py

@@ -1,88 +0,0 @@
-"""CAN Network Utilities for Linux (Jetson)."""
-
-import subprocess
-import time
-
-from loguru import logger
-
-
-def get_can_state(interface: str = "can0") -> dict:
-    """Parse CAN controller state from the kernel via `ip` command.
-
-    :param interface: CAN interface name (e.g. 'can0').
-    :return: Dict with keys 'state', 'tx_err', 'rx_err'.
-    """
-    try:
-        result = subprocess.run(
-            ["ip", "-details", "-statistics", "link", "show", interface],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        output = result.stdout
-        state = "UNKNOWN"
-        tx_err = rx_err = 0
-        for line in output.splitlines():
-            if "state" in line and "berr-counter" in line:
-                for part in line.split():
-                    if part in (
-                        "ERROR-ACTIVE",
-                        "ERROR-PASSIVE",
-                        "ERROR-WARNING",
-                        "BUS-OFF",
-                    ):
-                        state = part
-                if "tx" in line:
-                    idx = line.index("tx")
-                    tx_err = int(line[idx:].split()[1])
-                if "rx" in line:
-                    idx = line.index("rx")
-                    rx_err = int(line[idx:].split()[1].rstrip(")"))
-        return {"state": state, "tx_err": tx_err, "rx_err": rx_err}
-    except Exception as e:
-        logger.debug(f"Could not read CAN state: {e}")
-        return {"state": "UNKNOWN", "tx_err": 0, "rx_err": 0}
-
-
-def reset_can_interface(interface: str = "can0", bitrate: int = 1000000) -> bool:
-    """Fully reset the CAN interface by reloading the mttcan kernel module.
-
-    ``ip link set down/up`` does NOT reset TX/RX error counters on the
-    Jetson Orin Nano mttcan controller and causes a CAN bus disruption
-    that can push the motor into BUS-OFF (completely silent).  This method
-    instead:
-
-    1. Takes the interface down.
-    2. Unloads the mttcan module — the bus is silent during unload, giving
-       the motor's CAN controller time to see the 128×11 recessive bits
-       required by the CAN spec to recover from BUS-OFF.
-    3. Reloads the module and brings the interface back up.
-
-    :param interface: CAN interface name (e.g. 'can0').
-    :param bitrate: Desired bitrate (e.g. 1000000).
-    :return: True if successful, False if the commands fail (e.g. no sudo).
-    """
-    logger.warning(
-        f"Performing full kernel-level reset of {interface} to clear error states..."
-    )
-    cmds = [
-        f"sudo ip link set {interface} down",
-        "sudo rmmod mttcan",
-        "sleep 0.5",  # Let bus stay recessive so nodes can recover
-        "sudo modprobe mttcan",
-        # Keep runtime reset behavior aligned with setup_can.sh.
-        f"sudo ip link set {interface} up type can bitrate {bitrate} berr-reporting on restart-ms 100",
-        f"sudo ip link set {interface} txqueuelen 1000",
-    ]
-    try:
-        for cmd in cmds:
-            if cmd == "sleep 0.5":
-                time.sleep(0.5)
-            else:
-                subprocess.run(cmd.split(), check=True)
-            time.sleep(0.1)
-        logger.success(f"CAN interface {interface} reset successfully.")
-        return True
-    except subprocess.CalledProcessError as e:
-        logger.error(f"Failed to reset CAN interface: {e}")
-        return False