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

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

@@ -92,4 +92,6 @@ htmlcov/
 AGENTS.md
 PROTOCOL_LINE_BY_LINE.md
 SDK_API_AND_DESIGN.md
-TRAJECTORY_ALGORITHM.md
+TRAJECTORY_ALGORITHM.md
+plan.md
+aaa.txt

codroid_robot_sdk-2.1.1/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 2.1.1 — 机器人设置 API（协议 19.x）
+
+### Added
+
+- `robot_settings.py`：`RobotFrame`、`RobotPayloadFrame`、`RobotParameters`
+- `SetCollisionSensitivity`、`GetRobotParameters`
+- 仅改默认编号：`SetDefaultPayloadId`、`SetDefaultToolId`、`SetDefaultUserCoordinateId`
+- 先读后改：`SetToolFrame`、`SetPayloadFrame`、`SetUserCoordinateFrame`
+- 整表下发：`SaveToolFrames`、`SavePayloadFrames`、`SaveUserCoordinateFrames`
+- 示例：`examples/14_robot_parameters.py`；`codroid_test.py robotparam`
+
+### Changed / Breaking
+
+- 运动门面仅保留 C# 同名：`MovJ`、`MovL`、`MovC`、`MovCircle`、`Move`、`MoveTo`、`MoveToHeartbeat`
+- 移除 `move_j` / `move_l` / `move_c` / `move_circle` / `execute_path` / `move` / `move_to` / `move_to_heartbeat`
+- `MoveTarget` 更名为 `MoveToTarget`（与 C# 一致）；`MotionPath.mov_*` 更名为 `MovJ` / `MovL` / `MovC`
+- **`CodroidSession` / `CodroidClient` 全部公开方法改为 PascalCase**（`Connect`、`SwitchOn`、`GetDi`、`StartCriDataPush` 等）；移除文件末尾历史 snake_case 别名
+- `get_cri_data()` 改为属性 **`CriData`**（对齐 C#）
+- `close` / `disconnect` 合并为 **`Disconnect`**
+- `CriRealtimeDispatcher.send_command` → **`SendCommand`**，`send_trajectory` → **`SendTrajectory`**
+- 移除 `subscribe_publish_topic` 别名
+
+## 2.1.0 — 运动 API 类型化（Breaking）
+
+与 C++ SDK v2.1.1 / `update1.md` 对齐。
+
+### Added
+
+- `JointPoint`、`CartesianPoint`、`MoveInstruction` 及工厂（`Degrees`、`MmDeg`、`MmDegWithRef`、`MovJ`/`MovL`/…）
+- `pack_move_point` / `pack_instruction`（`jp` 优先；笛卡尔缺省 `rj=[20,…,20]`）
+- 门面 API：`MovJ`、`MovL`、`MovC`、`MovCircle`、`Move`、`MoveTo`、`MoveToHeartbeat`
+- `MoveToTarget.Joint` / `MoveToTarget.Cartesian`
+- `InitConsoleUtf8()`（Windows 控制台 UTF-8）
+
+### Changed
+
+- `MovePoint.to_dict()` 经统一打包逻辑，仅 `cp` 时 JSON 会带默认 `rj`
+- 示例与 `codroid_test` 运动段改用类型化 API
+
+### Deprecated
+
+- 旧版 snake_case 运动方法（2.1.1 起已删除，见 2.1.1 Breaking）
+- 直接 `MovePoint(jp=…)` 作业务目标（请改用 `JointPoint` / `CartesianPoint`）
+
+### Migration
+
+1. 程序入口首行：`InitConsoleUtf8()`
+2. 关节目标 → `JointPoint.Degrees([...])` + `MovJ` / `MoveInstruction.MovJ`
+3. TCP 目标 → `CartesianPoint.MmDeg` 或 `MmDegWithRef(pose, cri_joint)`
+4. 多段路径 → `Move([MoveInstruction.MovJ(...), ...])`

