blinky/docs/ble_multi_slot_design.md

Blinky 多槽蓝牙设计方案

1. 目标与约束

为 C:\projects\blinky 增加多槽蓝牙能力，当前阶段只实现 BLE，多 dongle 方案先预留结构，不实现完整业务流程。

本方案已经按当前讨论结论收敛为以下硬约束：

• 支持 3 个 BLE 槽位 Slot 1~3
• 每个槽位固定对应一个 Bluetooth local identity
• 槽位切换本质上是切换 bt_identity_id
• 不引入 app_slot_id
• 不使用临时 identity
• 不做 erase advertising
• 不做擦除确认
• 不做擦除回滚
• 擦除当前槽位时直接删除该 identity 上的 bond
• settings 只持久化 current_slot 和各槽位 meta
• slot_meta 中必须保留 display_name，用于 UI 显示
• 24G / dongle 采用方案 A，但本阶段只预留专用槽位

2. 本地参考基线

本方案主要参考本地 NCS 3.2.3 中以下实现和文档：

• c:\ncs\v3.2.3\nrf\applications\nrf_desktop\doc\ble_bond.rst
• c:\ncs\v3.2.3\nrf\applications\nrf_desktop\src\modules\ble_bond.c
• c:\ncs\v3.2.3\nrf\applications\nrf_desktop\src\modules\Kconfig.ble_bond
• c:\ncs\v3.2.3\nrf\include\caf\events\ble_common_event.h
• c:\ncs\v3.2.3\nrf\subsys\caf\modules\ble_adv.c
• c:\ncs\v3.2.3\nrf\subsys\caf\modules\Kconfig.ble_state
• c:\ncs\v3.2.3\nrf\doc\nrf\libraries\caf\ble_state.rst

参考方式如下：

• 继承 nrf_desktop 的总体方向：应用自定义 bond 管理模块，而不是 CAF 默认 ble_bond
• 继续通过 ble_peer_operation_event 驱动 CAF ble_adv
• 保留 dongle 专用 identity 的规划方式

明确不采用 nrf_desktop 的部分：

• 不使用 app_slot_id <-> bt_identity_id 的二级映射
• 不使用临时 identity
• 不采用 ERASE_ADV
• 不采用“新配对成功后再替换旧槽位”的回滚保护机制

3. 对现有项目的判断

blinky 当前已经具备多槽蓝牙需要的大部分基础能力：

• 已启用 CONFIG_CAF_BLE_STATE
• 已启用 CONFIG_CAF_BLE_ADV
• 已启用 CONFIG_BT_SETTINGS
• HID 和 NUS 都已基于 ble_peer_event 跟踪当前连接
• UI 已经预留 3 个蓝牙槽位和擦除当前槽位入口
• 模式策略层已经区分：
  • MODE_SWITCH_BLE -> BLE_PROFILE_POLICY_GENERAL
  • MODE_SWITCH_24G -> BLE_PROFILE_POLICY_DONGLE

相关文件：

• C:\projects\blinky\src\ble_hid_module.c
• C:\projects\blinky\src\ble_nus_module.c
• C:\projects\blinky\src\ui\ui_settings_ble.c
• C:\projects\blinky\src\ui\ui_settings_controller.c
• C:\projects\blinky\src\mode_policy_module.c
• C:\projects\blinky\prj.conf

当前限制也很明确：

• CONFIG_BT_MAX_PAIRED=1，全设备只能保存 1 个 bond
• 当前是单槽逻辑
• 还在使用 CAF 默认 CONFIG_CAF_BLE_BOND=y
• UI 的槽位状态仍是内存假数据

4. 配置语义结论

基于本地 Kconfig 和 CAF 文档，关键配置的含义如下：

• CONFIG_BT_MAX_PAIRED 说明：整个设备允许保存的 bond 总数
• CONFIG_CAF_BLE_STATE_MAX_LOCAL_ID_BONDS 说明：每个 Bluetooth local identity 允许的 bond 数上限
• CONFIG_BT_ID_MAX 说明：设备允许使用的 local identity 总数

如果目标是：

• 3 个 BLE 槽位
• 每槽 1 个 bond
• 预留 1 个 dongle 槽位

