TCP 速度

功能概述

TcpVelocity 插件围绕机器人的 TCP 末端速度提供一套端到端的监控和配置体验。它包含一个通用服务（前端 + 后端）和一个可以在用户程序中被 CALL_SERVICE 指令调用的简单服务，核心能力如下：

• 实时状态显示： 在界面上显示机器人的实时运行状态、TCP 速度以及当前执行的程序名称。
• 指令调用： 支持在用户程序中通过 CALL_SERVICE 指令，指定用于写入 TCP 速度的 R 寄存器索引。
• 多语言适配： 插件界面语言自动跟随系统语言切换。
• 日志持久化： 通用服务使用日志模块实现日志持久化。
• 插件示例： 提供可直接运行的 demo 工程，便于快速理解服务协作方式。

界面交互展示

布局概览

下图展示插件主界面布局及 TCP 速度的实时更新效果：

指令调用效果

通过 CALL_SERVICE 指令调用插件，可指定将 TCP 速度写入特定的 R 寄存器（如下图所示）：

多语言适配

切换系统语言后，插件界面会自动跟随系统语言切换（如下为英文模式）：

需要的基础知识和基础工具

技术储备

• 熟悉 Node.js 及包管理工具（pnpm），用于安装与调试通用服务前端。
• 了解 Python 虚拟环境配置与 Agilebot Python SDK。
• 具备基础 Web 前端开发经验（HTML/CSS/JavaScript）以及 Vue 框架使用经验。

基础工具与运行环境

• 确保电脑与机器人处于同一局域网。
• 机器人系统版本需要 >= Copper 7.7.3。
• 已安装 Agilebot Python SDK（>= 2.0.0.0），参考 SDK 安装文档。
• 浏览器（Chrome/Edge 最新版）。

软件文件结构

从插件开发工具包仓库的 "demo" 目录下载示例代码后，目录结构如下：

• TCP速度
  • RunningStatus
    • config.json
    • RunningStatus.py
  • TcpVelocity
    • app
      • assets
        • main.css
      • i18n
      • App.vue
      • main.ts
    • server
      • base_server.py
      • config.py
      • ipc_utils.py
      • logger.py
      • models.py
      • robot_service.py
      • robot_worker.py
      • state.py
    • config.json
    • main.py
    • package.json
    • requirements.txt

各目录职责如下：

• RunningStatus ：简单服务，接收 CALL_SERVICE 指令后调用 TcpVelocity ，写入目标 R 寄存器编号。
  • RunningStatus/config.json ：简单服务的元信息和入口声明。
• TcpVelocity ：通用服务，提供 FastAPI + WebSocket 接口， server/robot_services.py 处理机器人数据并写入 R。
  • TcpVelocity/app ：Vue 前端，订阅 WebSocket 展示速度与程序状态。
  • TcpVelocity/server ：与机器人通信、IPC、日志等后端实现。
  • TcpVelocity/config.json ：通用服务的元数据与入口声明。

核心交互流程

与机器人系统的交互

通用服务 TcpVelocity 通过 Agilebot Python SDK 同机器人建立 sub_pub 连接，订阅笛卡尔位姿与 TP 程序状态。

TcpVelocity/server/robot_services.py

await self.arm.sub_pub.connect()
await self.arm.sub_pub.subscribe_status(
    [
        RobotTopicType.CARTESIAN_POSITION,
        RobotTopicType.TP_PROGRAM_STATUS,
    ],
    frequency=200,
)
await self.arm.sub_pub.start_receiving(self.handle_robot_message)

收到位姿后，后端会计算 TCP 速度，并在寄存器索引有效时写入到指定的 R 寄存器。

TcpVelocity/server/robot_services.py

r_index = SharedState.get("tcp_velocity_r_index")
if r_index is not None and r_index > 0:
    ret = self.arm.register.write_R(r_index, self._last_tcp_velocity)
    if ret != StatusCodeEnum.OK:
        logger.error(f"写入 R 寄存器失败: {ret.errmsg}")

简单服务在收到 CALL_SERVICE 指令后，会查询 TcpVelocity 的运行端口，并向 /api/set_tcp_velocity_r_index 发送 HTTP 请求以设置目标寄存器编号。

