Update project and configurations
This commit is contained in:
Zou-Seay
473
docs/DBUS_API.md
Normal file
473
docs/DBUS_API.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# 线切割控制系统 DBus 接口说明文档
|
||||
|
||||
## 基本信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| **服务名** | `com.wirecut.service` |
|
||||
| **对象路径** | `/com/wirecut/control` |
|
||||
| **接口名** | `com.wirecut.IControl` |
|
||||
| **总线类型** | System Bus（系统总线） |
|
||||
| **设计用途** | 供"小龙虾"等外部程序对接线切割控制系统 |
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [运动控制接口](#1-运动控制接口)
|
||||
2. [加工参数接口](#2-加工参数接口)
|
||||
3. [状态查询接口](#3-状态查询接口)
|
||||
4. [NC 文件操作接口](#4-nc-文件操作接口)
|
||||
5. [工件坐标接口](#5-工件坐标接口)
|
||||
6. [放电设置接口](#6-放电设置接口)
|
||||
7. [信号（推送通知）](#7-信号推送通知)
|
||||
8. [状态码说明](#8-状态码说明)
|
||||
9. [命令行调用示例](#9-命令行调用示例)
|
||||
10. [注意事项](#10-注意事项)
|
||||
|
||||
---
|
||||
|
||||
## 1. 运动控制接口
|
||||
|
||||
### startRun() - 启动加工
|
||||
- **描述**: 启动加工程序，等价于点击界面"运行"按钮
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```powershell
|
||||
# 启动加工
|
||||
qdbus com.wirecut.service /com/wirecut/control startRun
|
||||
```
|
||||
|
||||
### stopRun() - 停止加工
|
||||
- **描述**: 停止当前加工，等价于点击"停止"按钮
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control stopRun
|
||||
```
|
||||
|
||||
### pauseRun() - 暂停加工
|
||||
- **描述**: 暂停加工（变频），等价于点击"变频暂停"
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus mock_qdbus.py com.wirecut.service /com/wirecut/control pauseRun
|
||||
```
|
||||
|
||||
### homeAll() - 全轴回零
|
||||
- **描述**: 所有轴执行回零操作
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control homeAll
|
||||
```
|
||||
|
||||
### startKongZou() - 开始空走
|
||||
- **描述**: 启动空走模式（不放电测试）
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control startKongZou
|
||||
```
|
||||
|
||||
### stopKongZou() - 停止空走
|
||||
- **描述**: 停止空走模式
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control stopKongZou
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 加工参数接口
|
||||
|
||||
### setSpeed(speed: int) -> int - 设置加工速度
|
||||
- **描述**: 设置加工速度
|
||||
- **参数**:
|
||||
- `speed`: 速度值，单位 mm/min，范围 1-9999
|
||||
- **返回**: 实际设置的速度值
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control setSpeed 80
|
||||
```
|
||||
|
||||
### getSpeed() -> int - 获取设定速度
|
||||
- **描述**: 获取当前设定的加工速度
|
||||
- **参数**: 无
|
||||
- **返回**: 设定速度值 (mm/min)
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control getSpeed
|
||||
```
|
||||
|
||||
### setVoltage(vol: int) - 设置放电电压
|
||||
- **描述**: 设置放电电压值
|
||||
- **参数**:
|
||||
- `vol`: 电压值
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control setVoltage 90
|
||||
```
|
||||
|
||||
### setCurrent(cur: int) - 设置放电电流
|
||||
- **描述**: 设置放电电流值
|
||||
- **参数**:
|
||||
- `cur`: 电流值
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control setCurrent 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 状态查询接口
|
||||
|
||||
### getStatus() -> QVariantMap - 获取完整状态
|
||||
- **描述**: 获取系统完整状态信息（字典格式）
|
||||
- **参数**: 无
|
||||
- **返回字段**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `running` | int | 运行状态：0=停止 1=运行中 2=暂停 |
|
||||
| `is_homed` | int | 是否已回零：0=否 1=是 |
|
||||
| `is_homing` | int | 是否正在回零：0=否 1=是 |
|
||||
| `pos_x` | double | X轴位置 (mm) |
|
||||
| `pos_y` | double | Y轴位置 (mm) |
|
||||
| `pos_z` | double | Z轴位置 (mm) |
|
||||
| `pos_u` | double | U轴位置 (mm) |
|
||||
| `pos_v` | double | V轴位置 (mm) |
|
||||
| `vol` | int | 当前电压值 |
|
||||
| `cur` | int | 当前电流值 |
|
||||
| `daohao` | int | 导号（加工段号） |
|
||||
| `speed` | int | 设定速度 (mm/min) |
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control getStatus
|
||||
```
|
||||
|
||||
### getAxisPos() -> QString - 获取各轴位置
|
||||
- **描述**: 轻量级接口，获取各轴当前位置
|
||||
- **参数**: 无
|
||||
- **返回**: `"x,y,z,u,v"` 格式字符串，保留3位小数，单位 mm
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control getAxisPos
|
||||
# 返回示例: "10.500,20.321,0.000,0.123,0.000"
|
||||
```
|
||||
|
||||
### isRunning() -> bool - 是否正在加工
|
||||
- **描述**: 查询是否处于加工状态
|
||||
- **参数**: 无
|
||||
- **返回**: true=运行中 false=已停止
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control isRunning
|
||||
```
|
||||
|
||||
### isHomed() -> bool - 是否已回零
|
||||
- **描述**: 查询是否已完成回零
|
||||
- **参数**: 无
|
||||
- **返回**: true=已回零 false=未回零
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control isHomed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. NC 文件操作接口
|
||||
|
||||
### loadNC(path: QString) -> bool - 加载 NC 文件
|
||||
- **描述**: 加载 NC 程序文件
|
||||
- **参数**:
|
||||
- `path`: NC 文件的**绝对路径**
|
||||
- **返回**: true=成功 false=失败
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control loadNC "/home/user/test.ngc"
|
||||
```
|
||||
|
||||
### getCurrentNC() -> QString - 获取当前 NC 文件
|
||||
- **描述**: 获取当前已加载的 NC 文件路径
|
||||
- **参数**: 无
|
||||
- **返回**: NC 文件路径
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control getCurrentNC
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 工件坐标接口
|
||||
|
||||
### clearAxisOffset(axis: int) - 清除单轴工件坐标
|
||||
- **描述**: 清除指定轴的工件坐标偏移
|
||||
- **参数**:
|
||||
- `axis`: 轴编号：0=X 1=Y 2=Z 3=U 4=V 5=C
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
# 清除 X 轴工件坐标
|
||||
qdbus com.wirecut.service /com/wirecut/control clearAxisOffset 0
|
||||
```
|
||||
|
||||
### clearAllAxisOffset() - 清除所有轴工件坐标
|
||||
- **描述**: 清除全部6个轴的工件坐标偏移
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control clearAllAxisOffset
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 放电设置接口
|
||||
|
||||
### ShowDischargeSetting() - 打开放电设置界面
|
||||
- **描述**: 弹出放电设置窗口
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control ShowDischargeSetting
|
||||
```
|
||||
|
||||
### HideDischargeSetting() - 关闭放电设置界面
|
||||
- **描述**: 隐藏放电设置窗口
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control HideDischargeSetting
|
||||
```
|
||||
|
||||
### SetWorkpieceId(workpieceId: int) - 设置当前工件号
|
||||
- **描述**: 切换到指定工件编号
|
||||
- **参数**:
|
||||
- `workpieceId`: 工件编号，范围 0-8
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
# 切换到工件3
|
||||
qdbus com.wirecut.service /com/wirecut/control SetWorkpieceId 3
|
||||
```
|
||||
|
||||
### SetDischargePara(workpieceId, knifeId, paramType, value) - 设置放电参数
|
||||
- **描述**: 设置指定工件、指定刀号的放电参数
|
||||
- **参数**:
|
||||
- `workpieceId`: 工件编号 (0-8)
|
||||
- `knifeId`: 刀号 (1-11)
|
||||
- `paramType`: 参数类型字符串：
|
||||
- `"voltage"` / `"放电码"` - 放电码
|
||||
- `"current"` / `"跟踪值"` - 跟踪值
|
||||
- `"servo"` / `"速度"` - 速度上限
|
||||
- `value`: 参数值
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
# 设置工件0，刀号1，放电码为80
|
||||
qdbus com.wirecut.service /com/wirecut/control SetDischargePara 0 1 voltage 80
|
||||
```
|
||||
|
||||
### GetDischargePara(workpieceId, knifeId, paramType) -> int - 获取放电参数
|
||||
- **描述**: 获取指定工件、指定刀号的放电参数值
|
||||
- **参数**: 同 SetDischargePara
|
||||
- **返回**: 参数值
|
||||
|
||||
```bash
|
||||
# 获取工件0，刀号1的放电码
|
||||
qdbus com.wirecut.service /com/wirecut/control GetDischargePara 0 1 voltage
|
||||
```
|
||||
|
||||
### CopyToAllWorkpieces() - 复制到所有工件
|
||||
- **描述**: 将当前工件的放电参数复制到所有工件
|
||||
- **参数**: 无
|
||||
- **返回**: 无
|
||||
|
||||
```bash
|
||||
qdbus com.wirecut.service /com/wirecut/control CopyToAllWorkpieces
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 信号（推送通知）
|
||||
|
||||
DBus 服务会主动推送以下信号，外部程序可以监听：
|
||||
|
||||
### runStateChanged(state: int) - 运行状态变化
|
||||
- **触发时机**: 运行状态改变时
|
||||
- **参数**:
|
||||
- `state`: 0=停止 / 1=运行 / 2=暂停
|
||||
|
||||
### alarmMessage(type: int, msg: QString) - 报警/提示
|
||||
- **触发时机**: 系统产生报警或提示时
|
||||
- **参数**:
|
||||
- `type`: 0=提示 / 1=警告 / 2=错误
|
||||
- `msg`: 消息内容
|
||||
|
||||
### axisPosUpdated(x, y, z, u, v: double) - 轴位置刷新
|
||||
- **触发时机**: 每 500ms 周期推送一次
|
||||
- **参数**: 各轴当前位置 (mm)
|
||||
|
||||
### machiningFinished() - 加工完成
|
||||
- **触发时机**: 加工程序执行完成时
|
||||
- **参数**: 无
|
||||
|
||||
---
|
||||
|
||||
## 8. 状态码说明
|
||||
|
||||
### 运行状态码 (running 字段)
|
||||
|
||||
| 值 | 状态 | 说明 |
|
||||
|----|------|------|
|
||||
| 0 | 停止 | 未运行或已停止 |
|
||||
| 1 | 运行中 | 正在加工 |
|
||||
| 2 | 暂停 | 已暂停（变频） |
|
||||
|
||||
### 轴编号
|
||||
|
||||
| 值 | 轴 | 说明 |
|
||||
|----|-----|------|
|
||||
| 0 | X | X轴 |
|
||||
| 1 | Y | Y轴 |
|
||||
| 2 | Z | Z轴 |
|
||||
| 3 | U | U轴 |
|
||||
| 4 | V | V轴 |
|
||||
| 5 | C | C轴 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 命令行调用示例
|
||||
|
||||
### 完整加工流程
|
||||
|
||||
```bash
|
||||
# 1. 查看当前状态
|
||||
qdbus com.wirecut.service /com/wirecut/control getStatus
|
||||
|
||||
# 2. 加载 NC 文件（必须绝对路径）
|
||||
qdbus com.wirecut.service /com/wirecut/control loadNC "/home/pi/sample.ngc"
|
||||
|
||||
# 3. 设置加工速度
|
||||
qdbus com.wirecut.service /com/wirecut/control setSpeed 80
|
||||
|
||||
# 4. 开始加工
|
||||
qdbus com.wirecut.service /com/wirecut/control startRun
|
||||
|
||||
# 5. 实时查看轴位置
|
||||
qdbus com.wirecut.service /com/wirecut/control getAxisPos
|
||||
|
||||
# 6. 暂停加工
|
||||
qdbus com.wirecut.service /com/wirecut/control pauseRun
|
||||
|
||||
# 7. 停止加工
|
||||
qdbus com.wirecut.service /com/wirecut/control stopRun
|
||||
```
|
||||
|
||||
### 空走测试流程
|
||||
|
||||
```bash
|
||||
# 1. 回零
|
||||
qdbus com.wirecut.service /com/wirecut/control homeAll
|
||||
|
||||
# 2. 开始空走（不放电）
|
||||
qdbus com.wirecut.service /com/wirecut/control startKongZou
|
||||
|
||||
# 3. 停止空走
|
||||
qdbus com.wirecut.service /com/wirecut/control stopKongZou
|
||||
```
|
||||
|
||||
### Python 调用示例（使用 dbus-python）
|
||||
|
||||
```python
|
||||
import dbus
|
||||
|
||||
# 连接系统总线
|
||||
bus = dbus.SystemBus()
|
||||
|
||||
# 获取服务对象
|
||||
obj = bus.get_object('com.wirecut.service', '/com/wirecut/control')
|
||||
iface = dbus.Interface(obj, 'com.wirecut.IControl')
|
||||
|
||||
# 调用方法
|
||||
status = iface.getStatus()
|
||||
print("运行状态:", status['running'])
|
||||
print("X轴位置:", status['pos_x'])
|
||||
|
||||
# 加载 NC 文件
|
||||
iface.loadNC("/home/pi/test.ngc")
|
||||
|
||||
# 启动加工
|
||||
iface.startRun()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 注意事项
|
||||
|
||||
### ⚠️ 重要提醒
|
||||
|
||||
1. **CNC 软件必须运行**
|
||||
- 所有 DBus 接口只有在 CNC 主程序启动后才能使用
|
||||
- 软件未启动时调用会返回 DBus 错误
|
||||
|
||||
2. **NC 文件路径必须为绝对路径**
|
||||
- `loadNC()` 的 path 参数必须使用完整绝对路径
|
||||
- 相对路径会导致加载失败
|
||||
|
||||
3. **速度设置范围**
|
||||
- 速度值范围：1-9999 mm/min
|
||||
- 超出范围会被截断或忽略
|
||||
|
||||
4. **System Bus 权限**
|
||||
- 服务运行在 System Bus 上，可能需要 root 权限
|
||||
- 普通用户调用可能需要配置 DBus 权限规则
|
||||
|
||||
5. **线程安全**
|
||||
- 所有接口调用都是异步队列执行（QueuedConnection）
|
||||
- 调用后不会阻塞，实际执行由主界面事件循环处理
|
||||
|
||||
6. **共享内存依赖**
|
||||
- 部分参数（电压、电流、位置）依赖共享内存
|
||||
- 共享内存未就绪时返回 0 或默认值
|
||||
|
||||
---
|
||||
|
||||
## 附录：DBus 权限配置
|
||||
|
||||
如果普通用户无法调用，需要在 `/etc/dbus-1/system.d/` 下添加权限配置文件 `com.wirecut.conf`：
|
||||
|
||||
```xml
|
||||
<!DOCTYPE busconfig PUBLIC
|
||||
"-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
|
||||
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
|
||||
<busconfig>
|
||||
<policy user="pi">
|
||||
<allow own="com.wirecut.service"/>
|
||||
<allow send_destination="com.wirecut.service"/>
|
||||
<allow receive_sender="com.wirecut.service"/>
|
||||
</policy>
|
||||
<policy context="default">
|
||||
<allow send_destination="com.wirecut.service"/>
|
||||
<allow receive_sender="com.wirecut.service"/>
|
||||
</policy>
|
||||
</busconfig>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**生成日期**: 2026-05-20
|
||||
**对应源码**: `/usr/share/runf/wirecutdbus.h` / `wirecutdbus.cpp`
|
||||
Reference in New Issue
Block a user