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

{codroid_robot_sdk-2.0.0 → codroid_robot_sdk-2.1.0}/.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.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 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`
+- `MoveTarget.Joint` / `MoveTarget.Cartesian`（别名 `MoveToTarget`）
+- `InitConsoleUtf8()`（Windows 控制台 UTF-8）
+
+### Changed
+
+- `MovePoint.to_dict()` 经统一打包逻辑，仅 `cp` 时 JSON 会带默认 `rj`
+- 示例与 `codroid_test` 运动段改用类型化 API
+
+### Deprecated
+
+- `move_j` / `move_l` / `move_c` / `move_circle` / `execute_path`（请改用 PascalCase 门面）
+- 直接 `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.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: codroid-robot-sdk
+Version: 2.1.0
+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.to_remote()
+    robot.switch_on()
+```
+
+运行：
+
+```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.0）**：请勿再用 `MovePoint(jp=...)` 作业务入口；`move_j` / `move_l` 已废弃，见 [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.to_remote()
+    robot.switch_on()
+```
+
+## 示例
+
+```bash
+PYTHONPATH=src python examples/08_move.py --robot 192.168.8.136
+PYTHONPATH=src python examples/codroid_test.py motion
+PYTHONPATH=src python examples/codroid_test.py s20
+```
+
+寄存器与 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.0/README.md

@@ -0,0 +1,181 @@
+# 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.to_remote()
+    robot.switch_on()
+```
+
+运行：
+
+```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.0）**：请勿再用 `MovePoint(jp=...)` 作业务入口；`move_j` / `move_l` 已废弃，见 [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.to_remote()
+    robot.switch_on()
+```
+
+## 示例
+
+```bash
+PYTHONPATH=src python examples/08_move.py --robot 192.168.8.136
+PYTHONPATH=src python examples/codroid_test.py motion
+PYTHONPATH=src python examples/codroid_test.py s20
+```
+
+寄存器与 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.0.0 → codroid_robot_sdk-2.1.0}/examples/01_basic_usage.py

@@ -1,12 +1,26 @@
 #!/usr/bin/env python3
 """
-基础示例：连接、远程、上使能、关节运动，并打印 CRI 缓存中的关节角。
+示例 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
 
-彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+【注意】
+  - 会实际运动机器人，请在安全空间内运行
+  - ``JointPoint.Degrees`` 表示六轴关节角（度），勿与 TCP 位姿混用
 """
 from __future__ import annotations
 
@@ -14,13 +28,14 @@ import argparse
 import sys
 import time
 