extension = Extension(ROBOT_IP)
res, ret = extension.get("TcpVelocity")
if ret != StatusCodeEnum.OK or not res.state.isRunning:
    raise Exception("TcpVelocity 服务未运行")
api_url = f"http://{ROBOT_IP}:{res.state.port}/api/set_tcp_velocity_r_index"
requests.post(api_url, json={"index": r_index}).json()

组件间通信机制

TcpVelocity 涉及简单服务、通用服务后端、子进程采集器及前端应用，多种通信方式贯穿其中：

• 简单服务 → 通用服务（HTTP）：

  • RunningStatus 调用 TcpVelocity 服务的 /api/set_tcp_velocity_r_index 接口下发配置， TcpVelocity 随即将该索引存入 SharedState ，供数据处理线程读取使用。
  TcpVelocity/main.py

  @app.post("/api/set_tcp_velocity_r_index")
  async def set_tcp_velocity_r_index(body: SetTcpVelocityIndexRequest):
      SharedState.set("tcp_velocity_r_index", body.index)
      logger.info(f"设置 TCP 速度写入的 R 寄存器为: {body.index}")
      return {"result": True}

• FastAPI 主进程 ↔ 机器人订阅子进程（IPC）：

  • 服务启动时用 IPCManager 派生 robot_worker 子进程采集机器人数据。
  • 子进程通过队列回传消息，主进程 _ipc_handle 负责广播并缓存速度。
  TcpVelocity/main.py

  ipc = IPCManager(
      spawn_proc=lambda q: start_robot_process(ROBOT_IP, q),
      handler=_ipc_handle,
      log=logger,
      watch_interval=2.0,
  )
  
  async def _ipc_handle(item):
      await ws_server.broadcast(item)
      if isinstance(item, dict) and item.get("type") == MessageType.TCP_VELOCITY:
          SharedState.set("last_tcp_velocity", float(item.get("velocity") or 0.0))

• 通用服务 → 前端页面（WebSocket）：

  • 前端 app/App.vue 借助 useWebSocket 直接接入通用服务提供的 WebSocket，实时展示 TCP 速度与当前运行的 TP 程序名称。
  TcpVelocity/app/App.vue

  const { data } = useWebSocket('/ws', {
    autoReconnect: true,
  })
  
  watch(data, (rawMsg) => {
    const msg = JSON.parse(rawMsg)
    if (msg.type === 'tcp_velocity') {
      velocityText.value = `${Number(msg.velocity).toFixed(3)} ${msg.unit || 'mm/s'}`
    } else if (msg.type === 'running_program') {
      programName.value = msg.program_name || '--'
    }
  })

开发指南

通用服务的开发

1. 打开 PowerShell ，进入 TCP速度/TcpVelocity 目录，执行 pnpm i 安装前端依赖

2. 激活 Python 虚拟环境，执行 pip install -r requirements.txt 安装后端依赖。

3. 执行 pnpm dev 启动通用服务。

4. 启动成功后浏览器会自动打开： http://localhost:8001

5. 在机器人上执行程序或示教，即可在页面上看到实时状态更新

简单服务的开发

1. 打开 PowerShell ，进入 TCP速度/RunningStatus 目录，执行 python RunningStatus.py 即可执行。

各组件的打包

通用服务的打包

1. 打开 PowerShell ，进入 TCP速度/TcpVelocity 目录，确保已经完成上述步骤中的 安装前端依赖 、 安装后端依赖 。

2. 执行 pnpm build 编译通用服务，编译完成后会生成 TCP速度/TcpVelocity/dist 目录

3. 使用插件打包工具打包为 TcpVelocity.gbtapp ，具体步骤请参考文档：打包与安装

注意

打包时请选择 TCP速度/TcpVelocity/dist 目录作为打包路径。

打包完成后，可在 插件管理界面 安装并启用插件 TcpVelocity 。

简单服务的打包

1. 使用插件打包工具打包为 RunningStatus.gbtapp ，具体步骤请参考文档：打包与安装

注意

打包时请选择 TCP速度/RunningStatus 目录作为打包路径。

打包完成后，可在 插件管理界面 安装并启用插件 RunningStatus 。