从首次激活到拔线三网换卡验收

01. 前提条件与已验证设备 Profile

1. 已验证设备与系统：当前内置 blackberry-passport-wolverine 设备 Profile，支持黑莓 Passport（SQW100-1 / SQW100-3 / SQW100-4，代号 wolverine）运行 LineageOS 18.1-UNOFFICIAL-wseries（Android 11 / API 30，SELinux 保持 Enforcing）。工具会自动匹配 devices/*/profile.json，未建档机型自动拦截基带写入。
2. SIM 卡要求：已插入开通了 VoLTE 高清语音业务的 4G/5G USIM 卡，且处于机身射频支持的 LTE 频段内并正常驻留 LTE。
3. 保持空闲状态：执行写入与重启前，请确认当前没有正在进行的通话，电量建议高于 30%，并使用可靠的数据线连接电脑。

02. 开启 LineageOS 18.1 的 USB 调试与 Root 调试

使用电脑端激活方式（方式一或方式三）完全不需要刷入 Magisk，只需打开系统自带的开发者开关：

1. 进入 设置 → 关于手机，连续点击 7 次最下方的 版本号（Build number） 启用开发者选项。
2. 返回进入 设置 → 系统 → 高级 → 开发者选项。
3. 开启 Android 调试（USB 调试），并在同页面开启 Root 调试（Rooted debugging）。
4. 连接电脑，在手机弹出的「允许 USB 调试吗？」对话框中勾选一律允许并点击确定。

03. 方式一：Windows 桌面一键激活工具（最推荐）

1. 下载 qcom32-volte-1.1.0-r1-windows-x64.exe 并双击运行（无需安装 Python 或 ADB）。
2. 确认顶部「ADB 设备」下拉框已识别到手机序列号，点击 「1. 只读检查状态」 确认匹配到设备 Profile。
3. 点击绿色主按钮 「2. 备份并一键激活 VoLTE」 并确认提示框。
4. 程序自动：切换 adb root → 将原始基带快照保存至电脑 %LOCALAPPDATA%\qcom32-volte\backups\ → 写入 Stage 6A 基带配置并执行 EFS_SYNC → 清理旧包残留并安装 Qcom32VolteIms.apk v2.4 → 正常重启手机并轮询确认 volte_stack_healthy: true。
5. （推荐顺手点一下）点击 「安装手机端管理 App」，将伴侣应用推送到手机桌面，拔掉数据线后换三网 SIM 卡可直接看屏幕状态。

04. 方式二：手机端独立状态与管理 App

安装 Qcom32VolteManager-1.1.0-r1.apk（桌面图标名称 Qcom32 VoLTE）：

1. 无 Magisk 场景（免 su 实时状态面板）：打开应用点击「刷新实时状态」，应用通过只读 content://org.octolab.qcom32ims.status 接口直接读取并展示当前 SIM 运营商、rild_ims0 连接、QMI_IMSA 承载/语音就绪与系统 mImsRegistered 状态——拔掉电脑数据线换卡测试时非常直观。
2. 已刷 Magisk 场景（机内独立激活/回滚）：点击「一键激活 / 修复原生 VoLTE（需 Magisk su）」并授予超级用户权限，即可脱离电脑在手机内校验内嵌载荷 SHA-256、备份原值、写入 Stage 6A 配置或一键恢复出厂基带。

05. 方式三：macOS / Linux / 跨平台便携包（CLI & GUI）

下载并解压 qcom32-volte-1.1.0-r1-portable.zip（内置已编译签名的 ARM32 工具、双 APK 与 devices/ Profile 库，仅需 Python 3.9+ 与 adb）：

# 1. 离线单元测试自检
python3 cli/volte_ctl.py self-test

# 2. 只读检查当前手机设备 Profile、QMI_IMSA 与 ImsResolver 状态
python3 cli/volte_ctl.py status

# 3. 备份基带原值 + 一键写入 Stage 6A + 安装通话栈 APK + 重启自动验收
python3 cli/volte_ctl.py deploy

# 4. 顺手安装手机端实时状态/管理伴侣 App
python3 cli/volte_ctl.py install-manager

# 5. 或启动跨平台桌面图形界面
python3 cli/gui.py

06. 方式四：LineageOS 18.1 ROM 源码集成与 32 位新机型适配

面向自定义 ROM 维护者，rom-integration/ 目录提供了通用 Soong Android.bp 与 device-qcom32-volte.mk：

# 在 LineageOS 18.1 源码树中引入通用通话栈服务：
mkdir -p packages/apps/Qcom32VolteIms
cp -r src/android-ims-service/* src/qmi-imsa-probe rom-integration/Android.bp packages/apps/Qcom32VolteIms/

# 在目标 32 位高通设备的 device.mk 末尾加入：
$(call inherit-product, packages/apps/Qcom32VolteIms/device-qcom32-volte.mk)

注意：ROM 刷机包不会改写高通独立基带分区（Modem EFS），每台实体机首次仍需执行一次基带 EFS 供给。为一加 1、小米 4、索尼 Z2/Z3、三星 S5 等同代 MSM8974 机型新增 devices/<id>/profile.json 的完整规范，请查阅 MSM8974_PORTING_GUIDE.md 与 devices/README.md。

07. 国内三网换 SIM 卡说明（拔线零电脑自愈）

1. 完全无需再连电脑：Stage 6A 基带配置采用标准 ims APN 与 mode=0 动态 PCO（自动从新 USIM 推导归属域）；同时 Android 侧 CarrierConfigBootstrapReceiver 监听 SIM_STATE_CHANGED 与 CARRIER_CONFIG_CHANGED，插拔或关机更换新卡开机后会自动为新卡 subId 写入持久化 VoLTE 配置。
2. 联通 / 电信 / 移动频段注意（Passport SQW100-1）：机身物理射频支持 FDD-LTE Band 1/2/3/4/5/7/8/13/17/20（不支持 TDD-LTE B38-41 与 CDMA 1x）。因此：中国联通（46001）与中国电信（46003/46011）在 FDD B1/B3/B5/B8 覆盖区可直接使用 4G VoLTE；中国移动（46000/46002/46007）在部署了 FDD B3/B8 的区域可使用 4G VoLTE，若所在小区仅有移动 TDD 频段则会自动回落 2G GSM 通话。

08. 真实通话验收清单（必做）

1. 拔掉 USB 数据线，打开手机桌面的 Qcom32 VoLTE 确认显示绿字「VoLTE 通话栈已激活并注册就绪」；
2. 用系统自带拨号器拨打外部电话，确认双方声音清晰，且顶部信号栏全程保持 LTE / 4G；
3. 用外部手机回拨，确认响铃正常、来电号码完整显示（非“未知”）、挂断干脆；
4. 正常重启一次手机，等待约 20–30 秒后再次拨打电话确认开机自愈生效。

09. 完整恢复出厂基带配置并卸载

连接电脑点击桌面工具的 「恢复出厂基带配置并卸载」，或执行：

python3 cli/volte_ctl.py rollback

该流程会清除持久化 CarrierConfig 覆盖、卸载 org.octolab.qcom32ims，调用 pp_regconfig_provision_v6 --rollback-all 将全部 54 项基带条目恢复出厂值并执行 EFS_SYNC，最后正常重启验证。

10. 校验下载文件 SHA-256

# Windows PowerShell:
Get-FileHash "$HOME\Downloads\qcom32-volte-1.1.0-r1-windows-x64.exe" -Algorithm SHA256

# macOS / Linux:
shasum -a 256 ~/Downloads/qcom32-volte-1.1.0-r1-portable.zip