ai-device/docs/DBUS_API.md

# 线切割控制系统 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`