codroid-robot-sdk 2.1.4__tar.gz → 2.1.5__tar.gz

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codroid-robot-sdk
-Version: 2.1.4
+Version: 2.1.5
 Summary: Codroid robot controller Python SDK (TCP/CRI, typed motion API)
 Project-URL: Documentation, https://guybod.github.io/CodroidSDK/
 Project-URL: Issues, https://github.com/guybod/CodroidSDK/issues

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/RELEASE_NOTES.md

@@ -1,5 +1,24 @@
 # Codroid Python SDK 版本说明
 
+## 2.1.5 — 隐患修复
+
+### Bug Fixes
+
+- **修复 `RunStep` 发错指令**：发送 `"project/run"` 改为 `"project/runStep"`，之前会导致单步调试变成完整运行
+- **修复 `CriData` 返回可变引用**：改为返回深拷贝，与 C# 行为一致，避免 UDP 线程更新时主线程读到不一致数据
+- **修复 `_id_counter` 竞态**：加 `threading.Lock` 保护，避免多线程并发发指令时 ID 冲突
+- **修复 `GetDi`/`GetDo` 缺少端口校验**：与 `SetDo`/`SetAo` 一致，传入非法端口时抛出 `CodroidError`
+- **修复 `_dispatch_publish` 静默吞异常**：publish handler 的异常现在会输出到日志
+
+### 改进
+
+- **`StartCriControl` 参数校验**：新增 `filter_type`（0-3）、`duration`（1-16 且整除 1000）、`start_buffer`（1-100）校验
+- **便捷运动方法补 `relative_blend` 参数**：`MovJ`、`MovL`、`MovC`、`MovCircle` 及其 `*Sync` 变体、`MotionPath` 构建方法全部支持 `relative_blend`，与 C# 对齐
+- **`CposToApos` 默认参考关节改为当前关节角度**：`rj=None` 时优先使用 `CriData.JointPosition`，CRI 未启动时兜底 `[20,20,20,20,20,20]`，与 C# 行为一致
+- **`CriStreamHandler.parse_packet()` 舍位方式修正**：从银行家舍位改为四舍五入（AwayFromZero），与 C# `Math.Round` 行为一致
+
+---
+
 ## 2.1.4 — blend 参数改为可选 + 欧拉角判定修复
 
 ### Bug Fixes

codroid_robot_sdk-2.1.4/docs/CodroidPython-SDK-Manual-v2.1.4-en.md → codroid_robot_sdk-2.1.5/docs/CodroidPython-SDK-Manual-v2.1.5-en.md

@@ -1,6 +1,6 @@
 # CodroidPython SDK Manual
 
-**Version:** 2.1.4 | **Package:** `codroid-robot-sdk` | **Python:** 3.7+
+**Version:** 2.1.5 | **Package:** `codroid-robot-sdk` | **Python:** 3.7+
 
 ---
 

codroid_robot_sdk-2.1.4/docs/CodroidPython-SDK-Manual-v2.1.4-zh.md → codroid_robot_sdk-2.1.5/docs/CodroidPython-SDK-Manual-v2.1.5-zh.md

@@ -1,6 +1,6 @@
 # CodroidPython SDK 手册
 
-**版本:** 2.1.4 | **包名:** `codroid-robot-sdk` | **Python:** 3.7+
+**版本:** 2.1.5 | **包名:** `codroid-robot-sdk` | **Python:** 3.7+
 
 ---
 
@@ -2059,7 +2059,7 @@ with CodroidClient(host="192.168.8.136") as robot:
 #### blend / relative_blend
 
 - `blend`：平滑半径。与 `relative_blend` 互斥——同时传入时 `relative_blend` 无效。不传表示无过渡。
-- `relative_blend`：相对平滑比（0–1）。与 `blend` 互斥——同时传入时此参数无效。
+- `relative_blend`：相对平滑比（0–100）。与 `blend` 互斥——同时传入时此参数无效。
 
 #### coor / tool
 

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/docs/README.md

@@ -1,6 +1,6 @@
 # CodroidPython SDK 手册
 
