• 中文说明文档
  • 项目概览
  • ESTKme 实体卡适配核心原理
  • 安全架构与测试红线约束
  • 支持设备与系统版本
  • 仓库与模块架构
  • 安装与部署指南
  • 模拟测试框架与非破坏性验证
  • 源码构建指南
  • 安全须知与免责声明
  • 开源协议与参与贡献
• English Documentation
  • Overview
  • Core Adaptation Principles
  • Security Architecture & Safety Red Lines
  • Supported Devices & System Requirements
  • Repository Architecture
  • Installation & Deployment Guide
  • Mock Testing Framework
  • Building from Source
  • Disclaimers & Safety Notice
  • License

HyperOS 4 实体 eSIM (ESTKme) 适配与桥接方案 是一套面向 Xiaomi HyperOS 4（Android 15 / 16 / 17，API 35+）的开源系统级兼容层与桥接模块，专门解决可插拔实体 eSIM 卡（如 ESTKme 系列卡片）在国行双物理卡槽小米机型上无法原生使用官方系统 LPA 的难题。

在小米 MIX Flip 2（bixi）等机型上，官方固件未开放对卡槽2中可插拔 eUICC 实体卡的原生支持。本项目实现：

1. 完整原生 eSIM 系统能力：免除修改官方 LPA 签名，系统底层挂载声明 android.hardware.telephony.euicc 特性，直接配合提取自小米旗舰机型的原版 MIUIEsimLPA.apk（v4.1.0.1）工作。
2. 透明 OMAPI SEService 桥接：将上层框架下发的 APDU 命令无缝转发至 SIM2 读卡器，彻底突破基带 RIL 通道限制。
3. Fail-Closed 实体卡安全守护（CardTypeGuard）：严格进行 ISD-R AID 探测，在插入普通 SIM 卡时立即自动关闭 eSIM 模式，杜绝误操作。
4. 卡槽1射频与网络彻底隔离：拦截官方 LPA 面向板载 eSIM 设计的 GPIO 硬件天线切换逻辑，确保主卡（SIM1）移动网络、通话及 VoLTE 完全不受干扰。
5. 零专有代码残留：采用独立现代清晰的架构设计，完全不包含第三方专有代码片段。

在 HyperOS 4 系统下，系统 Telephony RIL 守护进程在面对可插拔卡槽时往往会拒绝建立 eUICC 逻辑通道。本项目通过 CompatModule 拦截底层 APDU 通道交互，动态桥接至 Android 标准 Open Mobile API (android.se.omapi.SEService)：

• 指定连接底层 SIM2 智能卡读卡器；
• 分配从 12000+ 开始的独立虚拟逻辑通道 ID（如 12000、12001）；
• 将虚拟通道与 OMAPI 底层 Channel 实例严格同步管理，杜绝通道死锁与句柄泄漏。

+--------------------------------------------------------------------+
|       Android 系统框架 / 第三方运营商应用 / 官方 MIUIEsimLPA.apk     |
+--------------------------------------------------------------------+
                                  |
                                  v
+--------------------------------------------------------------------+
|          CompatModule (LSPosed 模块: com.android.phone / euicc)    |
|  - APDU 通道路由器与虚拟通道池 (12000+)                              |
+--------------------------------------------------------------------+
           |                                         |
           | (RIL 通道未就绪时自动降级)               | (普通 UICC 通道)
           v                                         v
+-----------------------------+           +--------------------------+
|  OMAPI SEService 桥接层     |           | 原生 Telephony RIL       |
|  读卡器: "SIM2"             |           | 物理卡槽 0 (SIM1 主卡)   |
+-----------------------------+           +--------------------------+
           |                                         |
           v                                         v
+-----------------------------+           +--------------------------+
| ESTKme 可插拔实体 eSIM 卡   |           | 用户物理 SIM1 电话卡     |
| 物理卡槽 2 (安全保护)       |           | 绝对隔离，保持常开       |
+-----------------------------+           +--------------------------+

GSMA SGP.22 规范定义了与 eUICC 根安全域（ISD-R）通信的应用标识符：

A0 00 00 05 59 10 10 FF FF FF FF 89 00 00 01 00

CompatModule 负责精细化的通道管理：

• 使用 P2 参数 0x00 打开逻辑通道；
• 发送 GET DATA [BF 3E] 指令并进行 ASN.1 DER 解码，精准提取卡片 32 位 EID（Tag 0x5A）；
• 在基带状态从 NOT_READY 转换到 LOADED 过程中具备指数退避与安全重试能力。

