# GMOCCAPY 分析与加载测试

更新时间：2026-08-25

## 结论

“没有看到加载程序按钮”不是按钮缺失，而是首次启动提示和 GMOCCAPY 的模式门控共同造成的视觉结果：

1. 首次启动会弹出模态的 `Important change(s)` 窗口。该窗口覆盖主界面并阻止底层点击；用户截图中的右侧 `X` 是关闭按钮，底部复选框是 `Don't show this again`。
2. 加载按钮只属于 AUTO 页面按钮组，不属于 MANUAL/JOG 页面。源码将它声明为 `btn_load`，提示为 `Load a new program`，图标为 `img_open`。
3. AUTO 模式还受机器状态和 homing 门控。`gmoccapy.py` 在未满足状态时会禁用 `rbt_auto`，并提示 `It is not possible to change to Auto Mode at the moment`。
4. 关闭首次提示、进入 AUTO 后，点击文件夹/打开文件图标会进入文件选择页。当前 `gmoccapy.ini` 的 `PROGRAM_PREFIX = ../../nc_files/` 解析到 `linuxcnc/nc_files`。

## 用户截图分析

![首次启动提示](gmoccapy-important-changes.png)

用户提供的图片尺寸为 `697 x 837`，内容是 GMOCCAPY 3.5.x 的版本变更提示：

- LinuxCNC 2.10/GMOCCAPY 3.5.0 不再在换刀后自动保留 G43；需要通过 REMAP 实现自动重新激活。
- 3.5.1 的工具表和偏置页默认使用计算器输入，可在设置或按钮中改变。
- MDI 和 G-code 编辑模式新增调用计算器的按钮。
- `release notes` 是橙色链接；右下方复选框用于永久隐藏该提示。

这张提示不是文件选择器，也不是加载失败信息。应先关闭它，再操作主界面。

### 新截图的源码逐项对照

![用户提供的最新提示截图](gmoccapy-important-changes-v2.png)

这张截图与前一张内容一致，尺寸为 `697 x 837`，SHA-256 为 `df7322c30bcb6af131591a04b11cad24e7b6d186beaff83059fcfd8ffbae2d1b`。截图中的每一块文字都能在当前系统安装的 `/usr/bin/gmoccapy` 中找到：

| 截图区域 | 源码证据 | 含义 |
|---|---|---|
| `Important change(s)` 标题 | `/usr/bin/gmoccapy:557-560` | `_startup_message()` 建立启动提示标题；注释要求新增消息只能追加，不能删除旧消息，否则隐藏索引会错位。 |
| 3.5.0 G43 提示 | `/usr/bin/gmoccapy:561-563` | GMOCCAPY 3.5.0 不再承诺换刀后自动保留 G43；想自动恢复必须使用 REMAP，示例在 GMOCCAPY 仿真配置中。 |
| 3.5.1 计算器提示 | `/usr/bin/gmoccapy:564-565` | 工具表和偏置页默认启用计算器输入；设置或页面按钮可以关闭；MDI 和 G-code 编辑页也增加了计算器按钮。 |
| `release notes` 链接 | `/usr/bin/gmoccapy:570-573` | 以 Pango markup 拼接 LinuxCNC 官方 release notes URL，并通过通知组件显示。点击它会打开文档，不会关闭提示。 |
| `Don't show this again` | `notification.py:151-155` | `show_checkbox=True` 时创建 GTK `CheckButton`；它不是普通说明文字，而是真正影响后续启动行为的复选框。 |
| 右侧 `X` | `notification.py:156-164` | 创建名为 `notification_close` 的 48x48 关闭按钮；点击后删除该消息，并把复选框状态发回 GMOCCAPY。 |

### 弹窗什么时候出现

系统运行时在 GUI 初始化和周期任务准备完成后，于 `/usr/bin/gmoccapy:519` 调用 `_startup_message()`。它读取偏好项 `hide_startup_messsage`（注意源码中确实有三个 `s` 的拼写）：

```python
hide_message = self.prefs.getpref("hide_startup_messsage", 0, int)
if hide_message < len(messages):
    ...
    self.notification.add_message(message, INFO_ICON, show_checkbox=True)
```

