huizhi's Aside
Go back

从原理到应用：智能魔方开发接入全景指南

Edit page

人工撰写，可放心食用~（约 3800 字，阅读时间约 15 min）

背景与前言

过去半年多，我先后尝试在 Web、Android 和 Windows 平台接入智能魔方，并将其应用于智能计时训练、操作映射等场景

本文不含具体的代码和协议，只是简单介绍智能魔方的连接原理、开发资料、技术栈选择、多品牌兼容，以及协议之上的应用方式

全文默认指智能三阶，协议相关信息截止到 2026.7

以下是内容大纲，可按需阅读：

难免存在纰漏，欢迎指出，一起交流~

原理 —— 一次完整连接是怎样发生的

基础概念

BLE 与 GATT 数据模型

连接过程

智能魔方连接流程

  1. 扫描和识别： 客户端扫描附近的 BLE 广播设备，根据设备名称、Service UUID、Manufacturer Data 等信息，初步判断魔方品牌和协议类型，例如 Moyu32、GAN、QiYi
  2. 建立 BLE 连接： 用户选择设备后，客户端与智能魔方建立连接，并开始进行 GATT 服务发现，获取魔方提供的 Service 和 Characteristic 结构
  3. 确认协议类型： 客户端结合广播信息、Service UUID、特征值等信息，确认具体协议版本，从而选择对应的解析实现
  4. 完成协议初始化： 不同品牌和协议的初始化过程有所差异，通常包括找到收发数据的 Characteristic、启用 Notify，以及在需要时初始化加密参数、发送设备信息或状态请求
  5. 同步初始状态： 客户端接收 Characteristic 返回的原始数据，经过解密、校验和解析，取得当前魔方状态、电量、转动序号等基础信息
  6. 接收后续数据： 连接保持期间，智能魔方会通过 Notify 主动上报转动和姿态等实时事件；完整状态、电量等信息也可由客户端主动请求，再由魔方通过 Notify 返回
  7. 应用层处理： 协议层将不同协议的数据转换为统一的转动和姿态事件，应用层再根据实际场景进行处理，例如智能计时训练、多人对战或操作映射

不同品牌智能魔方以及协议的概述

这里主要对三大品牌（魔域，奇艺，GAN）的智能魔方以及协议进行简单介绍：

魔域（MoYu）： 按时间顺序，协议分为三个版本：

目前在售的基本只有 MoYu32 系列

奇艺（QiYi）： 仅一套协议，适用于 QYSC （奇艺智能）以及 Tornado V4（风 AI），后者相比前者多了陀螺仪的上报

GAN： 分为四个版本：Gen1、Gen2、Gen3、Gen4 协议与部分魔方型号的对应关系：

来自 afedotov/gan-web-bluetooth，其中提到的 “GAN14 ui FreePlay” 存疑 —— 我并未查询到任何有关 GAN 14ui FreePlay 的发售信息

从时间线推测，Gen4 应该是较新的一代产品所使用的协议

资料 —— 从哪里开发接入智能魔方

推荐的参考资料

以上是相对推荐的几个， 还有不少的开源计时器项目涉及到了智能魔方，也有一定的参考价值（感谢开源社区~）

参考终究只是参考，具体表现仍然需要通过充分测试来验证

取舍 —— 实际技术栈该如何选择

这里主要讨论 Web，Android 和 Windows，以及简单补充 iOS（暂无 mac OS/Linux 开发经验，不作讨论）

开发平台取舍对比

Web

Android（优先推荐）

如果智能魔方是核心功能，推荐 Kotlin + Jetpack Compose —— Android 原生 + 现代化 UI 开发
或者 Kotlin 为主、Java 实现协议核心（即 RubiKey-Android 所使用的技术栈）

Windows

特点与 Android 类似，但作为桌面端，有以下几个特点：

WinUI 3、Tauri 和 Electron 等框架都能够实现 BLE 连接，但实现路径和开发成本存在差异，要补充的两点是：

