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

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

@@ -86,4 +86,10 @@ site/
 htmlcov/
 
 # 本地环境配置文件
-.env
+.env
+
+# 内部协议/设计文档（本地副本，不入库）
+AGENTS.md
+PROTOCOL_LINE_BY_LINE.md
+SDK_API_AND_DESIGN.md
+TRAJECTORY_ALGORITHM.md

{codroid_robot_sdk-1.2.0 → codroid_robot_sdk-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codroid-robot-sdk
-Version: 1.2.0
+Version: 2.0.0
 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
@@ -9,14 +9,19 @@ 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.8
+Requires-Python: >=3.7
+Provides-Extra: color
+Requires-Dist: colorama>=0.4.6; extra == 'color'
 Description-Content-Type: text/markdown
 
 # Codroid Robot Python SDK
@@ -60,10 +65,11 @@ pipx install hatch
 pip install hatch
 ```
 ### 2. 获取代码与初始化
-```Bash
+```bash
 git clone <your-repo-url>
-cd CodroidSDK/python
+cd CodroidPython
 ```
+若系统仅有 `python3` 命令（常见于 Debian/Ubuntu），下文请将 `python` 换成 `python3`，或使用 `hatch shell` 后按 Hatch 环境内的解释器为准。
 ### 3. 运行示例程序
 使用 Hatch 运行示例是最简单的方法，它会自动处理所有依赖和环境路径。
 ```Bash
@@ -81,12 +87,22 @@ pip install codroid-robot-sdk
 ```python
 from codroid import CodroidControlInterface
 
-# Initialize and connect automatically
+# Initialize and connect automatically (CodroidSession + synchronous JsonStreamClient)
 with CodroidControlInterface(host="192.168.1.136") as robot:
     robot.to_remote()
     robot.switch_on()
 ```
 
+需要 **后台收包、`id` 配对、Publish 按 `ty` 分发** 时，请使用 `CodroidClient`（内部为 `TransportClient`）：
+
+```python
+from codroid import CodroidClient
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.to_remote()
+    robot.switch_on()
+```
+
 # 🛠️ Hatch 开发工作流
 本项目采用了现代 Python 的 src 布局，建议通过以下命令进行开发：
 ## 进入开发 Shell
@@ -108,12 +124,32 @@ hatch build
 hatch run docs:serve
 ```
 # 📂 目录结构说明
-- src/codroid/: SDK 核心源码。
-  - CodroidControlInterface.py: 主控制类。
-  - cri.py: 实时数据流处理。
-  - models.py: 数据模型与枚举定义。
-- examples/: 示例程序目录。
-- pyproject.toml: 项目配置文件 (Hatch 配置)。
+
+源码布局与 C# SDK（``CodroidSDK/*.cs``）**同名模块一一对应**（Python 为 snake_case + ``.py``）。详细演进见仓库根目录 ``plan.md``。
+
+```text
+src/codroid/
+├── __init__.py              # 公开 API 聚合导出
+├── __about__.py             # 版本号
+├── Codroid.py               # CodroidSession；CodroidControlInterface 别名
+├── client.py                # CodroidClient（TransportClient + 门面）
+├── async_tcp_client.py      # JsonStreamClient、TransportClient / FutureTcpClient
+├── define.py                # DTO / 常量（Define.cs）
+├── types.py                 # DTO 再导出（便于与文档表述一致）
+├── exceptions.py            # CodroidCommandException、网络/超时等
+├── utils.py                 # 共用工具
+├── console.py               # PrintBanner 等
+├── publish.py               # CodroidPublish.cs
+├── trajectory.py            # Trajectory.cs
+├── cri_realtime_packet_parser.py   # CriRealtimePacketParser.cs（含 CriStreamHandler）
+└── cri_realtime_dispatcher.py      # CriRealtimeDispatcher.cs
+```
+
+下列文件在 **2.0 计划** 中与 C# 对齐，业务将从 ``Codroid.py`` 拆出后落盘（当前可能尚未存在）：``global_variables.py``、``io.py``、``register.py``、``robot_kinematics.py``、``robot_motion.py``。
+
+- ``examples/``: 示例程序。
+- ``pyproject.toml``: Hatch / 构建配置。
+- 契约与算法文档：``AGENTS.md``、``SDK_API_AND_DESIGN.md``、``PROTOCOL_LINE_BY_LINE.md``、``TRAJECTORY_ALGORITHM.md``。
 
 
 

{codroid_robot_sdk-1.2.0 → codroid_robot_sdk-2.0.0}/README.md

@@ -39,10 +39,11 @@ pipx install hatch
 pip install hatch
 ```
 ### 2. 获取代码与初始化
-```Bash
+```bash
 git clone <your-repo-url>
-cd CodroidSDK/python
+cd CodroidPython
 ```
+若系统仅有 `python3` 命令（常见于 Debian/Ubuntu），下文请将 `python` 换成 `python3`，或使用 `hatch shell` 后按 Hatch 环境内的解释器为准。
 ### 3. 运行示例程序
 使用 Hatch 运行示例是最简单的方法，它会自动处理所有依赖和环境路径。
 ```Bash
@@ -60,12 +61,22 @@ pip install codroid-robot-sdk
 ```python
 from codroid import CodroidControlInterface
 
-# Initialize and connect automatically
+# Initialize and connect automatically (CodroidSession + synchronous JsonStreamClient)
 with CodroidControlInterface(host="192.168.1.136") as robot:
     robot.to_remote()
     robot.switch_on()
 ```
 
+需要 **后台收包、`id` 配对、Publish 按 `ty` 分发** 时，请使用 `CodroidClient`（内部为 `TransportClient`）：
+
+```python
+from codroid import CodroidClient
+
+with CodroidClient(host="192.168.1.136") as robot:
+    robot.to_remote()
+    robot.switch_on()
+```
+
 # 🛠️ Hatch 开发工作流
 本项目采用了现代 Python 的 src 布局，建议通过以下命令进行开发：
 ## 进入开发 Shell
@@ -87,12 +98,32 @@ hatch build
 hatch run docs:serve
 ```
 # 📂 目录结构说明
-- src/codroid/: SDK 核心源码。
-  - CodroidControlInterface.py: 主控制类。
-  - cri.py: 实时数据流处理。
-  - models.py: 数据模型与枚举定义。
-- examples/: 示例程序目录。
-- pyproject.toml: 项目配置文件 (Hatch 配置)。
+
+源码布局与 C# SDK（``CodroidSDK/*.cs``）**同名模块一一对应**（Python 为 snake_case + ``.py``）。详细演进见仓库根目录 ``plan.md``。
+
+```text
+src/codroid/
+├── __init__.py              # 公开 API 聚合导出
+├── __about__.py             # 版本号
+├── Codroid.py               # CodroidSession；CodroidControlInterface 别名
+├── client.py                # CodroidClient（TransportClient + 门面）
+├── async_tcp_client.py      # JsonStreamClient、TransportClient / FutureTcpClient
+├── define.py                # DTO / 常量（Define.cs）
+├── types.py                 # DTO 再导出（便于与文档表述一致）
+├── exceptions.py            # CodroidCommandException、网络/超时等
+├── utils.py                 # 共用工具
+├── console.py               # PrintBanner 等
+├── publish.py               # CodroidPublish.cs
+├── trajectory.py            # Trajectory.cs
+├── cri_realtime_packet_parser.py   # CriRealtimePacketParser.cs（含 CriStreamHandler）
+└── cri_realtime_dispatcher.py      # CriRealtimeDispatcher.cs
+```
+
+下列文件在 **2.0 计划** 中与 C# 对齐，业务将从 ``Codroid.py`` 拆出后落盘（当前可能尚未存在）：``global_variables.py``、``io.py``、``register.py``、``robot_kinematics.py``、``robot_motion.py``。
+
+- ``examples/``: 示例程序。
+- ``pyproject.toml``: Hatch / 构建配置。
+- 契约与算法文档：``AGENTS.md``、``SDK_API_AND_DESIGN.md``、``PROTOCOL_LINE_BY_LINE.md``、``TRAJECTORY_ALGORITHM.md``。
 
 
 

codroid_robot_sdk-2.0.0/examples/01_basic_usage.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""
+基础示例：连接、远程、上使能、关节运动，并打印 CRI 缓存中的关节角。
+
+用法:
+  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
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from codroid import CodroidControlInterface, MovePoint, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    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 CodroidControlInterface(
+        host=args.robot,
+        local_ip=args.local_ip,
+        udp_port=args.udp_port,
+    ) as robot:
+        robot.enter_remote_mode_via_auto()
+        robot.switch_on()
+        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])
+            for _ in range(3):
+                robot.move_j(p1, 60, 120)
+                robot.move_j(p2, 60, 120)
+
+            PrintBanner("CRI cache loop", subtitle="Ctrl+C 退出")
+            while True:
+                data = robot.cri_cache
+                if data:
+                    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.stop_cri_data_push(ip=args.local_ip, port=args.udp_port)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/02_run_script.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+通过 ``project/runScript`` 下发 Lua 与共享变量。
+
+用法:
+  PYTHONPATH=src python examples/02_run_script.py
+  PYTHONPATH=src python examples/02_run_script.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from codroid import CodroidControlInterface, 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_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.enter_remote_mode_via_auto()
+            print("发送脚本 / Sending script...")
+            res = robot.run_script(lua_code, vars=vars_data)
+            if res.is_success:
+                print("脚本请求已发送 / Script request sent")
+            else:
+                print(f"失败 / Failed: {res.err}", file=sys.stderr)
+                return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/03_run_project.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+工程控制：运行、暂停、恢复、停止、按索引启动。
+
+用法:
+  PYTHONPATH=src python examples/03_run_project.py
+  PYTHONPATH=src python examples/03_run_project.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from codroid import CodroidControlInterface, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="Run / pause / resume / stop project")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    p.add_argument(
+        "--project-id",
+        default="projectluademo",
+        help="工程 ID（run_project）",
+    )
+    p.add_argument("--index", type=int, default=0, help="run_project_by_index 索引")
+    p.add_argument("--step-sleep", type=float, default=5.0, help="每步间隔（秒）")
+    args = p.parse_args(argv)
+
+    PrintBanner("03 — Run project", subtitle=f"{args.robot}  proj={args.project_id}")
+
+    try:
+        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)
+
+            res = robot.pause_project()
+            print("暂停 / pause:", "ok" if res.is_success else res.err)
+            time.sleep(args.step_sleep)
+
+            res = robot.resume_project()
+            print("恢复 / resume:", "ok" if res.is_success else res.err)
+            time.sleep(args.step_sleep)
+
+            res = robot.stop_project()
+            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)
+
+            res = robot.stop_project()
+            print("再次停止 / stop:", "ok" if res.is_success else res.err)
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/04_global_value.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+增量保存全局变量（整数、字符串、列表、字典）。
+
+用法:
+  PYTHONPATH=src python examples/04_global_value.py
+  PYTHONPATH=src python examples/04_global_value.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from codroid import CodroidControlInterface, GlobalVariable, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="Save global variables")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    args = p.parse_args(argv)
+
+    PrintBanner("04 — Global variables", subtitle=args.robot)
+
+    vars_to_save = {
+        "v_int": GlobalVariable(value=1024, note="整数示例"),
+        "v_str": GlobalVariable(value="Codroid", note="字符串示例"),
+        "v_list": GlobalVariable(value=[1.1, 2.2, 3.3], note="数组示例"),
+        "v_map": GlobalVariable(
+            value={"power": 100, "status": "on"},
+            note="Map 示例",
+        ),
+    }
+
+    try:
+        with CodroidControlInterface(host=args.robot) as robot:
+            robot.enter_remote_mode_via_auto()
+            print("增量保存全局变量 / Saving globals...")
+            res = robot.save_global_vars(vars_to_save)
+            if res.is_success:
+                print("保存成功 / Saved")
+            else:
+                print(f"失败 / Failed: {res.err}", file=sys.stderr)
+                return 1
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/05_rs485.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+RS485：初始化、清空、写入、按长度超时读取（示例 Modbus 帧）。
+
+用法:
+  PYTHONPATH=src python examples/05_rs485.py
+  PYTHONPATH=src python examples/05_rs485.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from codroid import CodroidControlInterface, RS485BaudRate, PrintBanner
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="RS485 init / flush / write / read")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    args = p.parse_args(argv)
+
+    PrintBanner("05 — RS485", subtitle=args.robot)
+
+    try:
+        with CodroidControlInterface(host=args.robot) as robot:
+            robot.enter_remote_mode_via_auto()
+            print("初始化 115200 N 8 1 / RS485 init")
+            robot.rs485_init(baudrate=RS485BaudRate.B115200)
+            robot.rs485_flush()
+
+            cmd = b"\x01\x03\x00\x00\x00\x02\xC4\x0B"
+            print(f"发送 / TX: {cmd.hex()}")
+            robot.rs485_write(cmd)
+
+            print("读取响应（7 字节，1s 超时）/ Read...")
+            res = robot.rs485_read(length=7, timeout=1000)
+            if res.is_success and res.db:
+                received = bytes(res.db)
+                print(f"收到 / RX (hex): {received.hex()}")
+            else:
+                print("未收到或失败 / No data or read failed")
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/06_jog_mode.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+点动：设置倍率、关节点动、后台 jog 心跳、停止。
+
+用法:
+  PYTHONPATH=src python examples/06_jog_mode.py
+  PYTHONPATH=src python examples/06_jog_mode.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import time
+
+from codroid import CodroidControlInterface, JogMode, PrintBanner
+
+
+def start_heartbeat(robot: CodroidControlInterface, stop_event: threading.Event, interval: float = 0.4) -> None:
+    while not stop_event.is_set():
+        try:
+            robot.jog_heartbeat()
+            time.sleep(interval)
+        except Exception:
+            break
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="Jog mode + heartbeat thread")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    p.add_argument("--duration", type=float, default=2.0, help="点动持续时间（秒）")
+    args = p.parse_args(argv)
+
+    PrintBanner("06 — Jog mode", subtitle=args.robot)
+
+    try:
+        with CodroidControlInterface(host=args.robot) as robot:
+            robot.enter_remote_mode_via_auto()
+            robot.switch_on()
+            robot.set_manual_move_rate(50)
+
+            stop_heartbeat = threading.Event()
+            heartbeat_thread = threading.Thread(
+                target=start_heartbeat,
+                args=(robot, stop_heartbeat),
+                daemon=True,
+            )
+
+            print("关节 1 点动（示例速度）/ Jog joint 1...")
+            robot.start_jog(mode=JogMode.JOINT, index=1, speed=-0.5)
+            heartbeat_thread.start()
+            time.sleep(args.duration)
+
+            print("停止点动 / Stop jog")
+            stop_heartbeat.set()
+            heartbeat_thread.join(timeout=2.0)
+            robot.stop_jog()
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