为防止用户在 SIM2 插回普通手机卡时系统产生混乱，CardTypeGuard 实现了严格的失效关闭（Fail-Closed）安全策略：

• 监听卡槽状态变化广播（ACTION_SIM_CARD_STATE_CHANGED）；
• 异步向 SIM2 发送 ISD-R AID 握手探测；
• 若卡片无法响应 ISD-R 或为非 eUICC 普通 SIM 卡，CardTypeGuard 立即判定 eUICC = false，禁止系统执行任何 eSIM 相关逻辑，保持 SIM2 原生 UICC 通信正常；
• 隐私保护原则：系统 Secure 设置中绝不存储明文 ICCID 或 EID，仅存储 SHA-256 校验摘要（xiaomi_esim_h4_verified_iccid、xiaomi_esim_h4_verified_eid）。

小米官方板载 eSIM 逻辑在激活时会通过底层硬件 GPIO 切断物理 SIM1 的射频通路。对于双实体卡槽机型，这会导致用户的 SIM1 主卡瞬间断网无服务。 CompatModule 对 com.android.phone 与 com.miui.euicc 进行了深度拦截：

• Hook QcMiuiEsimManager、MiuiPhoneInterfaceManager 以及 XmLPAService；
• 拦截并短路 OEM GPIO/RF 切换方法（setSimType、switchSlot、isSupportEsim）；
• 确保 SIM1 主卡在 eSIM 启停、配置切换、EID 读取过程中始终保持 5G/4G/VoLTE 稳定连接，不受丝毫干扰。

针对插有真实在用 eSIM profile 的 ESTKme 卡片，本项目在设计之初即设立了严格的测试安全红线：

• 验证基准机型：Xiaomi MIX Flip 2（代号 bixi，测试序列号 f3d6d3d0）。
• 支持操作系统：Xiaomi HyperOS 4（基于 Android 15、Android 16、Android 17 / API 35+）。
• 通用机型支持：代码中已消除所有硬编码设备代号，适配所有 HyperOS 4 双卡小米机型。
• 实体 eSIM 卡：ESTKme 及其兼容系列可插拔实体 eUICC（必须放置在 SIM 卡槽 2）。

work/esim-adapt/
├── .gitignore                      # Git 忽略配置（忽略构建缓存、私钥等）
├── LICENSE                         # Apache 2.0 开源协议
├── README.md                       # 中英双语完整技术文档
├── build_module.py                 # Magisk/KernelSU 刷机包自动化打包脚本
├── finalize_release.py             # 发布完整性校验脚本（10 项发布断言）
├── prebuilt/
│   └── MIUIEsimLPA.apk             # 提取自官方 HyperOS 4 固件的未修改原版 LPA (v4.1.0.1)
├── probe/                          # Android Studio Gradle 工程
│   ├── app/                        # LSPosed 核心桥接模块 (io.github.local.esimh4probe)
│   │   └── src/main/java/io/github/local/esimh4probe/
│   │       ├── CompatModule.java       # LibXposed 入口与 APDU 通道路由
│   │       ├── CardTypeGuard.java      # Fail-closed ISD-R AID 探测与防护
│   │       ├── EuiccCardReader.java    # OMAPI 读卡器交互与 ASN.1 EID 解码
│   │       ├── Sim2Subscription.java   # 卡2订阅映射与状态同步
│   │       ├── Sim2Control.java        # CLI 诊断与状态辅助工具
│   │       ├── LpaBridgeActivity.java  # LPA 扫码与 Intent 桥接
│   │       └── MainActivity.java       # 模块本地诊断界面
│   └── tester/                     # 独立安全模拟测试应用 (io.github.local.esimh4tester)
│       └── src/main/java/io/github/local/esimh4tester/
│           └── TesterActivity.java     # 模拟运营商下载与弹窗验证 Activity
└── outputs/                        # 构建发布产物目录（ZIP 包、APK、SHA256 校验单）

1. 前往 Release 发布产物目录下载 XiaomiEsimLPA-HyperOS4-bixi-v0.4.0.zip。
2. 打开 KernelSU / Magisk / APatch 管理器，选择从本地安装刷入该 ZIP。
3. 模块安装脚本会自动对系统当前状态进行只读备份，存放于 /data/adb/xiaomi-esim-hyperos4/（权限 0700）。
4. 重启手机。