当前消息数组有两项，因此默认值 `0` 会显示两项。关闭时如果复选框被勾选，`/usr/bin/gmoccapy:6241-6242` 将 `self.num`（当前为 `2`）写回 `hide_startup_messsage`。下次启动判断 `2 < 2` 为假，提示不再出现。普通点击 `X` 不勾选复选框时，只删除本次通知，下次仍会显示。

### 版本边界：截图运行时与仓库锁定源不同

这是本次分析中最重要的来源边界：

- 截图对应的实际运行程序是 `/usr/bin/gmoccapy`，其中 `_RELEASE = "3.5.2"`，并包含 `_startup_message()`、3.5.0/3.5.1 文本和隐藏偏好逻辑。
- 仓库锁定源是 `linuxcnc/VERSION = 2.10.0~pre0`；`linuxcnc/src/emc/usr_intf/gmoccapy/gmoccapy.py:79` 的版本为 `3.4.3`，该文件没有 `_startup_message()` 实现，也没有截图中的 3.5.0/3.5.1 文本。
- 本地启动日志曾显示 `LinuxCNC 2.10.0~pre1` 和 `gmoccapy 3.5.2`，与截图完全一致。因此这张截图是系统安装包的运行时证据，不应反向宣称锁定仓库 2.10.0~pre0/3.4.3 源码已经包含该功能。

已记录的运行时文件哈希：

```text
/usr/bin/gmoccapy                         11e7aee9216d24e4cc41018306f2541845bca9a9d6e16c38580f3ede9cca8d4d
/usr/share/gmoccapy/gmoccapy.glade       5fdc1557b02a716d30414fe739614fcd7c1d14cbe2e0a4c202c567a60b460adb
/usr/lib/python3/dist-packages/gmoccapy/notification.py
                                           e0317fea738745f480c79d1f690bc52e88cc7f81bb4d14fa09c8c7196afb4e2f
```

### 用户应如何处理

1. 只想本次继续操作：点击右侧 `X`，不要勾选复选框。
2. 不想以后重复看到：先勾选 `Don't show this again`，再点击 `X`。
3. 想查看变更依据：点击 `release notes`，但这需要浏览器/网络或本地文档可用。
4. 使用 G43 的程序：不要仅依赖界面自动行为；在 AUTO 程序中按机床配置和 REMAP 约定明确处理刀具长度补偿，并在正式加工前验证工具表和偏置。

## 实际界面证据

### 未加载状态

![未加载程序](gmoccapy-before-load.png)

主界面顶部显示 `No Program loaded`。右侧竖向按钮中第三个为 AUTO 模式图标；在 MANUAL 页面时，AUTO 页面里的 `Load a new program` 不会显示在当前按钮组。

### 文件选择页

![加载程序文件选择页](gmoccapy-load-file-page.png)

这张截图是实际运行 GMOCCAPY 后进入的文件选择页。页面显示 `gcmc_lib`、`macros`、`ngcgui_lib` 等目录以及 `3D_Chips.ngc`、`3dtest.ngc` 等程序。底部右侧绿色对勾是确认选择，右下黄色回退箭头是返回。

进入这张页面的完整点击链是：

1. 关闭首次 `Important change(s)` 模态提示。
2. 在主界面右侧点击第三个模式图标，进入 AUTO；源码控件为 `rbt_auto`。
3. 等待 AUTO 按钮组出现，在其中点击打开文件图标；源码控件为 `btn_load`，tooltip 为 `Load a new program`。
4. `on_btn_load_clicked()` 将按钮页切换到文件选择页；此时才会看到本截图中的文件网格。
5. 选中 `.ngc` 文件后点击底部绿色对勾，源码控件为 `btn_select`。

因此，文件网格不是主界面的固定按钮，也不是 MDI 入口；在 MANUAL/JOG 页面直接寻找它不会找到。

### 加载后的程序

![加载 3dtest.ngc 后](gmoccapy-program-loaded.png)

通过 LinuxCNC 的 `command.program_open()` 加载：

```text
/home/mes006/linuxcncWebWASM/linuxcnc/nc_files/3dtest.ngc
```

加载成功的证据是：

- 顶部由 `No Program loaded` 变成完整程序路径；
- 预览区出现 G-code 刀具轨迹；
- `linuxcnc.stat().file` 返回上述路径；
- `interp_state` 保持空闲，加载本身不会自动运行程序。

## 源码与界面映射

