# pm_ecat_tools

**Repository Path**: amoeee/pm_ecat_tools

## Basic Information

- **Project Name**: pm_ecat_tools
- **Description**: pm_ecat_tools
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-03
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EtherCAT 上位机工具

基于 `PyQt6 + pyqtgraph + pysoem` 的 EtherCAT 桌面上位机，面向联机调试、CiA402 轴控、参数读写和 PDO 监控场景。

当前文档按实际功能划分，优先说明“这个工具能做什么、怎么用、边界在哪里”。

## 功能总览

### 1. 设备管理

- 扫描可用有线网卡，尽量过滤无线、蓝牙、VPN、虚拟网卡
- 支持“一键准备”或手动选择网卡后连接主站
- 连接后自动扫描从站，展示站号、别名、名称、状态
- 支持从站筛选，便于快速定位目标设备
- 支持 `Init / Boot / PreOp / SafeOp / Operational` 状态迁移
- 切到 `Operational` 时采用后台顺序迁移：`PreOp -> SafeOp -> Operational`
- 页面顶部展示当前会话、总线状态、从站数量、PDO 周期状态

### 2. 轴控制

- 面向 CiA402 常用调试流程
- 实时展示 `状态字 / 控制字 / 反馈模式 / 实际位置 / 实际速度 / 实际转矩`
- 支持常用控制命令：
  - `Shutdown`
  - `Switch On`
  - `Enable Operation`
  - `Disable Operation`
  - `Quick Stop`
  - `Fault Reset`
- 支持控制模式切换：
  - `PP 点位模式`
  - `PV 速度模式`
  - `TQ 转矩模式`
  - `HM 回零模式`
  - `CSP 周期同步位置`
  - `CSV 周期同步速度`
  - `CST 周期同步转矩`
- 支持写入 `目标位置 / 目标速度 / 目标转矩`
- 控制面板会根据当前模式限制建议写入项，减少误操作
- 若目标从站尚未进入 `Operational`，轴控流程会先尝试补齐状态迁移

### 3. 参数管理

- 提供 `PDO` 与 `SDO` 两块参数面板
- 连接后可自动读取对象目录与 PDO 映射
- 支持按 `索引 / 名称 / 类型 / 来源` 筛选对象
- 支持手工输入 `Index / SubIndex`，便于处理未自动识别的对象
- 支持十进制与十六进制两种输入/显示格式
- 支持的数据类型：
  - `bool`
  - `int8 / uint8`
  - `int16 / uint16`
  - `int32 / uint32`
  - `int64 / uint64`
  - `float32 / float64`
- 页面底部统一记录每次读写结果和格式转换结果

### 4. 实时监控

- 以从站为单位选择监控对象
- 优先使用实际读取到的 PDO 映射对象
- 若未读取到 PDO 映射，会回退到内置的常用对象列表
- 支持勾选多个 PDO 通道并同时绘制多条曲线
- 支持开始、停止、清空采集
- 支持游标查看当前位置数值
- `Auto` 短按自动对齐 Y 轴，长按同时恢复 X/Y 自动跟随
- 曲线数据由后台 PDO 周期缓存批量推送到主线程绘图

### 5. EEPROM 工具

- 在主站已连接后，为目标从站加载并解析 `ESI XML`
- 自动按当前从站 `VendorId / ProductCode / RevisionNo` 匹配 XML 中的 `Device`
- 将 XML 中的 EtherCAT 设备描述与 ESC 配置生成为 EEPROM/SII 镜像
- 写入前自动将总线切到 `Init`，写入完成后恢复到 `PreOp`
- 支持 EEPROM 回读校验，避免只写成功一半却没有被发现
- 若 XML 与当前从站身份不匹配，界面会禁止执行写入
- 写入完成后会提示重新连接主站，以重新加载新的 SII 描述

### 6. 日志记录与界面

- 日志页统一汇总设备管理、轴控制、参数管理、实时监控、EEPROM 工具的操作记录
- 支持亮色 / 暗色主题切换
- 当前导航中已接入业务能力的页面：
  - `设备管理`
  - `轴控制`
  - `参数管理`
  - `实时监控`
  - `EEPROM工具`
  - `日志记录`
- 当前仍为占位页的页面：
  - `首页`
  - `关于`
  - `设置`

## 典型使用流程

### 1. 环境准备

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

Windows 下通常还需要先安装 `Npcap`，并启用 WinPcap 兼容模式。

如果 `Npcap` 的 DLL 不在默认路径，可设置：

