CellDock进阶调试：用内置AT控制台与探测工具排查模块问题

本文面向在 Mac 上使用 CellDock 搭配 QDC507 4G/5G 蜂窝模块的用户，讲解如何用应用内置的 AT 控制台和仓库中的命令行探测工具，快速排查蜂窝网络模块的信号、注册、SIM 与 ADB 等常见问题，适合进阶玩家自助定位故障。

CellDock 是一款 macOS 菜单栏应用，插上 QDC507 蜂窝模块后即可在 Mac 上使用蜂窝网络、短信和通话。绝大多数问题都可以先靠一条 AT 命令 + 一个探测脚本定位，不必一上来就重装或重烧模块。


什么时候需要进阶调试？

遇到以下情况时，建议进入调试流程：

• 🔌 模块插上后 CellDock 识别不到，或设备页一直显示"未连接"
• 📶 信号正常但网络未注册、拿不到蜂窝 IP
• 📵 SIM 卡状态异常（+CPIN 报 PIN、SIM 卡托等错误）
• 📞 通话卡在"呼叫中"，或挂断后状态残留
• 🔧 需要验证 ADB 接口、UAC 音频链路是否可用

第一步：只读自检。仓库自带的 inspect_module.sh 是一个零副作用的排查脚本，它只读取三样东西：USB 设备树中的 QDC507 条目、macOS 持久化的蜂窝网络服务，以及 CellDock 进程状态。在终端执行：

zsh scripts/inspect_module.sh

输出里应能看到2c7c:0125的 USB 设备和对应的网络接口；如果这里就已经没有模块，问题在 USB 硬件层，优先换线/换口，再继续往下。

使用内置 AT 控制台：最安全的排查入口

AT 控制台是 CellDock 内置的图形化 AT 命令执行器（ATConsoleView.swift），入口有三处：

1. 设备页：模块卡片上的"AT 控制台"按钮（CellularOverviewCard.swift）
2. SIM 管理页：针对指定模块内嵌显示
3. 独立窗口：通过 StandaloneFlowWindowController.swift 打开的完整窗口

控制台通过模块的 AT 接口 2 执行单行命令，底部自带常用命令快捷入口：


AT 控制台的安全限制

命令校验逻辑在 ATConsoleModels.swift 中，规则值得了解，能帮你避免误操作：

• ✅ 只允许单行、512 字符以内、纯可打印 ASCII命令，且必须以AT开头
• 🚫 会拦截进入数据提示符的命令（如ATD），因为控制台不会发送后续载荷
• 🚫 拨号、接听、挂断和 DTMF 必须走电话界面，防止绕过通话音频与状态管理
• ⏸️ 通话期间自动暂停手动 AT，避免破坏进行中的呼叫

每次执行的输出、错误与耗时都会保留在"执行记录"区，响应解析由 ATResponseParser.swift 完成，方便你对比前后两次命令的结果。

命令行探测工具：深入到接口层

仓库tools/目录提供了一组针对 QDC507（USB ID0x2C7C:0x0125）的 C 语言探测工具，基于 CModemBridge 直接操作 USB 接口，比图形界面看得更深。

先记住 QDC507 的接口分工：

qdc507_iokit_tool：核心诊断工具

qdc507_iokit_tool.c 是功能最全的一把"瑞士军刀"，通过子命令覆盖网络、通话、USB 配置三大类操作：

# 编译 zsh scripts/build_diagnostic_tool.sh # 只读查询：注册状态、IMS/VoLTE、CID1 IP、网络设备状态 .build/tools/qdc507_iokit_tool query # 通话残留清理 / DTMF 能力检测 / 通话结束原因 .build/tools/qdc507_iokit_tool cleanup-call .build/tools/qdc507_iokit_tool query-dtmf .build/tools/qdc507_iokit_tool query-call-end # 音频链路探测与 USB 配置开关（含自动还原） .build/tools/qdc507_iokit_tool probe-qpcmv .build/tools/qdc507_iokit_tool enable-adb-config .build/tools/qdc507_iokit_tool restore-adb-config # USB 配置异常时的重启组合 .build/tools/qdc507_iokit_tool restart-uac

注意两点：probe-qpcmv会先确认语音呼叫状态为空才允许写入，restore-*系列会校验基线状态后才回滚，整体是"失败即拒绝"的保守设计。

其他单点工具

• qdc507_adb_probe.c：打开 ADB 接口 6，完成 CNXN 握手后可执行shell COMMAND，例如.build/tools/qdc507_adb_probe shell "cat /proc/version"，用于确认模块侧 ADB 服务是否可用；编译脚本为 build_adb_probe.sh。
• qdc507_if3_at_probe.c：走诊断接口 3 查询AT+QPCMV?等音频路由能力，加query-only参数可只做只读检查，不写入任何配置。
• qdc507_raw_restart.c：在 AT 口先发ATH再发AT+CFUN=1,1，是最快的"软重启模块"手段。
• qdc507_usb_reenumerate.c：纯 IOKit 实现，对指定位置的 USB 设备强制重新枚举，适合 USB 状态僵死时尝试。

真实通话探测：验证完整呼叫链路

如果你要确认"AT 正常但通话不通"这类问题，仓库提供了真实拨号探测流程。以 run_qdc507_live_call_probe.sh 为例：

zsh scripts/run_qdc507_live_call_probe.sh --number 10086 --confirm-live-call

• 脚本会先自动构建探测程序，并强制要求 CellDock 已退出（它独占 AT/PCM 接口，脚本检测到 CellDock 运行会直接退出）
• --number指定被叫号码，--confirm-live-call是人工确认开关，防止误拨
• 姊妹脚本 run_qdc507_uac_live_call_probe.sh 走 UAC 音频链路，适合验证音频采集/播放是否正常

探测底层由 production_call_probe.swift 与 CellDockDialProbe 承担，编译脚本见 build_production_call_probe.sh。

推荐排查顺序：一张清单走下来

1. zsh scripts/inspect_module.sh— 确认 USB、网络服务、进程都在
2. AT 控制台依次发AT→AT+CPIN?→AT+COPS?→AT+QCSQ— 定位卡在哪一层
3. qdc507_iokit_tool query— 查看 IMS、IP、网络设备等深层状态
4. 按需执行probe-qpcmv/qdc507_adb_probe— 验证音频与 ADB 通道
5. 状态僵死时：restart-uac→ raw restart → USB 重新枚举，逐级加重
6. 最后用 live call probe 做端到端通话验证

⚠️ 提醒：探测工具与 CellDock 互斥运行（同时只能有一方占用模块接口）；enable-*-config类命令会修改模块 USB 配置，建议成对执行对应的restore-*还原，或执行后重新插拔模块。

小结

CellDock 的调试体系分三层：AT 控制台负责日常快速问诊，qdc507 系列 C 工具负责接口级精查，live call probe负责端到端验证。配合 inspect_module.sh 的只读自检，绝大多数模块问题都能在不动固件的前提下定位到具体环节。相关文件索引：

• 界面层：ATConsoleView.swift、SIMManagementView.swift
• 工具层：tools/、构建脚本 scripts/
• 模块模型：CellularModuleModels.swift、ModemInventoryService.swift