codroid_robot_sdk-2.1.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: codroid-robot-sdk
+Version: 2.1.1
+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
+Project-URL: Source, https://github.com/guybod/CodroidSDK
+Author-email: guybod <b13140185898@outlook.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.7
+Provides-Extra: color
+Requires-Dist: colorama>=0.4.6; extra == 'color'
+Description-Content-Type: text/markdown
+
+# Codroid 机器人 Python SDK
+
+Codroid 控制器 Python SDK，提供 TCP 控制、实时数据（CRI）与轨迹相关能力。
+
+[![PyPI - Version](https://img.shields.io/pypi/v/codroid-robot-sdk.svg)](https://pypi.org/project/codroid-robot-sdk)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/codroid-robot-sdk.svg)](https://pypi.org/project/codroid-robot-sdk)
+
+---
+
+## 教程：5 分钟跑通
+
+### 1) 环境准备
+
+- Python 3.7 及以上（建议 3.8+）
+- 机器人控制器与运行脚本的电脑网络互通
+
+### 2) 安装 SDK
+
+```bash
+pip install codroid-robot-sdk
+```
+
+可选彩色终端输出：
+
+```bash
+pip install "codroid-robot-sdk[color]"
+```
+
+### 3) 验证安装
+
+```bash
+python3 -c "import codroid; print(codroid.__version__)"
+```
+
+### 4) 第一个控制脚本
+
+新建 `demo.py`：
+
+```python
+from codroid import CodroidControlInterface, InitConsoleUtf8
+
+InitConsoleUtf8()  # Windows cmd 下中文日志不乱码；Linux 上为 no-op
+
+ROBOT_IP = "192.168.1.136"  # 改成实际控制器 IP
+
+with CodroidControlInterface(host=ROBOT_IP) as robot:
+    robot.ToRemote()
+    robot.SwitchOn()
+```
+
+运行：
+
+```bash
+python3 demo.py
+```
+
+### 5) 常见下一步
+
+- 进入远程模式后，继续调用运动、IO、寄存器等 API。
+- 需要持续收包和 publish 分发时，改用 `CodroidClient`。
+- 运动示例见 `examples/08_move.py`（四组合路径）与 `examples/codroid_test.py motion`。
+
+## 运动 API（2.1+）
+
+协议 JSON 未变；业务层须用类型区分关节与 TCP，避免把位姿当关节角下发。
+
+| 业务类型 | 工厂 | 用于 |
+|----------|------|------|
+| `JointPoint` | `Degrees([j1..j6])` | 六轴角（度） |
+| `CartesianPoint` | `MmDeg([x,y,z,rx,ry,rz])` | TCP（mm + 度） |
+| | `MmDegWithRef(pose, ref_joints)` | TCP + 逆解参考关节（推荐） |
+
+| 门面 API | 说明 |
+|----------|------|
+| `MovJ(target, speed, acceleration)` | 目标：`JointPoint` 或 `CartesianPoint` |
+| `MovL(target, speed, acceleration)` | 目标：`CartesianPoint` 或 `JointPoint` |
+| `Move([MoveInstruction.MovJ(...), ...])` | 多段路径 |
+
+四组合路径示例（与 C++ `04_move` 一致）：
+
+```python
+from codroid import (
+    CodroidClient,
+    JointPoint,
+    CartesianPoint,
+    MoveInstruction,
+    InitConsoleUtf8,
+)
+
+InitConsoleUtf8()
+
+path = [
+    MoveInstruction.MovJ(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acc=100),
+    MoveInstruction.MovJ(CartesianPoint.MmDeg([...]), speed=40, acc=100),
+    MoveInstruction.MovL(CartesianPoint.MmDeg([...]), speed=150, acc=500),
+    MoveInstruction.MovL(JointPoint.Degrees([0, 0, 0, 0, 0, 0]), speed=150, acc=500),
+]
+robot.Move(path)
+```
+
+打包规则：`jp` 优先；仅 `cp` 时若未提供 `rj`，JSON 中带默认 `[20,20,20,20,20,20]`（度）。
+
+**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
+
+在 `cmd`（非 Windows Terminal）下运行含中文的示例时，请在入口调用：
+
+```python
+from codroid import InitConsoleUtf8
+
+InitConsoleUtf8()
+```
+
+所有 `examples/*.py` 已在 `if __name__ == "__main__"` 首行调用。自建 CLI 请同样处理；`chcp 65001` 不能替代此调用。
+
+## 教程：进阶连接方式
+
+`CodroidClient` 适用于后台持续接收、请求 `id` 配对、publish 分发：
+
+```python
+from codroid import CodroidClient, InitConsoleUtf8
+
+InitConsoleUtf8()
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.ToRemote()
+    robot.SwitchOn()
+```
+
+## 示例
+
+```bash
+PYTHONPATH=src python examples/08_move.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
+PYTHONPATH=src python examples/codroid_test.py robotparam
+```
+
+机器人设置（协议 19.x）：`GetRobotParameters`、`SetToolFrame`、`SetDefaultToolId` 等见 `examples/14_robot_parameters.py`。
+
+寄存器与 S20 运动常量见仓库根目录 `AGENTS.md` §5.1。
+
+## 常见问题
+
+### `ModuleNotFoundError: No module named codroid`
+
+未在当前 Python 环境安装 SDK。重新执行：
+
+```bash
+pip install codroid-robot-sdk
+```
+
+### 脚本无响应或连接失败
+
+- 检查控制器 IP 与端口配置。
+- 检查本机与控制器网络连通性、防火墙策略。
+- 确认控制器处于可远程控制状态。
+
+## 项目架构
+
+```text
+src/codroid/
+├── __init__.py                     # 公开 API 导出（含 __version__）
+├── __about__.py                    # 版本号
+├── Codroid.py                      # CodroidSession / CodroidControlInterface
+├── client.py                       # CodroidClient
+├── async_tcp_client.py             # JsonStreamClient、TransportClient
+├── define.py                       # DTO / 常量（JointPoint、MoveInstruction 等）
+├── robot_motion.py                 # pack_move_point / pack_instruction
+├── types.py                        # DTO 再导出
+├── exceptions.py                   # 异常定义
+├── publish.py                      # 发布订阅模型
+├── trajectory.py                   # 轨迹生成
+├── cri_realtime_packet_parser.py   # CRI UDP 数据解析
+├── cri_realtime_dispatcher.py      # CRI 实时控制下发
+├── console.py                      # PrintBanner
+├── console_utf8.py                 # InitConsoleUtf8
+└── utils.py                        # 通用工具
+```
+
+## 许可证
+
+本项目采用 [MIT](https://spdx.org/licenses/MIT.html) 许可证。

codroid_robot_sdk-2.1.1/README.md

@@ -0,0 +1,185 @@
+# Codroid 机器人 Python SDK
+
+Codroid 控制器 Python SDK，提供 TCP 控制、实时数据（CRI）与轨迹相关能力。
+
+[![PyPI - Version](https://img.shields.io/pypi/v/codroid-robot-sdk.svg)](https://pypi.org/project/codroid-robot-sdk)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/codroid-robot-sdk.svg)](https://pypi.org/project/codroid-robot-sdk)
+
+---
+
+## 教程：5 分钟跑通
+
+### 1) 环境准备
+
+- Python 3.7 及以上（建议 3.8+）
+- 机器人控制器与运行脚本的电脑网络互通
+
+### 2) 安装 SDK
+
+```bash
+pip install codroid-robot-sdk
+```
+
+可选彩色终端输出：
+
+```bash
+pip install "codroid-robot-sdk[color]"
+```
+
+### 3) 验证安装
+
+```bash
+python3 -c "import codroid; print(codroid.__version__)"
+```
+
+### 4) 第一个控制脚本
+
+新建 `demo.py`：
+
+```python
+from codroid import CodroidControlInterface, InitConsoleUtf8
+
+InitConsoleUtf8()  # Windows cmd 下中文日志不乱码；Linux 上为 no-op
+
+ROBOT_IP = "192.168.1.136"  # 改成实际控制器 IP
+
+with CodroidControlInterface(host=ROBOT_IP) as robot:
+    robot.ToRemote()
+    robot.SwitchOn()
+```
+
+运行：
+
+```bash
+python3 demo.py
+```
+
+### 5) 常见下一步
+
+- 进入远程模式后，继续调用运动、IO、寄存器等 API。
+- 需要持续收包和 publish 分发时，改用 `CodroidClient`。
+- 运动示例见 `examples/08_move.py`（四组合路径）与 `examples/codroid_test.py motion`。
+
+## 运动 API（2.1+）
+
+协议 JSON 未变；业务层须用类型区分关节与 TCP，避免把位姿当关节角下发。
+
+| 业务类型 | 工厂 | 用于 |
+|----------|------|------|
+| `JointPoint` | `Degrees([j1..j6])` | 六轴角（度） |
+| `CartesianPoint` | `MmDeg([x,y,z,rx,ry,rz])` | TCP（mm + 度） |
+| | `MmDegWithRef(pose, ref_joints)` | TCP + 逆解参考关节（推荐） |
+
+| 门面 API | 说明 |
+|----------|------|
+| `MovJ(target, speed, acceleration)` | 目标：`JointPoint` 或 `CartesianPoint` |
+| `MovL(target, speed, acceleration)` | 目标：`CartesianPoint` 或 `JointPoint` |
+| `Move([MoveInstruction.MovJ(...), ...])` | 多段路径 |
+
+四组合路径示例（与 C++ `04_move` 一致）：
+
+```python
+from codroid import (
+    CodroidClient,
+    JointPoint,
+    CartesianPoint,
+    MoveInstruction,
+    InitConsoleUtf8,
+)
+
+InitConsoleUtf8()
+
+path = [
+    MoveInstruction.MovJ(JointPoint.Degrees([0, 0, 90, 0, 90, 0]), speed=40, acc=100),
+    MoveInstruction.MovJ(CartesianPoint.MmDeg([...]), speed=40, acc=100),
+    MoveInstruction.MovL(CartesianPoint.MmDeg([...]), speed=150, acc=500),
+    MoveInstruction.MovL(JointPoint.Degrees([0, 0, 0, 0, 0, 0]), speed=150, acc=500),
+]
+robot.Move(path)
+```
+
+打包规则：`jp` 优先；仅 `cp` 时若未提供 `rj`，JSON 中带默认 `[20,20,20,20,20,20]`（度）。
+
+**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
+
+在 `cmd`（非 Windows Terminal）下运行含中文的示例时，请在入口调用：
+
+```python
+from codroid import InitConsoleUtf8
+
+InitConsoleUtf8()
+```
+
+所有 `examples/*.py` 已在 `if __name__ == "__main__"` 首行调用。自建 CLI 请同样处理；`chcp 65001` 不能替代此调用。
+
+## 教程：进阶连接方式
+
+`CodroidClient` 适用于后台持续接收、请求 `id` 配对、publish 分发：
+
+```python
+from codroid import CodroidClient, InitConsoleUtf8
+
+InitConsoleUtf8()
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.ToRemote()
+    robot.SwitchOn()
+```
+
+## 示例
+
+```bash
+PYTHONPATH=src python examples/08_move.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
+PYTHONPATH=src python examples/codroid_test.py robotparam
+```
+
+机器人设置（协议 19.x）：`GetRobotParameters`、`SetToolFrame`、`SetDefaultToolId` 等见 `examples/14_robot_parameters.py`。
+
+寄存器与 S20 运动常量见仓库根目录 `AGENTS.md` §5.1。
+
+## 常见问题
+
+### `ModuleNotFoundError: No module named codroid`
+
+未在当前 Python 环境安装 SDK。重新执行：
+
+```bash
+pip install codroid-robot-sdk
+```
+
+### 脚本无响应或连接失败
+
+- 检查控制器 IP 与端口配置。
+- 检查本机与控制器网络连通性、防火墙策略。
+- 确认控制器处于可远程控制状态。
+
+## 项目架构
+
+```text
+src/codroid/
+├── __init__.py                     # 公开 API 导出（含 __version__）
+├── __about__.py                    # 版本号
+├── Codroid.py                      # CodroidSession / CodroidControlInterface
+├── client.py                       # CodroidClient
+├── async_tcp_client.py             # JsonStreamClient、TransportClient
+├── define.py                       # DTO / 常量（JointPoint、MoveInstruction 等）
+├── robot_motion.py                 # pack_move_point / pack_instruction
+├── types.py                        # DTO 再导出
+├── exceptions.py                   # 异常定义
+├── publish.py                      # 发布订阅模型
+├── trajectory.py                   # 轨迹生成
+├── cri_realtime_packet_parser.py   # CRI UDP 数据解析
+├── cri_realtime_dispatcher.py      # CRI 实时控制下发
+├── console.py                      # PrintBanner
+├── console_utf8.py                 # InitConsoleUtf8
+└── utils.py                        # 通用工具
+```
+
+## 许可证
+
+本项目采用 [MIT](https://spdx.org/licenses/MIT.html) 许可证。

codroid_robot_sdk-2.1.1/examples/01_basic_usage.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+示例 01 — 最简联调流程（连接 → 远程 → 使能 → movJ → CRI 打印）
+
+【目的】
+  演示 SDK 2.1+ 最小闭环：TCP 控制 + CRI 实时缓存读取。
+
+【前置条件】
+  - 控制器与 PC 同网段，TCP 9001 可达
+  - 本机 UDP 端口（默认 18888）未被占用，且防火墙放行
+  - 机器人可远程控制、允许上使能
+
+【涉及协议】
+  - TCP：模式切换、使能、Robot/move（movJ）、CRI/StartDataPush / StopDataPush
+  - UDP：308 字节 CRI 推送（解析后为 mm + 度，见 AGENTS.md §2.3）
+
+【运行】
+  PYTHONPATH=src python examples/01_basic_usage.py
+  PYTHONPATH=src python examples/01_basic_usage.py --robot 192.168.8.136
+
+【注意】
+  - 会实际运动机器人，请在安全空间内运行
+  - ``JointPoint.Degrees`` 表示六轴关节角（度），勿与 TCP 位姿混用
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from codroid import CodroidControlInterface, InitConsoleUtf8, JointPoint, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    # ---------- 命令行：现场改 IP / 本机 CRI 绑定 ----------
+    p = argparse.ArgumentParser(description="Basic connect, moveJ, CRI cache")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    p.add_argument("--local-ip", default="192.168.8.150", help="本机 IP（CRI 推送目标）")
+    p.add_argument(
+        "--udp-port",
+        type=int,
+        default=18888,
+        help="本机 UDP 端口（建议 10000–65534）",
+    )
+    args = p.parse_args(argv)
+
+    PrintBanner("01 — Basic usage", subtitle=f"{args.robot}  CRI → {args.local_ip}:{args.udp_port}")
+
+    # with 退出时自动 Disconnect，避免 TCP/UDP 泄漏
+    with CodroidControlInterface(
+        host=args.robot,
+        local_ip=args.local_ip,
+        udp_port=args.udp_port,
+    ) as robot:
+        # 典型上电顺序：先自动再远程（与 C# ConnectRemoteAndSwitchOn 子步骤一致）
+        robot.EnterRemoteModeViaAuto()
+        robot.SwitchOn()
+
+        # 后台线程收 CRI UDP，结果写入 robot.cri_cache（线程安全快照）
+        robot._start_cri_receiver()
+        robot.StartCriDataPush(ip=args.local_ip, port=args.udp_port)
+
+        try:
+            # 类型化目标：明确是「关节角」而非 TCP
+            p1 = JointPoint.Degrees([0, 0, 90, 0, 90, 0])
+            p2 = JointPoint.Degrees([0, 0, 0, 0, 0, 0])
+            for _ in range(3):
+                # MovJ(target, speed, acceleration)；单位：度、%/s 等按控制器约定
+                robot.MovJ(p1, 60, 120)
+                robot.MovJ(p2, 60, 120)
+
+            PrintBanner("CRI cache loop", subtitle="Ctrl+C 退出")
+            while True:
+                data = robot.cri_cache
+                if data:
+                    # joint_pos / is_moving 来自 CRI 解析（已是度、mm 等对外单位）
+                    print(f"关节角 / joint_pos: {data.joint_pos}")
+                    print(f"运动中 / is_moving: {data.status.is_moving}")
+                time.sleep(0.1)
+        except KeyboardInterrupt:
+            print("已中断 / Interrupted", file=sys.stderr)
+            return 130
+        finally:
+            # 停止推送，释放控制器侧推送任务
+            robot.StopCriDataPush(ip=args.local_ip, port=args.udp_port)
+
+    return 0
+
+
+if __name__ == "__main__":
+    # Windows cmd 下中文不乱码；Linux 为 no-op
+    InitConsoleUtf8()
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.1.1/examples/02_run_script.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""
+示例 02 — 远程 Lua 脚本（project/runScript）
+
+【目的】
+  向控制器下发一段 Lua 源码及可选全局变量字典，由控制器解释执行。
+
+【前置条件】
+  - 已进入远程模式（本示例调用 enter_remote_mode_via_auto）
+  - Lua 语法与控制器内置 API 匹配（如 movej 等）
+
+【涉及协议】
+  - TCP ``project/runScript``：db 含脚本文本与 vars
+
+【运行】
+  PYTHONPATH=src python examples/02_run_script.py --robot <IP>
+
+【注意】
+  - 示例脚本含 movej，会运动；请按现场修改 lua_code
+  - vars 键名须符合控制器变量命名规则
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from codroid import CodroidControlInterface, InitConsoleUtf8, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="Run remote Lua script")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    args = p.parse_args(argv)
+
+    PrintBanner("02 — Run script", subtitle=args.robot)
+
+    # 下发到控制器的 Lua 源码（字符串）；换行用 \\n
+    lua_code = "print('Hello Codroid')\nmovej([0,0,0,0,0,0])"
+    # 与脚本一起传入的共享变量（控制器侧可见）
+    vars_data = {"v1": 100, "v2": "test"}
+
+    try:
+        with CodroidControlInterface(host=args.robot) as robot:
+            robot.EnterRemoteModeViaAuto()
+            print("发送脚本 / Sending script...")
+            res = robot.RunScript(lua_code, vars=vars_data)
+            if res.is_success:
+                print("脚本请求已发送 / Script request sent")
+            else:
+                # res.err 非空表示控制器拒绝或执行报错
+                print(f"失败 / Failed: {res.err}", file=sys.stderr)
+                return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    InitConsoleUtf8()
+    raise SystemExit(main(sys.argv[1:]))

{codroid_robot_sdk-2.0.0 → codroid_robot_sdk-2.1.1}/examples/03_run_project.py

@@ -1,12 +1,23 @@
 #!/usr/bin/env python3
 """
-工程控制：运行、暂停、恢复、停止、按索引启动。
+示例 03 — 工程运行控制（运行 / 暂停 / 恢复 / 停止 / 按索引启动）
 
-用法:
-  PYTHONPATH=src python examples/03_run_project.py
-  PYTHONPATH=src python examples/03_run_project.py --robot 192.168.8.136
+【目的】
+  演示与示教器工程相关的 TCP 指令序列，便于集成 MES/上位机调度。
 
-彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+【前置条件】
+  - 控制器内存在对应工程（--project-id 默认 projectluademo）
+  - 远程模式
+
+【涉及协议】
+  - project/run、pause、resume、stop、runByIndex 等（见 PROTOCOL_LINE_BY_LINE.md）
+
+【运行】
+  PYTHONPATH=src python examples/03_run_project.py --robot <IP>
+
+【注意】
+  - 每步之间有 --step-sleep 间隔，便于观察示教器状态
+  - 不传工程名时 run_project 可能失败，请按现场修改 --project-id
 """
 from __future__ import annotations
 
@@ -14,7 +25,7 @@ import argparse
 import sys
 import time
 
-from codroid import CodroidControlInterface, PrintBanner
+from codroid import CodroidControlInterface, InitConsoleUtf8, PrintBanner
 
 
 def main(argv: list[str]) -> int:
@@ -33,29 +44,31 @@ def main(argv: list[str]) -> int:
 
     try:
         with CodroidControlInterface(host=args.robot) as robot:
-            robot.enter_remote_mode_via_auto()
+            robot.EnterRemoteModeViaAuto()
 
-            res = robot.run_project(args.project_id)
+            # 按工程名启动
+            res = robot.Run(args.project_id)
             print("运行 / run:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
-            res = robot.pause_project()
+            res = robot.PauseProject()
             print("暂停 / pause:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
-            res = robot.resume_project()
+            res = robot.ResumeProject()
             print("恢复 / resume:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
-            res = robot.stop_project()
+            res = robot.StopProject()
             print("停止 / stop:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
-            res = robot.run_project_by_index(args.index)
+            # 按索引启动（与示教器工程列表顺序相关）
+            res = robot.RunByIndex(args.index)
             print("按索引启动 / by_index:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
-            res = robot.stop_project()
+            res = robot.StopProject()
             print("再次停止 / stop:", "ok" if res.is_success else res.err)
     except KeyboardInterrupt:
         return 130
@@ -63,4 +76,5 @@ def main(argv: list[str]) -> int:
 
 
 if __name__ == "__main__":
+    InitConsoleUtf8()
     raise SystemExit(main(sys.argv[1:]))