-**版本:** 2.1.4 | **包名:** `codroid-robot-sdk` | **Python:** 3.7+
+**版本:** 2.1.5 | **包名:** `codroid-robot-sdk` | **Python:** 3.7+
 
 ---
 

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/src/codroid/Codroid.py

@@ -5,6 +5,7 @@
 """
 from __future__ import annotations
 
+import copy
 import threading
 import socket
 import time
@@ -35,6 +36,7 @@ class CodroidSession:
         """
         self._net = JsonStreamClient(host, port)
         self._id_counter = 1
+        self._id_lock = threading.Lock()
         self.debug = False
         # --- 新增属性 ---
         self.local_ip = local_ip
@@ -55,9 +57,11 @@ class CodroidSession:
         Returns:
             CommonResponse: 响应对象 / Response object.
         """
-        self._id_counter += 1
+        with self._id_lock:
+            self._id_counter += 1
+            current_id = self._id_counter
         # 构造请求模型
-        request = CodroidRequest(id=self._id_counter, ty=ty, db=db)
+        request = CodroidRequest(id=current_id, ty=ty, db=db)
         
         # 转换为字典并发送 (排除 db 为 None 的情况可根据具体接口微调)
         payload: Dict[str, Any] = {
@@ -173,8 +177,9 @@ class CodroidSession:
 
     @property
     def CriData(self) -> Optional[CriRealTimeData]:
-        """最新 CRI 快照（C# ``CriData``，内部 ``cri_cache``）。"""
-        return self.cri_cache
+        """最新 CRI 快照（线程安全深拷贝，与 C# ``CriData`` 行为一致）。"""
+        cache = self.cri_cache
+        return copy.deepcopy(cache) if cache is not None else None
 
     def WaitForCriData(self, timeout: float = 5.0) -> CriRealTimeData:
         """
@@ -298,7 +303,7 @@ class CodroidSession:
         """
         2.5 单步运行（C# ``RunStep``）。
         """
-        return self._send_command("project/run", {"id": project_id})
+        return self._send_command("project/runStep", {"id": project_id})
 
     def PauseProject(self) -> CommonResponse:
         """
@@ -542,9 +547,10 @@ class CodroidSession:
         Returns:
             CommonResponse: 响应对象 / Response object.
         """
-        # 处理默认参考关节角
+        # 处理默认参考关节角：优先用当前关节角度，CRI 未启动时兜底
         if rj is None:
-            rj = [20.0, 20.0, 20.0, 20.0, 20.0, 20.0]
+            cri = self.CriData
+            rj = list(cri.joint_position) if cri is not None and len(cri.joint_position) >= 6 else [20.0, 20.0, 20.0, 20.0, 20.0, 20.0]
             
         db = {
             "cp": cp, 
@@ -724,6 +730,7 @@ class CodroidSession:
         speed: float,
         acceleration: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> CommonResponse:
@@ -740,6 +747,7 @@ class CodroidSession:
                 speed,
                 acceleration,
                 blend=blend,
+                relative_blend=relative_blend,
                 coor=coor,
                 tool=tool,
             )
@@ -749,6 +757,7 @@ class CodroidSession:
             speed,
             acceleration,
             blend=blend,
+            relative_blend=relative_blend,
             coor=coor,
             tool=tool,
         )
@@ -760,6 +769,7 @@ class CodroidSession:
         speed: float,
         acceleration: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> CommonResponse:
@@ -775,6 +785,7 @@ class CodroidSession:
                 speed,
                 acceleration,
                 blend=blend,
+                relative_blend=relative_blend,
                 coor=coor,
                 tool=tool,
             )
@@ -784,6 +795,7 @@ class CodroidSession:
             speed,
             acceleration,
             blend=blend,
+            relative_blend=relative_blend,
             coor=coor,
             tool=tool,
         )
@@ -796,6 +808,7 @@ class CodroidSession:
         speed: float,
         acceleration: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> CommonResponse:
@@ -806,6 +819,7 @@ class CodroidSession:
             speed,
             acceleration,
             blend=blend,
+            relative_blend=relative_blend,
             coor=coor,
             tool=tool,
         )
@@ -819,6 +833,7 @@ class CodroidSession:
         speed: float,
         acceleration: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> CommonResponse:
@@ -830,6 +845,7 @@ class CodroidSession:
             speed,
             acceleration,
             blend=blend,
+            relative_blend=relative_blend,
             coor=coor,
             tool=tool,
         )
@@ -1013,6 +1029,7 @@ class CodroidSession:
         speed: float, acceleration: float,
         wait: Optional[MotionWaitOptions] = None,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> bool:
@@ -1024,7 +1041,8 @@ class CodroidSession:
             speed: 速度。
             acceleration: 加速度。
             wait: 等待参数，None 使用默认值。
-            blend: 平滑半径。
+            blend: 平滑半径。与 relative_blend 互斥。
+            relative_blend: 相对平滑比（0-100）。与 blend 互斥。
             coor: 用户坐标系。
             tool: 工具坐标系。
 
@@ -1032,7 +1050,7 @@ class CodroidSession:
             bool: 到达目标返回 True。
         """
         options = wait or MotionWaitOptions()
