Command Validation and Property Inheritance (#23)

Refactor robot controllers for unit standardization, shared validation, and extensibility

- Standardize units across all controllers (`Dobot`, `ElephantRobotics`, `Fanuc`, `Jaka`) using shared `units` (`uu`) and `CommandCheck` (`cc`) modules.
- Convert all internal joint values to radians, with protocol-specific conversions in `move_joints` and `move_cartesian`.
- Centralize motion command validation in `CommandCheck`, removing duplicated per-class logic.
- Update `Jaka` methods to use shared utilities for conversion and validation.
- Migrate all controllers to inherit from `Properties` for consistent attribute access and easier extension.
- Expand robot registry to include `UR3`, `UR10`, and `UR16`; comment out `OnRobot`.
- Remove deprecated `armctl/angle_utils.py` in favor of `units`.
- Update documentation and diagrams in `README.md` and formatting guidance in `CONTRIBUTING.md`.
- Apply minor fixes: logging initialization and `Pro600` home position handling.

Author: MGross21

CONTRIBUTING.md

@@ -146,10 +146,7 @@ poetry install --with dev
 To ensure consistency and code quality, run the following commands before submitting your changes:
 
 ```bash
-poetry run black . && \
-poetry run isort . && \
-poetry run ruff format . && \
-poetry run mypy armctl
+poetry run ruff format .
 ```
 
 > All code must be properly formatted and pass type checks. Please resolve any issues reported by these tools prior to opening a pull request.

README.md

@@ -230,7 +230,7 @@ The properties template exposes key robot class attributes as variables, allowin
 Below is a high-level diagram illustrating the architecture of the `armctl` library. This design emphasizes the careful templatization of connection and control APIs, ensuring a consistent and extensible interface across different manufacturers and robot series.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/images/template_overview_mermaid.png" alt="Template Overview" width="800">
+  <img src="https://raw.githubusercontent.com/MGross21/armctl/main/assets/diagrams/structure.svg" alt="Template Overview" width="800">
 </p>
 
 ### System Logging

armctl/__init__.py

@@ -26,15 +26,19 @@
     "ElephantRobotics",
     "Pro600",
     "UniversalRobots",
+    "UR3",
     "UR5",
     "UR5e",
-    "OnRobot",
+    "UR10",
+    "UR16",
+    # "OnRobot",
     "Vention",
     "Jaka",
 ]
 
 __version__ = "0.3.2"
 
+
 class Logger:
     """Global logger utility for armctl."""
 
@@ -54,6 +58,7 @@ def enable():
         # Re-enable logging to its previous state
         logging.disable(logging.NOTSET)
 
+
 import os
 
 if os.environ.get("ARMCTL_LOG", "").lower() in {"0", "false", "disable"}:

armctl/_blank/robot.py

@@ -19,7 +19,7 @@
 import math
 from armctl.templates import Commands
 from armctl.templates import Properties
-from armctl.utils import Angle as au
+from armctl.utils import units as uu
 from armctl.utils import CommandCheck as cc
 
 # Choose one of the following Communication Methods

armctl/angle_utils.py

@@ -1,51 +1,75 @@
 from armctl.templates import SerialController as SCT
+from armctl.templates import Commands
+from armctl.templates import Properties
+from armctl.utils import CommandCheck as cc
+from armctl.utils import units as uu
+import math
 
+### Notes ###
+# - Command Format: CMD(arg)
+# - Command units are degrees & mm.
 
-class Dobot(SCT):
+
+class Dobot(SCT, Commands, Properties):
     def __init__(self, ip: str, port: int):
         super().__init__(ip, port)
-        self.JOINT_RANGES = [
-            (-135.00, 135.00),
-            (-5.00, 80.00),
-            (-10.00, 85.00),
-            (-145.00, 145.00),
-        ]
-        self.DOF = len(self.JOINT_RANGES)
+        self.JOINT_RANGES = uu.joints2rad(
+            [
+                (-135.00, 135.00),
+                (-5.00, 80.00),
+                (-10.00, 85.00),
+                (-145.00, 145.00),
+            ]
+        )
+        self.MAX_JOINT_VELOCITY = None
+        self.MAX_JOINT_ACCELERATION = None
+
         raise NotImplementedError(
             f"{self.__class__.__name__.upper()} is not yet supported."
         )
 
     def sleep(self, seconds):
+        cc.sleep(seconds)
         self.send_command(f"sleep({seconds})")
 
-    def move_joints(self, pos, *args, **kwargs) -> str:
+    def move_joints(self, pos) -> str:
         "MovJ"
 
-        if len(pos) != kwargs.get("DOF", 4):
-            raise ValueError("Joint positions must have 4 elements")
-
-        for j, (lower, upper) in enumerate(self.JOINT_RANGES):
-            if not (lower <= pos[j] <= upper):
-                raise ValueError(
-                    f"Joint {j + 1} angle out of range: {lower} ~ {upper}"
-                )
+        cc.move_joints(self, pos)
 
         command = "MOVJ({})".format(",".join(map(str, pos)))
         return self.send_command(command)
 
     def move_cartesian(self, pose) -> str:
-        "MOVEL"
-
-        if len(pose) == 3:
-            pose.append(0)
-
-        # Now check again if the robot pose has 4 elements
-        if len(pose) != 4:
-            raise ValueError(
-                "Robot pose must have 3 ([x, y, z]) or 4 elements: [x, y, z, rz]"
+        """
+        Moves the robot arm to a specified Cartesian position.
+
+        Parameters:
+            pose (list or tuple): Target position as [x, y, z, r]. x, y, z are in meters and r is in radians.
+
+        Returns:
+            str: The response from the robot after executing the MOVEL command.
+
+        Notes:
+            - The method sends a MOVEL command to the robot controller.
+            - The pose is expected in m for x, y, z and radians for r.
+        """
+        cc.move_cartesian(self, pose)
+        # Convert x, y, z from meters to millimeters, r from radians to degrees
+
+        command = "MOVEL({})".format(
+            ",".join(
+                map(
+                    str,
+                    [
+                        pose[0] * 1000,  # x in mm
+                        pose[1] * 1000,  # y in mm
+                        pose[2] * 1000,  # z in mm
+                        math.degrees(pose[3]),  # r in degrees
+                    ],
+                )
             )
-
-        command = "MOVEL({})".format(",".join(map(str, pose)))
+        )
         return self.send_command(command)
 
     def get_joint_positions(self):
@@ -59,17 +83,3 @@ def stop_motion(self):
 
     def get_robot_state(self):
         pass
-
-    def move_arc(self, command):
-        """The trajectory of ARC mode is an arc, which is determined by three points (the current point, any point and the end point on the arc)"""
-        if len(command) != 3:
-            raise ValueError("Invalid ARC command. Must have 3 points")
-
-        self.send_command(f"ARC({','.join(map(str, command))})")
-
-    def move_jump(self, command):
-        """If the movement of two points is required to lift upwards by amount of height, such as sucking up, grabbing, you can choose JUMP"""
-        if len(command) != 2:
-            raise ValueError("Invalid JUMP command. Must have 2 points")
-
-        self.send_command(f"JUMP({','.join(map(str, command))})")

armctl/dobot/dobot.py

@@ -1,21 +1,32 @@
 import time
 
 from armctl.templates import Commands
+from armctl.templates import Properties
 from armctl.templates import SocketController as SCT
 
+from armctl.utils import CommandCheck as cc
+from armctl.utils import units as uu
 
-class ElephantRobotics(SCT, Commands):
+## Notes
+# - Command Format: CMD(arg)
+# - Command units are degrees & mm.
+
+
+class ElephantRobotics(SCT, Commands, Properties):
     def __init__(self, ip: str, port: int):
         super().__init__(ip, port)
-        self.JOINT_RANGES = [
-            (-180.00, 180.00),
-            (-270.00, 90.00),
-            (-150.00, 150.00),
-            (-260.00, 80.00),
-            (-168.00, 168.00),
-            (-174.00, 174.00),
-        ]
-        self.DOF = len(self.JOINT_RANGES)
+        self.JOINT_RANGES = uu.joints2rad(
+            [
+                (-180.00, 180.00),
+                (-270.00, 90.00),
+                (-150.00, 150.00),
+                (-260.00, 80.00),
+                (-168.00, 168.00),
+                (-174.00, 174.00),
+            ]
+        )
+        self.MAX_JOINT_VELOCITY = uu.deg2rad(2000)
+        self.MAX_JOINT_ACCELERATION = None
 
     def connect(self):
         super().connect()  # Socket Connection
@@ -43,46 +54,35 @@ def _waitforfinish(self):
             time.sleep(0.25)
 
     def sleep(self, seconds):
-        assert isinstance(
-            seconds, (int, float)
-        ), "Seconds must be a numeric value."
-        assert seconds >= 0, "Seconds must be a non-negative value."
+        cc.sleep(seconds)
         self.send_command(f"wait({seconds})")
         time.sleep(seconds)
 
-    def move_joints(self, pos: list[float], speed: int = 500) -> None:
+    def move_joints(
+        self, pos: list[float], speed: int = uu.deg2rad(500)
+    ) -> None:
         """
         Move the robot to the specified joint positions.
 
         Parameters
         ----------
         pos : list of float
-            Joint positions in degrees [j1, j2, j3, j4, j5, j6].
+            Joint positions in radians [j1, j2, j3, j4, j5, j6].
         speed : int, optional
-            Speed of the movement, range 0 ~ 2000 (default: 200).
-        DOF : int, optional
-            Degrees of freedom (default: 6).
+            Speed of the movement, range `0` ~ `math.radians(2000)` (default: `math.radians(500)`).
         """
 
-        if len(pos) != self.DOF:
-            raise ValueError("Joint positions must have 6 elements")
+        cc.move_joints(self, pos, speed)
 
-        for i, (low, high) in enumerate(self.JOINT_RANGES):
-            if not (low <= pos[i] <= high):
-                raise ValueError(
-                    f"Joint {i + 1} angle out of range: {low} ~ {high}"
-                )
+        pos_deg = uu.joints2deg(pos)
+        speed_deg = uu.rad2deg(speed)
 
-        if not (0 <= speed <= 2000):
-            raise ValueError("Speed out of range: 0 ~ 2000")
+        command = f"set_angles({','.join(map(str, pos_deg))},{speed_deg})"
+        response = self.send_command(command)
 
-        command = "set_angles"
-        response = self.send_command(
-            f"{command}({','.join(map(str, pos))},{speed})"
+        assert response == f"{command}:[ok]", (
+            f"Failed to move joints: {response}"
         )
-        assert (
-            response == f"{command}:[ok]"
-        ), f"Failed to move joints: {response}"
 
         while any(
             abs(a - b) > 3 for a, b in zip(self.get_joint_positions(), pos)
@@ -92,7 +92,7 @@ def move_joints(self, pos: list[float], speed: int = 500) -> None:
     def move_cartesian(
         self,
         pose: tuple[float, float, float, float, float, float],
-        speed: int = 500,
+        speed: int = uu.deg2rad(500),
     ) -> None:
         """
         Move the robot to the specified Cartesian coordinates.
@@ -102,17 +102,15 @@ def move_cartesian(
         pose : tuple of float
             Cartesian coordinates in the format `[x, y, z, rx, ry, rz]`.
         speed : int, optional
-            Speed of the movement, range 0 ~ 2000 (default: 500).
+            Speed of the movement, range `0` ~ `math.radians(2000)` (default: `math.radians(500)`).
         """
 
-        if not (0 <= speed <= 2000):
-            raise ValueError("Speed out of range: 0 ~ 2000")
-        if len(pose) != 6:
-            raise ValueError(
-                "Robot pose must have 6 elements: [x, y, z, rx, ry, rz]"
-            )
+        cc.move_cartesian(self, pose)
+
+        pose_deg = uu.pose2deg(pose)
+        speed_deg = uu.rad2deg(speed)
 
-        command = f"set_coords({','.join(map(str, pose))},{speed})"
+        command = f"set_coords({','.join(map(str, pose_deg))},{speed_deg})"
 
         assert self.send_command(command) == "set_coords:[ok]"
 

armctl/elephant_robotics/elephant_robotics.py

@@ -1,22 +1,12 @@
-from .elephant_robotics import ElephantRobotics
+from .elephant_robotics import ElephantRobotics, uu
+import math
 
 
 class Pro600(ElephantRobotics):
     def __init__(self, ip: str = "192.168.1.159", port: int = 5001):
         """Elephant Robotics myCobot Pro600"""
         super().__init__(ip, port)
-        self.HOME_POSITION = [0, -90, 90, -90, -90, 0]
-        self.JOINT_RANGES = [
-            (-180.00, 180.00),
-            (-270.00, 90.00),
-            (-150.00, 150.00),
-            (-260.00, 80.00),
-            (-168.00, 168.00),
-            (-174.00, 174.00),
-        ]
-        self.DOF = len(self.JOINT_RANGES)
-
-        self.__class__.__name__ = f"{self.__class__.__bases__[0].__name__} {__name__.split('.')[-1]} {self.__class__.__name__}"
+        self.HOME_POSITION = uu.joints2rad([0, -90, 90, -90, -90, 0])
 
     def home(self):
         """

armctl/elephant_robotics/mycobot.py

@@ -1,21 +1,29 @@
 from armctl.templates import Commands
+from armctl.templates import Properties
 from armctl.templates import PLCController as PLC
 
+from armctl.utils import CommandCheck as cc
+
 
 # Non-Operational (1/31/2025)
-class Fanuc(PLC, Commands):
+class Fanuc(PLC, Commands, Properties):
     def __init__(self, ip: str, port: int):
         super().__init__(ip, port)
+        self.JOINT_RANGES = None
+        self.MAX_JOINT_VELOCITY = None
+        self.MAX_JOINT_ACCELERATION = None
         raise NotImplementedError(
             f"{self.__class__.__name__.upper()} is not yet supported."
         )
 
     def move_joints(self, pos, speed=1.0):
+        cc.move_joints(self, pos, speed)
         return self.send_command(
             {"type": "move_joints", "positions": pos, "speed": speed}
         )
 
     def move_cartesian(self, pose, speed=1.0):
+        cc.move_cartesian(self, pose)
         return self.send_command(
             {"type": "move_cartesian", "position": pose, "speed": speed}
         )