1. 打开 LSPosed 管理器应用。
2. 找到已安装的模块 「HYPEROS4实体ESIM桥接」（io.github.jabe1122.esimh4probe）。
3. 勾选并确保以下作用域已启用：
   • com.android.phone（电话服务）
   • com.miui.euicc（小米 eSIM LPA）
4. 请勿勾选无关系统应用。

1. 将 ESTKme 卡放入手机 SIM 卡槽 2。
2. 打开 KernelSU / Magisk → 进入本模块界面 → 点击 「操作」（Action）切换为开启。
3. 重启手机。
4. 进入系统设置 →「双卡与移动网络」→「eSIM」，此时系统即可正常读取 ESTKme 实体卡 EID 并管理配置。

为了让开发者能够安全地验证全部 LPA 交互流程，模块附带了独立测试应用 io.github.local.esimh4tester：

• 使用模拟激活码：LPA:1$test.esim.local$MOCK_ACTIVATION_CODE。
• TesterActivity 调用 EuiccManager.downloadSubscription 后：
  1. CompatModule 在 EuiccController 层拦截该域名请求；
  2. XmLPAService 捕获模拟请求并唤起原厂一键授权弹窗 DownloadConfirmDialogActivity；
  3. DpDownloadOperation 返回模拟安装成功；
  4. 物理卡内的所有真实在用 eSIM profile 100% 保持原样，不发生任何闪存写入或擦除。

• JDK 21 (jdk-21.0.13+9 或更高版本)
• Android SDK (API 35+ / SDK Build Tools 36.0.0)
• Gradle 8.11.1
• Python 3.10+

# 1. 编译模块 APK 与测试应用 APK
cd work/esim-adapt
gradle -p probe :app:assembleDebug :tester:assembleDebug

# 2. 自动化打包 KernelSU / Magisk 模块 ZIP
python build_module.py

# 3. 运行 10 项发布断言完整性校验并生成 SHA256SUMS.txt
python finalize_release.py

1. Root 风险声明：本模块需要 Root 权限以及 LSPosed 框架支持。请务必了解玩机风险。
2. 商标与版权说明：Xiaomi、HyperOS、MIUI、ESTKme、GSMA 等商标及产品名称归其各自所有者拥有。本项目为开源社区兼容性适配方案，与小米公司或 ESTKme 官方无隶属关系。
3. 免责保证：本项目按 Apache License 2.0 协议发布，作者对任何由于刷机或使用本模块产生的数据丢失或硬件故障不承担法律责任。

本项目基于 Apache License 2.0 许可证开源。详细条款请参阅 LICENSE 文件。 欢迎提交 Issue 与 Pull Request 共同改进 HyperOS 实体 eSIM 适配生态！

HyperOS 4 Physical eSIM Adaptation is a clean-room, production-grade integration and compatibility layer enabling physical removable eUICC smart cards (specifically ESTKme and compatible removable eSIM cards) to function seamlessly with Xiaomi HyperOS 4 (Android 15 / 16 / 17, API 35+) and official system LPA services (com.miui.euicc).

Traditionally, Chinese-mainland Xiaomi devices (such as Xiaomi MIX Flip 2 bixi) lack native eSIM hardware or restrict system-level eSIM features to specific carrier eSIM hardware profiles. This solution provides:

1. Full System-Level eSIM Capability: Exposes standard Android android.hardware.telephony.euicc system feature declarations and integrates the genuine, unmodified Xiaomi HyperOS 4 LPA (MIUIEsimLPA.apk v4.1.0.1) without tampering with OEM platform signatures.
2. Transparent Hardware Bridging: Routes logical channel APDUs from the Android framework directly to SIM slot 2 via OMAPI SEService, bypassing modem RIL channel limitations.
3. Fail-Closed Hardware Protection: Guarantees that ordinary non-eUICC SIM cards inserted in SIM2 are never misidentified or disrupted.
4. Primary SIM1 Radio Isolation: Completely protects SIM slot 1 (user's primary cellular service) by neutralizing OEM RF/GPIO antenna-multiplexer switches.
5. Zero Upstream Residue: Completely independent, modern object-oriented implementation, free of legacy or third-party proprietary code.

Under HyperOS 4, the native cellular Telephony RIL daemon frequently rejects opening logical channels for removable SIM trays when queried with GSMA eUICC identifiers. This project intercepts low-level APDU transmissions within CompatModule and establishes a transparent proxy to the Android Open Mobile API (android.se.omapi.SEService):

• Targets the SIM2 physical smart card reader (SIM2 / slot 1).
• Allocates unique virtual logical channel IDs starting at 12000+ (e.g., 12000, 12001, etc.).
• Multiplexes virtual channel IDs to underlying OMAPI channel sessions with strict lifecycle synchronization, preventing handle leakage and channel contention.

+--------------------------------------------------------------------+
|  Android Framework / Third-party Apps / Official MIUIEsimLPA.apk   |
+--------------------------------------------------------------------+
                                  |
                                  v
+--------------------------------------------------------------------+
|          CompatModule (LSPosed: com.android.phone / euicc)         |
|  - Channel Router (Intercepts Telephony APDU requests)             |
|  - Virtual Channel ID Pool (12000+)                                |
+--------------------------------------------------------------------+
           |                                         |
           | (Native RIL Failed / Fallback)          | (Standard UICC)
           v                                         v
+-----------------------------+           +--------------------------+
|  OMAPI SEService Bridge     |           | Native Telephony RIL     |
|  Reader: "SIM2"             |           | Physical Slot 0 (SIM1)   |
+-----------------------------+           +--------------------------+
           |                                         |
           v                                         v
+-----------------------------+           +--------------------------+
| ESTKme Removable eUICC Card |           | Carrier SIM1 Card        |
| Physical Slot 2 (Protected) |           | Untouched & Isolated     |
+-----------------------------+           +--------------------------+

The GSMA SGP.22 standard mandates communicating with the Issuer Security Domain Root (ISD-R) application using AID:

A0 00 00 05 59 10 10 FF FF FF FF 89 00 00 01 00

CompatModule manages the initialization sequence:

• Probes and establishes logical channels using P2 parameter 0x00.
• Executes ASN.1 DER parsing against GET DATA [BF 3E] to retrieve the 32-digit EID (Tag 0x5A).
• Incorporates automatic fallbacks when modem states fluctuate between NOT_READY and LOADED.

To prevent accidents when users swap cards, CardTypeGuard implements a strict fail-closed verification state machine:

• Probes SIM slot 2 upon card state transitions (ACTION_SIM_CARD_STATE_CHANGED).
• Verifies that the card legitimately responds to the ISD-R AID.
• If an ordinary SIM card (e.g., standard China Mobile / China Telecom / China Unicom SIM) is detected, CardTypeGuard immediately reports eUICC = false, aborts eSIM initialization, and prevents the system from disabling UICC communications on SIM2.
• Privacy Assurance: Plaintext ICCID and EID are never stored in Android settings. Only SHA-256 digests (xiaomi_esim_h4_verified_iccid, xiaomi_esim_h4_verified_eid) are retained in secure settings for identity matching.

Official Xiaomi devices equipped with factory-embedded eSIMs physically disconnect or reroute radio-frequency paths away from physical SIM1 via GPIO switches whenever eSIM mode is enabled. On dual-SIM tray devices adapted with ESTKme in SIM2, triggering this factory OEM logic would cause SIM1 to lose signal completely. CompatModule hooks com.android.phone and com.miui.euicc:

• Hooks QcMiuiEsimManager, MiuiPhoneInterfaceManager, and XmLPAService.
• Intercepts and drops OEM GPIO switching calls (setSimType, switchSlot, isSupportEsim).
• Guarantees 100% continuous cellular, VoLTE, and data service on SIM1.

When developing or testing with removable physical eSIM cards containing live, in-use user profiles, accidental card overwriting or memory wiping must be strictly prevented.

• Primary Tested Device: Xiaomi MIX Flip 2 (codenamed bixi, serial f3d6d3d0).
• Target OS: Xiaomi HyperOS 4 (Android 15, Android 16, Android 17 / SDK 35, 36, 37).
• Generic Support: Clean-room implementation without hardcoded device codenames. Fully functional across all HyperOS 4 dual-physical-SIM devices.
• SIM Card Hardware: ESTKme removable eUICC (placed in SIM slot 2).

• Root Solution: KernelSU, Magisk (v20.4+), or APatch.
  • Note for KernelSU: Requires an active metamodule (e.g., meta-overlayfs) to support system partition overlay mounting.
• Xposed Framework: LSPosed (API 101+ compatible with Android 15/16/17).

work/esim-adapt/
├── .gitignore                      # Comprehensive git ignore rules
├── LICENSE                         # Apache 2.0 Open Source License
├── README.md                       # Bilingual project documentation
├── build_module.py                 # Automated Magisk/KernelSU packaging script
├── finalize_release.py             # Release integrity validator & checksum generator
├── prebuilt/
│   └── MIUIEsimLPA.apk             # Official unmodified Xiaomi HyperOS 4 LPA (v4.1.0.1)
├── probe/                          # Android Studio Gradle Project
│   ├── build.gradle.kts            # Root Gradle build configuration
│   ├── settings.gradle.kts         # Subproject declarations
│   ├── app/                        # LSPosed Bridge Module (io.github.local.esimh4probe)
│   │   └── src/main/java/io/github/local/esimh4probe/
│   │       ├── CompatModule.java       # Core LibXposed hook entry & APDU router
│   │       ├── CardTypeGuard.java      # Fail-closed ISD-R AID validator
│   │       ├── EuiccCardReader.java    # OMAPI reader & ASN.1 EID extraction
│   │       ├── Sim2Subscription.java   # Subscription mapping & slot binding
│   │       ├── Sim2Control.java        # CLI diagnostic & state helper
│   │       ├── LpaBridgeActivity.java  # LPA intent and activation bridge
│   │       └── MainActivity.java       # Module diagnostic UI
│   └── tester/                     # Mock Carrier Testing App (io.github.local.esimh4tester)
│       └── src/main/java/io/github/local/esimh4tester/
│           └── TesterActivity.java     # Safe mock profile download & UI dispatcher
└── outputs/                        # Final distribution artifacts (ZIPs, APKs, Hashes)

1. Download XiaomiEsimLPA-HyperOS4-bixi-v0.4.0.zip from the release artifacts.
2. In KernelSU / Magisk / APatch, select Install from storage and flash the ZIP.
3. The installer creates a backup of current settings in /data/adb/xiaomi-esim-hyperos4/ (file mode 0700).
4. Reboot the device.

1. Open the LSPosed Manager.
2. Locate the installed HYPEROS4实体ESIM桥接 (io.github.jabe1122.esimh4probe).
3. Enable the module and select the following scopes:
   • com.android.phone (Phone Services)
   • com.miui.euicc (Xiaomi eSIM LPA)
4. Do not check unrelated system apps.

1. Insert your ESTKme card into SIM Slot 2.
2. Open KernelSU / Magisk → Xiaomi eSIM LPA - HyperOS 4 → tap Action.
3. Toggle mode to ON.
4. Reboot the device.
5. Navigate to Settings → Mobile Networks → eSIM. Your ESTKme EID and profiles will now be fully accessible.

The repository includes a dedicated test suite (probe/tester) and mock carrier architecture:

• Target mock domain: test.esim.local.
• When TesterActivity initiates EuiccManager.downloadSubscription using an activation code like LPA:1$test.esim.local$MOCK_TOKEN:
  1. CompatModule intercepts the request at EuiccController.
  2. XmLPAService intercepts the metadata discovery and presents the genuine Xiaomi DownloadConfirmDialogActivity.
  3. DpDownloadOperation simulates a successful profile download in memory.
  4. The physical ESTKme card is 100% untouched.

• JDK 21 (jdk-21.0.13+9 or newer)
• Android SDK (API 35+ / SDK Build Tools 36.0.0)
• Gradle 8.11.1
• Python 3.10+

# 1. Compile debug and release APKs
cd work/esim-adapt
gradle -p probe :app:assembleDebug :tester:assembleDebug

# 2. Package the KernelSU/Magisk flashable ZIP
python build_module.py

# 3. Validate release assertions and generate SHA256SUMS.txt
python finalize_release.py

1. Root Privilege Notice: This project requires root access and Xposed framework injection. Use at your own risk.
2. Third-Party Trademarks: Xiaomi, HyperOS, MIUI, ESTKme, and GSMA are trademarks of their respective owners. This project is an independent community adaptation and is not affiliated with or endorsed by Xiaomi Inc. or ESTKme.
3. No Warranty: This software is distributed under the Apache License 2.0 without warranties or conditions of any kind.

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Copyright 2026 HyperOS 4 eSIM Adaptation Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0