那么推荐配置应为：

CONFIG_BT_MAX_CONN=1
CONFIG_BT_MAX_PAIRED=4
CONFIG_CAF_BLE_STATE_MAX_LOCAL_ID_BONDS=1
CONFIG_BT_ID_MAX=5

语义如下：

• BT_MAX_CONN=1 说明：同时只保持 1 条 BLE 连接
• BT_MAX_PAIRED=4 说明：全设备最多保存 4 个 bond
• CAF_BLE_STATE_MAX_LOCAL_ID_BONDS=1 说明：每个 identity 只允许绑定 1 个主机
• BT_ID_MAX=5 说明：可用 identity 为 0..4

配合本方案的 identity 规划：

• 0：默认 identity，不参与槽位
• 1：Slot 1
• 2：Slot 2
• 3：Slot 3
• 4：Dongle Slot 预留

5. 总体架构

5.1 设计结论

建议采用：

• 保留 CAF_BLE_STATE
• 保留 CAF_BLE_ADV
• 关闭 CAF 默认 BLE_BOND
• 新增应用自定义模块 ble_bond_multi_module

即：

• CONFIG_CAF_BLE_BOND=n
• 新增 CONFIG_BLINKY_BLE_BOND_MULTI
• 自定义模块 select CAF_BLE_BOND_SUPPORTED
• 由自定义模块向 CAF 提交 ble_peer_operation_event

原因：

• CAF 默认 ble_bond 不适合固定多 identity 槽位管理
• 你的需求已经明确不需要 nrf_desktop 那种复杂映射和回滚流程
• 自定义模块更适合和现有 UI、模式策略、settings 同步

5.2 核心模型

本方案直接把“槽位”和“identity”绑定：

• Slot 1 = bt_identity_id 1
• Slot 2 = bt_identity_id 2
• Slot 3 = bt_identity_id 3
• Dongle Slot = bt_identity_id 4

所以：

• current_slot 实际上就是当前使用的 bt_identity_id
• UI 显示“Slot 1/2/3”时，后端直接映射到固定 identity
• 不再存在可变的 id_lut

这个设计的优点：

• 逻辑简单
• settings 简单
• 调试简单
• 后续接入 dongle 不需要迁移已有 BLE 槽位

6. identity 规划

建议固定如下：

identity	角色	当前阶段
0	默认 identity	不使用
1	BLE Slot 1	使用
2	BLE Slot 2	使用
3	BLE Slot 3	使用
4	Dongle Slot	预留

设计原则：

• 不使用 BT_ID_DEFAULT 原因：默认 identity 的 reset/unpair 行为不适合作为固定槽位基线
• 3 个 BLE 槽位 identity 固定不变
• identity 4 只给 BLE_PROFILE_POLICY_DONGLE

7. 模块设计

7.1 新增模块和文件

建议新增：

• src/ble_bond_multi_module.c
• src/events/ble_bond_multi_event.c
• inc/events/ble_bond_multi_event.h

不建议新增：

• inc/ble_bond_multi.h

原因：

• 当前设计是事件驱动模块
• 没有必要向外暴露一组直接调用 API
• 共享内容更适合放在事件头文件里

只有在后续出现明确的跨模块直接调用需求时，才需要再补 inc/ble_bond_multi.h

7.2 模块职责边界

ble_bond_multi_module

负责：

• 管理当前活动 bt_identity_id
• 启动时恢复 current_slot
• 维护各 identity 槽位的 slot_meta
• 处理“切换当前槽位”
• 处理“直接擦除当前槽位”
• 监听连接、加密、断链事件，更新 slot_meta
• 向 CAF 提交 ble_peer_operation_event
• 向 UI / 显示层广播槽位状态

不负责：

• 发 HID/NUS 数据
• 改 GATT 服务
• 绘制 UI

ble_hid_module / ble_nus_module

保持现有思路，不理解“多槽逻辑”，只跟随当前活动连接：

• 连接上谁，就服务谁
• 切槽或擦除造成断链时，内部复位连接状态

mode_policy_module

负责决定当前是：

• BLE_PROFILE_POLICY_GENERAL
• BLE_PROFILE_POLICY_DONGLE

