---
url: /zh/01-intro/01-about.html
title: 关于插件
---
# 关于插件 [](#关于插件)
## 插件是什么 [](#插件是什么)
* 插件系统是捷勃特机器人提供的软件二次开发平台，基于工业机器人基础软件 Bronze 和协作机器人基础软件 Copper 的环境和接口，用户能够对机器人操作系统进行全新的功能拓展，或对现有功能进行个性化定制。
* 插件系统允许运行 3 种用户自定义的程序： Web 小程序、简单服务、通用服务。
以 Copper 协作机器人软件为例，他们的关系如下：
## 插件分类 [](#插件分类)
### Web 小程序 `webMiniProgram` [](#web小程序-webminiprogram)
Web 小程序允许开发者通过 Web 技术（如 HTML、CSS、JavaScript）编写插件的前端界面。并将其嵌入到系统的 Web 页面中，作为前端页面进行展示和交互。
### 简单服务 `easyService` [](#简单服务-easyservice)
简单服务插件是一个通过编写一个或多个 Python 方法来实现功能的插件。它允许开发者快速实现一个简单的后端功能，通过 HTTP 请求与系统交互。简单服务通常不涉及复杂的框架或外部依赖，只需要编写一些方法即可。
### 通用服务 `generalService` [](#通用服务-generalservice)
通用服务插件可提供更强大的功能支持。它通常是一个功能更复杂的后端服务，能够进行数据处理、复杂的逻辑运算，或者与外部系统交互。
## 插件文件组成 [](#插件文件组成)
### 配置文件 [](#配置文件)
任何类型的插件必须包含 `config.json` 文件，即[配置文件](./../02-development/05-config.html)。只有包含配置文件才能安装、初始化、运行。
### 数据文件 [](#数据文件)
后台插件包中一般都包含一个 data 目录，其中用于存储插件运行时生成的数据。具体可参考[数据持久化](./../02-development/03-advanced/04-data-persistence.html)。
---
url: /zh/01-intro/02-dev.html
title: 关于开发
---
# 关于开发 [](#关于开发)
## 开发教程一览 [](#开发教程一览)
### 入门教程 [](#入门教程)
如果您不知道从哪里开始，先学习下面的入门教程吧：
* 按照[开发环境搭建](./../02-development/01-environment.html)中的步骤搭建插件开发环境。
* 通过制作 "[HelloAgilebot](./../02-development/02-quick-start/01-web-mini-program.html)" 学习 Web 小程序类型的插件开发的基本流程和规则。
* 通过制作 "[MathService](./../02-development/02-quick-start/02-easy-service.html)" 学习简单服务类型的插件开发的基本流程和规则。
* 通过制作 "[WeatherService](./../02-development/02-quick-start/03-general-service.html)" 学习通用服务类型的插件开发的基本流程和规则。
## 开发所需文档 [](#开发所需文档)
* [前端技术](https://www.w3school.com.cn/)：在开发 Web 小程序插件时需要掌握一定的前端技术。
* [Python](https://www.runoob.com/python/python-tutorial.html): 在开发后端插件时需要掌握一定的 Python 编程知识。
---
url: /zh/02-development/01-environment.html
title: 开发环境搭建
---
# 开发环境搭建 [](#开发环境搭建)
插件开发需要依赖适当的开发环境，例如 Node.js、Python。
:::danger 危险
当插件的 Web 页面（包括 `Web小程序` 、 `通用服务` ）打开时，工业示教器上的物理按钮以及快捷键将会失效。
如需在插件中启用快捷按键，请参考：[启用快捷按键](/docs/extension/zh/02-development/03-advanced/02-web-runtime-package.html#enable-shortcut)
:::
## VSCode 下载、安装 [](#vscode下载-安装)
1. 下载 VSCode 安装文件
在官方网站：
下载最新版本的 VSCode 即可
1. 下载完成单击运行，按照提示安装即可
## VSCode 插件安装 [](#vscode插件安装)
1. 在 VSCode 插件市场中搜索 [Agilebot Extension Helper](https://marketplace.visualstudio.com/items?itemName=agilebot.vscode-agilebot-extension-helper) 进行安装
## Node.js 下载、安装 [](#nodejs下载-安装)
1. 下载 nvm 安装文件
在 GitHub:
下载 nvm-setup.exe 即可
1. 下载完成单击运行，按照提示安装即可
1. 安装完成后在终端输入 `nvm -v` ，能查到版本号，说明安装成功了
1. 设置 nvm 镜像源，在终端输入以下命令
```bash
nvm node_mirror https://npmmirror.com/mirrors/node/
```
1. 使用 nvm 安装 node，在终端输入以下命令
```bash
nvm install 20
nvm use 20
```
1. 安装完成后在终端输入 `node -v` ，能查到版本号，说明安装成功了
1. 设置 node 镜像源，在终端输入以下命令
```bash
npm config set registry https://registry.npmmirror.com
```
1. 启用 corepack，在终端输入以下命令
```bash
corepack enable
```
1. 设置 corepack 镜像源，在系统设置中设置如下环境变量
```bash
COREPACK_NPM_REGISTRY=https://registry.npmmirror.com
```
## Python 下载、安装 [](#python下载-安装)
1. 下载 Python 安装文件
在官方网站：
下载最新版本的 Python 即可
1. 下载完成单击运行，按照提示安装即可
---
url: /zh/02-development/02-quick-start/01-web-mini-program.html
title: Web小程序开发
---
# Web 小程序开发 [](#web小程序开发)
> 该页面旨在指导开发者如何开发 Web 小程序类型的插件包。
:::danger 危险
当插件的 Web 页面（包括 `Web小程序` 、 `通用服务` ）打开时，工业示教器上的物理按钮以及快捷键将会失效。
如需在插件中启用快捷按键，请参考：[启用快捷按键](/docs/extension/zh/02-development/03-advanced/02-web-runtime-package.html#enable-shortcut)
:::
## 关于 Web 小程序 [](#关于web小程序)
### Web 小程序是什么 [](#web小程序是什么)
Web 小程序是指开发者根据自己的需求，在符合 web 开发规范的情况下，开发出的除 AgileLink 内已有页面之外的其他页面。
## 创建 Web 小程序 [](#创建web小程序)
目前我们提供使用标准前端工程来创建一个 Web 小程序，在此处的示范中，我们会创建一个 Web 小程序类型的插件，该插件的功能是在页面显示 “Hello Agilebot!”。
### 步骤一：创建插件文件夹 [](#步骤一创建插件文件夹)
首先我们需要创建一份插件基本文件夹，该文件夹需包含一个 config.json 配置文件和前端工程文件，我们建议使用 src 作为前端工程的文件夹名称。
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/HelloAgilebot) 目录下的模板进行修改。
:::tip 提示
下文中的 HelloAgilebot 就是我们即将创建的 Web 小程序的插件名。
:::
目录结构:
* HelloAgilebot
* config.json
* src
* index.html
index.html
```html
Hello Agilebot!
Hello Agilebot!
```
config.json
```json
{
"name": "HelloAgilebot",
"type": "webMiniProgram",
"description": "显示 Hello Agilebot!",
"version": "0.1",
"url": "index.html"
}
```
### 步骤二：打包、安装 [](#步骤二打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
### 步骤三：访问页面 [](#步骤三访问页面)
下面将介绍两种方式访问之前制作的页面。
* 方法 1：在插件管理中找到插件名，点击指南针按钮访问。
* 方法 2：在 `应用-Extension` 菜单中，找到插件名，点击可访问。
---
url: /zh/02-development/02-quick-start/02-easy-service.html
title: 简单服务开发
---
# 简单服务开发 [](#简单服务开发)
> 该页面旨在指导开发者如何开发简单服务类型的插件包。
## 关于简单服务 [](#关于简单服务)
简单服务实际是 1 个 Python 文件，开发者无需关注 HTTP 服务的实现，而专注于编写具体的业务逻辑。与通用服务不同，简单服务插件更加轻量化，通常适用于实现简单的业务操作。
### 简单服务特点 [](#简单服务特点)
* 轻量级：只需一个 Python 文件，直接编写单个方法，快速实现功能。
* 无需 HTTP 实现：系统会自动处理 HTTP 接口和请求，不需要开发者手动配置。
* 快速集成：快速集成到插件系统中，可以立即作为一个后端服务进行使用。
* 简化业务逻辑：开发者只需关注核心的业务逻辑实现，而不需要处理与 HTTP 相关的部分。
### 启动要求 [](#启动要求)
当简单服务插件启动时，插件系统会启动 Python 解释器，并自动导入该插件对应的 Python 文件（即 import 模块的过程）。
在此过程中，系统会等待 Python 文件的导入过程完全完成后，才认为该插件启动成功。
:::warning 注意
* 只有当 Python 文件被完全导入（即 import 执行完毕）后，插件才会进入可调用状态。
* 如果在文件的顶层（模块级别）执行了耗时操作，如：
* 大量计算；
* 长时间的网络请求；
* 数据库初始化；
* 或阻塞式等待；
这些操作都会阻塞模块导入过程，从而导致插件系统长时间等待，最终触发启动超时错误。
* 因此，请将耗时操作放入函数或异步逻辑中，仅在实际调用时再执行。
:::
## 创建简单服务插件包 [](#创建简单服务插件包)
在此处的示范中，我们将创建一个简单服务类型的插件。该插件的功能是对外提供一个加法运算接口。
:::tip 提示
下文中的 MathService 就是我们即将创建的简单服务的插件名。
:::
### 步骤一：创建插件文件夹 [](#步骤一创建插件文件夹)
首先我们需要创建一份插件基本文件夹，该文件夹需包含一个 config.json 配置文件和一个 Python 文件，注意简单服务中，**Python 文件的名称必须与插件名称相同**。
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/MathService) 目录下的模板进行修改。
目录结构:
* MathService
* config.json
* MathService.py
MathService.py
```py
# 获取全局logger实例，只能在简单服务中使用
logger = globals().get('logger')
if logger is None:
# 本地调试时，使用自带日志库
import logging
logger = logging.getLogger(__name__)
def add(a: int, b: int) -> int:
"""
执行两个整数的加法运算
参数：
- a (int): 第一个加数
- b (int): 第二个加数
返回：
- int: 返回加法结果
"""
try:
result = a + b
return result
except Exception as ex:
logger.error(ex)
return 0
```
config.json
```json
{
"name": "MathService",
"type": "easyService",
"scriptLang": "python",
"description": "数学服务",
"version": "0.1"
}
```
### 步骤二：打包、安装 [](#步骤二打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
### 步骤三：调用接口 [](#call-interface)
下面将介绍几种方式调用之前制作的接口。
* 方法 1：使用 `CALL_SERVICE` 指令调用。
请参照[相关章节](./../03-advanced/03-complex-backend.html#call-service)。
* 方法 2：使用 JS 运行时在 Web 小程序中调用。
在 Web 小程序的 JS 代码中使用 `callEasyService` 函数调用。
```ts
import {
callEasyService
} from '@agilebot/extension-runtime';
callEasyService
('MathService', 'add', {
a
: 1,
b
: 2
}).
then
(
result
=> {
// 输出：加法计算结果为 3
console
.
log
(`加法计算结果为${
result
}`);
});
```
具体示例可参考[复杂的 Web 小程序](./../03-advanced/01-complex-page.html)
* 方法 3：直接访问接口地址。
```
http://10.27.1.254:5616/MathService/add?a=1&b=2
```
在这种方式下，URL 查询参数（ `a=1` 和 `b=2` ）会被自动映射到 `MathService` 插件中的 `add` 函数的参数上：
* `a=1` 会被映射到函数 `add` 的 `a` 参数，值为 `1` 。
* `b=2` 会被映射到函数 `add` 的 `b` 参数，值为 `2` 。
以下是一个使用 Python 获取的例子：
```py
import requests
response = requests.get('http://10.27.1.254:5616/MathService/add', {
'a': 1,
'b': 2
})
if response.status_code == 200:
# 解析 JSON 响应
data = response.json()
# 输出结果
print(f"Result: {data['result']}")
else:
print(f"Request failed with status code: {response.status_code}")
```
## 参数映射关系 [](#参数映射关系)
| 函数参数类型 | 示例参数 | 实际的 URI 地址 | 参数映射说明 |
| ------------ | --------------------------------- | ---------------------------------------------------------- | --------------------------------------- |
| int | a=1 | ?param1=1¶m2=2 | param1 映射为函数的 int 类型参数，值为 1 |
| str | name=John | ?name=John | name 映射为函数的 str 类型参数，值为 "John" |
| bool | isActive=true | ?isActive=true | isActive 映射为函数的 bool 类型参数，值为 true |
| List\[dict\] | items=\[{"id":1,"name":"item1"}\] | ?items\[0\]\[id\]=1&items\[0\]\[name\]=item1 [\[1\]](#fn1) | items 映射为函数的 List\[dict\] 类型参数，值为一个字典列表 |
## 局限性 [](#局限性)
虽然简单服务非常方便，但它的功能也有一些限制。以下是使用简单服务时需要注意的几个局限性：
1. 仅支持基本类型参数：简单服务的函数参数只支持以下基本类型： `str` 、 `int` 、 `bool` 、 `List[dict]` 。如果需要处理更复杂的数据结构或自定义类型，建议使用通用服务来实现。
2. 扩展性受限：简单服务适用于快速开发和集成简单的业务逻辑。若涉及到高并发、复杂路由、状态管理等需求，通用服务会提供更高的灵活性和可扩展性。
3. 功能集中在业务逻辑上：简单服务专注于核心业务逻辑，而不涉及 HTTP 处理、请求验证、安全性等功能。如果您需要更复杂的请求处理（如认证、权限管理等），通用服务可以提供更多的功能支持。
---
1. 在 JavaScript 中可以使用[ qs](https://www.npmjs.com/package/qs) 包序列化为这种格式。 [↩︎](#fnref1)
---
url: /zh/02-development/02-quick-start/03-general-service.html
title: 通用服务开发
---
# 通用服务开发 [](#通用服务开发)
> 该页面旨在指导开发者如何开发通用服务类型的插件包。
:::danger 危险
当插件的 Web 页面（包括 `Web小程序` 、 `通用服务` ）打开时，工业示教器上的物理按钮以及快捷键将会失效。
如需在插件中启用快捷按键，请参考：[启用快捷按键](/docs/extension/zh/02-development/03-advanced/02-web-runtime-package.html#enable-shortcut)
:::
## 关于通用服务 [](#关于通用服务)
通用服务插件是用于实现复杂后端功能的插件。
与简单服务不同，通用服务插件需要开发者关注服务的配置、接口设计、请求处理、数据存储等内容，因此开发过程较为复杂，但也提供了更多的灵活性和扩展性。
### 通用服务特点 [](#通用服务特点)
* 功能强大：可以处理更复杂的业务逻辑和数据操作。
* 灵活可扩展：可以根据业务需求扩展或修改服务的功能。
* 支持外部交互：能够与数据库、外部 API 或其他系统进行交互。
* 需要手动配置：相比简单服务，开发者需要配置 HTTP 接口、请求处理、路由等内容。
### 启动要求 [](#启动要求)
当通用服务插件启动时，插件系统会为它分配一个端口号，并通过环境变量 `PORT` 传入插件进程。
插件系统随后会检测：**该端口是否已被插件进程成功监听（Listen）。**
:::warning 必须满足的条件
* 无论你实现的是 HTTP / TCP /gRPC/ WebSocket / 自定义二进制协议， 都必须绑定并监听 `PORT` 指定的端口。
* 系统会自动分配 **6100-6199** 范围内的端口号。如果你需要使用多个端口，请自行在该范围内动态获取可用端口。
* 否则，系统无法检测到该端口的监听状态，会在检测超时后（默认约 60 秒）判定插件启动失败。
:::
## 创建通用服务插件包 [](#创建通用服务插件包)
在此处的示范中，我们将创建一个通用服务类型的插件。该插件的功能是对外提供一个天气查询接口。
:::tip 提示
下文中的 WeatherService 就是我们即将创建的通用服务的插件名。
:::
### 步骤一：创建插件文件夹 [](#步骤一创建插件文件夹)
首先我们需要创建一份插件基本文件夹，该文件夹需包含一个 config.json 配置文件和一个 Python 文件。
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/WeatherService) 目录下的模板进行修改。
目录结构:
* WeatherService
* config.json
* app.py
app.py
```py
import os
import logging
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import requests
# 动态获取端口号，普通服务的端口为自动分配
PORT = os.getenv("PORT", 8000)
logger = logging.getLogger(__name__)
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(filename)s:%(lineno)d - %(levelname)s - %(message)s',
)
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"]
)
@app.get("/weather")
async def get_weather():
"""
获取指定城市的天气
:return: 城市天气信息
"""
# 构建查询 URL
url = f'http://t.weather.sojson.com/api/weather/city/101030100'
try:
response = requests.get(url)
if response.status_code != 200:
raise HTTPException(status_code=response.status_code, detail="请求天气数据失败")
# 返回的数据是字符串，直接返回给客户端
weather_info = response.json()
return {"weather": weather_info}
except requests.exceptions.RequestException as e:
raise HTTPException(status_code=500, detail="请求外部天气服务失败")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=int(PORT))
```
config.json
```json
{
"name": "WeatherService",
"type": "generalService",
"scriptLang": "python",
"description": "天气服务",
"version": "0.1",
"entry": "app.py"
}
```
### 步骤二：打包、安装 [](#步骤二打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
### 步骤三：调用接口 [](#步骤三调用接口)
1. 与简单服务相同，通用服务需激活才能使用
1. 激活后，将看到服务端口号：
:::tip 提示
通用服务一经启动，重启时会优先被分配上次启动占据的端口号（若此时此端口号已被占用则会随机分配一个新的端口号）。
:::
1. 在其它程序中调用此接口：
```
http://10.27.1.254:6100/weather
```
例如，可以使用 Python 的 `requests` 包 调用此接口：
```py
import requests
url = "http://10.27.1.254:6100/weather"
try:
response = requests.get(url)
# 判断请求是否成功
if response.status_code == 200:
result = response.json()
print("天气信息：")
print(result)
else:
print(f"请求失败，状态码: {response.status_code}")
except requests.exceptions.RequestException as e:
print("请求过程中出现错误:", e)
```
---
url: /zh/02-development/03-advanced/01-complex-page.html
title: 复杂的Web小程序
---
# 复杂的 Web 小程序 [](#复杂的web小程序)
> 本页面旨在指导开发者如何使用前端工程化工具构建一个复杂的 Web 小程序。
在开始操作本页面之前，请确保已学习以下内容：
* [Vite](https://cn.vite.dev/)：一个现代化的前端构建工具，具备极速的开发体验。
* [Vue](https://cn.vuejs.org/)：一个渐进式的 JavaScript 框架，用于构建用户界面。
* [PNPM](https://www.pnpm.cn/)：一个高效的 JavaScript 包管理器。
## 关于复杂的 Web 小程序 [](#关于复杂的web小程序)
复杂 Web 小程序允许开发者通过前端工程化工具，像 Vite 和 Vue，构建更加灵活和复杂的页面。这些页面通常包含动态内容、交互逻辑和与后端的实时通信，并可根据需求进行高度定制。
与入门教程相比，复杂 Web 小程序提供了更多的功能和灵活性，适合需要更复杂前端操作和交互的应用场景。
## 创建 Web 小程序插件包 [](#创建web小程序插件包)
在此处的示范中，我们将创建一个 Web 小程序类型的插件。该插件的功能是调用入门教程中的[ MathService](./../02-quick-start/02-easy-service.html)，并返回加法计算的结果显示在页面中。
:::tip 提示
下文中的 MathPage 就是我们即将创建的 Web 小程序的插件名。
:::
### 步骤一：创建空白的 Vite+Vue 项目 [](#步骤一创建空白的vitevue项目)
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/MathPage) 目录下的模板进行修改。
```bash
pnpm create vue@latest
```
这将启动 Vue 官方的项目脚手架工具，以下是项目创建过程的一个示例：
### 步骤二：完成初始化后，进入项目目录并安装依赖 [](#步骤二完成初始化后进入项目目录并安装依赖)
```bash
cd MathPage
pnpm i
pnpm i @agilebot/extension-runtime
```
### 步骤三：撰写代码 [](#步骤三撰写代码)
新建加法计算器组件：
src/components/Math.vue
```vue
<
div
class
="math">
<
h1
>加法计算器
<
div
class
="container">
<
label
for
="inputA">a:
<
input
type
="number" v-model="
a
"
placeholder
="输入第一个数字" />
<
label
for
="inputB">b:
<
input
type
="number" v-model="
b
"
placeholder
="输入第二个数字" />
<
button
@
click
="
handleCalculate
">计算 a + b
<
div
class
="result">
<
p
>
结果: <
span
>{{
c
}}
```
在首页中导入 Math 组件：
src/App.vue
```vue
```
值得注意的是，需修改 `vite.config.ts` 配置中的 `base` 选项：
vite.config.ts
```ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
// https://vite.dev/config/
export default defineConfig({
base: './',
plugins: [
vue(),
vueDevTools(),
],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url))
},
},
})
```
### 步骤四：编译 Vue 项目 [](#步骤四编译vue项目)
```bash
pnpm build
```
### 步骤五：打包、安装 [](#步骤五打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
需要注意的是，打包时的入口文件需选择 `dist/index.html` 。
---
url: /zh/02-development/03-advanced/02-web-runtime-package.html
title: Web小程序的运行库
---
# Web 小程序的运行库 [](#web小程序的运行库)
我们提供了 Web 小程序的运行库，可以方便的调用一些方法。
您可以通过包管理工具来安装：
:::code-group
```sh [npm]
npm install @agilebot/extension-runtime
```
```sh [yarn]
yarn add @agilebot/extension-runtime
```
```sh [pnpm]
pnpm add @agilebot/extension-runtime
```
:::
也可以直接在浏览器中引用：
```html
```
当您使用 `
```
## 多语言 [](#多语言)
当 Web 小程序在 AgileLink 中打开时，需要获取 App 当前的语言，进而切换用户 Web 小程序的语言与 App 一致。可以采用下面的方式实现该功能。
示例代码：
```ts
import {
getLanguage
} from '@agilebot/extension-runtime';
const
currentLang
= await
getLanguage
();
console
.
log
(`当前的语言: ${
currentLang
}`);
```
## 启用快捷按键 [](#enable-shortcut)
当插件的 Web 页打开时，一些快捷按键将被禁用，如工业示教器上的物理按钮。您可以通过以下方式启用快捷按键：
```ts
import {
enableShortcut
} from '@agilebot/extension-runtime';
enableShortcut
();
```
:::danger 危险
如不调用此方法，可能导致的后果：
* 工业示教器锁屏后，屏幕将无法通过物理按钮来唤醒
* 只能通过长按示教器电源按钮 15 秒以上，进行强制关机并重启
:::
## 显示弹框等组件 [](#显示弹框等组件)
为了与 AgileLink 保持一致的风格，我们提供了一些常用函数用于展示通知消息和弹框。
### rtmNotification - 通知消息 [](#rtmnotification-通知消息)
通知消息用于向用户显示简短的提示信息，支持四种类型：
```ts
import {
rtmNotification
} from '@agilebot/extension-runtime';
// 显示信息通知
rtmNotification
.
info
('这是一个信息消息');
// 显示错误通知
rtmNotification
.
error
('这是一个错误消息');
// 显示成功通知
rtmNotification
.
success
('操作成功');
// 显示警告通知
rtmNotification
.
warning
('这是一个警告消息');
```
所有通知方法都支持可选的 `detail` 参数，用于显示详细信息：
```ts
// 带详细信息的通知
rtmNotification
.
error
('操作失败', '请检查您的输入并重试');
rtmNotification
.
info
('系统提示', '您有3条新消息');
```
#### API 参考 [](#api-参考)
| 方法 | 参数 | 返回值 | 说明 |
| ------------------------- | ------------------------------ | ---- | ------ |
| info(message, detail?) | message: stringdetail?: string | void | 显示信息通知 |
| error(message, detail?) | message: stringdetail?: string | void | 显示错误通知 |
| success(message, detail?) | message: stringdetail?: string | void | 显示成功通知 |
| warning(message, detail?) | message: stringdetail?: string | void | 显示警告通知 |
### rtmMessageBox - 弹框对话框 [](#rtmmessagebox-弹框对话框)
弹框对话框用于需要用户确认或输入的场景，支持三种类型：
#### confirm - 确认对话框 [](#confirm-确认对话框)
```ts
import {
rtmMessageBox
} from '@agilebot/extension-runtime';
// 基础用法
rtmMessageBox
.
confirm
('您确定要删除吗？')
.
then
(() => {
console
.
log
('用户确认了操作');
})
.
catch
(() => {
console
.
log
('用户取消了操作');
});
// 使用 async/await
async function
deleteItem
() {
try {
await
rtmMessageBox
.
confirm
('确定删除此项吗？');
console
.
log
('已确认删除');
// 执行删除操作...
} catch {
console
.
log
('已取消删除');
}
}
```
#### alert - 警告对话框 [](#alert-警告对话框)
```ts
// 显示警告对话框
rtmMessageBox
.
alert
('请注意：此操作不可撤销！')
.
then
(() => {
console
.
log
('用户已阅读警告');
});
```
#### prompt - 输入对话框 [](#prompt-输入对话框)
```ts
// 获取用户输入
rtmMessageBox
.
prompt
('请输入您的名字：', {
inputPlaceholder
: '在此输入名字',
inputValue
: '默认名字',
inputValidator
: (
value
: string) => {
if (!
value
) return '名字不能为空';
if (
value
.
length
< 2) return '名字至少需要2个字符';
return true;
},
inputErrorMessage
: '输入无效'
})
.
then
((
result
) => {
// prompt 成功时返回 { value: string, action: string }
console
.
log
('用户输入:',
result
);
})
.
catch
(() => {
console
.
log
('用户取消了输入');
});
```
#### 高级配置选项 [](#高级配置选项)
所有 MessageBox 方法都支持第二个可选的 `options` 参数，用于自定义对话框的外观和行为：
```ts
rtmMessageBox
.
confirm
('删除此项？', {
title
: '确认删除',
type
: 'warning',
confirmButtonText
: '确定删除',
cancelButtonText
: '取消',
center
: true,
closeOnClickModal
: false,
closeOnPressEscape
: false
});
```
#### 配置选项说明 [](#配置选项说明)
所有 MessageBox 方法都基于 Element UI 的 MessageBox 组件，支持以下配置选项：
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| ------------------------- | ---------------------------------------------------------- | -------------------------------- | -------------------------------- | ------------------------------------- |
| title | MessageBox 标题 | string | — | — |
| message | MessageBox 消息正文内容 | string / VNode | — | — |
| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | boolean | — | false |
| type | 消息类型，用于显示图标 | string | success / info / warning / error | — |
| iconClass | 自定义图标的类名，会覆盖 type | string | — | — |
| customClass | MessageBox 的自定义类名 | string | — | — |
| callback | 若不使用 Promise，可以使用此参数指定 MessageBox 关闭后的回调 | function(action, instance) | — | — |
| showClose | MessageBox 是否显示右上角关闭按钮 | boolean | — | true |
| beforeClose | MessageBox 关闭前的回调，会暂停实例的关闭 | function(action, instance, done) | — | — |
| distinguishCancelAndClose | 是否将取消（点击取消按钮）与关闭（点击关闭按钮或遮罩层、按下 ESC 键）进行区分 | boolean | — | false |
| lockScroll | 是否在 MessageBox 出现时将 body 滚动锁定 | boolean | — | true |
| showCancelButton | 是否显示取消按钮 | boolean | — | false（以 confirm 和 prompt 方式调用时为 true） |
| showConfirmButton | 是否显示确定按钮 | boolean | — | true |
| cancelButtonText | 取消按钮的文本内容 | string | — | 取消 |
| confirmButtonText | 确定按钮的文本内容 | string | — | 确定 |
| cancelButtonClass | 取消按钮的自定义类名 | string | — | — |
| confirmButtonClass | 确定按钮的自定义类名 | string | — | — |
| closeOnClickModal | 是否可通过点击遮罩关闭 MessageBox | boolean | — | true（以 alert 方式调用时为 false） |
| closeOnPressEscape | 是否可通过按下 ESC 键关闭 MessageBox | boolean | — | true（以 alert 方式调用时为 false） |
| closeOnHashChange | 是否在 hashchange 时关闭 MessageBox | boolean | — | true |
| showInput | 是否显示输入框 | boolean | — | false（以 prompt 方式调用时为 true） |
| inputPlaceholder | 输入框的占位符 | string | — | — |
| inputType | 输入框的类型 | string | — | text |
| inputValue | 输入框的初始文本 | string | — | — |
| inputPattern | 输入框的校验表达式 | regexp | — | — |
| inputValidator | 输入框的校验函数。可以返回布尔值或字符串，若返回一个字符串，则返回结果会被赋值给 inputErrorMessage | function | — | — |
| inputErrorMessage | 校验未通过时的提示文本 | string | — | 输入的数据不合法！ |
| center | 是否居中布局 | boolean | — | false |
| roundButton | 是否使用圆角按钮 | boolean | — | false |
:::tip 说明
* `callback` 参数：function (action, instance)，action 的值为 'confirm'、'cancel' 或 'close'，instance 为 MessageBox 实例
* `beforeClose` 参数：function (action, instance, done)，done 用于关闭 MessageBox 实例
* 更多详细信息请参考 [Element UI MessageBox 文档](https://element.eleme.cn/#/zh-CN/component/message-box)
:::
#### API 参考 [](#api-参考-1)
| 方法 | 参数 | 返回值 | 说明 |
| -------------------------- | -------------------------------------------- | ----------------------- | ------- |
| alert(message, options?) | message: stringoptions?: ElMessageBoxOptions | Promise | 显示警告对话框 |
| confirm(message, options?) | message: stringoptions?: ElMessageBoxOptions | Promise | 显示确认对话框 |
| prompt(message, options?) | message: stringoptions?: ElMessageBoxOptions | Promise | 显示输入对话框 |
## 获取插件的状态 [](#获取插件的状态)
您可以通过以下方式获取某个插件的当前状态：
```ts
import {
getExtensionState
} from '@agilebot/extension-runtime';
const
extension
= await
getExtensionState
('myService');
console
.
log
(
`插件是否已经启用: ${
extension
.
enabled
}, 端口号：${
extension
.
port
}`
);
```
## 是否处于插件环境中 [](#是否处于插件环境中)
本地调试 Web 页面时，可以判断当前运行在插件环境还是本地电脑：
```ts
import {
isInExtension
} from '@agilebot/extension-runtime';
console
.
log
(`当前是否处于插件环境：${
isInExtension
()}`);
```
---
url: /zh/02-development/03-advanced/03-complex-backend.html
title: 简单服务中调用SDK
---
# 简单服务中调用 SDK [](#简单服务中调用sdk)
> 本页面旨在指导开发者如何在简单服务中调用 Agilebot SDK，并通过程序指令调用。
## 创建简单服务插件包 [](#创建简单服务插件包)
在此处的示范中，我们将创建一个简单服务类型的插件。该插件的功能是对外提供一个加法运算接口，并写入某个 R 寄存器。
:::tip 提示
下文中的 MathServiceComplex 就是我们即将创建的简单服务的插件名。
:::
### 步骤一：创建插件文件夹 [](#步骤一创建插件文件夹)
首先我们需要创建一份插件基本文件夹，该文件夹需包含一个 config.json 配置文件和一个 Python 文件，注意简单服务中，**Python 文件的名称必须与插件名称相同**。
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/MathServiceComplex) 目录下的模板进行修改。
目录结构:
* MathServiceComplex
* config.json
* MathServiceComplex.py
MathServiceComplex.py
```py
from Agilebot.IR.A.arm import Arm
from Agilebot.IR.A.status_code import StatusCodeEnum
from Agilebot.IR.A.sdk_classes import Register
# 获取全局logger实例，只能在简单服务中使用
logger = globals().get('logger')
if logger is None:
# 本地调试时，使用自带日志库
import logging
logger = logging.getLogger(__name__)
arm = Arm()
ret = arm.connect("10.27.1.254")
if ret != StatusCodeEnum.OK:
logger.error("连接失败")
def add(a: int, b: int) -> int:
"""
执行两个整数的加法运算，并写入寄存器
参数：
- a (int): 第一个加数
- b (int): 第二个加数
返回：
- int: 返回加法结果
"""
try:
result = a + b
# 将结果写入寄存器
register = Register()
register.id = 1
register.name = "math_result"
register.comment = "加法服务的结果"
register.value = result
ret = arm.register.write(1, register)
if ret != StatusCodeEnum.OK:
logger.error("更新R失败")
return result
except Exception as ex:
logger.error(ex)
return 0
```
config.json
```json
{
"name": "MathServiceComplex",
"type": "easyService",
"scriptLang": "python",
"description": "数学服务",
"version": "0.1"
}
```
### 步骤二：打包、安装 [](#步骤二打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
### 步骤三：使用 `CALL_SERVICE` 指令调用 [](#call-service)
1. 选择插入指令 `CALL_SERVICE`
1. 填写 `CALL_SERVICE` 指令的相关参数
* 服务名称：即简单服务的名称，本例中填写 `MathServiceComplex`
* 指令名称：即要调用的服务中的函数名，本例中填写 `add`
* 参数：即要传给上述函数名的参数列表，本例中填写 `a: 1` 、 `b: 2`
1. 点击执行按钮
1. 用户程序执行成功后，将在 `R[1]` 中写入值 `3`
---
url: /zh/02-development/03-advanced/04-data-persistence.html
title: 数据持久化
---
# 数据持久化 [](#数据持久化)
> 本页面旨在指导开发者如何在简单服务中将数据持久化。
对于后台插件，数据应存储在插件目录下的 `data` 目录中。插件启动后，系统会自动将该目录挂载为可写。为了确保数据在插件重启后不会丢失，必须将所有数据存放在此目录下。如果数据存放在其他目录，插件重启后将无法恢复这些数据，从而导致数据丢失。
:::warning 警告
机器人断电后可能造成文件缓存数据丢失。建议在写入数据文件后调用 [sync](https://www.runoob.com/linux/linux-comm-sync.html) 命令，确保数据刷新到磁盘。
:::
示例代码：
```py
import os
os.system("sync")
```
## 数据操作建议 [](#数据操作建议)
1. **本地文件存储**：对于小型数据，推荐使用 JSON、SQLite 等文件存储方案。
2. **数据库存储**：对于更复杂的数据需求，可以选择数据库进行持久化。
## 创建简单服务插件包 [](#创建简单服务插件包)
在下面的示例中，我们将创建一个简单服务类型的插件。该插件将对外提供配置写入、配置读取、配置删除接口，并将数据持久化到 SQLite 数据库中。
:::tip 提示
下文中的 DataService 就是我们即将创建的简单服务的插件名。
:::
### 步骤一：创建插件文件夹 [](#步骤一创建插件文件夹)
首先我们需要创建一份插件基本文件夹，该文件夹需包含一个 config.json 配置文件和一个 Python 文件，注意简单服务中，**Python 文件的名称必须与插件名称相同**。
您可以从头开始手动创建，也可以使用插件开发包仓库中 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/DataService) 目录下的模板进行修改。
目录结构:
* DataService
* config.json
* DataService.py
DataService.py
```py
from pathlib import Path
import sqlite3
# 获取全局logger实例，只能在简单服务中使用
logger = globals().get('logger')
if logger is None:
# 本地调试时，使用自带日志库
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
def __init_db():
"""
初始化数据库
"""
try:
current_dir = Path(__file__).parent.resolve()
data_dir = current_dir / 'data'
# 如果data目录不存在，手动创建
if not data_dir.exists():
data_dir.mkdir(parents=True)
db_path = data_dir / 'data.db'
# 连接到数据库
conn = sqlite3.connect(db_path)
cursor = conn.cursor()
logger.info("数据库打开成功")
# 创建表
cursor.execute('''
CREATE TABLE IF NOT EXISTS `robot_config` (
`id` INTEGER PRIMARY KEY AUTOINCREMENT,
`key` VARCHAR(255) NOT NULL UNIQUE,
`value` TEXT NOT NULL
);
''')
logger.info("表创建成功")
conn.commit()
return conn
except Exception as e:
logger.error(f"初始化数据库失败: {e}")
return None
conn = __init_db()
"""
全局变量，用于持有唯一的数据库连接实例
"""
def get_robot_config(key: str):
"""根据 key 获取配置值。"""
try:
cursor = conn.cursor()
cursor.execute('SELECT value FROM robot_config WHERE key = ?', (key,))
result = cursor.fetchone()
return result[0] if result else None
except sqlite3.Error as e:
logger.error(f"获取配置 '{key}' 失败: {e}")
return None
def set_robot_config(key: str, value: str):
"""设置或更新一个配置项。"""
try:
cursor = conn.cursor()
cursor.execute('INSERT OR REPLACE INTO robot_config (key, value) VALUES (?, ?)', (key, str(value)))
conn.commit()
logger.info(f"配置 '{key}' 已设置为 '{value}'。")
return True
except sqlite3.Error as e:
logger.error(f"设置配置 '{key}' 失败: {e}")
return False
def delete_robot_config(key: str):
"""根据 key 删除一个配置项。"""
try:
cursor = conn.cursor()
cursor.execute('DELETE FROM robot_config WHERE key = ?', (key,))
conn.commit()
logger.info(f"配置 '{key}' 已删除。")
return True
except sqlite3.Error as e:
logger.error(f"删除配置 '{key}' 失败: {e}")
return False
```
config.json
```json
{
"name": "DataService",
"type": "easyService",
"scriptLang": "python",
"description": "数据服务",
"version": "0.1"
}
```
### 步骤二：打包、安装 [](#步骤二打包-安装)
插件打包请参考[打包与安装](./../04-package.html)
### 步骤三：调用接口 [](#步骤三调用接口)
1. **设置配置**：访问 `http://10.27.1.254:5616/DataService/set_robot_config?key=model_type&value=GBT-C5A`
此操作会写入一个配置项，名称为 `model_type` ，值为 `GBT-C5A` 。
1. **获取配置**：访问 `http://10.27.1.254:5616/DataService/get_robot_config?key=model_type`
正常情况下会返回：
```json
{
"result": "GBT-C5A"
}
```
1. **删除配置**：访问 `http://10.27.1.254:5616/DataService/delete_robot_config?key=model_type`
此操作会将配置项 `model_type` 删除。
注：更多调用方式请参照[相关章节](./../02-quick-start/02-easy-service.html#call-interface)。
---
url: /zh/02-development/03-advanced/05-debug.html
title: 调试指南
---
# 调试指南 [](#调试指南)
## 日志 [](#日志)
对于后台插件（简单服务、通用服务），可以在插件管理界面中查看插件运行时的日志信息。
### 简单服务 [](#简单服务)
仅当使用 `globals` 中提供的 `logger` 打印日志时，日志内容才会出现在插件管理界面中：
```py
logger = globals().get('logger')
logger.info("这是一条日志")
```
### 通用服务 [](#通用服务)
通用服务可以使用任意日志库（如 `logging` 、 `loguru` 等）进行日志输出，插件管理界面同样支持展示。
只要日志内容打印到标准输出（stdout）或标准错误输出（stderr），都会被插件系统捕获并在管理界面中展示，不受日志库限制。
> 以下是插件管理界面中日志展示的截图：
## 在线编辑 [](#在线编辑)
所有插件类型都支持在线编辑，允许用户直接在插件管理界面中修改插件代码，并保存更改。
点击 “保存” 按钮后，后台服务将自动重启以应用更新内容。
---
url: /zh/02-development/03-advanced/06-ir-tips.html
title: 工业插件开发注意项
---
# 工业插件开发注意项 [](#工业插件开发注意项)
> 本页面介绍为工业机器人开发插件时需要注意的兼容性问题和最佳实践。
## 环境限制 [](#环境限制)
### alert 和 confirm 函数不可用 [](#alert-和-confirm-函数不可用)
在工业机器人的插件环境中，原生的 `alert()` 、 `confirm()` 和 `prompt()` 函数无法使用。
#### 问题说明 [](#问题说明)
示教器的 WebView 环境禁用了这些阻塞式的对话框函数，直接调用会导致：
* `alert()` \- 无响应或静默失败
* `confirm()` \- 无法获取用户确认
* `prompt()` \- 无法获取用户输入
#### 推荐解决方案 [](#推荐解决方案)
**我们强烈建议直接使用 UI 框架（如 Element UI、Ant Design 等）或运行时 API 来实现通知和对话框功能**，而不是使用浏览器原生的 `alert` / `confirm` / `prompt` 函数。
运行时 API 提供了完整的通知和对话框功能：
**使用运行时 API**（推荐）：
运行时 API 的使用方式取决于你的开发方式：
* **传统方式**（直接在 HTML 中引入 script 标签）：使用全局对象 `gbtExtension`
将运行时库下载到本地项目，下载方式：
```bash
# 方式1：通过npm安装后复制
npm add @agilebot/extension-runtime
cp ./node_modules/@agilebot/extension-runtime/dist/browser.js ./static/extension-runtime.js
# 方式2：直接从unpkg下载到项目
curl -o ./static/extension-runtime.js https://unpkg.com/@agilebot/extension-runtime/dist/browser.js
# 或使用 wget
wget -O ./static/extension-runtime.js https://unpkg.com/@agilebot/extension-runtime/dist/browser.js
```
* **模块化方式**（使用构建工具和模块化开发）：使用 `import` 语法
```ts
import {
rtmNotification
,
rtmMessageBox
} from '@agilebot/extension-runtime';
// 显示通知
rtmNotification
.
success
('操作成功！');
rtmNotification
.
error
('操作失败');
rtmNotification
.
info
('提示信息');
// 显示确认对话框
rtmMessageBox
.
confirm
('确定要删除吗？')
.
then
(() =>
console
.
log
('用户确认'))
.
catch
(() =>
console
.
log
('用户取消'));
// 获取用户输入
rtmMessageBox
.
prompt
('请输入名字：')
.
then
((
result
) =>
console
.
log
('用户输入:',
result
))
.
catch
(() =>
console
.
log
('用户取消'));
```
现代构建工具（如 Vite、Webpack）会自动将依赖打包到最终文件中，无需额外处理。
更多运行时 API 的详细说明，请参考 [Web 小程序的运行库](./02-web-runtime-package.html)。
#### 备选方案：兼容原生 alert/confirm [](#备选方案兼容原生-alertconfirm)
:::warning 仅在必要时使用
**只有当你的项目已经大量使用了原生的 `alert()` / `confirm()` 函数，且无法重构时**，才需要使用以下兼容方案。
对于新项目或可以重构的项目，请直接使用上述推荐的运行时 API 或 UI 框架。
:::
如果你必须保持对原生 `alert()` / `confirm()` 的兼容，可以封装一层兼容代码：
**传统方式兼容示例**：
```js
// 判断当前环境是否运行在插件中
const isExtension = gbtExtension.isInExtension();
// 兼容 alert
const alertSuccess = !isExtension
? alert
: gbtExtension.rtmNotification.success;
const alertError = !isExtension
? alert
: gbtExtension.rtmNotification.error;
const alertInfo = !isExtension
? alert
: gbtExtension.rtmNotification.info;
// 兼容 confirm（异步形式）
const myConfirm = function(message) {
if (!isExtension) {
return Promise.resolve(confirm(message));
}
return new Promise((resolve) => {
gbtExtension.rtmMessageBox.confirm(message)
.then(() => resolve(true))
.catch(() => resolve(false));
});
};
// 使用示例
alertSuccess('操作成功！');
async function deleteItem() {
const confirmed = await myConfirm('确定要删除吗？');
if (confirmed) {
console.log('用户确认删除');
}
}
```
**模块化方式兼容示例**：
```ts
import {
isInExtension
,
rtmNotification
,
rtmMessageBox
} from '@agilebot/extension-runtime';
const
isExtension
=
isInExtension
();
// 兼容 alert
const
alertSuccess
= !
isExtension
?
alert
:
rtmNotification
.
success
;
const
alertError
= !
isExtension
?
alert
:
rtmNotification
.
error
;
const
alertInfo
= !
isExtension
?
alert
:
rtmNotification
.
info
;
// 兼容 confirm（异步形式）
const
myConfirm
= function(
message
: string) {
if (!
isExtension
) {
return
Promise
.
resolve
(
confirm
(
message
));
}
return new
Promise
((
resolve
) => {
rtmMessageBox
.
confirm
(
message
)
.
then
(() =>
resolve
(true))
.
catch
(() =>
resolve
(false));
});
};
```
:::warning 注意事项
使用兼容方案时需要注意：
* `confirm` 的替代方法是**异步的**（返回 Promise），必须使用 `await` 或 `.then()` 处理
* 原生 `confirm()` 是同步的，封装后变为异步，可能需要调整代码结构
* `alert` 替代为通知消息，显示效果与原生对话框不同
* 建议在项目入口文件中统一封装这些函数，避免重复代码
:::
## 代码转义配置 [](#代码转义配置)
### 为什么需要转义 [](#为什么需要转义)
插件的前端页面运行在不同设备的 WebView 环境中:
* **工业机器人**：由于示教器搭载的 Android 系统 (如 Android 13) 的 WebView 可能不支持 ES6 + 的新特性 (如箭头函数、async/await、可选链等)，因此**需要配置转义**，将现代 JavaScript 代码转义 (transpile) 为 ES5 兼容代码。
* **协作机器人**：协作机器人搭载较新版本的 Android 系统，WebView 对现代 JavaScript 特性有良好支持，**通常不需要配置转义**。
:::tip 提示
如果你是为**工业机器人**开发插件，那就需要按照本文档配置转义。如果是为**协作机器人**开发插件，那么大概率不需要转义配置，可以直接使用现代 JavaScript 语法。
:::
### 场景一：使用 Babel 转义 (传统方式) [](#场景一使用babel转义传统方式)
如果你使用传统方式开发，即不使用现代构建工具，而是直接编写原生 JavaScript，那么可以使用 Babel 来转义代码。
#### 配置示例 [](#配置示例)
以下是一个完整的 `package.json` 配置示例:
package.json
```json
{
"name": "my-extension",
"private": true,
"scripts": {
"build": "babel ./static/script.js --out-file=./static/script-compiled.js"
},
"devDependencies": {
"@babel/cli": "^7.27.0",
"@babel/core": "^7.26.10",
"@babel/preset-env": "^7.26.9"
},
"babel": {
"presets": [
[
"@babel/preset-env",
{
"modules": false,
"targets": {
"android": "13",
"chrome": "80"
}
}
]
]
}
}
```
#### 关键配置说明 [](#关键配置说明)
1. **依赖安装**:
* `@babel/cli` : Babel 命令行工具
* `@babel/core` : Babel 核心库
* `@babel/preset-env` : 智能预设，根据目标环境自动转换
2. **转义配置**:
```json
"babel": {
"presets": [
[
"@babel/preset-env",
{
"modules": false,
"targets": {
"android": "13",
"chrome": "80"
}
}
]
]
}
```
3. **构建脚本**:
```bash
pnpm build
```
这将把 `./static/script.js` 转义为 `./static/script-compiled.js`
#### 使用示例 [](#使用示例)
假设你有以下现代 JavaScript 代码:
static/script.js
```js
// 使用箭头函数和async/await
const fetchData = async () => {
const response = await fetch('/api/data');
const data = await response.json();
return data?.results ?? [];
};
// 使用可选链和空值合并
const getUserName = (user) => {
return user?.profile?.name ?? 'Anonymous';
};
```
运行 `pnpm build` 后，Babel 会将其转义为 ES5 兼容代码:
static/script-compiled.js
```js
// 转义后的代码(示例)
var fetchData = function fetchData() {
return regeneratorRuntime.async(function fetchData$(_context) {
while (1) {
switch (_context.prev = _context.next) {
case 0:
_context.next = 2;
return regeneratorRuntime.awrap(fetch('/api/data'));
case 2:
response = _context.sent;
// ...
}
}
});
};
```
然后在 HTML 中引用转义后的文件:
```html
```
### 场景二：使用 Vite Legacy 插件 (模块化方式) [](#场景二使用vite-legacy插件模块化方式)
如果你使用 Vite、Webpack 等现代构建工具，可以使用相应的 Legacy 插件来处理转义。
#### Vite 配置示例 [](#vite配置示例)
1. **安装插件**:
```bash
pnpm add -D @vitejs/plugin-legacy
```
2. **配置 `vite.config.ts`**:
vite.config.ts
```ts
import {
fileURLToPath
,
URL
} from 'node:url'
import {
defineConfig
} from 'vite'
import
vue
from '@vitejs/plugin-vue'
import
legacy
from '@vitejs/plugin-legacy'
export default
defineConfig
({
base
: './',
plugins
: [
vue
(),
legacy
({
targets
: ['android >= 13', 'chrome >= 80'],
modernPolyfills
: true,
}),
],
resolve
: {
alias
: {
'@':
fileURLToPath
(new
URL
('./src', import.meta.
url
))
},
},
})
```
3. **构建项目**:
```bash
pnpm build
```
#### Legacy 插件的作用 [](#legacy插件的作用)
`@vitejs/plugin-legacy` 会自动完成以下工作:
1. 生成两个版本的代码:
* 现代版本 (ES 模块，供新浏览器使用)
* Legacy 版本 (ES5，供旧浏览器使用)
2. 注入 polyfills (如 Promise、Array.from 等)
3. 根据浏览器能力自动加载对应版本
构建后，Vite 会生成类似这样的 HTML:
```html
```
### 其他构建工具 [](#其他构建工具)
#### Webpack 配置示例 [](#webpack配置示例)
如果使用 Webpack，可以通过 `babel-loader` 配置:
webpack.config.js
```js
module.exports = {
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader',
options: {
presets: [
['@babel/preset-env', {
targets: {
android: '13',
chrome: '80'
}
}]
]
}
}
}
]
}
};
```
### 验证转义效果 [](#验证转义效果)
构建完成后，建议在示教器上测试:
1. 将插件安装到目标设备
2. 打开插件页面
3. 验证所有功能是否正常工作
---
url: /zh/02-development/03-advanced/07-ai-coding.html
title: AI 编程支持
---
# AI 编程支持 [](#ai-编程支持)
本文档介绍如何使用 AI 辅助工具（如 CodeBuddy、Codex、Cursor 等）快速开发机器人插件。
## 准备工作 [](#准备工作)
使用 AI 编程前，需要准备参考文档：
* **SDK 文档**：
* **插件开发文档**：
> **提示**：如果您使用的 AI Agent 无法很好地读取 URL，建议将以上两个 txt 文档下载到本地项目目录中，然后在 prompt 中引用本地文件路径。
## 示例 Prompt [](#示例-prompt)
以下是一个完整的示例，用于创建一个显示机器人状态的通用服务插件：
```
阅读以下文档，写一个通用服务插件，包含前端页面，显示机器人的当前位置、坐标系编号、伺服状态等信息。
参考资料：
SDK文档：https://dev.svfactory.com/docs/sdk/knowledge/docs.txt
插件文档：https://dev.svfactory.com/docs/extension/knowledge/docs.txt
```
如果使用本地文档，可以修改为：
```
阅读以下文档，写一个通用服务插件，包含前端页面，显示机器人的当前位置、坐标系编号、伺服状态等信息。
参考资料：
SDK文档：./docs/sdk_docs.txt
插件文档：./docs/extension_docs.txt
```
## 使用技巧 [](#使用技巧)
1. **明确需求**：清晰描述要实现的功能
2. **提供上下文**：引用相关文档和示例
3. **分步实现**：复杂功能可以分步骤让 AI 生成
## 注意事项 [](#注意事项)
1. AI 生成的代码需要经过验证和测试
2. 确保代码符合项目编码规范
3. 涉及机器人控制的代码必须进行安全审查
---
url: /zh/02-development/04-package.html
title: 打包与安装
---
# 打包与安装 [](#打包与安装)
插件开发完毕后，可以使用我们提供的工具 `捷勃特插件打包工具` 进行打包成特定的格式。
[软件下载链接](https://gitee.com/agilebot/extension-toolkit/releases)
软件界面如图所示：
## 打包插件为.gbtapp 格式 [](#打包插件为gbtapp格式)
1. 点击选择目录按钮，选择开发好的插件目录。
1. 根据提示填写参数，并点击打包插件按钮，工具会在当前目录下生成插件包。
## 安装插件 [](#安装插件)
在 AgileLink 中的插件管理页面安装插件。
:::warning 警告
在 Bronze 中，无法在示教器上选择文件，请通过 PC 安装插件包。
:::
---
url: /zh/02-development/05-config.html
title: 配置文件
---
# 配置文件 [](#配置文件)
## 文件命名 [](#文件命名)
固定为 `config.json` 。
## 文件内容 [](#文件内容)
一个典型的插件配置文件如下所示：
config.json
```json
{
"name": "MyExtension",
"author": "Your Name",
"type": "generalService",
"scriptLang": "python",
"description": "My Demo Extension",
"version": "1.0",
"entry": "app.py",
"url": ""
}
```
## 字段说明 [](#字段说明)
### `name` [](#name)
插件名称，作为插件的唯一标识。建议使用英文，并确保该名称在插件系统中是唯一的。
* 类型：string
* 示例： `"MyExtension"`
### `type` [](#type)
插件类型，指定插件的功能类别。包括：
* "generalService"：通用服务插件。
* "easyService"：简单服务插件
* "webMiniProgram"：Web 小程序插件
* 类型：string
* 示例： `"generalService"`
### `scriptLang` [](#scriptlang)
插件所使用的编程语言。目前只支持：
* "python"
### `description` [](#description)
插件的简短描述，帮助用户了解插件的功能和用途。
* 类型：string
* 示例： `"My Demo Extension"`
### `version` [](#version)
插件的版本号，建议采用常见的语义化版本控制（SemVer）格式： `主版本号.次版本号.修订号` 。
* 类型：string
* 示例： `"1.0"`
### `author` [](#author)
插件作者的姓名或团队名。
* 类型：string
* 示例： `"agilebot"`
### `contact` [](#contact)
插件作者的联系方式，用于用户在使用插件时遇到问题时的沟通渠道。
* 类型：string
* 示例： `"support@example.com"`
### `copyright` [](#copyright)
插件的版权信息，声明插件的版权归属。
* 类型：string
* 示例： `"Copyright © 2024 Agilebot Inc."`
### `license` [](#license)
插件的授权许可信息，说明插件的使用许可条款。
* 类型：string
* 示例： `"MIT"`
### `entry` [](#entry)
通用服务插件的入口文件，这通常是一个 Python 脚本文件。
* 类型：string
* 示例： `"app.py"`
### `url` [](#url)
Web 页面的入口文件，适合 `Web小程序` 或 `通用服务` ，这通常是一个 html 网页文件或网页路由地址。
* 类型：string
* 示例： `"index.html"`
## 智能提示 [](#智能提示)
我们使用 JSON Schema 来规范插件的配置文件格式。通过 JSON Schema，您可以明确指定插件配置的结构、字段类型、必填项等信息，确保插件的配置文件符合规范。这使得插件的开发和安装过程更加简单和可靠。
您可以通过包管理工具来安装 JSON Schema：
:::code-group
```sh [npm]
npm install @agilebot/extension-schemas
```
```sh [yarn]
yarn add @agilebot/extension-schemas
```
```sh [pnpm]
pnpm add @agilebot/extension-schemas
```
:::
安装之后，您可以在项目中引用该插件的配置文件：
config.json
```json
{
"$schema": "./node_modules/@agilebot/extension-schemas/v1.0/extension-schema.json"
}
```
也可以使用 unpkg CDN 进行引用，如下所示：
config.json
```json
{
"$schema": "https://unpkg.com/@agilebot/extension-schemas/v1.0/extension-schema.json"
}
```
---
url: /zh/02-development/06-runtime.html
title: 运行环境
---
# 运行环境 [](#运行环境)
后端插件运行在一个隔离的容器内，预装了 Python3 以及常用的 pip 包，可以通过界面上的 `环境信息` 按钮查看。
:::warning 注意
出于安全考虑，插件仅能访问自己的工作目录，无法访问系统目录（如 `/dev` 、 `/etc` 等）和其他插件的文件。
注：工业插件没有这个限制。
:::
## 安装额外的 pip 包 [](#安装额外的pip包)
插件系统支持安装额外的 Python 包来扩展运行环境的功能。为了保证系统安全性和稳定性，只支持安装预编译的 wheel 包（.whl 文件）。
### 支持的包格式 [](#支持的包格式)
* **仅支持 wheel 格式（.whl）**：wheel 是 Python 的预编译二进制分发格式，安装速度快且避免了编译依赖问题
* **不支持源码包（.tar.gz）**：为了安全性考虑，系统禁止在线编译和下载依赖
### 安装方式 [](#安装方式)
通过系统管理界面上传 `.whl` 文件：
---
url: /zh/03-detailed-case/01-tcp-velocity.html
title: TCP速度
---
# TCP 速度 [](#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 安装文档](https://dev.svfactory.com/docs/sdk/zh/1-python/1-intro/1.3-install.html)。
* 浏览器（Chrome/Edge 最新版）。
## 软件文件结构 [](#软件文件结构)
从插件开发工具包仓库的 ["demo"](https://gitee.com/agilebot/extension-toolkit/tree/master/demo/TCP%E9%80%9F%E5%BA%A6) 目录下载示例代码后，目录结构如下：
* 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\_services.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
```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
```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 请求以设置目标寄存器编号。
```py
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
```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
```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
```ts
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` 安装前端依赖
1. 激活 Python 虚拟环境，执行 `pip install -r requirements.txt` 安装后端依赖。
1. 执行 `pnpm dev` 启动通用服务。
1. 启动成功后浏览器会自动打开： `http://localhost:8001`
1. 在机器人上执行程序或示教，即可在页面上看到实时状态更新
### 简单服务的开发 [](#简单服务的开发)
1. 打开 `PowerShell` ，进入 `TCP速度/RunningStatus` 目录，执行 `python RunningStatus.py` 即可执行。
## 各组件的打包 [](#各组件的打包)
### 通用服务的打包 [](#通用服务的打包)
1. 打开 `PowerShell` ，进入 `TCP速度/TcpVelocity` 目录，确保已经完成上述步骤中的 `安装前端依赖` 、 `安装后端依赖` 。
2. 执行 `pnpm build` 编译通用服务，编译完成后会生成 `TCP速度/TcpVelocity/dist` 目录
1. 使用插件打包工具打包为 `TcpVelocity.gbtapp` ，具体步骤请参考文档：[打包与安装](./../02-development/04-package.html)
:::warning 注意
打包时请选择 `TCP速度/TcpVelocity/dist` 目录作为打包路径。
:::
打包完成后，可在 `插件管理界面` 安装并启用插件 `TcpVelocity` 。
### 简单服务的打包 [](#简单服务的打包)
1. 使用插件打包工具打包为 `RunningStatus.gbtapp` ，具体步骤请参考文档：[打包与安装](./../02-development/04-package.html)
:::warning 注意
打包时请选择 `TCP速度/RunningStatus` 目录作为打包路径。
:::
打包完成后，可在 `插件管理界面` 安装并启用插件 `RunningStatus` 。
---
url: /zh/04-app-intro/01-force-control.html
title: 恒力控制插件
---
# 恒力控制插件 [](#恒力控制插件)
## 使用方法 [](#使用方法)
1. 插件包含了恒力控制**配置**及**可视化**功能，二者分页显示
2. 恒力控制**配置**项：
1. 传感器安装方式：力控输入传感器的安装方式，依据实际情况选择；
2. 传感器数据配置：力控输入传感器的数据来源，需要指明使用的传感器类型及地址；
3. 力控检测配置：
1. 使用的坐标系：在程序中配置，此处只读显示；
2. 预设力值：在程序中配置，此处只读显示；
3. 预设力输出方式：配置力控结果的输出方式，配置完成后会将机器 TCP 在此方向上的力输出到指定的寄存器进行可视化。
4. 可视化配置 (为检测力控实际效果，可以在力控目标方向上安装一维力传感器，用于对比判断力控的效果)：
1. 结果观察寄存器类型：安装的检测用的传感器类型；
2. 结果观察寄存器映射：安装的检测用的传感器的寄存器地址；
3. 恒力控制**可视化**：
1. 开始 / 停止采样：点击对应按钮开始 / 停止采样；
2. 采样配置：通过调整采样频率和采样个数来控制波形图的频率和容量；
3. 波形图：横轴代表时间，纵轴代表力大小，不同曲线以颜色区分，需要注意的是预设力与计算力颜色相同，其中虚线代表预设力，实线代表计算力；
## 注意事项 [](#注意事项)
1. 恒力控制插件需要安装在 Copper 版本 >= `7.7.0.0` 的机器人上
## 更新日志 [](#更新日志)
### v1.0.1-- 工博会特殊版本 [](#v101-工博会特殊版本)
* 增加可选的底座力传感器，可映射到机器人上的 M 寄存器并显示到波形图上
### v1.0.1 [](#v101)
* 修复深色主题下部分文本不可见的问题
* 力控开启时，波形图显示力值，关闭时不显示
* 调整波形图数据采样范围：
* 采样频率可选范围调整为： `[100, 200, 500, 1000, 2000]ms`
* 采样个数可选范围调整为： `[10, 20, 50, 100, 200, 500, 1000]`
### v1.0.0 [](#v100)
* 添加恒力控制插件基本功能（见功能用法说明）
---
url: /zh/04-app-intro/02-rm-gripper.html
title: 增广夹爪插件
---
# 增广夹爪插件 [](#增广夹爪插件)
## 插件信息 [](#插件信息)
* 增广夹爪后端
* 名称：rm-gripper-easy-service
* 增广夹爪 Web
* 名称：rm-gripper-web
* 品牌官网链接：
## 适用范围 [](#适用范围)
Copper：v7.6.0.0 及以上
## 安装指南 [](#安装指南)
1. 打开 `应用 - 插件管理` ，点击右上角的 `安装插件` 按钮。
1. 分别安装 `rm-gripper-easy-service` 、 `rm-gripper-web`
1. 在 `Web小程序` 类别中启用 `rm-gripper-web` ，在 `简单服务` 类别中启用 `rm-gripper-easy-service`
## 使用说明 [](#使用说明)
打开 `应用 - 插件 - rm-gripper-web` ，可进入配置界面
点击 `扫描` ，可扫描各通道下的手爪
扫描后，点击 `添加夹爪` ，将夹爪添加到列表中
添加后，默认通道为 `不可用` ，需手动配置为相应的通道
点击 `操作` 按钮，可对手爪进行夹取和旋转操作
点击 `配置` 按钮，可进入指令编辑页，具体操作说明可参考增广手册，也可点击 `帮助` 查看简易说明。
### 程序指令调用 [](#程序指令调用)
打开 `程序 - 新增程序` 界面，使用 `CALL_SERVICE` 指令可调用 `增广夹爪后端` 中的相关方法。
例：激活手爪 1，通过调用 `rm-gripper-easy-service` 服务中的 `gripperActivate` 指令实现，参数为 `gripperId=1`
以下 `rm-gripper-easy-service` 支持调用的指令列表：
| 指令说明 | 指令名 | 参数 |
| ----------- | -------------------- | --------------------------------------------------------------- |
| 激活手爪 | gripperActivate | \- gripperId: 手爪 ID |
| 控制手爪移动 | gripperMove | \- gripperId: 手爪 ID\- position: 目标位置\- speed: 移动速度 |
| 控制手爪旋转 | gripperRotate | \- gripperId: 手爪 ID\- position: 目标位置\- speed: 移动速度\- force: 作用力 |
| 控制手爪伺服开关 | servo\_switch | \- gripperId: 手爪 ID\- on: 布尔值，是否开启伺服 |
| 初始化抓手 | init\_gripper | \- gripperId: 手爪 ID |
| 重置手爪错误状态 | reset\_error | \- gripperId: 手爪 ID |
| 重置手爪的力矩状态 | reset\_force | \- gripperId: 手爪 ID |
| 触发执行指令 | execute\_instruction | \- gripperId: 手爪 ID\- id: 指令 ID |
| 停止当前正在执行的指令 | stop\_instruction | \- gripperId: 手爪 ID |
| JOG + | forward | \- gripperId: 手爪 ID\- step\_length: 步长，默认为 1 |
| JOG - | backward | \- gripperId: 手爪 ID\- step\_length: 步长，默认为 1 |
### 操作视频 [](#操作视频)
#### 扫描设备 [](#扫描设备)
#### 指令动作 [](#指令动作)
## 更新日志 [](#更新日志)
### v1.0 [](#v10)
初始版本
---
url: /zh/04-app-intro/03-socket.html
title: SOCKET通讯（JSON）插件
---
# SOCKET 通讯（JSON）插件 [](#socket通讯json插件)
---
[文档链接](https://w8212nxs8v.feishu.cn/docx/QMZydtfMaoFI8sxi1bqcfKw5nlf)
[PDF 下载链接](https://dev.svfactory.com/files/SOCKET%E9%80%9A%E8%AE%AFSDK%5F%E6%8F%92%E4%BB%B6%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3.pdf)
---
url: /zh/04-app-intro/04-hitbot-z-erg-20c.html
title: 慧灵夹爪插件
---
# 慧灵夹爪插件 [](#慧灵夹爪插件)
---
# 1\. 文档概述 [](#1-文档概述)
## 1.1 文档目的 [](#1-1)
提供一份专业且全面的协作机器人夹爪插件使用文档，指导使用者正确的使用插件以满足实际调试现场要求。本文提供 GBT 机器人关于慧灵夹爪 Z-ERG-20C 的两个插件，分别可以在程序中使用简单服务定义的指令编程和通用服务中打开 UI 进行手动调试和配置夹爪相关参数。
## 1.2 适用产品与版本 [](#1-2)
夹爪品牌与型号：**HITBOT\_Z-ERG-20C**
机器人品牌与型号：**GBT - 协作机器人系列**
机器人版本要求：**V7.6.D.1** 及以上，末端版本 **2542** 及以上
### 插件版本号： [](#插件版本号)
简单服务插件：HL-20251205
通用服务插件：HLUI-20251205
## 1.3 相关文档 [](#1-3)
夹爪相关手册：
机器人相关手册：
# 2\. 用前需知 [](#2-用前需知)
## 2.1 注意事项与更新记录 [](#21注意事项与更新记录)
更新日期：2025/12/5
更新内容：初版发布
①
当前该插件仅支持波特率 115200，数据位 8，停止位 1，校验方式无，请提前在 hitbot 上位机软件配置。
如有特殊要求请联系开发人员，后续增加自定义通讯参数配置
②
指令异常暂无自定义日志信息，只会报警远程服务调用超时
## 2.2 安全相关 [](#2-2)
## 通用安全规范 [](#通用安全规范)
操作前必须接受培训。
在自动运行前务必进行手动测试。
工作区域内确保**安全**。
## 安装与调试警告 [](#安装与调试警告)
断电后进行电气连接。
确保夹爪安装牢固，负载（工件）在夹爪承受能力范围内。
注意夹爪运动范围，避免与机器人本体或周围环境发生碰撞。
## 操作期间警告 [](#操作期间警告)
切勿在夹爪夹持物体时将手或身体部位伸入夹爪操作区域。
急停按钮在合理范围内。
# 3\. 系统要求与准备工作 [](#3-系统要求与准备工作)
## 3.1 硬件要求 [](#3-1)
协作机器人控制器可正常开机使用。
夹爪本体可正常上电使用。
必要的线缆（通讯线、电源线）。（目前仅支持末端 io 使用，如需接入控制柜使用请联系开发人员）
安装法兰或适配板。
## 3.2 软件要求 [](#3-2)
机器人操作系统版本正常可以使用。
机器人支持插件环境和插件安装。
其它：见 1.2 适用产品与版本
# 4\. 安装与配置 [](#4-安装与配置)
## 4.1 插件安装 [](#4-1)
**注意：**应 在夹爪硬件接线成功且末端 io 配置成功后再激活插件使用
## 4.2 硬件安装与连接 [](#4-2)
### 机械安装： [](#机械安装)
按照实际需求连接机器人夹爪至机器人法兰连接件，机器人法兰接口尺寸查看对应型号本体机械说明书
### 电气连接： [](#电气连接)
#### 接线图 [](#接线图)
##### 电源连接: [](#电源连接)
采用机器人末端 io 供电 24v
请选择下图：**引脚 5 供 24v**, **引脚 8 供电 0V,**并 查看 **4.3** 如何在机器人软件配置
##### 通讯连接: [](#通讯连接)
采用机器人末端 485 通讯，
请选择下图：**引脚 1** 和**引脚 2** 接线并查看 **4.3** 如何在机器人软件配置
夹爪接口：
请选择红色 24V + 与上述引脚 5 接线
选择黑色 0V + 与上述引脚 8 接线
选择黄色 485a 与上述引脚 1 接线
选择黄白色 485b 与上述引脚 2 接线
注意 485 与 24v 夹爪内部未隔离，如有需要需客户使用其它设备进行隔离，夹爪部分详细使用请联系 HITBOT 技术支持
## 4.3 软件配置 [](#4-3)
登录机器人 TP 并成功连接至机器人
点击通讯 -- 接口配置 -- 手腕，配置相关通讯参数 (建议使用默认参数：115200,8,1,N）。
# 5\. 功能使用指南 [](#5-功能使用指南)
## 5.1 通用服务插件 [](#5-1)
### 功能： [](#功能)
手动调试夹爪张开闭合、旋转
查看夹爪当前状态
修改夹爪参数
### 使用说明： [](#使用说明)
#### 1\. 激活插件 [](#1激活插件)
激活插件成功后插件名称左边会出现绿点表示插件激活成功，如果为出现则检查当前版本是否支持或联系技术支持人员
#### 2\. 通用服务插件 - UI 界面 [](#2通用服务插件-ui界面)
可点击菜单 -- 应用 -- 插件，选择对应插件进入
如果出现下图页面则表示插件未连接至夹爪，请检查接线和配置
连接成功会出现下述页面
##### 解释： [](#解释)
###### 3.1 公共区域部分： [](#31公共区域部分)
插件使用 sdk 连接控制器内部，该状态表示成功连接，如果出现连接异常请检查当前版本是否支持或联系技术人员
该状态通过读取从站寄存器信息检查 modbus 连接状态，并映射至数字输出状态，可供外部设备检查夹爪连接状态，连接正常为 1，失败为 0，配置信息可以在界面 “数字输出控制” 选择，默认地址数字输出 1
该栏目可以手动断开 modbu 和 sdk 连接，刷新页面状态，和手动控制连接状态的数字输出
页面的自动刷新指的是页面定期（例如每 5 秒）自动向服务器请求最新数据并更新页面显示，而不需要用户手动点击刷新按钮。
###### 3.2 公共参数部分 [](#32公共参数部分)
可以配置夹爪：
* ID
* 波特率（目前只支持 115200）
* 电机使能状态
* 初始化方向
* 手动执行初始化
###### 3.3 高级设置 [](#33高级设置)
可以配置夹爪：
* 上电是否自动初始化
保存参数
包含：ID, 波特率，初始化方向，自动初始化设置，旋转堵停使能，旋转堵停灵敏度
且需要断电重启后生效
旋转堵停使能设置
旋转堵停灵敏度是指在堵转停转使能的情况下（夹爪旋转堵转后会停止旋转）
旋转堵停灵敏度
夹爪停转时的灵敏度要求，取值范围为 0-100，例如设定值为 100，则夹爪在旋转过程中碰到障碍，会在较 高的速度下停止旋转，保护夹爪和所夹取的产品，相对来说比较灵敏，若设定值为 10，则是旋转时碰到障碍，旋转速度降到更低时，才会触发夹爪的停转；
复位多圈转动值
复位多圈转动值是指夹爪在旋转多圈后，将当前位置的多圈数值清除的方法，比如当前夹爪的旋转角度是 760°（2\*360°+40°），清除多圈后，旋转角度就变为 40°（减去整数圈的度数 720°），当前旋转角度为 - 600° （-360°-240°），清除多圈后，旋转角度变为 - 240°（减去整数圈的度数 - 360°），非必要不建议使用
其它相关设置请使用 HITBOT 上位机软件连接夹爪设置
###### 3.4 夹持控制 [](#34夹持控制)
可以设置：
夹持位置
单位 mm，范围 0-20，点击写入夹爪加持
夹持速度
单位 mm/s，范围 1-100，点击写入修改速度，如果当前夹爪正在运动则写入速度不会立即生效
###### 3.5 旋转控制 [](#35旋转控制)
可以设置：
* 绝对旋转角度
单位度，范围 - 3600000 至 3600000
* 旋转速度
单位度 / 秒，范围 1-1080，点击写入修改速度，如果当前夹爪正在运动则写入速度不会立即生效
###### 3.6 状态监控 [](#36状态监控)
该页面可以监控已添加的所有参数信息
注意如果在其它页面想读取信息，需要先点击该处的 “刷新所有状态”
###### 3.7 数字输出控制 [](#37数字输出控制)
该页面可以配置将数字输出 1-16 中任意一个信号点映射为夹爪连接状态，理论误差小于 1 秒
注意关闭插件运行状态属于人工干预，数字输出状态并不会复位！
## 5.2 简单服务插件 - 程序指令 [](#5-2)
### 功能： [](#功能-1)
在程序中可以连接 / 断开夹爪，控制夹爪运动，等待夹爪到位
### 使用说明： [](#使用说明-1)
##### 1\. 连接与断开夹爪 [](#1连接与断开夹爪)
可选参数：id, 波特率，奇偶校验，数据位，停止位，超时时间
##### 2\. 控制夹爪开合和速度 [](#2控制夹爪开合和速度)
可选参数：id, 位置 0-20mm，速度 1-100mm/s
##### 3\. 控制夹爪旋转和速度 [](#3控制夹爪旋转和速度)
可选参数：id, 绝对旋转角度：-3600000\~3600000°，旋转速度：1-1080°/s
##### 4\. 等待夹爪开合到位 [](#4等待夹爪开合到位)
可选参数：id, 目标位置 mm，容许偏差 mm, 超时时间 ms（需要小于 800ms），采样间隔 s
##### 5\. 等待夹爪旋转到位 [](#5等待夹爪旋转到位)
可选参数：id，目标角度 °，容许偏差 mm, 超时时间 ms（需要小于 800ms），采样间隔 s
程序示例：
# 6\. 维护与故障排除 [](#6-维护与故障排除)
## 6.1 日常维护 [](#6-1)
清洁、检查等建议。
## 6.2 常见问题与解决方案（FAQ） [](#6-2)
现象：插件无法连接夹爪。
可能原因：线缆松动、地址错误、电源未开启。
解决方案：检查物理连接，确认配置参数。
## 6.3 错误代码说明 [](#6-3)
联系技术支持人员
# 7\. 附录 [](#7-附录)
## 7.1 技术规格 [](#7-1)
夹爪的详细技术参数，请查看 1.3 相关文档
插件的技术参数，请查看 5 功能使用指南
## 7.2 免责声明 [](#7-2)
本插件及相关文档均按 “现状” 提供，不附带任何明示或暗示的保证，包括但不限于对商品适销性、特定用途适用性以及不侵犯第三方权利的暗示保证。开发商不保证本插件完全无缺陷或错误，也不保证其操作不会中断。
在任何情况下，开发商及其关联方均不对因使用或无法使用本插件而导致的任何直接、间接、附带、特殊、惩罚性或后果性损失承担责任，包括但不限于：
* 数据丢失或损坏。
* 生产中断或利润损失。
* 业务中断。
* 设备损坏或人身伤害。
* 任何第三方提出的索赔。
任何对本插件的未经授权的修改、反向工程、反编译或反汇编均被严格禁止。因用户或第三方对插件进行的任何未授权改动而导致的任何问题，开发商概不负责。
用户有责任确保在使用本产品时，完全遵守其所在国家或地区的所有适用的安全标准、法律、法规，包括但不限于机械指令、电气安全法规、职业健康与安全规定等。开发商提供的安全信息仅为一般性指导，不能替代用户根据其具体应用场景进行的全面风险评估
---
url: /zh/04-app-intro/05-autoplan.html
title: 智能摆盘插件 AUTOPLAN
---
# 智能摆盘插件 AUTOPLAN [](#智能摆盘插件-autoplan)
---
:::info 开源地址
:::
# 1 插件概述 [](#1)
AUTOPLAN 插件，即捷勃特智能摆盘规划系统。它依据工件形状、尺寸、摆盘容器规格等数据，以先进算法快速精准算出工件在托盘等承载器具上的最佳排盘点位，通过合理布局提升空间利用率、减少托盘用量或占用面积，同时兼顾工件间隔、摆放方向等生产工艺要求，保障后续加工顺畅、避免碰撞干涉，最终提高生产效率、降低生产成本。
## 1.1 插件信息 [](#1-1)
名称：AUTOPLAN.gbtapp
版本：v6.9
## 1.2 插件运行环境要求 [](#1-2)
机器人软件版本：V7.6.6.0 及以上
## 功能模块 [](#功能模块)
系统提供以下 5 个主要功能模块：
### 1\. 机器人设置 [](#1-机器人设置)
* **机器人连接**：通过 IP 地址连接机器人控制器
* **程序读取**：从机器人读取指定程序的 P 点数据
* **工具配置**：设置工具数量、间距、方向、布局等参数
* **坐标系设置**：配置 UF 值、坐标系方向、自动 TF 计算等
### 2\. 智能规划 [](#2-智能规划)
* **料框设置**：配置料框长度、宽度、深度
* **工件设置**：支持多种工件类型
* 圆形工件
* 长方形工件
* 多边形工件（5-8 边）
* 三角形工件（等边 / 等腰）
* **摆放设置**：
* 横向 / 纵向间距设置
* 边框距离设置
* 包材厚度设置
* 摆放层数设置
* 排布方式：阵列式 / 蜂窝式
* 摆盘方式：行优先 / 列优先
* 余行列转向设置
* **实时预览**：自动生成规划结果预览图，显示可填充数量和单行 / 列数量
### 3\. 手动规划 [](#3-手动规划)
* **网格参数设置**：设置行数、列数、计算方式（行优先 / 列优先）
* **参考点读取**：可自定义 3 个参考点 PR ID（默认 1/2/3），并从机器人读取对应 PR
* **点位计算**：基于参考点自动计算所有网格点位坐标
* **数据生成**：生成完整的点位数据表格
### 4\. 数据清单 [](#4-数据清单)
* **数据展示**：以表格形式展示所有规划点位数据
* 行号 / 列号
* P 点 ID
* X/Y/C 坐标值
* X/Y/C 补偿值
* **补偿调整**：
* 支持按行 / 列进行补偿
* 支持角度补偿
* 实时更新补偿值
* **数据写入**：将规划数据写入机器人 P 点程序
* 支持设置 “起始 P 点”（默认 1），按起始编号连续写入
* **配方保存**：保存当前规划参数为配方
### 5\. 配方库 [](#5-配方库)
* **配方管理**：
* 配方列表查看
* 配方保存 / 加载
* 配方删除
* 配方导入 / 导出
* **配方调用**：
* 通过配方号（MH 寄存器）调用配方
* 支持外部调用监控
* 支持自动写入功能
* **配方预览**：查看配方的详细参数和预览图
---
## 核心特性 [](#核心特性)
### 智能算法 [](#智能算法)
* **自动优化**：自动计算最优摆放方案，最大化料框利用率
* **碰撞检测**：自动检测工件边界，避免超出料框范围
* **多种排布**：支持阵列式和蜂窝式两种排布方式
* **灵活配置**：支持行优先 / 列优先两种摆盘方式
### 机器人集成 [](#机器人集成)
* **实时通信**：与机器人控制器实时通信
* **数据同步**：自动读取和写入机器人程序数据
* **寄存器操作**：支持 PR、R、SR 寄存器读写
* **状态监控**：实时监控机器人连接状态和运行状态
### 配方系统 [](#配方系统)
* **配方存储**：本地 JSON 格式存储配方数据
* **配方导入导出**：支持 USB 导入导出配方
* **配方冲突检测**：自动检测配方编号冲突
* **配方自动分配**：自动分配可用配方编号
### 多语言支持 [](#多语言支持)
* 中文简体
* English
* Tiếng Việt（越南语）
* 日本語（日语）
* 한국어（韩语）
# 2 机器人设置 [](#2)
在使用 AUTOPLAN 插件前，需要先创建机器人程序、托盘用户坐标及工具坐标。
## 2.1 创建程序 [](#2-1)
1\. 创建一个机器人程序 “PUT”，点击新建创建 N 个 P 点（N≥一层的工件总数）。
## 2.2 创建 UF/TF [](#2-2)
1\. 创建工具坐标 TF, 创建步骤请参考《捷勃特机器人系统操作说明书》 2\. 创建托盘用户坐标 UF，使用四点法。设定坐标原点为：人面对料盘状态下的料盘左下角，Z 轴 + 方向向上。
创建步骤请参考《捷勃特机器人系统操作说明书》。
## 2.3 创建数值寄存器 [](#2-3)
菜单→数据→数值寄存器，创建如下寄存器。
---
# 3 AUTOPLAN 插件界面 [](#3)
## 3.1 机器人设置 [](#3-1)
1\. 机器人 IP 地址：控制柜 IP 地址，连接后可显示连接状态、型号、控制柜版本信息。 2\. 程序名称：码垛点位调用程序（需预先创建程序及 P 点）
 查看程序中 P 点参数
3\. 工具参数设定：
* Z＆C 参考寄存器：填写放料基准点 PR 的 ID 号，取放料基准 PR 的 Z 和 C，生成托盘放料点
* UF 值：用户坐标系，参数可选
* 工具数量：安装工具数量
* 工具间距：工具之间安装间隙距离，单位 mm
* 工具方向：工具安装的方向，X/Y 方向（世界坐标系为基准）
* 工具布局：单侧 / 双侧
* 单侧：单工具移动变距。机器人工具仅在机器人末端的一侧进行排列安装；
* 双侧：双工具移动变距。机器人工具在机器人末端的两侧均有排列安装。
* 自动 TF 计算：关闭 / 开启，开启时，根据填写的间距参数改写 TF1、TF2 的坐标值；关闭时不做处理。
* 坐标系方向：左手系 / 右手系
## 3.2 智能规划 [](#3-2)
1\. 料框设置：设置料框长度、料框宽度、料框深度，单位 mm 2\. 工件设置：
| 类型 | 设置参数 | 说明 |
| --- | ------------------------------------------------------------------------------------------ | -- |
| 圆形 | 1\. 圆形直径、工件高度单位为 mm 2\. 前端单次下料数量：前道设备单次下料数量 | |
| 长方形 | 1\. 长方形长度、宽度、工件高度单位为 mm 2\. 前端单次下料数量：前道设备单次下料数量 | |
| 多边形 | 1\. 多边形边长、工件高度单位为 mm 2\. 当多边形为六边形时，可选对边或对角排列 3\. 前端单次下料数量：前道设备单次下料数量 | |
| 三角形 | 1\. 三角形类型 等边三角形：设置边长，单位为 mm 等腰三角形：设置边长和底长，单位为 mm 2\. 三角形朝向 朝上 朝下 朝左 朝右 前端单次下料数量：前道设备单次下料数量 | |
3\. 摆放设置
* 横向间距：工件之间的横向间隔距离，单位：mm
* 纵向间距：工件之间的纵向间隔距离，单位：mm
* 横向边框距离：工件行与边框的距离，单位：mm
* 纵向边框距离：工件列与边框的距离，单位：mm
* 包材厚度：包材自身的厚度，单位：mm
* 摆放层数：工件摆放的总层数
* 排布方式：
* 阵列式
* 蜂窝式
* 摆盘方式：行优先 / 列优先，机器人按行顺序摆或者列顺序摆
* 余行列转向：关闭 / 左转 90° / 右转 90°，当工具数量和摆盘数量非倍数关系时，可选先摆放倍数部分，最后单独摆放单数部分
4\. 计算 参数设置完成后，点击计算会自动生成规划结果，如下图。
## 3.3 手动规划 [](#3-3)
该功能用于手动规划料盘摆放点位。 网格参数
* 行数：手动输入摆盘物料行数
* 列数：手动输入摆盘物料列数
* 计算方式：行优先 / 列优先，机器人按行顺序摆或者列顺序摆
* 读取参考点：读取示教 PR1、PR2、PR3 的点位数据
* 计算所有点位：由列数、行数、计算方式及参考点数据，生成摆盘点位参数
操作步骤 以下图红框料盘为例。
步骤 1 输入行数及列数
步骤 2
使用示教器，将三个参考位置的中心点示教记录到三个 PR 寄存器。第 1 行第 1 列 (PR1)，第 4 行第 1 列 (PR2)，第 1 行第 5 列 (PR3)
步骤 3 点击计算所有坐标系，进入数据清单。
## 3.4 数据清单 [](#3-4)
1\. 补偿行 / 列：可选单行 / 列以及编号，行补偿 Y 值，列补偿 X 值。 2\. 补偿值：输入补偿值和角度补偿，点击更新按钮，补偿值显示在数据清单中。如需修改多行，则多次输入补偿更新即可。 3\. 程序名称：数据修改完成后，输入程序名。点击写入 P 点，生成数据信息自动填入到程序中 P 点。 4\. 配方名、配方编号：设置配方名及配方编号（唯一），保存配方，以便机器人调用。 注：智能规划页面重新计算则清除所有的补偿值，重新生成数据表单。
## 3.5 配方库 [](#3-5)
该功能支持通过配置信号（MH 寄存器、DI/DO ）实现配方远程调用。 操作约束：外部调用时机器人处于空闲状态，未在运动，且无机器人程序运行，否则禁止调用。
* 配方查询：通过 “查找配方” 输入框，快速检索目标配方，支持精准名称匹配。
* 配方号 MH：配置调用配方的 MH 寄存器 ID，给该寄存器输入配方编号调用不同配方。
* 调用信号 DI：设置触发配方调用的输入信号 DI 的 ID。
* 完成信号 DO：配置配方执行完成后反馈的输出信号 DO 的 ID。
* 外部调用控制：
* 允许外部调用：切换 “关闭 / 开启”。
* 自动写入：切换 “关闭 / 开启”。
配方列表：
* 支持 “全选” 批量处理，“导出选中配方” 可备份配置到优盘，“导入配方” 可将优盘中的备份配方恢复至本地；
* 对单个配方（如 test1、test2 ），点击配方名可在右侧预览区域预览配方内容 ，点击 “读取” 可加载参数，“删除” 则移除无用配方。
外部启动流程：
1. 初始设置与启动
* 开启 “允许外部启动” 功能，机器人进入待命状态，开始监控指定 ID 的 DI 输入信号。
2. DI 信号触发，读取 MH 寄存器值调用配方
* 当监控的 DI 输入信号变为 ON 时，机器人读取指定 ID 的 MH 寄存器中存储的值。
* 根据 MH 寄存器值对应的配方编号，调用相应配方。
3. 自动写入配方数据
* 若 “自动写入” 功能开启：机器人将配方数据写入数据清单页面设置的程序名对应的程序 P 点。
4. 完成写入后，输出 DO 脉冲信号
* 完成写入（或仅调用配方）后，机器人通过指定 ID 的 DO 输出信号发送一个 1s 的脉冲，用于告知外部设备流程已完成。
5. 重置监控状态
* 完成一次写入后，重新监控指定 ID 的 DI 输入信号，等待下一次触发。
## 3.6 U 盘导出 / 导入配方 [](#3-6)
导出配方：
1. 将 U 盘（格式为 FAT32）插入示教器上的 USB 接口处。
2\. 将机器人切换至 SERVO\_OFF 状态及手动模式，选中需备份的配方后点击 “导出选中配方”，待右上角提示 “备份成功” 即可。
导入配方
1. 将 U 盘（格式为 FAT32）插入示教器上的 USB 接口处。
2. 机器人切换到 SERVO\_OFF 状态与手动模式，点击 “导入配方”，就能查看 U 盘中的配方文件。
1. 勾选想要导入的配方，点击 “导入选中配方”，再点击 “确定”。
1. 等右上角显示 “导入成功” 后，点击 “配方” 就可以查看了。
## 常见问题 [](#常见问题)
### 问题：启动 EXE 时提示被 Device Guard 或智能应用控制拦截 [](#问题启动-exe-时提示被-device-guard-或智能应用控制拦截)
**现象**：
* 启动程序时出现类似提示： `已被组织的 Device Guard 策略阻止`
* 程序窗口显示 `Launched. You can close this window.` 后无法正常运行
**适用系统**：Windows 10 / Windows 11
**处理方法**：
1. 打开 `Windows 安全中心` （可在开始菜单搜索 “Windows 安全中心”）。
2. 进入 `应用和浏览器控制` 。
3. 找到 `智能应用控制` 。
4. 将智能应用控制设置为 `关闭` 。
5. 重新启动本软件。
> 说明：关闭后通常可解除对未受信任应用的拦截。如设备存在组织策略（企业管控），请联系 IT 或系统管理员处理。
---
## 注意事项 [](#注意事项)
### 重要提示 [](#重要提示)
1. **机器人连接**：
* 确保机器人控制器与运行系统的设备在同一网络
* 连接前检查 IP 地址是否正确
* 连接失败时检查网络连接和防火墙设置
2. **数据备份**：
* 写入 P 点前建议备份原有程序
* 配方数据存储在 `data/` 目录，建议定期备份
3. **参数设置**：
* 料框尺寸必须大于工件尺寸
* 间距和边框距离必须为正值
* 工具数量必须与实际工具数量一致
4. **配方管理**：
* 配方编号（ID）必须唯一
* 系统会自动检测并提示编号冲突
* 删除配方前请确认不再需要
5. **坐标系设置**：
* UF 值范围：0-30
* 工具坐标系 ID 范围：1-30
* 坐标系方向：右手坐标系 / 左手坐标系
6. **手动规划**：
* 参考点 1/2/3 支持自定义 PR ID（默认 1/2/3）
* 三个参考点对应关系建议：
* 参考点 1：第一行第一列
* 参考点 2：最后一行第一列
* 参考点 3：第一行最后一列
---
## 版本历史 [](#版本历史)
### v7.5.4 (2026 年 4 月 10 日) [](#v754-2026年4月10日)
* 修复工具数量为 0 时写入 P 点仍为 TF1 的问题
* 为静态资源增加版本参数，避免浏览器缓存旧脚本导致逻辑未生效
### v7.5.3 (2026 年 4 月 10 日) [](#v753-2026年4月10日)
* 修复写入 P 点时 `None` 值触发 `int()` 转换异常的问题
### v7.5.2 (2026 年 4 月 9 日) [](#v752-2026年4月9日)
* 新增电脑端
* 工具数量范围调整为 0-10
* 当工具数量为 0 时，写入 P 点使用 TF0
* 工具数量为 0/1 时跳过自动 TF 更新，避免无效报错
### v7.5.1 (2026 年 4 月 8 日) [](#v751-2026年4月8日)
* 手动规划参考点坐标表格新增 C 列显示
* 参考点文案统一为 “参考点 1/2/3”
* 修复手动规划计算时误读取默认 PR1 导致的报错
### v7.5 (2026 年 4 月 7 日) [](#v75-2026年4月7日)
* 新增韩语界面支持
* 手动规划支持自定义参考点 PR ID（默认 1/2/3）
* 数据清单新增 “起始 P 点” 写入起点配置
* UF 范围调整为 0-30
### v7.4.0 (2026 年 1 月 16 日) [](#v740-2026年1月16日)
* 当前稳定版本
* 支持智能规划和手动规划
* 完整的配方管理系统
* 多语言支持
* 外部调用监控功能
---
**捷勃特智能摆盘规划系统 | 版本 v7.5.4 | 更新日期：2026 年 4 月 10 日 | © 2026**
> 本手册中包含的信息如有变更，恕不另行通知，且不应视为捷勃特的承诺。捷勃特对本手册中可能出现的错误概不负责。
>
> 除本手册中有明确陈述之外，本手册中的任何内容不应解释为捷勃特对个人损失、财产损坏或具体适用性等做出的任何担保或保证。
>
> 捷勃特对因使用本手册及其中所述产品而引起的意外或间接伤害概不负责。
>
> 未经捷勃特的书面许可，不得再生或复制本手册和其中的任何部件。
>
> 可从捷勃特处获取此手册的额外复印件。
>
> 本出版物的原始语言为中文。
>
> © 版权所有 2025Agilebot. 保留所有权利。
>
> AgilebotRoboticsCo.,Ltd
>
> 中国上海
---
url: /zh/04-app-intro/06-usm.html
title: USM - User Socket Message
---
# USM - User Socket Message [](#usm-user-socket-message)
:::info 开源地址
:::
## 概述 [](#概述)
USM 是捷勃特（Agilebot）机器人 Socket 控制插件，基于 `Agilebot.Robot.SDK.A-2.0.0.0` 开发。
通过 TCP 字符串命令调用 Python SDK，实现对机器人寄存器、IO、程序、运动、报警、伺服等控制。
---
## 兼容 SDK 版本说明 [](#兼容sdk版本说明)
本插件使用 SDK 版本 **Agilebot.Robot.SDK.A-2.0.0.0** 开发，请确保您的机器人系统环境与此版本兼容。
---
## 打包说明 [](#打包说明)
插件开发完毕后，需要使用捷勃特插件打包工具进行打包。详细的打包与安装说明请参考：
[打包与安装文档](https://dev.svfactory.com/docs/extension/zh/02-development/04-package.html)
---
## 版本信息 [](#版本信息)
* 插件版本： `v1.0`
* SDK 版本： `Agilebot.Robot.SDK.A-2.0.0.0`
---
## 注意事项 [](#注意事项)
* 协议：TCP，UTF-8
* 命令格式： `command,arg1,arg2,...`
* 返回格式：成功 `OK[,data]` ，失败 `NG,error[,detail]`
* 命令名：**不区分大小写**
* 唯一大小写敏感参数： `program_start/stop/pause/resume` 的**程序名**
* 字段分隔：除特殊说明外均为**逗号分隔**
---
## 连接与响应 [](#连接与响应)
* 默认端口： `7000`
* 单客户端模式：已有连接时拒绝新连接（返回 `busy` ）
常见错误码：
* `not_connected`
* `invalid_args`
* `sdk_error`
* `internal_error`
* `unknown_command`
* `busy`
---
## 功能命令示例 [](#功能命令示例)
### 寄存器 [](#寄存器)
* `read_R` — 读 R 浮点寄存器。 例：发送 `read_R,5` → 回复 `OK,8.6`
* `write_R` — 写 R 寄存器。 例：发送 `write_R,5,10.5` → 回复 `OK`
* `delete_R` — 删 R 寄存器。 例：发送 `delete_R,5` → 回复 `OK`
* `read_MR` — 读 MR 整型寄存器。 例：发送 `read_MR,1` → 回复 `OK,100`
* `write_MR` — 写 MR 整型寄存器。 例：发送 `write_MR,1,200` → 回复 `OK`
* `delete_MR` — 删 MR 整型寄存器。 例：发送 `delete_MR,1` → 回复 `OK`
* `read_SR` — 读 SR 字符串寄存器。 例：发送 `read_SR,1` → 回复 `OK,hello`
* `write_SR` — 写 SR 字符串寄存器。 例：发送 `write_SR,1,hello` → 回复 `OK`
* `delete_SR` — 删 SR 字符串寄存器。 例：发送 `delete_SR,1` → 回复 `OK`
* `read_MH` — 读 MH 保持型寄存器。 例：发送 `read_MH,1` → 回复 `OK,100`
* `write_MH` — 写 MH 保持型寄存器。 例：发送 `write_MH,1,50` → 回复 `OK`
* `read_MI` — 读 MI 输入型寄存器。 例：发送 `read_MI,1` → 回复 `OK,50`
* `write_MI` — 写 MI 输入型寄存器。 例：发送 `write_MI,1,75` → 回复 `OK`
* `read_PR` — 读 PR 位姿（逗号分隔，格式： `OK,id,C/J,六个数` ）。 例：发送 `read_PR,5` → 回复 `OK,5,C,100.000,200.000,300.000,0.000,0.000,0.000`
* `write_PR` — 写 PR： `id,J/C,六个数` 。 例：发送 `write_PR,5,C,100,200,300,0,0,0` → 回复 `OK`
* `delete_PR` — 删 PR。 例：发送 `delete_PR,5` → 回复 `OK`
### IO [](#io)
* `read_DO` — 读 DO（ `ON/OFF` ）。 例：发送 `read_DO,1` → 回复 `OK,ON`
* `write_DO` — 写 DO。 例：发送 `write_DO,1,OFF` → 回复 `OK`
* `read_DI` — 读 DI。 例：发送 `read_DI,3` → 回复 `OK,OFF`
* `read_AO` — 读 AO（部分机型支持） 例：发送 `read_AO,2` → 回复 `OK,2048`
* `write_AO` — 写 AO（部分机型支持） 例：发送 `write_AO,2,1` → 回复 `OK`
* `read_AI` — 读 AI（部分机型支持） 例：发送 `read_AI,1` → 回复 `OK,3276`
### 程序与操作权 [](#程序与操作权)
* `program_start` — 启动程序（**程序名区分大小写**）。 例：发送 `program_start,test` → 回复 `OK`
* `program_stop` — 停止程序（**程序名区分大小写**）。 例：发送 `program_stop,test` → 回复 `OK`
* `program_pause` — 暂停程序（**程序名区分大小写**）。 例：发送 `program_pause,test` → 回复 `OK`
* `program_resume` — 恢复程序（**程序名区分大小写**）。 例：发送 `program_resume,test` → 回复 `OK`
* `program_list` — 列运行中程序（仅返回程序名称，多个用逗号分隔）。 例：发送 `program_list` → 回复 `OK,test,t`
* `program_prepare` — 程序启动前状态确认。 例：发送 `program_prepare` → 回复 `OK,soft_mode=ok`
* `acquire_access` — 获取 PC 操作权。 例：发送 `acquire_access` → 回复 `OK`
* `release_access` — 释放 PC 操作权。 例：发送 `release_access` → 回复 `OK`
### 运动 [](#运动)
* `move_joint` — 关节运动。 写法： `move_joint,J,j1,j2,j3,j4,j5,j6,vel,acc` / `move_joint,C,x,y,z,a,b,c,vel,acc` / `move_joint,PR,id[,vel,acc]` 。 说明： `vel` 必须 `xx%` （0-100%）， `acc` 必须 `xx%` （1-120%）。 例：发送 `move_joint,J,0,0,60,60,0,0,50%,100%` → 回复 `OK` 例：发送 `move_joint,C,0,0,60,60,0,0,50%,100%` → 回复 `OK` 例：发送 `move_joint,PR,1,50%,100%` → 回复 `OK`
* `move_line` — 直线运动。 写法： `move_line,J,j1,j2,j3,j4,j5,j6,vel,acc` / `move_line,C,x,y,z,a,b,c,vel,acc` / `move_line,PR,id[,vel,acc]` 。 说明： `vel` 单位 mm/s， `acc` 必须 `xx%` （1-120%）。 例：发送 `move_line,J,-63,127,-106,36,0,0,500,60%` → 回复 `OK` 例：发送 `move_line,C,0,0,60,60,0,0,500,60%` → 回复 `OK` 例：发送 `move_line,PR,1,500,60%` → 回复 `OK`
* `get_current_pose` — 当前位姿 J/C（逗号分隔）。 例：发送 `get_current_pose,J` → 回复 `OK,J,0.000,0.000,60.000,60.000,0.000,0.000`
### 点动 / 速度 / 坐标系 [](#点动-速度-坐标系)
* `jog_step` — 步进点动：（ `1` 代表 `+` ， `2` 代表 `-` ）。 例：发送 `jog_step,1,1,0.5` → 回复 `OK`
* `get_ovc` / `set_ovc` — 全局速度倍率（百分比）。 例：发送 `get_ovc` → 回复 `OK,100%` ；发送 `set_ovc,30%` → 回复 `OK`
* `get_oac` / `set_oac` — 全局加速度倍率。 例：发送 `get_oac` → 回复 `OK,100%`
* `get_tf` / `set_tf` — 工具坐标系编号（0-50）。 例：发送 `set_tf,2` → 回复 `OK`
* `get_uf` / `set_uf` — 用户坐标系编号（0-50）。 例：发送 `set_uf,1` → 回复 `OK`
* `get_tcs` / `set_tcs` — 参考坐标系。 `set_tcs` 支持： `JOINT/BASE/WORLD/UF/TF/RTCP_UF/RTCP_TF` （不区分大小写）。 例：发送 `set_tcs,WORLD` → 回复 `OK`
### 状态 [](#状态)
* `robot_status` — 机器人运行状态。 例：发送 `robot_status` → 回复 `OK,Robot idle`
* `ctrl_status` — 控制器状态。 例：发送 `ctrl_status` → 回复 `OK,Controller enabled`
* `servo_status` — 伺服状态。 例：发送 `servo_status` → 回复 `OK,Servo controller idle`
* `ready_check` — 启动前一键检查（alarm/robot/ctrl/servo/op/soft）。 例：发送 `ready_check` → 回复 `OK,alarm=none,robot=...,ctrl=...,servo=...,op=...,soft=...`
### 报警 [](#报警)
* `get_alarms` — 活动报警列表 例：发送 `get_alarms` → 依次回复： `OK,示教器急停按钮触发` 、 `OK,双通道安全板信号有不一致`
* `get_top_alarm` — 最高优先级报警 例：发送 `get_top_alarm` → 回复 `OK,示教器急停按钮触发`
### 伺服与急停 [](#伺服与急停)
* `servo_on` — 上使能。 例：发送 `servo_on` → 回复 `OK`
* `servo_off` — 下使能。 例：发送 `servo_off` → 回复 `OK`
* `servo_reset` — 伺服复位。 例：发送 `servo_reset` → 回复 `OK`
* `estop` — 急停。 例：发送 `estop` → 回复 `OK`
### 负载 [](#负载)
* `get_payload` — 当前负载，格式 `mass,x,y,z` （逗号分隔，三位小数）。 例：发送 `get_payload` → 回复 `OK,2.500,0.000,0.000,50.000`
---
## 常见现场问题 [](#常见现场问题)
* 示教器提示 “没有操作权”：检查是否已 `acquire_access` ，需要时 `release_access`
* NetAssist 乱码：接收编码改为 UTF-8
* `program_start` 报启动条件错误：先发 `program_prepare`
---
url: /zh/04-app-intro/07-background-process.html
title: 背景程序插件
---
# 背景程序插件 [](#背景程序插件)
:::info 开源地址
:::
## 概述 [](#概述)
背景程序插件是一个通用服务插件，为捷勃特机器人提供背景程序 I/O 信号处理功能。该插件通过 Web 界面实现对机器人 I/O 信号和寄存器的监控、配置和控制，支持可视化图形化编程，持续运行在机器人控制器中而不影响机器人主程序。
本插件支持信号触发信号、信号触发寄存器操作、寄存器间数据传递等复杂逻辑场景，通过积木块式的可视化编程界面，降低了用户使用门槛，提高了开发效率。
---
## 兼容 SDK 版本说明 [](#兼容sdk版本说明)
本插件使用 SDK 版本 **PYTHON\_v2.0.0.0** 开发，请确保您的机器人系统环境与此版本兼容。
---
## 打包说明 [](#打包说明)
插件开发完毕后，需要使用捷勃特插件打包工具进行打包。详细的打包与安装说明请参考：
[打包与安装文档](https://dev.svfactory.com/docs/extension/zh/02-development/04-package.html)
---
## 功能列表 [](#功能列表)
插件提供以下核心功能：
1. **I/O 信号实时监控** \- 实时监控数字量输入 / 输出信号状态
2. **寄存器操作** \- 支持 R、MH、MI 寄存器的读写和运算
3. **背景程序管理** \- 创建、编辑、删除、复制背景程序
4. **程序导入导出** \- 支持程序配置的导入导出（Web 模式 / U 盘模式）
5. **系统配置管理** \- 去抖滤波、信号订阅周期等系统参数配置
6. **实时状态监控** \- 系统日志、性能监控、程序运行状态实时显示
7. **多语言支持** \- 支持中文、英文、越南语、日语四种语言界面和日志翻译
8. **可视化编程增强积木** \- 组合触发 / 组合条件（AND/OR，可嵌套）：信号边沿、电平、寄存器、机器人模式、程序状态均为布尔值块，可用逻辑与 / 或组合
---
## 功能详细说明 [](#功能详细说明)
### 1\. I/O 信号实时监控 [](#1-io信号实时监控)
实时监控来自传感器、按钮、限位开关、光电开关等外部设备的输入信号，以及输出信号的状态。
**功能特性：**
* 自动获取机器人已配置的所有 IO 信号
* 按配置的周期订阅所有信号状态
* 实时显示信号状态（绿色 = 激活，灰色 = 非激活）
* 支持数字量输入（DI）和数字量输出（DO）
**界面位置：**
* 导航菜单：I/O 信号
* 输入信号区域：网格布局显示所有 DI 信号
* 输出信号区域：网格布局显示所有 DO 信号
---
### 2\. 寄存器操作 [](#2-寄存器操作)
支持对机器人各种寄存器的读写和运算操作，包括数值寄存器、位置寄存器、字符串寄存器等。
**支持的寄存器类型：**
* **R 寄存器**：浮点型数值寄存器（读写、运算）
* **MH 寄存器**：整型寄存器（读写、运算）
* **MI 寄存器**：整型寄存器（读写、运算）
**操作类型：**
* **读取**：读取寄存器当前值
* **写入**：设置寄存器为指定值
* **运算**：加法、减法、乘法、除法
* **传递**：将一个寄存器的值复制到另一个寄存器
---
### 4\. 背景程序管理 [](#4-背景程序管理)
创建、编辑、删除、复制背景程序，支持程序列表管理和程序状态控制。
**功能特性：**
* **程序列表**：显示所有已保存的背景程序
* 显示程序名称、状态、最后修改时间
* 支持程序搜索（按名称过滤）
* 按最后修改时间排序（最近修改的在上）
* **程序操作**：
* 新建程序：创建新的背景程序
* 编辑程序：修改现有程序
* 删除程序：删除不需要的程序
* 复制程序：复制现有程序创建副本
* **程序状态**：
* 运行中：程序正在执行
* 已停止：程序已停止
* **程序格子**：概览页显示最多 9 个活跃程序
* 显示程序名称、运行状态、周期时间
* 支持单个程序启动 / 停止
* 支持多选批量操作
**界面位置：**
* 导航菜单：背景程序
* 程序列表：显示所有已保存的程序
* 程序格子：概览页显示活跃程序运行状态
---
### 4\. 程序导入导出 [](#4-程序导入导出)
支持程序配置的导入导出功能，方便程序备份、迁移和共享。
**导出功能：**
* **Web 模式**（PC / 协作机器人）：
* 选择要导出的程序（勾选复选框）
* 点击 "导出" 按钮
* 浏览器自动下载 zip 压缩文件
* **USB 模式**（工业机器人示教器）：
* 选择要导出的程序（勾选复选框）
* 点击 "导出" 按钮
* 程序自动保存到 U 盘 `/mnt/udisk/background_programs/` 目录
**导入功能：**
* **Web 模式**（PC / 协作机器人）：
* 点击 "导入" 按钮
* 选择 zip 文件上传
* 系统自动检测冲突并提示选择处理方式
* **USB 模式**（工业机器人示教器）：
* 点击 "导入" 按钮
* 从 U 盘文件列表中选择 zip 文件
* 系统自动检测冲突并提示选择处理方式
**冲突处理：** 导入时如果检测到重名程序，系统会显示冲突对话框，为每个冲突提供三种处理方式：
* **跳过**：不导入该程序，保留现有程序
* **覆盖**：用导入的程序覆盖现有程序
* **重命名**：自动重命名为 `原程序名_1` 、 `原程序名_2` 等（自动查找可用编号）
---
### 5\. 系统配置管理 [](#5-系统配置管理)
管理系统参数配置，包括去抖滤波、信号订阅周期等设置。
**系统参数：**
* **去抖滤波**：信号去抖延时时间（0-1000ms）
* 默认值：50ms
* 最小值：0ms（不去抖）
* 最大值：1000ms
* **信号订阅周期**：信号状态订阅周期（30-1000ms）
* 默认值：50ms
* 最小值：30ms
* 最大值：1000ms
**配置方法：**
1. 进入 "系统设置" 页面
2. 调整参数滑块或输入框
3. 点击 "保存参数" 按钮保存配置
4. 配置会自动保存到 `data/config/system.json` 文件
---
### 6\. 实时状态监控 [](#6-实时状态监控)
实时显示系统运行状态、日志信息、性能监控数据和程序运行状态。
**系统日志：**
* 实时显示系统启动日志、规则执行日志、错误和警告信息
* 终端风格显示（深色背景，绿色文字）
* 自动保存到本地日志文件（ `data/logs/` 目录）
* 支持日志轮转（单个文件最大 10MB，文件夹最大 100MB）
**性能监控：**
* CPU 占用率（后端进程）
* 内存占用（后端进程）
* 实时更新显示
**程序运行状态：**
* 显示最多 9 个活跃程序的运行状态
* 每个程序显示：程序名称、运行状态、周期时间
* 支持单个程序启动 / 停止操作
* 支持多选批量操作
**界面位置：**
* 导航菜单：概览
* 系统日志区域：实时日志显示
* 性能监控区域：CPU 和内存占用
* 活跃程序运行状态区域：9 个格子布局
---
### 7\. 多语言支持 [](#7-多语言支持)
插件支持多语言界面和日志翻译功能，提供更好的国际化体验。
**支持的语言：**
* **中文（简体）** \- 默认语言
* **English** \- 英文
* **Tiếng Việt** \- 越南语
* **日本語** \- 日语
**功能特性：**
* **界面多语言**：
* 所有 UI 元素（按钮、标签、菜单等）支持多语言切换
* Blockly 可视化编程积木块支持多语言
* 事件日志、程序列表等动态内容支持多语言
* **日志翻译**：
* 系统日志支持后端翻译，根据用户选择的语言显示翻译后的日志
* 本地日志文件保持中文不变，便于技术人员查看
* 实时日志推送时根据用户语言偏好自动翻译
* 历史日志查询时支持语言参数
**使用方法：**
1. 点击界面右上角的语言切换按钮（地球图标）
2. 从下拉菜单中选择目标语言
3. 界面和日志会自动切换到所选语言
---
## 典型使用场景 [](#典型使用场景)
### 场景 1：信号触发信号 [](#场景1信号触发信号)
当收到一个或多个输入信号时，立即输出一个或多个信号。
**示例：**
* 安全门打开时（DI\_1=ON），立即关闭输出（DO\_1=OFF）
* 启动按钮按下（DI\_2 上升沿），启动指示灯（DO\_2=ON）
**实现方法：**
1. 创建背景程序
2. 设置触发条件：DI\_1=ON 或 DI\_2 上升沿
3. 设置动作：DO\_1=OFF 或 DO\_2=ON
4. 保存并启动程序
---
### 场景 2：信号触发寄存器运算 [](#场景2信号触发寄存器运算)
当收到信号时，对寄存器进行数值运算。
**示例：**
* 收到计数信号（DI\_2 上升沿）时，将计数器寄存器（MR\_1）加 1
* 收到复位信号（DI\_3=ON）时，将位置寄存器（PR\_1）设置为初始值
**实现方法：**
1. 创建背景程序
2. 设置触发条件：DI\_2 上升沿 或 DI\_3=ON
3. 设置动作：MR\_1 = MR\_1 + 1 或 PR\_1 = 初始值
4. 保存并启动程序
---
### 场景 3：寄存器数据传递 [](#场景3寄存器数据传递)
信号触发时，读取一个寄存器的值并写入另一个寄存器。
**示例：**
* 收到同步信号（DI\_4 上升沿）时，将 R \[1\] 的值复制到 R \[2\]
**实现方法：**
1. 创建背景程序
2. 设置触发条件：DI\_4 上升沿
3. 设置动作：R \[2\] = R \[1\]
4. 保存并启动程序
---
### 场景 4：复合逻辑判断 [](#场景4复合逻辑判断)
多个信号组合判断后执行动作。
**示例：**
* 当 DI\_1=ON 且 DI\_2=OFF 时，执行寄存器运算和信号输出
**实现方法：**
1. 创建背景程序
2. 设置触发条件：DI\_1=ON 且 DI\_2=OFF
3. 设置动作序列：寄存器运算 + 信号输出
4. 保存并启动程序
---
## 注意事项 [](#注意事项)
1. **SDK 连接**：
* 确保机器人控制器已启动并可以连接
* SDK 连接断开时会自动重连
* 连接失败时系统会记录错误日志
2. **程序数量限制**：
* 最多同时运行 9 个背景程序
* 程序总数无限制
3. **文件存储**：
* 程序配置文件保存在 `data/rules/` 目录
* 系统配置文件保存在 `data/config/` 目录
* 日志文件保存在 `data/logs/` 目录（自动轮转）
* 事件日志保存在 `data/events/` 目录
4. **性能优化**：
* 信号订阅周期建议设置为 50-100ms
* 去抖滤波根据实际信号特性设置
* 避免创建过于复杂的程序逻辑
5. **导入导出**：
* 导出文件为 zip 格式
* 导入时会检测冲突，请仔细选择处理方式
* USB 模式需要确保 U 盘已正确挂载，且仅支持 FAT32 磁盘格式
6. **日志管理**：
* 日志文件自动轮转（单个文件最大 10MB）
* 日志文件夹自动清理（最大 100MB）
* 日志文件按时间戳命名
---
## 更新日志 [](#更新日志)
### V1.4.0 (2026-01-16) [](#v140-2026-01-16)
* **新增多语言支持**：
* 支持中文、英文、越南语、日语四种语言界面
* 所有 UI 元素、Blockly 积木块、事件日志等支持多语言切换
* 系统日志支持后端翻译，根据用户语言偏好显示翻译后的日志
* 本地日志文件保持中文不变
* 实时日志推送时根据连接的语言偏好自动翻译
* **界面优化**：
* 添加语言切换按钮（地球图标）
* 优化语言切换交互体验
* 语言偏好自动保存和恢复
### V1.0.0 (2025-12-29) [](#v100-2025-12-29)
* 初始版本发布
* 支持 SDK 2.0.0.0
* 实现 I/O 信号实时监控（SubPub 订阅机制）
* 实现信号去抖滤波和订阅周期配置
* 实现寄存器操作（R、MR、PR、SR、MH、MI）
* 实现背景程序管理（创建、编辑、删除、复制）
* 实现程序导入导出功能（Web 模式 / USB 模式）
* 实现系统配置管理
* 实现实时状态监控（系统日志、性能监控、程序运行状态）
* 支持程序搜索和排序
* 支持日志轮转和自动清理
---
---
url: /zh/04-app-intro/08-custom-instructions.html
title: 用户自定义指令插件
---
# 用户自定义指令插件 [](#用户自定义指令插件)
:::info 开源地址
:::
---
**版本 V1.4 | 更新日期：2026 年 3 月 25 日**
## 概述 [](#概述)
**CM（Custom Module）** 是一个用户自定义指令插件，为捷勃特机器人提供了一系列实用的自定义指令。
---
## 版本说明 [](#版本说明)
本插件提供两个版本，分别对应不同的 SDK 版本：
### SDK v1.7.1.3 版本 [](#sdk-v1713-版本)
* **目录：** `CoordinateModifier（SDKV1.7.1.3）/`
* **主文件：** `CM_oldsdk.py`
* **兼容 SDK：** Python SDK v1.7.1.3
* **兼容机器人软件版本：**
* Copper v7.6.X.X
* Bronze v7.6.X.X
### SDK v2.0.0.0 版本 [](#sdk-v2000-版本)
* **目录：** `CoordinateModifier（SDKV2.0.0.0）/`
* **主文件：** `CM.py`
* **兼容 SDK：** Python SDK v2.0.0.0
* **兼容机器人软件版本：**
* Copper v7.7.X.X
* Bronze v7.7.X.X
### 版本选择建议 [](#版本选择建议)
* **使用 SDK v1.7.1.3 版本：** 如果您的机器人软件版本为 v7.6.X.X
* **使用 SDK v2.0.0.0 版本：** 如果您的机器人软件版本为 v7.7.X.X 或更高
**注意：** 请根据您的机器人软件版本选择对应的插件版本，确保 SDK 版本与机器人软件版本兼容。
---
## 打包说明 [](#打包说明)
插件开发完毕后，需要使用捷勃特插件打包工具进行打包。详细的打包与安装说明请参考：
[📦 打包与安装文档](https://dev.svfactory.com/docs/extension/zh/02-development/04-package.html)
---
## 功能列表 [](#功能列表)
插件提供以下 13 个自定义指令：
1. **SetTF** \- 设置工具坐标系参数（直接数值）
2. **SetUF** \- 设置用户坐标系参数（直接数值）
3. **SetTF\_R** \- 从 R 寄存器读取值设置工具坐标系参数
4. **SetUF\_R** \- 从 R 寄存器读取值设置用户坐标系参数
5. **SetTF\_PR** \- 从 PR 寄存器读取完整位姿设置工具坐标系
6. **SetUF\_PR** \- 从 PR 寄存器读取完整位姿设置用户坐标系
7. **Incr** \- R 寄存器自增
8. **Decr** \- R 寄存器自减
9. **Strp** \- 拆解字符串数据到 PR 寄存器
10. **TFShift** \- 工具坐标系补正（基于视觉反馈）
11. **DecToHex** \- 从十进制转换为十六进制
12. **TurnCountToR** \- 将 PR 位姿回转数写入 R 寄存器（单轴）
13. **RToTurnCount** \- 将 R 寄存器回写到 PR 位姿回转数（单轴）
---
## 指令详细说明 [](#指令详细说明)
### 1\. SetTF - 设置工具坐标系参数（直接数值） [](#1-settf-设置工具坐标系参数直接数值)
直接通过数值设置工具坐标系的指定参数。
**参数：**
* `ID` (int): 工具坐标系 ID 号（1-30）
* `Pos` (int): 位置参数编号（1-6）
* 1: X 坐标（单位：mm）
* 2: Y 坐标（单位：mm）
* 3: Z 坐标（单位：mm）
* 4: A 角度（单位：度）
* 5: B 角度（单位：度）
* 6: C 角度（单位：度）
* `Value` (float): 参数值
**示例：**
```
CALL_SERVICE CM, Set TF, ID=1, Pos=1, Value=111.11
```
---
### 2\. SetUF - 设置用户坐标系参数（直接数值） [](#2-setuf-设置用户坐标系参数直接数值)
直接通过数值设置用户坐标系的指定参数。
**参数：**
* `ID` (int): 用户坐标系 ID 号（1-30）
* `Pos` (int): 位置参数编号（1-6）
* `Value` (float): 参数值
**示例：**
```
CALL_SERVICE CM, SetUF, ID=1, Pos=1, Value=222.354
```
---
### 3\. SetTF\_R - 从 R 寄存器读取值设置工具坐标系参数 [](#3-settf%5Fr-从r寄存器读取值设置工具坐标系参数)
从指定的 R 寄存器读取数值，并设置到工具坐标系的指定参数。
**参数：**
* `ID` (int): 工具坐标系 ID 号（1-30）
* `Pos` (int): 位置参数编号（1-6）
* `R_ID` (int): R 寄存器编号
**示例：**
```
CALL_SERVICE CM, Set TF_R, ID=3, Pos=1, R_ID=1
```
---
### 4\. SetUF\_R - 从 R 寄存器读取值设置用户坐标系参数 [](#4-setuf%5Fr-从r寄存器读取值设置用户坐标系参数)
从指定的 R 寄存器读取数值，并设置到用户坐标系的指定参数。
**参数：**
* `ID` (int): 用户坐标系 ID 号（1-30）
* `Pos` (int): 位置参数编号（1-6）
* `R_ID` (int): R 寄存器编号
**示例：**
```
CALL_SERVICE CM, SetUF_R, ID=3, Pos=1, R_ID=1
```
---
### 5\. SetTF\_PR - 从 PR 寄存器读取完整位姿设置工具坐标系 [](#5-settf%5Fpr-从pr寄存器读取完整位姿设置工具坐标系)
从指定的 PR 寄存器读取完整的位姿信息（X、Y、Z、A、B、C），并一次性设置到工具坐标系。
**参数：**
* `ID` (int): 工具坐标系 ID 号（1-30）
* `PR_ID` (int): PR 寄存器编号
**示例：**
```
CALL_SERVICE CM, Set TF_PR, ID=2, PR_ID=1
```
---
### 6\. SetUF\_PR - 从 PR 寄存器读取完整位姿设置用户坐标系 [](#6-setuf%5Fpr-从pr寄存器读取完整位姿设置用户坐标系)
从指定的 PR 寄存器读取完整的位姿信息，并一次性设置到用户坐标系。
**参数：**
* `ID` (int): 用户坐标系 ID 号（1-30）
* `PR_ID` (int): PR 寄存器编号
**示例：**
```
CALL_SERVICE CM, SetUF_PR, ID=2, PR_ID=2
```
---
### 7\. Incr - R 寄存器自增 [](#7-incr-r寄存器自增)
将指定 R 寄存器的值增加指定的步长。
**参数：**
* `R_ID` (int): R 寄存器编号
* `Step` (float): 自增步长，默认为 1.0
**示例：**
```
CALL_SERVICE CM, Incr, R_ID=2, Step=1
```
---
### 8\. Decr - R 寄存器自减 [](#8-decr-r寄存器自减)
将指定 R 寄存器的值减少指定的步长。
**参数：**
* `R_ID` (int): R 寄存器编号
* `Step` (float): 自减步长，默认为 1.0
**示例：**
```
CALL_SERVICE CM, Decr, R_ID=1, Step=1
```
---
### 9\. Strp - 拆解字符串数据到 PR 寄存器 [](#9-strp-拆解字符串数据到pr寄存器)
从 SR 寄存器读取字符串数据，拆解后写入 PR 寄存器。
**参数：**
* `SR_ID` (int): 字符串寄存器编号
* `R_ID_Status` (int): R 寄存器编号，用于输出物料检测状态（1 = 有物料，0 = 无物料）
* `PR_ID` (int): PR 寄存器起始编号
* `R_ID_Error` (int): R 寄存器编号，用于输出错误状态码（0 = 正确，1 = 错误）
**数据格式：**
* SR 寄存器格式：状态位，数据 1, 数据 2, 数据 3,...
* 状态位：0 = 无物料，1 = 有物料
* 数据映射关系：数据 1→PR 的 X 坐标，数据 2→PR 的 Y 坐标，数据 3→PR 的 C 角度
* 支持分隔符：逗号、分号、竖线、制表符、空格等（自动检测）
* 每个 PR 寄存器存储 6 个分量（X,Y,Z,A,B,C），其中 Z、A、B 保留原值不变
**状态码说明：**
* `R_ID_Status` ：物料检测状态（1 = 有物料，0 = 无物料）
* `R_ID_Error` ：错误状态码（0 = 正确，1 = 错误）
* 状态位 = 0（无物料）→ R\_ID\_Status=0, R\_ID\_Error=1（错误）
* 状态位 = 1 且数据格式正确 → R\_ID\_Status=1, R\_ID\_Error=0（正确）
* 状态位 = 1 但数据格式错误 → R\_ID\_Status=1, R\_ID\_Error=1（格式错误）
**示例：**
```
SR[1] = "1,100.5,200.3,45.0"
// 说明：状态位=1（有物料），数据1=100.5（X坐标），数据2=200.3（Y坐标），数据3=45.0（C角度）
// 执行后：PR[1].x=100.5, PR[1].y=200.3, PR[1].c=45.0（Z、A、B保留原值）
CALL_SERVICE CM, Strp, SR_ID=1, R_ID_Status=1, PR_ID=1, R_ID_Error=2
```
---
### 10\. TFShift - 工具坐标系补正（基于视觉反馈 Eye-to-Hand） [](#10-tfshift-工具坐标系补正基于视觉反馈eye-to-hand)
通过读取不同的视觉目标点偏差与基准视觉位置的偏差，来计算工具坐标系的相对偏差，从而将偏差输出在工具坐标系中。
**参数：**
* `InputTF_ID` (int): 基准标定坐标系编号（1-30），默认 1
* `ResultTF_ID` (int): 最终算法计算后写入的坐标系编号（1-30），默认 3
* `CamPose_ID` (int): 拍照点 PR 寄存器编号，默认 60
* `RefVis_ID` (int): 基准视觉模板数据 PR 寄存器编号，默认 61（需要手动写入）
* `ActVis_ID` (int): 视觉输出的实际坐标数据 PR 寄存器编号，默认 62（需要手动写入）
**示例：**
```
// 假设：
// - TF[1] 为基准标定坐标系
// - PR[60] 存储拍照点位姿
// - PR[61] 存储基准视觉模板数据（需要手动写入）
// - PR[62] 存储实际视觉坐标数据（需要手动写入）
// - TF[3] 为计算结果输出坐标系
CALL_SERVICE CM, TFShift, InputTF_ID=1, ResultTF_ID=3, CamPose_ID=60, RefVis_ID=61, ActVis_ID=62
```
**工作原理：**
1. 读取基准工具坐标系（InputTF\_ID）的位姿数据
2. 读取拍照点位姿（CamPose\_ID）PR 寄存器数据
3. 读取基准视觉模板数据（RefVis\_ID）PR 寄存器数据
4. 读取实际视觉坐标数据（ActVis\_ID）PR 寄存器数据
5. 通过坐标变换矩阵计算工具坐标系的相对偏差
6. 将计算结果写入结果工具坐标系（ResultTF\_ID）
**注意事项：**
* 所有 PR 寄存器必须在使用前手动创建并写入正确的位姿数据
* 基准视觉模板数据（RefVis\_ID）和实际视觉坐标数据（ActVis\_ID）需要根据视觉系统输出手动写入对应的 PR 寄存器
* 计算结果会自动进行误差验证，并在日志中输出误差分析信息
* 工具坐标系 ID 必须在 1-30 之间
---
### 11\. DecToHex - 从十进制转换为十六进制 [](#11-dectohex-从十进制转换为十六进制)
将 R 寄存器中的十进制数值转换为十六进制字符串，并写入 SR 寄存器。
**参数：**
* `R_ID` (int): R 寄存器编号，包含需要转换的十进制数（支持整数和浮点数）
* `SR_ID` (int): SR 寄存器编号，用于保存转换后的十六进制字符串
**转换规则：**
1. 浮点数处理：截断（直接丢弃小数部分，不四舍五入）
2. 数值范围：32 位整数（-2147483648 到 2147483647）
3. 负数处理：使用 32 位补码形式表示
4. 输出格式：固定 8 位十六进制字符串（大写，不足 8 位前面补零）
**示例：**
```
// 示例1：正数转换
R[1] = 255
CALL_SERVICE CM, DecToHex, R_ID=1, SR_ID=1
// 结果：SR[1] = "000000FF"
// 示例2：浮点数截断
R[1] = 255.99
CALL_SERVICE CM, DecToHex, R_ID=1, SR_ID=1
// 结果：SR[1] = "000000FF"（截断为255）
// 示例3：负数转换（32位补码）
R[1] = -1
CALL_SERVICE CM, DecToHex, R_ID=1, SR_ID=1
// 结果：SR[1] = "FFFFFFFF"
// 示例4：负数转换
R[1] = -255
CALL_SERVICE CM, DecToHex, R_ID=1, SR_ID=1
// 结果：SR[1] = "FFFFFF01"
// 示例5：零值
R[1] = 0
CALL_SERVICE CM, DecToHex, R_ID=1, SR_ID=1
// 结果：SR[1] = "00000000"
```
**注意事项：**
* R 寄存器中的浮点数会被截断为整数（不四舍五入）
* 数值必须在 32 位整数范围内（-2147483648 到 2147483647）
* 负数使用 32 位补码形式表示
* 输出始终为 8 位大写十六进制字符串，不足 8 位前面补零
---
### 12\. TurnCountToR - 将 PR 位姿回转数写入 R 寄存器（单轴） [](#12-turncounttor-将pr位姿回转数写入r寄存器单轴)
读取指定 `PR_ID` 寄存器中的 `turnCircle` （回转数），并只写入一个指定轴（ `Joint_ID` ）到 `R[R_ID]` 。
**参数：**
* `PR_ID` (int): PR 寄存器编号，读取其姿态中的 `turnCircle`
* `R_ID` (int): R 寄存器编号（单个 R）
* `Joint_ID` (int): 需要写入的关节轴（1=J1, 2=J2, ..., 6=J6）
**数据规则：**
* 仅允许写入值 `-1 / 0 / 1`
* 只替换指定轴的回转标记，不涉及其它轴
**示例：**
```
CALL_SERVICE CM, TurnCountToR, PR_ID=10, R_ID=100, Joint_ID=3
```
---
### 13\. RToTurnCount - 将 R 寄存器回写到 PR 位姿回转数（单轴） [](#13-rtoturncount-将r寄存器回写到pr位姿回转数单轴)
从 `R[R_ID]` 读取值，校验后只写回 `PR_ID` 的指定轴（ `Joint_ID` ）回转标记。
**参数：**
* `PR_ID` (int): PR 寄存器编号，写入其姿态中的 `turnCircle`
* `R_ID` (int): R 寄存器编号（单个 R）
* `Joint_ID` (int): 需要回写的关节轴（1=J1, 2=J2, ..., 6=J6）
**数据规则：**
* R 寄存器值必须为整数，且仅允许 `-1 / 0 / 1`
* 只替换指定轴，其它轴保持不变
**示例：**
```
CALL_SERVICE CM, RToTurnCount, PR_ID=10, R_ID=100, Joint_ID=3
```
---
## 关键项 [](#关键项)
### 核心特性 [](#核心特性)
* \*\* 长连接机制：\*\* 自动管理机器人连接，首次调用时自动连接，已连接时复用现有连接
* \*\* 自动寄存器创建：\*\*Strp 指令支持自动创建 R 寄存器（如果不存在），PR 寄存器需要手动创建
* \*\* 数据验证：\*\* 所有指令都包含完整的参数验证和错误处理
* \*\* 精度控制：\*\* 坐标系参数值自动保留三位小数
* \*\* 分隔符自动检测：\*\*Strp 指令支持自动检测多种分隔符（逗号、分号、竖线、制表符、空格等）
* \*\* 回转数同步：\*\* 支持 PR `turnCircle` 与 R 寄存器双向同步（ `TurnCountToR` / `RToTurnCount` ，单轴替换）
---
## 使用方法 [](#使用方法)
1. 打开 应用 - 插件管理 ，点击右上角的 安装插件 按钮。
图片
1. 安装 CM\_oldsdk.gbtapp
图片
1. 在 简单服务 类别中启用 CM\_oldsdk.gbtapp
图片
1. 在建好的程序 test 里面插入插件指令，这里以更改 TF1 的 X 值举例，运行程序，可以看到 TF 的 X 值已被更改，其他的指令参照 readme。
图片
图片
图片
## 注意事项 [](#注意事项)
### 重要提示 [](#重要提示)
1. \*\* 坐标系 ID 范围：\*\*ID 必须在 1-30 之间，0 是基础坐标系不可修改
2. \*\* 参数编号：\*\* 位置参数编号必须在 1-6 之间（1=X, 2=Y, 3=Z, 4=A, 5=B, 6=C）
3. \*\* 寄存器存在性：\*\* 使用 R 寄存器或 PR 寄存器前，建议确保寄存器已创建（Strp 指令支持自动创建 R 寄存器）
4. \*\* 连接状态：\*\* 确保机器人已正确连接且可访问，插件会自动管理连接
5. \*\* 数据类型：\*\* 所有数值参数会自动进行类型转换和验证
6. **Strp 指令特殊说明：**
* PR 寄存器需要手动创建，使用前请确保 PR 寄存器已存在
* R\_ID\_Status 和 R\_ID\_Error 寄存器如果不存在会自动创建
* 状态位为 0 时，不会进行数据拆解，直接返回错误（R\_ID\_Status=0, R\_ID\_Error=1）
* 写入 PR 寄存器后会立即验证数据是否正确写入
* 建议在使用前检查 R\_ID\_Status 和 R\_ID\_Error 的值来判断执行结果
7. \*\* 错误处理：\*\* 所有指令返回字典格式，包含 success、message/error 字段，建议始终检查 success 字段
8. **回转数约束：** `TurnCountToR` 与 `RToTurnCount` 仅支持 `-1/0/1` ，用于轴回转标记同步
---
## 版本历史 [](#版本历史)
### V1.4 (2026 年 3 月 25 日) [](#v14-2026年3月25日)
* 新增 **TurnCountToR** 指令：将 PR 寄存器中的回转数（turnCircle）写入 R 寄存器
* 新增 **RToTurnCount** 指令：将 R 寄存器中的回转数回写到 PR 寄存器
* 增强回转数数据校验：仅允许 `-1/0/1`
* 将 **TurnCountToR** / **RToTurnCount** 调整为 “单轴替换” 模式：每次只更新一个轴，新增 `Joint_ID` 指定 J1\~J6
* 回转数同步仍仅支持 `-1/0/1`
### V1.3 (2026 年 1 月 12 日) [](#v13-2026年1月12日)
* 新增 **DecToHex** 指令：从十进制转换为十六进制
* 支持将 R 寄存器中的十进制数值转换为 32 位十六进制字符串
* 支持浮点数截断、负数补码转换
* 输出固定 8 位大写十六进制格式
### V1.2 (2026 年 1 月 9 日) [](#v12-2026年1月9日)
* 新增 **TFShift** 指令：工具坐标系补正（基于视觉反馈）
* 支持通过视觉反馈自动计算和更新工具坐标系
* 提供高精度坐标变换计算，支持误差验证
### V1.1 (2026 年 1 月 9 日) [](#v11-2026年1月9日)
* 新增 SDK v2.0.0.0 版本支持
* 更新坐标系接口：使用 `coordinate_system.TF/UF` 子类
* 更新坐标系数据结构：使用 `coordinate.data.x/y/z/a/b/c`
* 更新连接状态检查： `is_connect()` → `is_connected()`
* 更新错误处理：使用 `ret.errmsg` 获取错误信息
* 更新 Extension 使用方式：支持独立实例化获取 IP 地址
---
**CM 用户自定义指令插件 | 版本 V1.4 | 更新日期：2026 年 3 月 25 日 | © 2026**
---
url: /zh/01-intro/
title: 基本介绍
---
# 基本介绍 [](#基本介绍)
---
url: /zh/02-development/02-quick-start/
title: 入门教程
---
# 入门教程 [](#入门教程)
---
url: /zh/02-development/03-advanced/
title: 高级教程
---
# 高级教程 [](#高级教程)
---
url: /zh/02-development/
title: 开发
---
# 开发 [](#开发)
---
url: /zh/03-detailed-case/
title: 具体案例
---
# 具体案例 [](#具体案例)
---
url: /zh/04-app-intro/
title: 插件应用介绍
---
# 插件应用介绍 [](#插件应用介绍)
---
url: /zh/
title: Extension
---
# Extension捷勃特机器人插件系统
插件系统是捷勃特机器人提供的软件二次开发平台，让您聚焦自身业务场景，打破了传统机器人功能固化的局限，通过平台提供的模块化组件及接口（如运动控制指令、寄存器调用接口、UI 交互组件等）快速搭建属于自己的应用框架。
获取您所需的代码示例、指南等参考资料，利用这些资源，可以更快、更高质量地开发您的插件应用。
[立即开始](./01-intro/01-about.html)
## 功能介绍
覆盖前端界面、轻量后端和通用服务三条开发路径，帮助你按业务复杂度快速起步。
[Web小程序通过 Web 技术（HTML、CSS、JavaScript）轻松创建并嵌入 Web 前端界面。了解更多](./02-development/02-quick-start/01-web-mini-program)[简单服务通过简单的 Python 方法快速实现后端功能，便捷地与系统进行交互。了解更多](./02-development/02-quick-start/02-easy-service)[通用服务使用您喜欢的 Python 框架开发复杂的后端服务，支持数据处理、逻辑计算和外部系统交互。了解更多](./02-development/02-quick-start/03-general-service)
## 应用商店
直接查看可运行案例，快速理解插件能力如何落到具体设备与业务场景。
全部8夹爪控制2网络通信2力控算法1工艺规划1后台逻辑1指令扩展1
[夹爪控制**RM**增广夹爪提供即插即用的驱动及界面，实现高精度、低延迟的开合控制。查看详情](./04-app-intro/02-rm-gripper)[夹爪控制**HITBOT**慧灵夹爪提供即插即用的驱动及界面，实现高精度、低延迟的开合控制。查看详情](./04-app-intro/04-hitbot-z-erg-20c)[网络通信**SOCKET**Socket通讯（JSON）实现机器人与PLC、视觉系统及上位机的稳定SOCKET通讯查看详情](./04-app-intro/03-socket)[网络通信**USM**USM Socket控制通过TCP字符串命令统一控制机器人寄存器、IO、运动、报警与伺服。查看详情](./04-app-intro/06-usm)[力控算法**FORCE**恒力控制实时控制保持末端恒力，确保工艺质量一致性查看详情](./04-app-intro/01-force-control)[工艺规划**AUTOPLAN**智能摆盘自动计算摆盘点位，灵活的配方设置，大幅简化编程流程查看详情](./04-app-intro/05-autoplan)[后台逻辑**BGPROC**背景程序Web可视化编程实现I/O与寄存器常驻监控及触发逻辑，独立于主程序运行。查看详情](./04-app-intro/07-background-process)[指令扩展**CM**自定义指令提供坐标系设置、寄存器运算、视觉补正等13条自定义指令，扩展机器人编程能力。查看详情](./04-app-intro/08-custom-instructions)