```powershell
$env:NPCAP_DLL_DIR = "C:\Windows\System32\Npcap"
```

### 2. 启动程序

两种方式都可以：

```powershell
python main.py
```

或：

```powershell
python -m ecat_hmi.main
```

### 3. 建立 EtherCAT 会话

1. 进入“设备管理”
2. 点击“扫描网卡”确认可用有线网卡
3. 点击“一键准备”或“应用并连接”
4. 连接成功后查看从站清单
5. 根据需要切换到 `PreOp / SafeOp / Operational`

### 4. 进行业务操作

- 轴控调试：进入“轴控制”，选择从站，执行 CiA402 命令或写入目标值
- 参数读写：进入“参数管理”，在 PDO 或 SDO 面板选择对象后读写
- 曲线监视：进入“实时监控”，勾选对象后开始采集
- EEPROM 写入：进入“EEPROM工具”，选择从站与 XML，解析后执行 EEPROM/SII 写入
- 结果追踪：进入“日志记录”，查看各功能页汇总日志

## 环境要求

- Python 环境可正常安装 `PyQt6`、`pyqtgraph`、`pysoem`
- 当前账户具备网卡访问权限
- 机器存在可用于 EtherCAT 的有线网卡
- 从站若支持 CoE，可自动读取更多对象目录与 PDO 映射信息

依赖见 [`requirements.txt`](requirements.txt)：

```txt
PyQt6>=6.6
pyqtgraph>=0.13
pysoem>=1.1
```

## 当前实现边界

- 主站连接成功后默认停留在 `PreOp`，不会在连接时直接自动进入 `Operational`
- `PDO` 读写只适用于已映射对象；未映射对象需要走 `SDO` 或手工输入地址处理
- 参数目录在 PDO 周期运行中不会强制在线重载，以避免连接抖动
- 实时监控适合调试观察，不是硬实时示波器
- 监控曲线基于后台缓存批量刷新，界面刷新速率与总线周期不是同一个概念
- 未接入的导航页仍为占位实现，不包含业务逻辑

## 常见问题

### 1. 启动时报 `pysoem 未就绪` 或加载失败

优先检查：

- `pysoem` 是否安装成功
- Python 与 `pysoem` 位数是否一致
- Windows 下 `Npcap` 是否安装完整
- 是否需要设置 `NPCAP_DLL_DIR`
- 当前账户是否具备网卡访问权限

### 2. 扫描不到网卡

优先检查：

- 当前机器是否存在可用有线网卡
- 当前环境是否只有无线网卡或虚拟网卡
- `Npcap` 驱动是否安装正常
- 当前账户是否具备抓包驱动访问权限

### 3. 扫描不到从站

优先检查：

- 物理链路与供电是否正常
- 选中的网卡是否正确
- 主站是否已经成功连接
- 从站是否处于可响应状态

### 4. 参数页提示 PDO 对象未映射

这表示目标对象没有进入当前 PDO 过程映射。

可选处理方式：

- 改用 `SDO` 访问
- 手工确认从站 PDO 映射配置
- 重新上电或重新连接后再读取对象目录

## 代码分层

代码按功能分成四层：

- 入口层
  - [`main.py`](main.py)
  - [`ecat_hmi/main.py`](ecat_hmi/main.py)
- 控制协调层
  - [`ecat_hmi/app_controller.py`](ecat_hmi/app_controller.py)
- 后端通信层
  - [`ecat_hmi/backend/ethercat_client.py`](ecat_hmi/backend/ethercat_client.py)
  - [`ecat_hmi/backend/models.py`](ecat_hmi/backend/models.py)
  - [`ecat_hmi/backend/pysoem_runtime.py`](ecat_hmi/backend/pysoem_runtime.py)
- UI 页面层
  - [`ecat_hmi/ui/main_window.py`](ecat_hmi/ui/main_window.py)
  - [`ecat_hmi/ui/pages/device_page.py`](ecat_hmi/ui/pages/device_page.py)
  - [`ecat_hmi/ui/pages/axis_page.py`](ecat_hmi/ui/pages/axis_page.py)
  - [`ecat_hmi/ui/pages/params_page.py`](ecat_hmi/ui/pages/params_page.py)
  - [`ecat_hmi/ui/pages/monitor_page.py`](ecat_hmi/ui/pages/monitor_page.py)
  - [`ecat_hmi/ui/pages/log_page.py`](ecat_hmi/ui/pages/log_page.py)

## 开发验证

如本地已安装 `pytest`，可执行：

```powershell
pytest -q
```

测试目录位于 [`tests`](tests)。