---
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` 指定的端口。
* 否则，系统无法检测到该端口的监听状态，会在检测超时后（默认约 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 保持一致的风格，我们提供了一些常用函数用于展示通知消息和弹框。
```ts
import {
rtmNotification
,
rtmMessageBox
} from '@agilebot/extension-runtime';
// 显示信息通知
rtmNotification
.
info
('这是一个信息消息');
// 显示错误通知
rtmNotification
.
error
('这是一个错误消息');
// 显示成功通知
rtmNotification
.
success
('操作成功');
// 显示警告通知
rtmNotification
.
warning
('这是一个警告消息');
// 显示确认对话框
rtmMessageBox
.
confirm
('您确定要删除吗？')
.
then
(() => {
console
.
log
('用户确认了操作');
})
.
catch
(() => {
console
.
log
('用户取消了操作');
});
```
## 获取插件的状态 [](#获取插件的状态)
您可以通过以下方式获取某个插件的当前状态：
```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` 等）进行日志输出，插件管理界面同样支持展示。
> 以下是插件管理界面中日志展示的截图：
## 在线编辑 [](#在线编辑)
所有插件类型都支持在线编辑，允许用户直接在插件管理界面中修改插件代码，并保存更改。
点击 “保存” 按钮后，后台服务将自动重启以应用更新内容。
---
url: /zh/02-development/03-advanced/06-ai-coding.html
title: AI 编程支持
---
# AI 编程支持 [](#ai-编程支持)
本文档介绍如何使用 AI 辅助工具（如 CodeBuddy、Codex、Cursor 等）快速开发机器人插件。
## 准备工作 [](#准备工作)
使用 AI 编程前，需要准备参考文档：
* **SDK 文档**：
* **插件开发文档**：
> **提示**：如果您使用的 AI Agent 无法很好地读取 URL，建议将以上两个 txt 文档下载到本地项目目录中，然后在 prompt 中引用本地文件路径。
## 示例 Prompt [](#示例-prompt)
以下是一个完整的示例，用于创建一个显示机器人状态的通用服务插件：
```
阅读以下文档，写一个通用服务插件，包含前端页面，显示机器人的当前位置、坐标系编号、伺服状态等信息。
参考资料：
SDK文档：https://dev.sh-agilebot.com/docs/sdk/knowledge/docs.txt
插件文档：https://dev.sh-agilebot.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 包，可以通过界面上的 `环境信息` 按钮查看。
## 安装额外的 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.sh-agilebot.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\_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
```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
* 版本：0.1
* 增广夹爪 Web
* 名称：rm-gripper-web
* 版本：0.1
## 品牌官网链接 [](#品牌官网链接)
## 安装指南 [](#安装指南)
* 系统要求 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 |
### 操作视频 [](#操作视频)
#### 扫描设备 [](#扫描设备)
#### 指令动作 [](#指令动作)
---
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/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.html)
[⚡简单服务通过简单的 Python 方法快速实现后端功能，便捷地与系统进行交互。了解更多 ](./02-development/02-quick-start/02-easy-service.html)
[🔧通用服务使用您喜欢的 Python 框架开发复杂的后端服务，支持数据处理、逻辑计算和外部系统交互。了解更多 ](./02-development/02-quick-start/03-general-service.html)