WinUI 3 虽然颜值很高，但组件生态、复杂交互能力有限（例如 SharpTimer）
对于更完美的桌面级客户端，Tauri + Rust 是我的理想方案

iOS

iOS 作为移动端，也有不少用户；
开发上需要 macOS & Xcode ；上架到 App Store 需要开发者账号，以及材料与审核；
因此，如果暂无 macOS 设备以及 iOS 开发经验，不建议优先考虑

总结

难点 —— 多品牌兼容过程的真正麻烦

多品牌兼容性测试覆盖

这里也只讨论三大品牌的兼容，其他品牌（Go，Giiker 等）在国内很少使用：

设备准备

在原理部分已经初步介绍过三大品牌的协议，如果希望在开发测试阶段对热门的全品牌进行充分适配，那么至少需要 4~5 款智能魔方：即 Moyu32，QYSC，Tornado V4，GAN Gen2/Gen4

其中：

如果扩展到智能计时器，三大厂也分别具有，需要额外准备；
不过智能计时器之间的协议差异我暂未研究，只接入过奇艺智能魔方计时器

开发与测试

尽管大部分协议与代码较为成熟，但实际的适配过程中需要考虑边缘情况 —— 不同语言 / 技术栈下的表现有所差异，应当通过多品牌的充分测试来保证稳定性

当前也可通过反馈和日志，选择让拥有对应设备的用户配合测试来进行适配 —— 但效率可想而知

我不建议任何未经过充分测试的协议与设备上线

在充分完成本地的多品牌兼容测试之后，也不意味着上线就足够稳 —— 不同型号的设备/系统的表现又会不同 …容易出现各种神秘的问题，这里不再展开

总结

对于多品牌兼容，测试 > 代码，测试需要覆盖尽可能全的设备

应用 —— 智能魔方映射类项目的核心

对于智能魔方，计时训练 / 专项训练 / 数据分析 往往是主要功能点，但扩展到娱乐部分，映射操作类的项目往往更有意思，更吸引人（也更有流量 bushi）

例如这些映射类项目：

它们的本质/核心都很简单，即前面介绍过的连接过程的应用层处理部分，由一般的计时训练改为外部映射，例如安卓的无障碍服务，Nodejs 的 nut-js，也可以再单独封装 API 来控制智能家具类的硬件 —— 映射层足够自由

智能魔方映射层架构

实践 —— 个人项目介绍与展望

个人项目介绍

最后夹带私货，简单介绍一下相关的个人项目~

DCTimer-BLE

已历经两个月，6 个版本的迭代优化，欢迎体验，提出建议~
软件官网：DCTimer-BLE —— 支持智能魔方的优化版 DCTimer
开源仓库：huizhiLLL/DCTimer-BLE: 基于 DCTimer，支持智能魔方并改进部分功能

RubiKey

一个较为简单的映射类项目，即通过无障碍服务让智能魔方操控安卓设备，即可实现智能魔方刷视频、看小说、听音乐、充当游戏手柄（例如地铁跑酷）等操作，同样支持三大品牌智能魔方，欢迎尝试

开源仓库：huizhiLLL/RubiKey-Android: 智能魔方控制安卓设备
下载地址：

也是前文已提到的 Kotlin + Java + Jetpack Compose 的技术栈（为了直接复用 DCTimer-BLE 较为成熟的协议层）

展望

说是展望，实际上只是个提一嘴的理想需求

即需要一个足够轻量的，多品牌多平台适配的，智能魔方在线对战客户端 不仅解决多品牌下，不同智能魔方无法在线 pk 的需求，也可以解决部分场景下的在线周赛/月赛问题 可以摆脱分品牌 + 腾讯会议等的约束，使用一种非同步实时竞技的在线比赛，同时间段内同打乱异步进行，由于智能魔方，可以自动录入，并高度对接赛事平台

嗯，只是想想，如果真的有人做出一个比较完美的，还是很有价值的…

参考资料

Edit page
Next Post
发布 DCTimer-BLE 后，我对软件开发理解的变化