codroid-robot-sdk 2.1.1__tar.gz → 2.1.2__tar.gz

codroid_robot_sdk-2.1.2/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git rm *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(python3 *)"
+    ]
+  }
+}

{codroid_robot_sdk-2.1.1 → codroid_robot_sdk-2.1.2}/.gitignore

@@ -6,7 +6,6 @@ build_msvc/
 bin/
 lib/
 out/
-docs/
 up.md
 
 # === 编译器产生的中间文件 (Objects & Libraries) ===
@@ -72,8 +71,8 @@ dist/
 build/
 *.egg-info/
 
-# 文档输出
-site/
+# 文档输出（mkdocs 已移除，site/ 不再生成）
+# site/
 
 # IDE 设置
 .vscode/

{codroid_robot_sdk-2.1.1 → codroid_robot_sdk-2.1.2}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.1.2 — 阻塞式运动 API / RunScript 完整参数 / StopMoveTo
+
+### Added
+
+- **阻塞式运动 API**（对齐 C# `*Sync` 方法）：
+  - `MoveSync`、`MovJSync`、`MovLSync`、`MovCSync`、`MovCircleSync`
+  - `MotionWaitOptions`：可配置超时、轮询间隔、CRI 过期判定、稳定采样数、关节/笛卡尔容差
+  - 内部 CRI 新鲜度追踪（`_last_cri_received_utc`）
+- **`RunScript` 完整参数**：新增 `sub_threads`、`sub_programs`、`interrupts` 可选字典参数（对齐 C# `RunScript(main, subThreads, subPrograms, interrupts, vars)`）
+- **`StopMoveTo()`**：发送 `type=-1` 停止 MoveTo 运动
+- `MoveToType.STOP = -1` 枚举值
+- 更新示例：`08_move.py` 增加 Sync 阻塞运动演示；`02_run_script.py` 增加子线程/子程序/中断演示；`07_move_to.py` 增加 StopMoveTo 演示
+
 ## 2.1.1 — 机器人设置 API（协议 19.x）
 
 ### Added
@@ -9,7 +22,7 @@
 - 仅改默认编号：`SetDefaultPayloadId`、`SetDefaultToolId`、`SetDefaultUserCoordinateId`
 - 先读后改：`SetToolFrame`、`SetPayloadFrame`、`SetUserCoordinateFrame`
 - 整表下发：`SaveToolFrames`、`SavePayloadFrames`、`SaveUserCoordinateFrames`
-- 示例：`examples/14_robot_parameters.py`；`codroid_test.py robotparam`
+- 示例：`examples/14_robot_parameters.py`；`codroid_test.py robotparam`；`examples/08_move.py` 四组合 + MovC
 
 ### Changed / Breaking
 

