motor-python 0.0.4__tar.gz → 0.0.7__tar.gz

{motor_python-0.0.4 → motor_python-0.0.7}/.gitignore

@@ -170,3 +170,20 @@ cython_debug/
 *.egg-info
 
 /logs/log_*
+
+# Motion capture logs and plots
+data/logs/
+
+# Local thesis / working documents that should not go to main
+docs/*.md
+docs/**/*.md
+docs/*.tex
+docs/**/*.tex
+tmp/
+
+# Local analysis/workspace artifacts
+.codex
+CSV/
+data/csv_logs/*.csv
+!data/csv_logs/.gitkeep
+repo_tree.py

motor_python-0.0.7/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: motor_python
+Version: 0.0.7
+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>
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: pyserial>=3.5
+Requires-Dist: python-can>=4.4.0
+Description-Content-Type: text/markdown
+
+# Motor Control Software for Soft Exoskeleton
+[![Coverage Status](https://coveralls.io/repos/github/TUM-Aries-Lab/motor-module/badge.svg?branch=main)](https://coveralls.io/github/TUM-Aries-Lab/motor-module?branch=main)
+![Docker Image CI](https://github.com/TUM-Aries-Lab/motor-module/actions/workflows/ci.yml/badge.svg)
+
+Motor control for the CubeMars AK60-6 actuator module used in Aries soft-exosuit development.
+
+## Current Status
+
+- Primary interface: CAN on Jetson Orin Nano via Linux SocketCAN
+- Current maintained CAN path: MIT-only control
+- Supported high-level helpers: `set_position()`, `set_velocity()`, `set_current()`, `stop()`
+- UART support remains available for compatibility and earlier bring-up workflows
+
+This repository is the motor-module codebase, not a full exosuit application. Its current focus is a modular actuator-control layer plus the bench-side scripts used to validate it.
+
+## Key Features
+
+- Transport-independent motor abstraction through `BaseMotor`
+- Maintained SocketCAN backend for the CubeMars AK60-6
+- MIT-only CAN control path with one consistent command model
+- Background command refresh, feedback decoding, cached state handling, and staged recovery
+- Bench-validation scripts for MIT mode, position stepping, velocity verification, and plotting
+
+## Installation
+
+For normal development, testing, and analysis:
+
+```bash
+uv sync --all-groups
+source .venv/bin/activate
+```
+
+If you only want to install the package itself:
+
+```bash
+uv pip install -e .
+```
+
+## CAN Setup on Jetson Orin Nano
+
+### Recommended: systemd startup
+
+Install the tracked `can0.service` once so `can0` comes up automatically on boot:
+
+```bash
+sudo cp can0.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable can0.service
+sudo systemctl start can0.service
+```
+
+This brings `can0` up at 1 Mbps with bus-off auto-recovery.
+
+Useful checks:
+
+```bash
+systemctl status can0.service
+sudo systemctl restart can0.service
+ip -details link show can0
+```
+
+### Manual setup
+
+If you do not want to use the service, configure the interface manually:
+
+```bash
+sudo ./setup_can.sh
+```
+
+## Important Hardware Note
+
+If the R-Link / UART cable is connected to the motor, CAN commands may be silently ignored even though feedback frames are still visible on the bus. For CAN operation, disconnect the UART cable and then reset the CAN interface.
+
+## Recommended Workflow
+
+### 1. Confirm MIT/CAN communication
+
+```bash
+sudo ./setup_can.sh
+.venv/bin/python scripts/mit_mode_test.py --motor-id 0x03
+```
+
+### 2. Validate sustained velocity behavior
+
+```bash
+.venv/bin/python scripts/verify_set_velocity.py --motor-id 0x03 --velocity-erpm 3000
+```
+
+### 3. Run repeated MIT position stepping
+
+```bash
+.venv/bin/python scripts/mit_position_steps.py --motor-id 0x03 --duration 180 --angle-deg 50 --velocity-deg-s 100
+```
+
+### 4. Generate comparison plots from recorded CSV files
+
+```bash
+.venv/bin/python scripts/plot_graph.py velocity --data-root CSV --out-dir CSV/plots
+.venv/bin/python scripts/plot_graph.py position --data-root CSV --out-dir CSV/plots
+```
+
+## Python API
+
+The default convenience alias is the CAN motor class:
+
+```python
+from motor_python import Motor
+
+with Motor(motor_can_id=0x03) as motor:
+    motor.enable_mit_mode()
+    motor.set_velocity(3000)
+    motor.set_position(90.0)
+    motor.stop()
+```
+
+For direct access to the specific implementations:
+
+```python
+from motor_python.cube_mars_motor_can import CubeMarsAK606v3CAN
+from motor_python.cube_mars_motor import CubeMarsAK606v3
+```
+
+### Main CAN lifecycle methods
+
+| Method | Purpose |
+| --- | --- |
+| `enable_mit_mode()` | Enter MIT mode |
+| `disable_mit_mode()` | Exit MIT mode |
+| `check_communication()` | Verify that the motor responds on the bus |
+| `get_status()` | Return the latest cached `MotorState` |
+| `close()` | Stop and close transport resources |
+
+### Main CAN control methods
+
+| Method | Purpose |
+| --- | --- |
+| `set_position(position_degrees)` | MIT-backed position command |
+| `set_velocity(velocity_erpm, allow_low_speed=False)` | MIT-backed velocity command |
+| `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 |
+
+## Useful Bench Scripts
+
+These are the maintained scripts that matter most for the current implementation:
+
+| Script | Purpose |
+| --- | --- |
+| `scripts/mit_mode_test.py` | Focused MIT/CAN protocol validation |
+| `scripts/verify_set_velocity.py` | Bench verification of `set_velocity()` |
+| `scripts/mit_position_steps.py` | Long-run MIT position stepping for bench tests |
+| `scripts/plot_graph.py` | Chapter-4-style overlay and summary plots from recorded CSV files |
+| `scripts/diagnose_can.py` | CAN bus diagnostics and recovery support |
+| `scripts/scan_ids.py` | CAN ID discovery |
+| `scripts/reset_degree.py` | Practical MIT recentering helper |
+
+Additional exploratory and legacy scripts remain under `scripts/`, but they are not the primary maintained validation path.
+
+## Testing
+
+Run unit tests:
+
+```bash
+make test
+```
+
+Run CAN hardware tests:
+
+```bash
+make test-hardware-can
+```
+
+Run all hardware tests:
+
+```bash
+make test-hardware-all
+```
+
+## Project Structure
+
+```text
+can0.service                    systemd unit for automatic can0 startup
+setup_can.sh                    manual CAN setup and reset helper
+src/motor_python/               package source
+scripts/                        bench and validation scripts
+tests/                          unit and hardware-oriented tests
+data/csv_logs/.gitkeep          placeholder for locally generated CSV logs
+Test Rig CAD files/             CAD assets for the bench rig
+```
+
+## Notes on Scope
+
+- The current CAN implementation is MIT-only.
+- Legacy servo transport modes are intentionally not part of the maintained CAN path.
+- The repository includes bench-validation tooling, but not thesis-only notes, temporary files, or local analysis artifacts.
+
+## Run the Package Entry Point
+
+```bash
+uv run python -m motor_python
+```

motor_python-0.0.7/README.md

@@ -0,0 +1,201 @@
+# Motor Control Software for Soft Exoskeleton
+[![Coverage Status](https://coveralls.io/repos/github/TUM-Aries-Lab/motor-module/badge.svg?branch=main)](https://coveralls.io/github/TUM-Aries-Lab/motor-module?branch=main)
+![Docker Image CI](https://github.com/TUM-Aries-Lab/motor-module/actions/workflows/ci.yml/badge.svg)
+
+Motor control for the CubeMars AK60-6 actuator module used in Aries soft-exosuit development.
+
+## Current Status
+
+- Primary interface: CAN on Jetson Orin Nano via Linux SocketCAN
+- Current maintained CAN path: MIT-only control
+- Supported high-level helpers: `set_position()`, `set_velocity()`, `set_current()`, `stop()`
+- UART support remains available for compatibility and earlier bring-up workflows
+
+This repository is the motor-module codebase, not a full exosuit application. Its current focus is a modular actuator-control layer plus the bench-side scripts used to validate it.
+
+## Key Features
+
+- Transport-independent motor abstraction through `BaseMotor`
+- Maintained SocketCAN backend for the CubeMars AK60-6
+- MIT-only CAN control path with one consistent command model
+- Background command refresh, feedback decoding, cached state handling, and staged recovery
+- Bench-validation scripts for MIT mode, position stepping, velocity verification, and plotting
+
+## Installation
+
+For normal development, testing, and analysis:
+
+```bash
+uv sync --all-groups
+source .venv/bin/activate
+```
+
+If you only want to install the package itself:
+
+```bash
+uv pip install -e .
+```
+
+## CAN Setup on Jetson Orin Nano
+
+### Recommended: systemd startup
+
+Install the tracked `can0.service` once so `can0` comes up automatically on boot:
+
+```bash
+sudo cp can0.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable can0.service
+sudo systemctl start can0.service
+```
+
+This brings `can0` up at 1 Mbps with bus-off auto-recovery.
+
+Useful checks:
+
+```bash
+systemctl status can0.service
+sudo systemctl restart can0.service
+ip -details link show can0
+```
+
+### Manual setup
+
+If you do not want to use the service, configure the interface manually:
+
+```bash
+sudo ./setup_can.sh
+```
+
+## Important Hardware Note
+
+If the R-Link / UART cable is connected to the motor, CAN commands may be silently ignored even though feedback frames are still visible on the bus. For CAN operation, disconnect the UART cable and then reset the CAN interface.
+
+## Recommended Workflow
+
+### 1. Confirm MIT/CAN communication
+
+```bash
+sudo ./setup_can.sh
+.venv/bin/python scripts/mit_mode_test.py --motor-id 0x03
+```
+
+### 2. Validate sustained velocity behavior
+
+```bash
+.venv/bin/python scripts/verify_set_velocity.py --motor-id 0x03 --velocity-erpm 3000
+```
+
+### 3. Run repeated MIT position stepping
+
+```bash
+.venv/bin/python scripts/mit_position_steps.py --motor-id 0x03 --duration 180 --angle-deg 50 --velocity-deg-s 100
+```
+
+### 4. Generate comparison plots from recorded CSV files
+
+```bash
+.venv/bin/python scripts/plot_graph.py velocity --data-root CSV --out-dir CSV/plots
+.venv/bin/python scripts/plot_graph.py position --data-root CSV --out-dir CSV/plots
+```
+
+## Python API
+
+The default convenience alias is the CAN motor class:
+
+```python
+from motor_python import Motor
+
+with Motor(motor_can_id=0x03) as motor:
+    motor.enable_mit_mode()
+    motor.set_velocity(3000)
+    motor.set_position(90.0)
+    motor.stop()
+```
+
+For direct access to the specific implementations:
+
+```python
+from motor_python.cube_mars_motor_can import CubeMarsAK606v3CAN
+from motor_python.cube_mars_motor import CubeMarsAK606v3
+```
+
+### Main CAN lifecycle methods
+
+| Method | Purpose |
+| --- | --- |
+| `enable_mit_mode()` | Enter MIT mode |
+| `disable_mit_mode()` | Exit MIT mode |
+| `check_communication()` | Verify that the motor responds on the bus |
+| `get_status()` | Return the latest cached `MotorState` |
+| `close()` | Stop and close transport resources |
+
+### Main CAN control methods
+
+| Method | Purpose |
+| --- | --- |
+| `set_position(position_degrees)` | MIT-backed position command |
+| `set_velocity(velocity_erpm, allow_low_speed=False)` | MIT-backed velocity command |
+| `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 |
+
+## Useful Bench Scripts
+
+These are the maintained scripts that matter most for the current implementation:
+
+| Script | Purpose |
+| --- | --- |
+| `scripts/mit_mode_test.py` | Focused MIT/CAN protocol validation |
+| `scripts/verify_set_velocity.py` | Bench verification of `set_velocity()` |
+| `scripts/mit_position_steps.py` | Long-run MIT position stepping for bench tests |
+| `scripts/plot_graph.py` | Chapter-4-style overlay and summary plots from recorded CSV files |
+| `scripts/diagnose_can.py` | CAN bus diagnostics and recovery support |
+| `scripts/scan_ids.py` | CAN ID discovery |
+| `scripts/reset_degree.py` | Practical MIT recentering helper |
+
+Additional exploratory and legacy scripts remain under `scripts/`, but they are not the primary maintained validation path.
+
+## Testing
+
+Run unit tests:
+
+```bash
+make test
+```
+
+Run CAN hardware tests:
+
+```bash
+make test-hardware-can
+```
+
+Run all hardware tests:
+
+```bash
+make test-hardware-all
+```
+
+## Project Structure
+
+```text
+can0.service                    systemd unit for automatic can0 startup
+setup_can.sh                    manual CAN setup and reset helper
+src/motor_python/               package source
+scripts/                        bench and validation scripts
+tests/                          unit and hardware-oriented tests
+data/csv_logs/.gitkeep          placeholder for locally generated CSV logs
+Test Rig CAD files/             CAD assets for the bench rig
+```
+
+## Notes on Scope
+
+- The current CAN implementation is MIT-only.
+- Legacy servo transport modes are intentionally not part of the maintained CAN path.
+- The repository includes bench-validation tooling, but not thesis-only notes, temporary files, or local analysis artifacts.
+
+## Run the Package Entry Point
+
+```bash
+uv run python -m motor_python
+```

motor_python-0.0.7/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "motor_python"
+version = "0.0.7"
+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" }]
+requires-python = ">=3.11,<3.14"
+
+# --- Core dependencies ---
+# The maintained path is the CAN backend, and tests import it in CI.
+dependencies = [
+    "numpy>=2.2.3",
+    "loguru>=0.7.3",
+    "pyserial>=3.5",
+    "python-can>=4.4.0",
+]
+
+[dependency-groups]
+dev = [
+  "ruff>=0.6.9",
+  "mypy>=1.11",
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "pytest-rerunfailures>=15.0",
+  "pre-commit>=4.1.0",
+  "coveralls>=4.0.1",
+  "pyright>=1.1.407",
+]
+hw = [
+]
+analysis = [
+  "matplotlib>=3.9",
+  "scipy>=1.14",
+]
+no_hw = [
+]
+[project.urls]
+homepage = "https://github.com/TUM-Aries-Lab/motor-module"
+
+[tool.ruff]
+line-length = 88
+fix = true
+
+lint.select = [
+  "E","F","W","C90","I","N","D","UP","B","S","YTT","Q","PL","RUF","T20","F841","ERA001",
+]
+
+lint.ignore = [
+  "D203","D213","E501","N803","N806","D415","S101","E203","E731",
+  "D107","PLR2004","S607","S605","S603",
+  "RUF002","RUF003",  # Unicode × and – in docstrings/comments are intentional
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+# Lazy subprocess import inside methods is intentional
+# subprocess.run without check= is handled via try/except
+"src/motor_python/can_utils.py" = ["PLC0415", "PLW1510"]
+
+# Complexity limit – feedback/refresh loops are inherently complex
+# Too many returns and lazy imports for socket flags
+"src/motor_python/cube_mars_motor_can.py" = ["C901", "PLR0911", "PLC0415"]
+
+# Too many return statements in feedback parser
+"src/motor_python/motor_status_parser.py" = ["PLR0911"]
+
+# Test helpers may need >5 args for full fixture coverage
+# Pytest fixtures don't need public docstrings
+# Lazy mocks are acceptable in test fixtures
+"tests/*" = ["PLR0913", "D103", "PLC0415"]
+"tests/manual_our_implementation_test.py" = ["T201"]
+"tests/manual_servo_mode_test.py" = ["T201"]
+"scripts/plot_graph.py" = ["PLR0913", "PLR0915"]
+
+
+[tool.ruff.lint.isort]
+known-first-party = ["motor_python"]
+combine-as-imports = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.coverage.run]
+omit = [
+  "src/motor_python/examples.py",
+  "src/motor_python/examples_can.py",
+  "tests/can_test.py",
+  "src/motor_python/__main__.py",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "hardware: CAN hardware tests — require motor on can0, NO UART cable (deselect with '-m \"not hardware\"')",
+    "hardware_uart: UART/serial hardware tests — require R-Link cable, incompatible with CAN tests",
+]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+# Tell hatchling where the package lives (src layout)
+[tool.hatch.build.targets.wheel]
+packages = ["src/motor_python"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/motor_python",
+  "README.md",
+  "LICENSE",
+]