Files

skiinder 88ee4da089 docs: 添加Blinky键盘2.4G端详细设计文档

- 定义了键盘外设固件内实现2.4G端的设计方案
- 描述了基于专用local identity的dongle peer设计方案
- 详细说明了身份规划和模块职责分工
- 包含了行为模型、状态事件设计和UI设计
- 提供了分阶段实施建议和风险评估

2026-05-06 18:36:39 +08:00

11 KiB

Raw Blame History

Blinky 键盘 2.4G 端详细设计稿

1. 背景

当前 C:\projects\blinky 已经完成了外设侧多槽 BLE 基础能力：

Slot 1~3 对应普通 BLE 主机
identity 4 预留为 Dongle Slot
mode_policy_module 已经区分：
- MODE_SWITCH_BLE -> BLE_PROFILE_POLICY_GENERAL
- MODE_SWITCH_24G -> BLE_PROFILE_POLICY_DONGLE

但目前 identity 4 还只是“预留位”，没有真正落成完整的 dongle peer 行为。
本设计稿的目标，是定义如何在键盘外设固件内实现“2.4G 端”，参考 nrf_desktop 的外围设备侧 dongle peer 设计。

这里的“2.4G 端”在第一阶段的实现语义不是 ESB 或私有无线协议，而是：

键盘继续作为 BLE Peripheral
通过专用 local identity 与自家 dongle 建立专用连接
在产品层把该模式呈现为“2.4G”

这和 nrf_desktop 的 dongle peer 设计方向一致。

2. 设计目标

本方案的目标如下：

在当前键盘固件内实现专用 dongle peer
MODE_SWITCH_24G 时固定使用专用 identity 4
MODE_SWITCH_BLE 时继续使用普通 BLE 槽位 identity 1/2/3
dongle peer 与普通 BLE 槽位完全隔离
dongle peer 有独立 bond 和独立状态显示
Swift Pair 对普通 BLE 开启，对 dongle peer 默认关闭
后续为自家 dongle 识别准备一个最小 dev_descr 风格自定义 GATT 服务

本设计稿不包含“dongle central 固件”的实现，只定义键盘外设侧。

3. 参考基线

本设计主要参考本地 nrf_desktop 的外围设备侧设计：

c:\ncs\v3.2.3\nrf\applications\nrf_desktop\doc\ble_bond.rst
c:\ncs\v3.2.3\nrf\applications\nrf_desktop\doc\dev_descr.rst
c:\ncs\v3.2.3\nrf\applications\nrf_desktop\doc\qos.rst
c:\ncs\v3.2.3\nrf\applications\nrf_desktop\src\modules\dev_descr.c
c:\ncs\v3.2.3\nrf\applications\nrf_desktop\src\modules\qos.c

参考结论：

dongle peer 的核心不是新的无线协议，而是专用 Bluetooth local identity
外设与 dongle 的专用配对要和普通 BLE peer 隔离
dev_descr 是未来 dongle 识别外设的关键入口
QoS 是增强项，不是第一阶段前置条件

4. 当前工程现状

当前工程已经具备实现 dongle peer 的关键基础：

ble_bond_multi_module 已支持固定 identity 多槽
identity 1/2/3 已用于普通 BLE 槽位
identity 4 已预留为 Dongle Slot
mode_policy_module 已输出 BLE_PROFILE_POLICY_GENERAL / DONGLE
Swift Pair 已默认开启，并且在 identity 4 上默认关闭

5. 总体设计

5.1 核心设计结论

采用 nrf_desktop 风格的“专用 dongle peer”设计：

保持当前键盘为 BLE Peripheral
使用 identity 4 作为专用 dongle identity
以 MODE_SWITCH_24G 作为选择 dongle peer 的产品模式
普通 BLE 槽位 1/2/3 与 dongle peer 独立管理

也就是说：

2.4G 是产品语义
第一阶段实现仍然是 BLE Peripheral + 专用 identity

5.2 identity 规划

identity 规划继续固定如下：

Identity	角色	用途
`0`	默认 identity	不使用
`1`	BLE Slot 1	普通 BLE
`2`	BLE Slot 2	普通 BLE
`3`	BLE Slot 3	普通 BLE
`4`	Dongle Slot	专用 2.4G / dongle peer

设计原则：

identity 4 不参与普通槽位轮换
identity 4 不参与普通 BLE 设置页
identity 4 有独立 bond 和独立状态

6. 模块职责分工

6.1 `mode_policy_module`

职责保持不变：

根据拨杆位置输出 transport policy

当前定义：

MODE_SWITCH_BLE -> BLE_PROFILE_POLICY_GENERAL
MODE_SWITCH_24G -> BLE_PROFILE_POLICY_DONGLE

它不直接管理 bond，只输出“当前应该走哪种 BLE profile”。