-        self.MovJ(target, speed, acceleration, blend=blend, coor=coor, tool=tool)
+        self.MovJ(target, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
         if isinstance(target, JointPoint):
             predicate = (lambda jp: lambda data:
                 self._max_abs_diff(data.joint_position, jp) <= options.joint_tolerance_deg
@@ -1050,6 +1068,7 @@ class CodroidSession:
         speed: float, acceleration: float,
         wait: Optional[MotionWaitOptions] = None,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> bool:
@@ -1061,7 +1080,8 @@ class CodroidSession:
             speed: 速度。
             acceleration: 加速度。
             wait: 等待参数，None 使用默认值。
-            blend: 平滑半径。
+            blend: 平滑半径。与 relative_blend 互斥。
+            relative_blend: 相对平滑比（0-100）。与 blend 互斥。
             coor: 用户坐标系。
             tool: 工具坐标系。
 
@@ -1069,7 +1089,7 @@ class CodroidSession:
             bool: 到达目标返回 True。
         """
         options = wait or MotionWaitOptions()
-        self.MovL(target, speed, acceleration, blend=blend, coor=coor, tool=tool)
+        self.MovL(target, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
         if isinstance(target, JointPoint):
             predicate = (lambda jp: lambda data:
                 self._max_abs_diff(data.joint_position, jp) <= options.joint_tolerance_deg
@@ -1088,6 +1108,7 @@ class CodroidSession:
         speed: float, acceleration: float,
         wait: Optional[MotionWaitOptions] = None,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> bool:
@@ -1098,8 +1119,8 @@ class CodroidSession:
             bool: 到达目标返回 True。
         """
         options = wait or MotionWaitOptions()
-        self.MovC(middle, target, speed, acceleration, blend=blend, coor=coor, tool=tool)
-        inst = MoveInstruction.MovC(middle, target, speed, acceleration, blend=blend, coor=coor, tool=tool)
+        self.MovC(middle, target, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
+        inst = MoveInstruction.MovC(middle, target, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
         cmds = [inst.to_dict()]
         predicate = self._build_move_target_reached_predicate(cmds, options)
         self._wait_until_settled_by_cri(predicate, "MovCSync", options)
@@ -1113,6 +1134,7 @@ class CodroidSession:
         speed: float, acceleration: float,
         wait: Optional[MotionWaitOptions] = None,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
         coor: Optional[Sequence[float]] = None,
         tool: Optional[Sequence[float]] = None,
     ) -> bool:
@@ -1123,8 +1145,8 @@ class CodroidSession:
             bool: 到达目标返回 True。
         """
         options = wait or MotionWaitOptions()
-        self.MovCircle(middle, target, circle_num, speed, acceleration, blend=blend, coor=coor, tool=tool)
-        inst = MoveInstruction.MovCircle(middle, target, circle_num, speed, acceleration, blend=blend, coor=coor, tool=tool)
+        self.MovCircle(middle, target, circle_num, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
+        inst = MoveInstruction.MovCircle(middle, target, circle_num, speed, acceleration, blend=blend, relative_blend=relative_blend, coor=coor, tool=tool)
         cmds = [inst.to_dict()]
         predicate = self._build_move_target_reached_predicate(cmds, options)
         self._wait_until_settled_by_cri(predicate, "MovCircleSync", options)
@@ -1267,6 +1289,7 @@ class CodroidSession:
         Returns:
             int: 0 或 1 / 0 or 1.
         """
+        self._validate_io(IOType.DI, port)
         res = self.GetIoValues([{"type": IOType.DI, "port": port}])
         if res.db is not None and len(res.db) > 0:
             return int(res.db[0]["value"])
@@ -1283,6 +1306,7 @@ class CodroidSession:
         Returns:
             int: 0 或 1 / 0 or 1.
         """
+        self._validate_io(IOType.DO, port)
         res = self.GetIoValues([{"type": IOType.DO, "port": port}])
         if res.db is not None and len(res.db) > 0:
             return int(res.db[0]["value"])
@@ -1497,10 +1521,16 @@ class CodroidSession:
         17.6 开启实时控制 / Start CRI control mode（C# ``StartCriControl``，``CRI/StartControl``）。
 
         Args:
-            filter_type: 滤波类型。
+            filter_type: 滤波类型（0=关闭，1=平均，2=二阶低通，3=椭圆）。
             duration: 指令间隔 ms（1–16，且可整除 1000）。
             start_buffer: 启动缓冲点数（1–100）。
         """
+        if int(filter_type) not in (0, 1, 2, 3):
+            raise ValueError(f"filter_type 须为 0-3，收到 {int(filter_type)}")
+        if not (1 <= duration <= 16) or 1000 % duration != 0:
+            raise ValueError(f"duration 须为 1-16 且整除 1000，收到 {duration}")
+        if not (1 <= start_buffer <= 100):
+            raise ValueError(f"start_buffer 须为 1-100，收到 {start_buffer}")
         db = {
             "filterType": int(filter_type),
             "duration": duration,

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/src/codroid/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2026-present guybod <b13140185898@outlook.com>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "2.1.4"
+__version__ = "2.1.5"

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/src/codroid/async_tcp_client.py

@@ -214,7 +214,8 @@ class TransportClient(JsonStreamClient):
         for handler in handlers:
             try:
                 handler(ty, db, raw_json)
-            except Exception:
+            except Exception as e:
+                logger.warning("publish handler error [%s]: %s", ty, e)
                 continue
 
     def _fail_all_pending(self, exc: BaseException):

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/src/codroid/cri_realtime_packet_parser.py

@@ -189,13 +189,13 @@ class CriStreamHandler:
             if self.mask & (1 << 8):
                 fmt = f"<{self.joint_count}{self.float_fmt}"
                 raw_jp = struct.unpack_from(fmt, data, offset)
-                res.joint_pos = [round(math.degrees(q), 3) for q in raw_jp]
+                res.joint_pos = [_round_away_from_zero(math.degrees(q)) for q in raw_jp]
                 offset += self.joint_count * self.float_size
 
             if self.mask & (1 << 9):
                 fmt = f"<{self.joint_count}{self.float_fmt}"
                 raw_jv = struct.unpack_from(fmt, data, offset)
-                res.joint_vel = [round(math.degrees(q), 3) for q in raw_jv]
+                res.joint_vel = [_round_away_from_zero(math.degrees(q)) for q in raw_jv]
                 offset += self.joint_count * self.float_size
 
             if self.mask & (1 << 10):
@@ -204,13 +204,13 @@ class CriStreamHandler:
                 raw_cp = struct.unpack_from(fmt, data, offset)
 
                 converted_cp = [
-                    round(raw_cp[0] * 1000.0, 3),
-                    round(raw_cp[1] * 1000.0, 3),
-                    round(raw_cp[2] * 1000.0, 3),
+                    _round_away_from_zero(raw_cp[0] * 1000.0),
+                    _round_away_from_zero(raw_cp[1] * 1000.0),
+                    _round_away_from_zero(raw_cp[2] * 1000.0),
                 ]
-                converted_cp.extend([round(math.degrees(a), 3) for a in raw_cp[3:6]])
+                converted_cp.extend([_round_away_from_zero(math.degrees(a)) for a in raw_cp[3:6]])
                 if count == 7:
-                    converted_cp.append(round(math.degrees(raw_cp[6]), 3))
+                    converted_cp.append(_round_away_from_zero(math.degrees(raw_cp[6])))
 
                 res.cartesian_pos = converted_cp
                 offset += count * self.float_size
@@ -219,37 +219,37 @@ class CriStreamHandler:
                 fmt = f"<{6}{self.float_fmt}"
                 raw_cv = struct.unpack_from(fmt, data, offset)
                 res.cartesian_vel = [
-                    round(raw_cv[0] * 1000.0, 3),
-                    round(raw_cv[1] * 1000.0, 3),
-                    round(raw_cv[2] * 1000.0, 3),
-                    round(math.degrees(raw_cv[3]), 3),
-                    round(math.degrees(raw_cv[4]), 3),
-                    round(math.degrees(raw_cv[5]), 3),
+                    _round_away_from_zero(raw_cv[0] * 1000.0),
+                    _round_away_from_zero(raw_cv[1] * 1000.0),
+                    _round_away_from_zero(raw_cv[2] * 1000.0),
+                    _round_away_from_zero(math.degrees(raw_cv[3])),
+                    _round_away_from_zero(math.degrees(raw_cv[4])),
+                    _round_away_from_zero(math.degrees(raw_cv[5])),
                 ]
                 offset += 6 * self.float_size
 
             if self.mask & (1 << 12):
                 raw_tcp = struct.unpack_from(f"<{self.float_fmt}", data, offset)[0]
-                res.tcp_speed = round(raw_tcp * 1000.0, 3)
+                res.tcp_speed = _round_away_from_zero(raw_tcp * 1000.0)
                 offset += self.float_size
 
             if self.mask & (1 << 13):
                 fmt = f"<{self.joint_count}{self.float_fmt}"
                 raw_jt = struct.unpack_from(fmt, data, offset)
-                res.joint_torque = [round(q, 3) for q in raw_jt]
+                res.joint_torque = [_round_away_from_zero(q) for q in raw_jt]
                 offset += self.joint_count * self.float_size
 
             if self.mask & (1 << 14):
                 fmt = f"<{self.joint_count}{self.float_fmt}"
                 raw_et = struct.unpack_from(fmt, data, offset)
-                res.external_torque = [round(q, 3) for q in raw_et]
+                res.external_torque = [_round_away_from_zero(q) for q in raw_et]
                 offset += self.joint_count * self.float_size
 
             if self.mask & (1 << 15):
                 if self.extra_axis_count > 0:
                     fmt = f"<{self.extra_axis_count}{self.float_fmt}"
                     raw_ep = struct.unpack_from(fmt, data, offset)
-                    res.extra_axis_pos = [round(q, 3) for q in raw_ep]
+                    res.extra_axis_pos = [_round_away_from_zero(q) for q in raw_ep]
                     offset += self.extra_axis_count * self.float_size
 
         except struct.error as e:

{codroid_robot_sdk-2.1.4 → codroid_robot_sdk-2.1.5}/src/codroid/define.py

@@ -648,9 +648,10 @@ class MotionPath:
         speed: float,
         acc: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
     ) -> MotionPath:
         """添加关节运动 movJ。"""
-        return self._add_item(MotionType.MOVJ, target, speed, acc, blend)
+        return self._add_item(MotionType.MOVJ, target, speed, acc, blend, relative_blend=relative_blend)
 
     def MovL(
         self,
@@ -658,9 +659,10 @@ class MotionPath:
         speed: float,
         acc: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
     ) -> MotionPath:
         """添加直线运动 movL。"""
-        return self._add_item(MotionType.MOVL, target, speed, acc, blend)
+        return self._add_item(MotionType.MOVL, target, speed, acc, blend, relative_blend=relative_blend)
 
     def MovC(
         self,
@@ -669,6 +671,7 @@ class MotionPath:
         speed: float,
         acc: float,
         blend: Optional[float] = None,
+        relative_blend: Optional[float] = None,
     ) -> MotionPath:
         """添加圆弧运动 movC（目标与中间点均为 TCP）。"""
         target_mp = (
@@ -687,6 +690,7 @@ class MotionPath:
             speed,
             acc,
             blend,
+            relative_blend=relative_blend,
             middle=middle_mp,
         )