codroid_robot_sdk-2.0.0/examples/07_move_to.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""
+MoveTo：Home、关节规划（Type 4）、直线规划（Type 5），配合 move_to_heartbeat 后台线程。
+
+用法:
+  PYTHONPATH=src python examples/07_move_to.py
+  PYTHONPATH=src python examples/07_move_to.py --robot 192.168.8.136
+
+彩色横幅（可选）: pip install codroid-robot-sdk[color] 或 pip install colorama
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import time
+
+from codroid import CodroidControlInterface, MoveToType, MoveTarget, PrintBanner
+
+
+def heartbeat_worker(robot: CodroidControlInterface, stop_event: threading.Event) -> None:
+    print("[心跳] 启动 / heartbeat start (~400ms)")
+    while not stop_event.is_set():
+        try:
+            robot.move_to_heartbeat()
+            time.sleep(0.4)
+        except Exception as e:
+            print(f"[心跳] 异常 / error: {e}")
+            break
+    print("[心跳] 已停止 / heartbeat stop")
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="moveTo + heartbeat")
+    p.add_argument("--robot", default="192.168.8.136", help="控制器 IP")
+    args = p.parse_args(argv)
+
+    PrintBanner("07 — MoveTo", subtitle=args.robot)
+
+    stop_event = threading.Event()
+
+    try:
+        with CodroidControlInterface(host=args.robot) as robot:
+            robot.enter_remote_mode_via_auto()
+            robot.switch_on()
+
+            PrintBanner("Scene 1 — HOME", subtitle="MoveToType.HOME")
+            robot.move_to(MoveToType.HOME)
+            stop_event.clear()
+            t = threading.Thread(target=heartbeat_worker, args=(robot, stop_event))
+            t.start()
+            time.sleep(3)
+            stop_event.set()
+            t.join(timeout=2.0)
+
+            PrintBanner("Scene 2 — JOINT (Type 4)", subtitle="关节规划")
+            target_joints = MoveTarget(jp=[0.0, 0.0, 0.0, 0.0, 0.0, 0.0])
+            robot.move_to(MoveToType.JOINT, target=target_joints)
+            stop_event.clear()
+            t = threading.Thread(target=heartbeat_worker, args=(robot, stop_event))
+            t.start()
+            time.sleep(5)
+            stop_event.set()
+            t.join(timeout=2.0)
+
+            PrintBanner("Scene 3 — LINEAR (Type 5)", subtitle="直线规划")
+            target_pose = MoveTarget(cp=[350.0, 100.0, 400.0, 180.0, 0.0, 90.0])
+            robot.move_to(MoveToType.LINEAR, target=target_pose)
+            stop_event.clear()
+            t = threading.Thread(target=heartbeat_worker, args=(robot, stop_event))
+            t.start()
+            time.sleep(4)
+            stop_event.set()
+            t.join(timeout=2.0)
+
+        PrintBanner("07 — Done", subtitle="所有场景结束")
+    except KeyboardInterrupt:
+        stop_event.set()
+        return 130
+    except Exception as e:
+        stop_event.set()
+        print(f"错误 / Error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))