6.2 `ble_bond_multi_module`

这是本方案第一阶段的主修改模块。

需要扩展职责：

支持根据 BLE_PROFILE_POLICY_DONGLE 固定选择 identity 4
普通 BLE 与 dongle peer 分开管理
提供 dongle peer 独立状态输出
提供 dongle peer 独立擦除操作

仍然保留已有职责：

普通 BLE 三槽切换
普通 BLE 三槽擦除
slot meta 持久化

6.3 `swift_pair_module`

职责保持：

普通 BLE 槽位启用 Swift Pair
dongle peer 默认关闭 Swift Pair payload

这和 nrf_desktop 的思路一致。

6.4 新增 `dev_descr_module`

建议新增一个最小版 dev_descr 风格服务。

目标：

给未来的 dongle 提供外设识别信息
不依赖设备名做唯一识别

第一阶段最小字段：

caps
hwid

后续可扩展：

role
product type
firmware revision

6.5 `qos_module`

第一阶段不做。

理由：

nrf_desktop 已明确说明自家 dongle 不依赖外围设备 QoS
当前先做 dongle peer identity 和识别就足够

7. 行为模型

7.1 普通 BLE 模式

条件：

MODE_SWITCH_BLE
BLE_PROFILE_POLICY_GENERAL

行为：

当前 active slot 只能为 1/2/3
UI 显示普通 BLE 三槽
允许普通 BLE 切槽和擦除
Swift Pair 默认开启

7.2 2.4G / Dongle 模式

条件：

MODE_SWITCH_24G
BLE_PROFILE_POLICY_DONGLE

行为：

当前 active identity 固定为 4
当前 bond 只属于 identity 4
不允许普通 BLE 三槽逻辑影响 identity 4
Swift Pair 默认关闭
UI 应显示：
- Dongle Searching
- Dongle Paired
- Dongle Connected
- Dongle Empty

7.3 模式切换语义

BLE -> 24G

mode_policy_module 发布 BLE_PROFILE_POLICY_DONGLE
ble_bond_multi_module 切 active identity 到 4
提交 PEER_OPERATION_SELECTED
CAF ble_adv 切到 identity 4
当前连接断开
使用 identity 4 广播
dongle 重连

24G -> BLE

mode_policy_module 发布 BLE_PROFILE_POLICY_GENERAL
ble_bond_multi_module 恢复普通 BLE 当前槽位 1/2/3
提交 PEER_OPERATION_SELECTED
CAF ble_adv 切回对应 identity
当前连接断开
使用普通 BLE 槽位广播

8. 状态与事件设计

8.1 当前已有事件

可继续复用：

transport_policy_event
ble_peer_event
ble_peer_operation_event
ble_bond_multi_event

8.2 建议扩展 `ble_bond_multi_event`

建议增加字段或语义：

active_profile
- GENERAL
- DONGLE
dongle_slot_meta
- occupied
- last_peer_addr
- display_name
current_identity

如果不想改现有事件结构，也可以新增一个独立事件：

ble_dongle_state_event

推荐字段：

state
- EMPTY
- SEARCHING
- PAIRED
- CONNECTED
identity_id
display_name

8.3 UI 状态来源

主界面与设置页可以通过以下信息判断：

当前 mode
当前 active_identity_id
identity 4 是否有 bond
当前是否有连接且该连接属于 identity 4

9. `dev_descr` 设计

9.1 目标

最小化模仿 nrf_desktop dev_descr：

为 dongle 提供一个稳定可读的识别服务
避免仅靠设备名判断

9.2 服务内容

建议服务包含两个 characteristic：

Characteristic 1: `caps`

建议字节布局：

bit0: supports_llpm
bit1: supports_dongle_peer
bit2: is_keyboard

第一阶段只要能读出：

这个设备支持 dongle peer
这是 keyboard 类型

Characteristic 2: `hwid`

固定长度硬件 ID：

用于以后让 dongle 唯一识别这把键盘
也可用于配置通道映射

9.3 权限建议

建议与 nrf_desktop 保持一致：

BT_GATT_PERM_READ_ENCRYPT

原因：

避免未加密链路上暴露识别信息

9.4 依赖

需要：

CONFIG_HWINFO
固件内已有或新增 hwid_get() 辅助逻辑

10. Settings 设计

继续沿用现有 namespace：

ble_multi/current_slot
ble_multi/meta/1
ble_multi/meta/2
ble_multi/meta/3
ble_multi/meta/4

其中 meta/4 现在正式用于 dongle peer。

建议 meta/4 字段仍保持：

occupied
last_peer_addr
display_name

显示策略：

有真实名字则显示名字
否则显示 MAC 地址
无 bond 显示 Empty

11. UI 设计

11.1 主界面

当前主界面可新增或扩展显示：