但不负责槽位 bond 细节。

8. 状态机设计

第一阶段建议极简化，只保留：

• DISABLED
• IDLE
• SWITCHING
• ERASING

明确不引入：

• SELECT_SLOT
• ERASE_PENDING
• ERASE_ADV
• TEMP_IDENTITY
• ROLLBACK

8.1 切槽流程

1. 用户在 UI 选择 Slot N
2. 模块判断：
   • 如果 N == current_slot，直接返回
   • 否则进入 SWITCHING
3. 提交 PEER_OPERATION_SELECTED
4. CAF ble_adv 切换当前 advertising identity
5. 当前连接断开
6. 设备以新 identity 重新广播
7. 目标主机重新连接
8. 保存新的 current_slot
9. 返回 IDLE

这里采用“直接切换”，不做预选确认。

8.2 擦除当前槽位流程

1. 用户选择“Erase Bond”
2. 模块进入 ERASING
3. 对当前 bt_identity_id 执行：
   • bt_unpair(identity, BT_ADDR_LE_ANY)
4. 清除该槽位 slot_meta
5. 重新以当前 identity 进入可配对广播
6. 返回 IDLE

这里采用产品级简化语义：

• 不确认
• 不保护旧配对
• 不回滚
• 擦除后旧主机立即失效

9. Settings 设计

9.1 持久化范围

只持久化：

• current_slot
• 各槽位 slot_meta

不持久化：

• id_lut
• 临时 identity 状态
• 擦除中间态

9.2 settings namespace

建议采用：

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

其中：

• 1/2/3 是 BLE 槽位
• 4 是 dongle 预留槽位

9.3 slot_meta 结构

slot_meta 建议固定包含以下字段：

• occupied
• last_peer_addr
• display_name

字段说明：

• occupied 说明：该槽位当前是否有有效 bond
• last_peer_addr 说明：最近一次绑定主机的 BLE 地址，用于识别和调试
• display_name 说明：UI 显示名，不做简化，作为正式字段保留

这里 display_name 是明确保留项，不是可选优化项。
设计目的就是让 UI 能直接显示：

• MacBook Pro
• iPad Mini
• Windows-PC

而不是只能显示 Bonded / Empty。

9.4 display_name 来源

需要注意一点：

• Zephyr bond 本身不会自动提供“友好主机名”

因此 display_name 的来源需要在实现阶段明确，一般有两个方向：

1. 配对后由应用层通过协议或自定义方式写入
2. 若当前阶段无法拿到真实主机名，则先允许 UI/上位机为该槽位写入名称

也就是说：

• display_name 必须作为正式持久化字段存在
• 但其填充机制可以分阶段实现

第一阶段如果没有自动名称来源，建议默认值如下：

• 有 bond 但无名称："Bonded Device"
• 无 bond：空串或 "Empty"

10. UI 设计

现有 UI 结构已经适合复用，不建议重做。

现有文件：

• C:\projects\blinky\src\ui\ui_settings_ble.c
• C:\projects\blinky\src\ui\ui_settings_controller.c

建议交互规则如下：

• 进入 BLE 设置页后显示 Slot 1~3
• 每个槽位 value 直接显示 display_name
• 若该槽位无 bond，则显示 Empty
• 当前槽位显示为 Slot N
• 擦除项显示为 Erase Slot N

操作方式：

• 选中某个槽位后直接切换
• 选中擦除项后直接擦除
• 不加确认页

UI 需要的数据来源：

• current_slot
• slot_meta[1]
• slot_meta[2]
• slot_meta[3]

所以建议 UI 不再维护本地假数据，而改为订阅 ble_bond_multi_event 或读取统一状态缓存。

11. 与模式切换的兼容设计

11.1 BLE 档

MODE_SWITCH_BLE 下：

• 只允许使用 identity 1/2/3
• UI 允许切槽和擦除
• current_slot 必须属于 1..3

11.2 24G / dongle 档

采用方案 A：

• MODE_SWITCH_24G 绑定专用 identity 4
• identity 4 不与普通 BLE 槽位混用
• 第一阶段只预留，不实现完整 dongle bond 生命周期