{codroid_robot_sdk-2.1.1 → codroid_robot_sdk-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codroid-robot-sdk
-Version: 2.1.1
+Version: 2.1.2
 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
@@ -102,6 +102,10 @@ python3 demo.py
 | `MovJ(target, speed, acceleration)` | 目标：`JointPoint` 或 `CartesianPoint` |
 | `MovL(target, speed, acceleration)` | 目标：`CartesianPoint` 或 `JointPoint` |
 | `Move([MoveInstruction.MovJ(...), ...])` | 多段路径 |
+| `MovJSync(target, speed, acc, wait?)` | 阻塞式关节运动，等待到达目标 |
+| `MovLSync(target, speed, acc, wait?)` | 阻塞式直线运动，等待到达目标 |
+| `MovCSync(middle, target, speed, acc, wait?)` | 阻塞式圆弧运动 |
+| `MoveSync(instructions, wait?)` | 阻塞式路径执行 |
 
 四组合路径示例（与 C++ `04_move` 一致）：
 
@@ -127,6 +131,29 @@ robot.Move(path)
 
 打包规则：`jp` 优先；仅 `cp` 时若未提供 `rj`，JSON 中带默认 `[20,20,20,20,20,20]`（度）。
 
+### 阻塞式运动 API
+
+`*Sync` 方法发送运动指令后自动轮询 CRI 数据，直到机器人稳定到达目标。需要先启动 CRI 数据推送（`StartListenUdp`）。
+
+```python
+from codroid import CodroidClient, JointPoint, MotionWaitOptions
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.ConnectRemoteAndSwitchOn()
+    robot.StartListenUdp()
+    robot.WaitForCriData()  # 等待第一个 CRI 包到达
+
+    # 阻塞式关节运动，使用默认等待参数
+    robot.MovJSync(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acceleration=100)
+
+    # 自定义等待参数
+    opts = MotionWaitOptions(timeout=30.0, joint_tolerance_deg=0.5)
+    robot.MovLSync(CartesianPoint.MmDeg([400, 200, 500, 180, 0, 90]),
+                   speed=150, acceleration=500, wait=opts)
+```
+
+`MotionWaitOptions` 可调整超时、轮询间隔、到达容差等参数。
+
 **Breaking（2.1.1）**：公开 API 与 C# 一致，统一 **PascalCase**（`Connect`、`SwitchOn`、`GetDi`、`MovJ`、`SetToolFrame` 等）；`CriData` 为属性；`move_j` / `switch_on` 等 snake_case 已移除。见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## Windows 控制台 UTF-8
@@ -159,6 +186,7 @@ with CodroidClient(host="192.168.1.136") as robot:
 
 ```bash
 PYTHONPATH=src python examples/08_move.py --robot 192.168.8.136
+PYTHONPATH=src python examples/15_sync_motion.py --robot 192.168.8.136
 PYTHONPATH=src python examples/14_robot_parameters.py --robot 192.168.8.136
 PYTHONPATH=src python examples/codroid_test.py motion
 PYTHONPATH=src python examples/codroid_test.py s20

{codroid_robot_sdk-2.1.1 → codroid_robot_sdk-2.1.2}/README.md

@@ -75,6 +75,10 @@ python3 demo.py
 | `MovJ(target, speed, acceleration)` | 目标：`JointPoint` 或 `CartesianPoint` |
 | `MovL(target, speed, acceleration)` | 目标：`CartesianPoint` 或 `JointPoint` |
 | `Move([MoveInstruction.MovJ(...), ...])` | 多段路径 |
+| `MovJSync(target, speed, acc, wait?)` | 阻塞式关节运动，等待到达目标 |
+| `MovLSync(target, speed, acc, wait?)` | 阻塞式直线运动，等待到达目标 |
+| `MovCSync(middle, target, speed, acc, wait?)` | 阻塞式圆弧运动 |
+| `MoveSync(instructions, wait?)` | 阻塞式路径执行 |
 
 四组合路径示例（与 C++ `04_move` 一致）：
 
@@ -100,6 +104,29 @@ robot.Move(path)
 
 打包规则：`jp` 优先；仅 `cp` 时若未提供 `rj`，JSON 中带默认 `[20,20,20,20,20,20]`（度）。
 
+### 阻塞式运动 API
+
+`*Sync` 方法发送运动指令后自动轮询 CRI 数据，直到机器人稳定到达目标。需要先启动 CRI 数据推送（`StartListenUdp`）。
+
+```python
+from codroid import CodroidClient, JointPoint, MotionWaitOptions
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.ConnectRemoteAndSwitchOn()
+    robot.StartListenUdp()
+    robot.WaitForCriData()  # 等待第一个 CRI 包到达
+
+    # 阻塞式关节运动，使用默认等待参数
+    robot.MovJSync(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acceleration=100)
+
+    # 自定义等待参数
+    opts = MotionWaitOptions(timeout=30.0, joint_tolerance_deg=0.5)
+    robot.MovLSync(CartesianPoint.MmDeg([400, 200, 500, 180, 0, 90]),
+                   speed=150, acceleration=500, wait=opts)
+```
+
+`MotionWaitOptions` 可调整超时、轮询间隔、到达容差等参数。
+
 **Breaking（2.1.1）**：公开 API 与 C# 一致，统一 **PascalCase**（`Connect`、`SwitchOn`、`GetDi`、`MovJ`、`SetToolFrame` 等）；`CriData` 为属性；`move_j` / `switch_on` 等 snake_case 已移除。见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## Windows 控制台 UTF-8
@@ -132,6 +159,7 @@ with CodroidClient(host="192.168.1.136") as robot:
 
 ```bash
 PYTHONPATH=src python examples/08_move.py --robot 192.168.8.136
+PYTHONPATH=src python examples/15_sync_motion.py --robot 192.168.8.136
 PYTHONPATH=src python examples/14_robot_parameters.py --robot 192.168.8.136
 PYTHONPATH=src python examples/codroid_test.py motion
 PYTHONPATH=src python examples/codroid_test.py s20

codroid_robot_sdk-2.1.2/docs/01-quick-start.md

@@ -0,0 +1,160 @@
+# 快速上手
+
+## 安装
+
+### 通过 pip 安装
+
+```bash
+pip install codroid-robot-sdk
+```
+
+可选彩色终端输出：
+
+```bash
+pip install "codroid-robot-sdk[color]"
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/guybod/CodroidSDK.git
+cd CodroidSDK/CodroidPython
+pip install -e .
+```
+
+---
+
+## 最小示例
+
+连接控制器，进入远程模式，上使能。
+
+```python
+from codroid import CodroidControlInterface, InitConsoleUtf8
+
+InitConsoleUtf8()  # Windows cmd 下中文日志不乱码；Linux 上为 no-op
+
+ROBOT_IP = "192.168.1.136"
+
+with CodroidControlInterface(host=ROBOT_IP) as robot:
+    robot.EnterRemoteModeViaAuto()
+    robot.SwitchOn()
+```
+
+运行：
+
+```bash
+python3 demo.py
+```
+
+---
+
+## 完整工作流示例
+
+```python
+from codroid import (
+    CodroidControlInterface,
+    JointPoint,
+    CartesianPoint,
+    MoveInstruction,
+    InitConsoleUtf8,
+)
+
+InitConsoleUtf8()
+
+ROBOT_IP = "192.168.1.136"
+
+with CodroidControlInterface(host=ROBOT_IP) as robot:
+    # 1. 连接并上电
+    robot.EnterRemoteModeViaAuto()
+    robot.SwitchOn()
+
+    # 2. IO 操作
+    di0 = robot.GetDi(0)
+    robot.SetDo(10, di0)
+
+    # 3. 寄存器
+    reg_val = robot.GetRegisterValue(0)
+    robot.SetRegisterValue(0, reg_val + 1)
+
+    # 4. 关节运动
+    robot.MovJ(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acceleration=100)
+
+    # 5. 直线运动
+    robot.MovL(CartesianPoint.MmDeg([400, 200, 500, 180, 0, 90]),
+               speed=150, acceleration=500)
+```
+
+---
+
+## 使用 CodroidClient
+
+`CodroidClient` 继承自 `CodroidSession`，使用后台线程接收数据，支持 publish/subscribe 事件分发。适用于需要持续收包的场景。
+
+```python
+from codroid import CodroidClient, InitConsoleUtf8
+
+InitConsoleUtf8()
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.EnterRemoteModeViaAuto()
+    robot.SwitchOn()
+```
+
+---
+
+## 运行示例项目
+
+```bash
+# 基本用法
+PYTHONPATH=src python examples/01_basic_usage.py --robot 192.168.8.136
+
+# 运动示例
+PYTHONPATH=src python examples/08_move.py --robot 192.168.8.136
+
+# 阻塞式运动
+PYTHONPATH=src python examples/15_sync_motion.py --robot 192.168.8.136
+
+# 机器人设置
+PYTHONPATH=src python examples/14_robot_parameters.py --robot 192.168.8.136
+```
+
+---
+
+## 错误处理
+
+所有 TCP 指令在失败时抛出异常：
+
+| 异常 | 条件 |
+|------|------|
+| `CodroidError` | 基础异常类 |
+| `CodroidCommandException` | 控制器返回 `err` 字段 |
+| `CodroidNetworkError` | TCP 连接或通信失败 |
+| `CodroidTimeoutError` | 操作超时 |
+
+```python
+from codroid import CodroidControlInterface, CodroidError, CodroidTimeoutError
+
+try:
+    with CodroidControlInterface(host="192.168.1.136") as robot:
+        robot.EnterRemoteModeViaAuto()
+        robot.SwitchOn()
+        robot.MovJ([0, 0, 90, 0, 90, 0], speed=40, acceleration=100)
+except CodroidTimeoutError:
+    print("操作超时")
+except CodroidError as e:
+    print(f"SDK 错误: {e}")
+```
+
+---
+
+## Windows 控制台 UTF-8
+
+在 `cmd`（非 Windows Terminal）下运行含中文的示例时，请在入口调用：
+
+```python
+from codroid import InitConsoleUtf8
+
+InitConsoleUtf8()
+```
+
+所有 `examples/*.py` 已在 `if __name__ == "__main__"` 首行调用。自建 CLI 请同样处理；`chcp 65001` 不能替代此调用。Linux / macOS 上为 no-op。

codroid_robot_sdk-2.1.2/docs/02-concepts.md

@@ -0,0 +1,167 @@
+# 核心概念
+
+## 客户端生命周期
+
+`CodroidSession`（别名 `CodroidControlInterface`）和 `CodroidClient` 的典型生命周期：
+
+```python
+from codroid import CodroidClient
+
+# 方式一：with 语句（推荐）
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.EnterRemoteModeViaAuto()
+    robot.SwitchOn()
+    # ... 使用 API ...
+# 自动调用 Disconnect()
+
+# 方式二：手动管理
+robot = CodroidClient(host="192.168.1.136")
+robot.Connect()
+try:
+    robot.EnterRemoteModeViaAuto()
+    robot.SwitchOn()
+    # ... 使用 API ...
+finally:
+    robot.Disconnect()
+```
+
+### CodroidSession vs CodroidClient
+
+| 特性 | CodroidSession | CodroidClient |
+|------|---------------|---------------|
+| 传输层 | `JsonStreamClient`（同步阻塞） | `TransportClient`（后台线程） |
+| 请求/响应匹配 | 同步发送-接收 | 异步 ID 匹配 |
+| Publish/Subscribe | 不支持 | 支持 |
+| 适用场景 | 简单脚本、一次性操作 | 持续收包、事件驱动 |
+
+---
+
+## TCP 命令模型
+
+SDK 通过 TCP JSON 与控制器通信。每条指令的流程：
+
+1. SDK 分配自增 `id`
+2. 发送请求：`{"id": N, "ty": "command/path", "db": {...}}`
+3. 控制器响应：`{"id": N, "ty": "...", "db": {...}, "err": ...}`
+4. SDK 按 `id` 匹配请求与响应
+
+```python
+# SDK 内部自动处理 id 分配和匹配
+response = robot._send_command("Robot/switchOn", "")
+# response = CommonResponse(id=1, ty="Robot/switchOn", db=None, err=None)
+```
+
+### CommonResponse
+
+所有 TCP 指令返回 `CommonResponse`：
+
+```python
+@dataclass
+class CommonResponse:
+    id: Union[int, str]   # 请求 ID
+    ty: str               # 响应类型
+    db: Optional[Any]     # 响应数据
+    err: Optional[Any]    # 错误信息（None 表示成功）
+
+    @property
+    def is_success(self) -> bool:
+        return self.err is None
+```
+
+---
+
+## 单位约定
+
+| 层级 | 线性 | 角度 |
+|------|------|------|
+| SDK 公共 API | **mm** | **deg（度）** |
+| TCP JSON 协议 | **mm** | **deg** |
+| CRI UDP 二进制（线路层） | **m** | **rad（弧度）** |
+| `CriRealTimeData`（已解析） | **mm** | **deg** |
+
+`CriRealtimePacketParser.parse()` 自动将线路层的 m/rad 转换为 mm/deg。
+
+---
+
+## API 命名约定
+
+所有公共方法使用 **PascalCase**，与 C# / C++ SDK 保持一致：
+
+```python
+robot.Connect()
+robot.SwitchOn()
+robot.GetDi(0)
+robot.MovJ(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acceleration=100)
+robot.SetToolFrame(1, RobotFrame(id=1, x=100, y=0, z=0, a=0, b=0, c=0))
+```
+
+> **Breaking（2.1.1）**：`move_j`、`switch_on` 等 snake_case 别名已移除。
+
+---
+
+## 异常处理
+
+SDK 定义了四种异常类型：
+
+| 异常 | 触发条件 |
+|------|----------|
+| `CodroidError` | 基础异常类；参数校验失败、非法操作 |
+| `CodroidCommandException` | 控制器返回 `err` 字段（协议层错误） |
+| `CodroidNetworkError` | TCP 连接失败、通信中断 |
+| `CodroidTimeoutError` | 操作超时（连接、CRI 等待、阻塞运动） |
+
+```python
+from codroid import (
+    CodroidError,
+    CodroidCommandException,
+    CodroidNetworkError,
+    CodroidTimeoutError,
+)
+
+try:
+    with CodroidClient(host="192.168.1.136") as robot:
+        robot.ConnectRemoteAndSwitchOn()
+except CodroidNetworkError:
+    print("无法连接控制器")
+except CodroidTimeoutError:
+    print("连接超时")
+except CodroidCommandException as e:
+    print(f"控制器错误: {e}")
+except CodroidError as e:
+    print(f"SDK 错误: {e}")
+```
+
+---
+
+## 线程安全
+
+- `CriData` 属性返回当前缓存的 CRI 快照，可从任意线程读取。
+- TCP 方法（`GetDi`、`MovJ` 等）可从任意线程调用，但同一客户端实例不支持并发调用。
+- `CriRealtimeDispatcher` 的 `SendCommand` / `SendTrajectory` 是线程安全的（UDP 无状态）。
+
+---
+
+## Publish / Subscribe
+
+`CodroidClient` 支持订阅控制器推送的事件主题：
+
+```python
+from codroid import CodroidClient, PublishTopics
+
+def on_robot_status(notification):
+    print(f"收到 {notification.ty}: {notification.db}")
+
+with CodroidClient(host="192.168.1.136") as robot:
+    sub = robot.SubscribePublishTopic(PublishTopics.ROBOT_STATUS, on_robot_status)
+    # ... 运行 ...
+    sub.dispose()  # 取消订阅
+```
+
+可用主题见 `PublishTopics` 常量：
+- `PROJECT_STATE` — 工程状态变更
+- `VAR_UPDATE` — 变量更新
+- `ROBOT_STATUS` — 机器人状态
+- `ROBOT_POSTURE` — 机器人姿态
+- `ROBOT_COORDINATE` — 机器人坐标
+- `LOG` — 日志
+- `ERROR` — 错误