当前模式 USB / BLE / 24G
如果 24G 模式：
- 右上角额外状态位显示：
  - searching
  - connected

现有 BLE LINK 状态位可以复用，但语义建议细化：

BLE 模式下：表示普通 BLE 当前槽状态
24G 模式下：表示 dongle peer 状态

11.2 设置页

建议新增二级入口：

Bluetooth
- Slot 1
- Slot 2
- Slot 3
- Erase Current
Dongle
- Status
- Erase Dongle Bond

第一阶段如果不想扩菜单，至少要做到：

主界面显示 dongle peer 状态
设置页不把 identity 4 混入 Slot 1~3

12. 分阶段实施建议

阶段 1：Dongle Slot 真正接线

内容：

ble_bond_multi_module 支持 BLE_PROFILE_POLICY_DONGLE
MODE_SWITCH_24G 时固定切到 identity 4
identity 4 独立 bond 和独立状态
Swift Pair 在 identity 4 默认关闭

交付标准：

24G 模式和 BLE 模式切换时 identity 正确切换
identity 4 与 1/2/3 完全隔离

阶段 2：UI / 状态管理

内容：

增加 dongle 状态显示
增加独立擦除 dongle bond 入口
不把 dongle 混入普通 BLE 三槽 UI

交付标准：

用户可以明确区分：
- 普通 BLE 槽位
- 2.4G / dongle peer

阶段 3：最小 `dev_descr`

内容：

实现最小自定义 GATT service
提供 caps + hwid

交付标准：

未来 dongle 可稳定识别这把键盘

阶段 4：后续增强（非当前范围）

可选项：

QoS
更强的 dongle 配对约束
生产预绑定
更明确的 dongle selector/恢复流程

13. 风险与边界

13.1 “2.4G” 实际仍然是 BLE

第一阶段产品语义是 2.4G，链路实现仍是 BLE。
这没有问题，但必须在代码和文档中明确，避免后续和真正私有 2.4G 链路混淆。

13.2 `dev_descr` 与未来 dongle 要对齐

如果未来 dongle 端也参考 nrf_desktop central，那这里的 UUID 和字段应该尽量稳定，不要后面再频繁改。

13.3 `identity 4` 与普通 UI 必须隔离

一旦 identity 4 被误混入普通三槽，就会造成用户理解混乱：

不知道哪个是普通蓝牙
哪个是 2.4G

这是 UI 设计上最需要避免的问题。

14. 结论

本方案建议把当前键盘的“2.4G 端”实现为：

BLE Peripheral + 专用 Dongle identity
MODE_SWITCH_24G 时固定走 identity 4
与普通 BLE 三槽完全隔离
第一阶段先打通 identity / bond / UI 状态
第二阶段补最小 dev_descr
QoS 暂缓

这条路径与 nrf_desktop 外设侧的 dongle peer 设计一致，也与当前工程已有的 transport_policy_event 语义完全匹配。

11 KiB Raw Blame History Unescape Escape

Blinky 键盘 2.4G 端详细设计稿

1. 背景

2. 设计目标

3. 参考基线

4. 当前工程现状

5. 总体设计

5.1 核心设计结论

5.2 identity 规划

6. 模块职责分工

6.1 mode_policy_module

6.2 ble_bond_multi_module

6.3 swift_pair_module

6.4 新增 dev_descr_module

6.5 qos_module

7. 行为模型

7.1 普通 BLE 模式

7.2 2.4G / Dongle 模式

7.3 模式切换语义

BLE -> 24G

24G -> BLE

8. 状态与事件设计

8.1 当前已有事件

8.2 建议扩展 ble_bond_multi_event

8.3 UI 状态来源

9. dev_descr 设计

9.1 目标

9.2 服务内容

Characteristic 1: caps

Characteristic 2: hwid

9.3 权限建议

9.4 依赖

10. Settings 设计

11. UI 设计

11.1 主界面

11.2 设置页

12. 分阶段实施建议

阶段 1：Dongle Slot 真正接线

阶段 2：UI / 状态管理

阶段 3：最小 dev_descr

阶段 4：后续增强（非当前范围）

13. 风险与边界

13.1 “2.4G” 实际仍然是 BLE

13.2 dev_descr 与未来 dongle 要对齐

13.3 identity 4 与普通 UI 必须隔离

14. 结论

11 KiB

Raw Blame History

6.1 `mode_policy_module`

6.2 `ble_bond_multi_module`

6.3 `swift_pair_module`

6.4 新增 `dev_descr_module`

6.5 `qos_module`

8.2 建议扩展 `ble_bond_multi_event`

9. `dev_descr` 设计

Characteristic 1: `caps`

Characteristic 2: `hwid`

阶段 3：最小 `dev_descr`

13.2 `dev_descr` 与未来 dongle 要对齐

13.3 `identity 4` 与普通 UI 必须隔离