这样做的好处：

• 保持 mode_policy_module.c 现有设计语义
• 普通 BLE 槽位和 dongle 配对状态不会互相污染
• 后续接入 dongle 时无需改动 BLE 三槽数据模型

12. 事件设计

建议新增应用事件：

• ble_bond_multi_event

放在：

• inc/events/ble_bond_multi_event.h
• src/events/ble_bond_multi_event.c

字段建议：

• current_slot
• active_identity_id
• slot_occupied_bitmap
• slot_meta_summary
• op

至少要能支持：

• UI 刷新槽位名称
• 显示层提示当前槽位
• 设置层同步当前 active slot

继续复用 CAF 事件：

• ble_peer_event
• ble_peer_operation_event

第一阶段不需要依赖：

• ble_peer_search_event

13. 对现有代码的影响评估

13.1 必改

• prj.conf
• CMakeLists.txt
• 新增 src/ble_bond_multi_module.c
• 新增 inc/events/ble_bond_multi_event.h
• 新增 src/events/ble_bond_multi_event.c
• ui_settings_controller.c

13.2 小改

• mode_policy_module.c 说明：把 BLE_PROFILE_POLICY_GENERAL 约束到 identity 1/2/3，把 BLE_PROFILE_POLICY_DONGLE 预留到 identity 4
• display_module.c 说明：如果要显示当前槽位或名称，需要订阅新事件

13.3 原则上不应大改

• ble_hid_module.c
• ble_nus_module.c
• keyboard_core_module.c

这些模块只应该感知当前连接状态，不承担槽位管理职责。

14. 实施分阶段建议

阶段 1：固定 identity 多槽骨架

• 替换 CAF 默认 ble_bond
• 新增 ble_bond_multi_module
• 固定 identity 1/2/3 为 BLE 槽位
• 预留 identity 4 为 dongle 槽位
• 恢复和保存 current_slot
• 打通直接切槽

交付标准：

• Slot 1~3 可以切换
• 每个槽位 bond 独立
• 重启后当前槽位可恢复

阶段 2：slot_meta 与 UI 打通

• 维护 occupied
• 维护 last_peer_addr
• 正式持久化 display_name
• UI 改为显示真实槽位数据

交付标准：

• 屏幕上显示真实槽位名
• display_name 可稳定持久化

阶段 3：直接擦除与 dongle 预留对齐

• 实现当前槽位直接 unpair
• 擦除后刷新 slot_meta
• 擦除后重新进入可配对状态
• 明确 identity 4 的模式入口

交付标准：

• 擦除后旧主机不能再连接
• 当前槽位可重新配对
• 24G 路径已有干净预留点

15. 风险与注意事项

15.1 直接擦除的用户体验

本方案放弃回滚能力。
一旦擦除：

• 旧 bond 立即失效
• 用户必须重新配对

这是当前明确接受的产品行为。

15.2 display_name 获取机制

display_name 虽然是正式字段，但自动来源未必现成。
实现阶段必须明确：

• 名称是自动采集
• 还是通过 UI / 上位机写入

这不是字段是否保留的问题，而是字段填充路径的问题。

15.3 BT_ID_MAX=5 可用性

必须在目标板上验证：

• identity 创建正常
• 切换 advertising identity 正常
• settings 恢复正常

15.4 默认 identity 不参与槽位

本方案建议 BT_ID_DEFAULT 不参与槽位管理，避免后续行为不一致。

16. 当前版本结论

按目前所有已确认信息，最终设计结论如下：

1. 只做 BLE 三槽，dongle 只预留专用槽位
2. 三个 BLE 槽位直接固定到 bt_identity_id 1/2/3
3. bt_identity_id 4 预留给 dongle
4. 不使用 app_slot_id
5. 不使用临时 identity
6. 不做 erase advertising
7. 不做擦除确认和回滚
8. slot_meta 固定包含：
   • occupied
   • last_peer_addr
   • display_name
9. display_name 作为正式持久化字段保留，用于 UI 显示
10. 不新增 inc/ble_bond_multi.h，共享接口放到事件头文件

如果你认可这个版本，下一步就可以按这份方案进入实现阶段。