| 层 | 文件/符号 | 结论 |
|---|---|---|
| 主逻辑 | `linuxcnc/src/emc/usr_intf/gmoccapy/gmoccapy.py` | `on_btn_load_clicked()` 切到文件选择页；`on_IconFileSelection1_selected()` 调用 `hal_action_open.load_file(path)`。 |
| 加载按钮 | `btn_load` / `img_open` | tooltip 是 `Load a new program`，只在 AUTO 按钮页 `hbtb_auto`。 |
| 运行按钮 | `btn_run` / `img_run` | tooltip 是 `Run the loaded program`；加载后仍需手动运行。 |
| 文件确认 | `btn_select` / `img_select` | tooltip 是 `select the highlighted file and return the path`。 |
| 返回 | `btn_back_file_load` / `img_back_file_load` | 关闭文件选择页但不返回路径。 |
| 文件资源 | `linuxcnc/lib/python/gladevcp/iconview.py` 及 GMOCCAPY 初始化 | 读取 `PROGRAM_PREFIX`，按配置扩展名展示文件和目录。 |
| 首次提示 | GMOCCAPY preferences/release-notes 逻辑 | 模态提示优先于主界面，必须先关闭。 |

## 配置与资源分析

默认配置为 `linuxcnc/configs/sim/gmoccapy/gmoccapy.ini`：

- `[DISPLAY] DISPLAY = gmoccapy`：选择 GMOCCAPY GUI。
- `[DISPLAY] PROGRAM_PREFIX = ../../nc_files/`：从配置目录解析到 `linuxcnc/nc_files`。
- `[RS274NGC] PARAMETER_FILE = sim.var`：仿真参数文件。
- `[RS274NGC] SUBROUTINE_PATH = macros`：宏和子程序搜索路径。
- `[EMCIO] TOOL_TABLE = tool.tbl`：工具表。
- `[HAL]` 加载 `core_sim.hal`、`spindle_sim.hal`、`simulated_home.hal`，并在 GUI 启动后加载 `gmoccapy_postgui.hal`。

`configs/sim/gmoccapy` 不是单一案例，而是一组配置族，包含标准三轴、四轴、XYZAB/XYZAC/XYZCW、多轴、侧面板、消息、工具传感器、用户页、等离子和车床配置。完整逐文件路径与哈希见 [文件清单](gmoccapy-file-inventory.md)。

## 运行环境与限制

- 启动入口：[`../run-gmoccapy.sh`](../run-gmoccapy.sh)，默认执行 `gmoccapy.ini`。
- 实际 GUI 进程：`/usr/bin/python3 /usr/bin/gmoccapy -ini .../gmoccapy.ini`。
- 当前环境没有实时内核，LinuxCNC 日志明确回退到 POSIX non-realtime；这不影响本次“加载和预览”验证，但不等同于实时硬件运行验证。
- `simulated_home.hal` 的共享 home switch 在本次手动尝试中报告 `Cannot home while shared home switch is closed j=2`，因此 AUTO 模式按钮可能保持禁用。加载程序本身仍可通过 GUI 文件页/API 验证。
- 加载和运行是两个动作：`program_open` 只读入程序并生成预览；需要 `AUTO` 页面中的 Run 按钮或 `R` 快捷键才会执行。

## 推荐操作顺序

1. 启动 `./run-gmoccapy.sh`。
2. 关闭首次 `Important change(s)` 提示；可勾选 `Don't show this again`。
3. 确认急停复位、机器上电，并按配置完成 homing；否则 AUTO 可能被门控。
4. 点击右侧 AUTO 图标，进入 AUTO 按钮页。
5. 点击带打开文件/文件夹图标的 `Load a new program`。
6. 选择 `linuxcnc/nc_files` 下的 `.ngc` 文件，点击底部绿色对勾。
7. 检查顶部路径和预览轨迹，再使用 Run；不要把加载误认为已经执行。

## 证据文件

- `gmoccapy-important-changes.png`：用户原始提示截图。
- `gmoccapy-before-load.png`：未加载程序。
- `gmoccapy-after-popup-close.png`：关闭提示后的主界面。
- `gmoccapy-load-file-page.png`：实际文件选择页。
- `gmoccapy-program-loaded.png`：加载后的程序和轨迹。
- `gmoccapy-file-inventory.json`：逐文件 SHA-256 清单。