-from codroid import CodroidControlInterface, MovePoint, PrintBanner
+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("--local-ip", default="192.168.8.150", help="本机 IP（CRI 推送目标）")
     p.add_argument(
         "--udp-port",
         type=int,
@@ -31,27 +46,34 @@ def main(argv: list[str]) -> int:
 
     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.enter_remote_mode_via_auto()
         robot.switch_on()
+
+        # 后台线程收 CRI UDP，结果写入 robot.cri_cache（线程安全快照）
         robot._start_cri_receiver()
         robot.start_cri_data_push(ip=args.local_ip, port=args.udp_port)
 
         try:
-            p1 = MovePoint(jp=[0, 0, 90, 0, 90, 0])
-            p2 = MovePoint(jp=[0, 0, 0, 0, 0, 0])
+            # 类型化目标：明确是「关节角」而非 TCP
+            p1 = JointPoint.Degrees([0, 0, 90, 0, 90, 0])
+            p2 = JointPoint.Degrees([0, 0, 0, 0, 0, 0])
             for _ in range(3):
-                robot.move_j(p1, 60, 120)
-                robot.move_j(p2, 60, 120)
+                # 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)
@@ -59,10 +81,13 @@ def main(argv: list[str]) -> int:
             print("已中断 / Interrupted", file=sys.stderr)
             return 130
         finally:
+            # 停止推送，释放控制器侧推送任务
             robot.stop_cri_data_push(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.0.0 → codroid_robot_sdk-2.1.0}/examples/02_run_script.py

@@ -1,19 +1,30 @@
 #!/usr/bin/env python3
 """
-通过 ``project/runScript`` 下发 Lua 与共享变量。
+示例 02 — 远程 Lua 脚本（project/runScript）
 
-用法:
-  PYTHONPATH=src python examples/02_run_script.py
-  PYTHONPATH=src python examples/02_run_script.py --robot 192.168.8.136
+【目的】
+  向控制器下发一段 Lua 源码及可选全局变量字典，由控制器解释执行。
 
-彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+【前置条件】
+  - 已进入远程模式（本示例调用 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, PrintBanner
+from codroid import CodroidControlInterface, InitConsoleUtf8, PrintBanner
 
 
 def main(argv: list[str]) -> int:
@@ -23,7 +34,9 @@ def main(argv: list[str]) -> int:
 
     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:
@@ -34,6 +47,7 @@ def main(argv: list[str]) -> int:
             if res.is_success:
                 print("脚本请求已发送 / Script request sent")
             else:
+                # res.err 非空表示控制器拒绝或执行报错
                 print(f"失败 / Failed: {res.err}", file=sys.stderr)
                 return 1
     except KeyboardInterrupt:
@@ -42,4 +56,5 @@ def main(argv: list[str]) -> int:
 
 
 if __name__ == "__main__":
+    InitConsoleUtf8()
     raise SystemExit(main(sys.argv[1:]))

{codroid_robot_sdk-2.0.0 → codroid_robot_sdk-2.1.0}/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:
@@ -35,6 +46,7 @@ def main(argv: list[str]) -> int:
         with CodroidControlInterface(host=args.robot) as robot:
             robot.enter_remote_mode_via_auto()
 
+            # 按工程名启动
             res = robot.run_project(args.project_id)
             print("运行 / run:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
@@ -51,6 +63,7 @@ def main(argv: list[str]) -> int:
             print("停止 / stop:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
 
+            # 按索引启动（与示教器工程列表顺序相关）
             res = robot.run_project_by_index(args.index)
             print("按索引启动 / by_index:", "ok" if res.is_success else res.err)
             time.sleep(args.step_sleep)
@@ -63,4 +76,5 @@ def main(argv: list[str]) -> int:
 
 
 if __name__ == "__main__":
+    InitConsoleUtf8()
     raise SystemExit(main(sys.argv[1:]))

{codroid_robot_sdk-2.0.0 → codroid_robot_sdk-2.1.0}/examples/04_global_value.py

@@ -1,19 +1,29 @@
 #!/usr/bin/env python3
 """
-增量保存全局变量（整数、字符串、列表、字典）。
+示例 04 — 全局变量增量保存（globalVar/save）
 
-用法:
-  PYTHONPATH=src python examples/04_global_value.py
-  PYTHONPATH=src python examples/04_global_value.py --robot 192.168.8.136
+【目的】
+  演示 ``GlobalVariable`` 包装不同类型（int/str/list/dict）并批量写入控制器。
 
-彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+【前置条件】
+  - 远程模式
+  - 变量名合法（字母数字下划线等，见 SDK 校验）
+
+【涉及协议】
+  - TCP globalVar/save：每个变量含 val（JSON 字符串）与可选 nm（备注）
+
+【运行】
+  PYTHONPATH=src python examples/04_global_value.py --robot <IP>
+
+【注意】
+  - save_global_vars 为增量保存，不会删除未出现在字典中的其它全局变量
 """
 from __future__ import annotations
 
 import argparse
 import sys
 
-from codroid import CodroidControlInterface, GlobalVariable, PrintBanner
+from codroid import CodroidControlInterface, GlobalVariable, InitConsoleUtf8, PrintBanner
 
 
 def main(argv: list[str]) -> int:
@@ -23,6 +33,7 @@ def main(argv: list[str]) -> int:
 
     PrintBanner("04 — Global variables", subtitle=args.robot)
 
+    # 键为控制器侧全局变量名；value 为 GlobalVariable(value=..., note=...)
     vars_to_save = {
         "v_int": GlobalVariable(value=1024, note="整数示例"),
         "v_str": GlobalVariable(value="Codroid", note="字符串示例"),
@@ -49,4 +60,5 @@ def main(argv: list[str]) -> int:
 
 
 if __name__ == "__main__":
+    InitConsoleUtf8()
     raise SystemExit(main(sys.argv[1:]))