为 Xiaomi Pad 5 上的第三方 A1931 蓝牙键盘壳提供 Android 原生多点触控和 Windows Precision Touchpad 驱动支持的硬件适配项目。
Nabu A1931 Bridge
一个改装的键盘壳。两套原生输入栈。
为 Xiaomi Pad 5 上的第三方 A1931 键盘壳提供 Android 多点触控和 Windows Precision Touchpad 支持。
AI 生成的项目插图。我的相机把真实的setup拍得实在不怎么样，所以用这张图来保持 README 的美观。硬件和项目都是真实的；这张图片只是封面图。
## 下载并安装
大多数用户不需要 Git、Visual Studio、WinRM、SSH 或源码文件夹中的任何内容。
| | Android 13 | Windows 11 ARM64 |
| --- | --- | --- |
| 下载 | `Nabu-A1931-Android-v82.48.zip` | `Nabu-A1931-Windows-ARM64-v0.76.zip` |
| 这是什么？ | 一个带有受监督 Python 输入中继的 Magisk 模块 ZIP | 一个带有受保护 PowerShell 辅助程序的测试签名 UMDF 驱动程序包 |
| 它会自动运行吗？ | 是的。Magisk 会在开机后启动该中继。 | 是的。Windows 会为匹配的设备启动驱动程序；没有项目 daemon、托盘应用或窗口。 |
| 一次性准备 | 安装 Termux Python 3.13 和 `python-evdev` | 准备测试签名模式，重启，然后运行一条受保护的安装命令 |
| 完整指南 | **[在 Android 上安装](docs/android-install.md)** | **[在 Windows ARM64 上安装](docs/windows-install.md)** |
| 浏览源码 | [`android/`](android/) | [`windows/`](windows/) |
无论您选择哪个平台：
1. 检查[兼容性](docs/compatibility.md)。仅凭 `A1931 Keyboard` 这个名称并不能证明其他配件具有相同的固件。
2. 从同一个发布版本中下载该平台的 ZIP 文件和 `SHA256SUMS.txt`。
3. 在安装之前验证校验和，并准备好[恢复说明](docs/recovery.md)。
### Android 快速路径
准备一次 Termux，然后保持下载的模块 ZIP 文件原样。在 Magisk 中，打开 **Modules**，选择 **Install from storage**，选中 `Nabu-A1931-Android-v82.48.zip`，然后重启。有关两条前置命令和常规卸载方法，请参阅 [Android 页面](android/)。
### Windows 快速路径
这是一个驱动程序，而不是手动启动的 daemon。在测试签名准备就绪后，解压 `Nabu-A1931-Windows-ARM64-v0.76.zip`，阅读 `00-START-HERE.md`，然后从提升的 PowerShell 中运行受保护的安装程序。随后，Windows 会通过即插即用来管理其生命周期。有关确切的顺序以及为何在首次配对前进行准备很重要的原因，请参阅 [Windows 页面](windows/)。
## 本项目是什么
Nabu A1931 Bridge 使得一款 **为 iPad Air 4 制造的 GOOJODOQ 悬浮键盘壳**（通过 Bluetooth 通告为 `A1931 Keyboard`）能够在 **Xiaomi Pad 5 (`nabu`)** 上使用。该平板电脑在物理上被适配到了键盘壳中；这不是原装的 Xiaomi 配件、Apple Magic Keyboard 或厂商支持的配对。
原有的默认行为暴露了两个不同的故障：
| 平台 | 原始行为 | 当前结果 |
| --- | --- | --- |
| Android 13 | 键盘输入可用，但触摸板表面和轴语义无法清晰地映射到 Android 输入中。休眠和重新连接的行为也使得手动中继变得不切实际。 | 一个由 Magisk 管理的日常主力服务发布了一个原生的四触点 Linux protocol-B 触摸板。Android 负责处理加速、滚动、捏合和系统手势；中继在 MIUI 禁用它的情况下恢复了单指点击以实现点击操作。 |
| Windows 11 ARM64 | 配对或枚举设备反复触发 `SYSTEM_SERVICE_EXCEPTION`。当 Windows 创建指针设备时，匹配的 `0x3B` 转储到达了 `win32kbase!rimInUserCritCreatePointerDeviceInfo`。 | 一个精确匹配的 UMDF 过滤器保留了 Microsoft 的 HID-over-GATT 传输，替换了不安全的 HID 接口，并暴露了键盘、消费者控件以及一个 Windows Precision Touchpad 形状的集合。 |
目标不是为了广泛的设备兼容性。它是针对一个已知配件和一个已知平板电脑配置的受控、可逆的修复方案。
## 当前状态
| 目标 | 版本 | 状态 | 公开内容 |
| --- | ---: | --- | --- |
| Android | `82.48` | 日常主力候选版本；唤醒和深度休眠稳定性仍在连续测试中 | GPL 源码和 Magisk 候选发布版 ZIP |
| Windows ARM64 | `0.76` | 发布工作流已在项目平板电脑上验证 | GPL 源码和受保护的测试签名发布版 ZIP |
## 探索本项目
- **[Android 着陆页和源码](android/)**
- **[Windows 着陆页和源码](windows/)**
- **[带版本号的下载](https://github.com/ArgaAAL/nabu-a1931-bridge/releases)**
文档：
- [兼容性](docs/compatibility.md)
- [Android 安装](docs/android-install.md)
- [Windows ARM64 安装](docs/windows-install.md)
- [自定义按键、按钮和手势](docs/key-mappings.md)
- [从源码自定义映射](docs/customizing.md)
- [版本控制策略](docs/versioning.md)
- [回滚和恢复](docs/recovery.md)
- [故障排除](docs/troubleshooting.md)
- [支持和诊断](SUPPORT.md)
- [从源码构建](docs/building.md)
- [发布流程](docs/releasing.md)
- [当前候选发布版的验证](docs/release-validation-2026-07-29.md)
- [更新日志](CHANGELOG.md)
### Android
- 开机时作为 Magisk 服务启动，并接管已经正常运行的 relay，而不是启动重复的 worker。
- 处理键盘休眠、唤醒、设备节点替换和重新连接，无需手动启动脚本。
- 在默认路径将重复的触摸字段扁平化之前，保留所有四个固件接触记录。
- 发布有序的 protocol-B 插槽，以便 Android 自身的输入栈处理指针加速和多点触控手势。
- 将简短、静止的单指轻触恢复为即时的左键点击脉冲，而不会延迟或排队正常的移动。
- 使用专用的物理点击拖拽状态，这样第二根手指就可以移动按住的项目，而不会重复丢弃或替换逻辑接触。
- 将格式错误的物理 HID 排除在 MIUI 的框架输入注册之外，同时 root relay 继续读取其 kernel 事件节点。
- 消耗完整的锁定/电源键生命周期，并在唤醒期间保持对物理设备的 grab 状态，以便触摸板切换不会泄漏到电源/SOS 中。
- 为与已验证 Bluetooth 栈指纹不匹配的 Android 构建保留兼容性回退。
### Windows ARM64
- 仅匹配观察到的 A1931 HID-over-GATT 父设备，而不是过滤全局 Bluetooth 或 HID 类。
- 将收件箱 Microsoft HID-over-GATT 组件保留为受信任的 BLE 传输。
- 在 Windows raw input 看到原始指针接口之前，对描述符进行清理并翻译报告。
- 暴露键盘输入、媒体和亮度控制、四触点 Precision Touchpad 接口及其配置集合。
- 尽可能将单指移动、物理点击拖拽、双指滚动和辅助轻触、捏合以及三/四指手势留给 Windows 处理。
- 将原本没用的右上角电源键映射为本地触摸板切换。左下角的 Globe/Fn 键在 Windows 上被故意设置为无效。
- 从生产构建中编译掉了同步的每报告文件日志记录。WPR 追踪显示，在存储负载下，这些写入可能会阻塞高优先级的 UMDF 报告线程长达数百毫秒，从而导致输入延迟和光标瞬移。
## 架构
该仓库包含构建每个已发布 GPL 软件包所需的首选源码形式。原始 crash dump、个人设备标识符、开发凭据、签名私钥和私有部署基础设施均保留在仓库之外。
```
flowchart LR
HW[GOOJODOQ A1931
BLE HID reports]
HW -->|Android| AR[Relay service]
AR --> AK[Virtual keyboard
and consumer controls]
AR --> AT[Native protocol-B
multitouch device]
AT --> AI[Android InputReader]
HW -->|Windows ARM64| HG[Microsoft HidOverGatt]
HG --> WF[Exact-match
UMDF translator]
WF --> WK[Keyboard and
consumer collections]
WF --> WP[Precision Touchpad
and configuration collections]
WP --> WI[Windows input stack]
```
这种架构将策略敏感的 Bluetooth 传输保留在已获得授权执行该操作的平台组件内。然后，每个私有翻译器都会公开一个干净的原生输入契约，而不是试图让原始描述符在各处都能被接受。
## 兼容性
| 组件 | 已测试配置 |
| --- | --- |
| 主控平板 | Xiaomi Pad 5，代号为 `nabu`，Snapdragon 860，6 GB RAM |
| 键盘壳 | 第三方 GOOJODOQ iPad Air 4 悬浮键盘壳，Bluetooth 名称为 `A1931 Keyboard` |
| Android | Android 13，使用 Magisk 获取 root 权限，项目平板 Bluetooth 构建 |
| Windows | ReviOS 11 ARM64 24.06，内部版本 22621 和 22631 |
| 传输 | Bluetooth Low Energy HID over GATT |
| 观察到的触摸数据 | 在测试报告格式中最多支持四个同时接触点 |
目前未声明或不支持：
- 原装 Apple Magic Keyboard 硬件
- 恰好通告为 `A1931` 的其他产品
- 其他 Xiaomi 平板或 Android Bluetooth 构建
- Windows x64 系统
- 通用的系统级 HID 或 Bluetooth 修复
- 没有独立恢复路径的安装
## 工程证据
工作成果是通过捕获行为得出的，而不仅仅是靠描述符猜测：
1. Android 的 raw 和 cooked 输入捕获确立了物理接触和点击行为，这与虚拟设备无关。
2. 在将与摄像头和电源相关的 bugcheck 与 A1931 证据分离开来之后，Windows crash dump 将配对失败范围缩小到了指针设备的创建。
3. 精确匹配的隔离包证明，可以在不修改全局 Bluetooth 栈的情况下防止崩溃。
4. 连续的 UMDF 构建恢复了键盘和消费者输入，接着是鼠标行为、四触点遥测，最后是 Precision Touchpad 接口。
5. WPR/ETW 追踪将重负载输入突发与报告路径上的同步诊断文件写入联系起来；移除了生产日志记录，且未改变输入语义。
私有捕获可能包含设备标识符、本地路径、计时数据和用户输入。它们保留用于开发，但不是发布资产。
## 发布策略
官方发布只有在与其匹配的源码、兼容性检查、验证和回滚路径一起提供时才算完整。每次发布包括：
- 确切的兼容性清单和明确不支持的配置；
- 带有已测试 Android 或 Windows 构建的带版本号的更新日志；
- 安装、验证、回滚和恢复说明；
- 每个可下载产物的 SHA-256 校验和；
- 发布主机支持的构建来源或产物证明；
- 每个 GPL 二进制文件在 `GPL-3.0-only` 下相应的源码；
- 随平台软件包一起提供的完整源码归档；
- 不包含任何私有签名密钥、本地证书存储、原始捕获或部署凭据。
Android 和 Windows 软件包具有不同的风险概况，可能会独立发布。Windows 辅助程序减少了可避免的错误，但它并没有将测试签名、Secure Boot 或恢复要求隐藏在一键安装程序背后。
## 安全
低级输入更改可能会剥夺键盘或指针访问权限，干扰配对，或导致操作系统崩溃。因此，开发过程中使用了精确的硬件匹配、按需启动组件、版本验证和经过测试的回滚包。
该软件在 GPL-3.0 下提供，不提供任何担保。[`RISK_NOTICE.md`](RISK_NOTICE.md) 中总结了操作风险、安装程序责任以及该声明的局限性。
在进行任何 Windows 安装之前，目标设备必须具有有效的触摸输入和独立的恢复途径，例如 RDP/WinRM 或对 Windows 卷的离线访问。Android 测试同样需要 Magisk 恢复访问权限和已知的良好模块备份。
不要仅仅因为配件具有相似的产品名称就安装产物。Bluetooth 名称不是充分的兼容性标识符。
## 开放式开发
您无需许可即可阅读代码、构建代码、从中学习、提出 issue、提出补丁或维护 fork。本仓库中的软件是 `GPL-3.0-only` 下的自由软件：在保留 GPL 声明、源码义务和更改披露的前提下，欢迎重新分发和修改版本。
狭窄的上游支持政策是出于安全考虑，而不是为了设立门槛。一个 fork 可以在其自身的身份下添加其他硬件、固件或操作系统构建，而不会削弱官方软件包使用的精确匹配。在实质上进行修改的发行版不应将自己呈现为官方发布；请参阅 [`TRADEMARKS.md`](
)。
## 许可与身份
**项目负责人和维护者：** ArgaAAL
**软件版权：** 版权所有 (C) 2026 ArgaAAL。
软件源码和相应的二进制文件基于 [`GPL-3.0-only`](LICENSE) 授权。文档基于 [`CC-BY-SA-4.0`](LICENSING.md) 授权。贡献使用已分配给其目标路径的许可证。
软件许可证不授予将项目名称、徽标或官方发布身份用作修改构建品牌的权利。Fork 可以准确地描述其来源，但不得暗示认可或官方地位。请参阅 [`TRADEMARKS.md`](TRADEMARKS.md) 和 [`LICENSING.md`](LICENSING.md)。
仓库历史、带版本号的发布、校验和和和发布证明用于保留公共来源。它们是起源的证据，而不是许可证的替代品。
欢迎在 [`CONTRIBUTING.md`](CONTRIBUTING.md) 中规定的质量和隐私要求下做出贡献。
## 第三方声明
本项目是独立的，不隶属于 Xiaomi、GOOJODOQ、Apple、Google、Microsoft、Qualcomm 或 Magisk 项目，也未获得其授权、维护或认可。产品名称和商标归其各自所有者所有，仅用于标识兼容性和平台行为。
本项目不分发任何专有的供应商驱动程序、固件、签名密钥、徽标或机密的供应商材料。
为一个异常强大的键盘壳、一台被重新利用的平板电脑，以及最初与这两者都不兼容的两个操作系统而构建。