Wx_BLWConfigTools_V02_Prod/Document/BLV_RQ蓝牙通信控制页面实施文档.md

BLV_RQ 蓝牙通信控制页面实施文档

• 归档日期：2026年3月19日
• 适用项目：Wx_BLWConfigTools_V02_Prod
• 参考协议：Document/RF_RQ2603 蓝牙通讯协议.md
• 当前状态：已确认，待进入代码实现

---

一、实施目标

为 BLV_RQ 设备新增独立的蓝牙通信控制页面，用于完成以下能力：

1. 展示 BLE 连接信息
2. 读取设备版本信息
3. 设置蓝牙名称
4. 读取按键配置
5. 设置按键功能与按键映射
6. 基于映射关系执行按键控制
7. 查看、清空、导出通信日志

页面采用从上到下的单屏结构，页面自身不做上下滚动；若日志区需要展示更多内容，仅允许日志内容区内部滚动。

---

二、已确认实施约束

1. 单独新建一个新页面路径
2. 设备型号固定写死为 BLV_RQ
3. 按键支持映射设置
4. 蓝牙名称输入规则为 ASCII + 最多 8 字节自定义名，仅允许数字和英文字符
5. 允许按键类型由用户先选，读取配置后再按设备返回结果自动修正
6. 允许通信日志导出
7. 未配置映射的按键允许继续下发（方案 B）
8. 采纳建议：未配置映射项下发时，优先“保持设备当前返回值不变”

---

三、页面路径规划

建议新增页面路径：

pages/basics/BluetoothDebugging/BLVRQPage/

页面文件包括：

• BLVRQPage.js
• BLVRQPage.wxml
• BLVRQPage.wxss
• BLVRQPage.json

该页面仅服务于 BLV_RQ 设备，不复用 W13 页面逻辑。

---

四、页面结构设计

1. 页面总结构

页面自上而下分为三大区域：

1. 蓝牙信息栏
2. 设备管理框
3. 通信日志框组

页面整体不滚动，建议通过高度配比保证三块区域稳定展示：

• 蓝牙信息栏：约 26%
• 设备管理框：约 46%
• 通信日志框组：约 28%

---

2. 蓝牙信息栏

展示内容

• 蓝牙名称
• MAC / DeviceId
• ServiceId
• Tx 特征值
• Rx 特征值
• 连接状态
• 蓝牙信号 / RSSI

交互内容

• 断开 按钮
• 重连 按钮
• 蓝牙名称输入框
• 设置蓝牙名称 按钮

交互规则

蓝牙名称输入限制

输入内容必须满足：

• 仅允许数字和英文字符
• 长度为 1~8 字节
• ASCII 编码

建议使用如下校验规则：

^[A-Za-z0-9]{1,8}$

设置蓝牙名称按钮启用条件

仅当同时满足以下条件时可点击：

• 当前已连接设备
• 输入内容非空
• 输入内容满足校验规则

设置蓝牙名称交互流程

1. 用户输入新名称
2. 点击 设置蓝牙名称
3. 下发 0x05 指令
4. 回包成功后刷新显示名称
5. 记录 TX / RX / UI 日志

---

3. 设备管理框

设备管理框分为两部分：

3.1 设备信息栏

包含：

• 设备型号：BLV_RQ（固定写死）
• 软件版本
• 硬件版本
• 读取版本 按钮
• 按键类型下拉框
• 读取按键配置 按钮
• 设置按键配置 按钮

3.2 设备按键栏

根据按键类型动态生成按键卡片。

布局要求：

• 一行 2 个卡片
• Z 型排列
• 奇数卡片时最后一个左对齐

每个按键卡片包含：

• 按键序号（表示硬件按键位置）
• 按键控制按钮
• 按键功能下拉框
• 映射下拉框

建议标题展示方式：

• 按键1（硬件）
• 按键2（硬件）
• ...

可附加展示小字：

• 当前映射：键值X

---

五、按钮与控件启用逻辑

1. 读取版本按钮

启用条件：

• 已连接设备

2. 读取按键配置按钮

启用条件：

• 已连接设备
• 已选择按键类型（1~8键）

3. 设置按键配置按钮

启用条件：

• 已连接设备
• 已选择按键类型（1~8键）

4. 按键控制按钮

启用条件：

• 已连接设备
• 当前按键存在有效映射

5. 设置蓝牙名称按钮

启用条件：

• 已连接设备
• 名称输入合法

---

六、按键类型、功能与映射设计

1. 按键类型下拉框

选项：

• 请选择按键类型
• 1键
• 2键
• 3键
• 4键
• 5键
• 6键
• 7键
• 8键

规则

• 用户先选择按键类型后，才允许读取/设置按键配置
• 读取设备配置后，如果设备返回键数与当前选择不同：
  • 页面提示：设备返回为 X 键，已按设备实际值修正
  • 页面自动修正下拉框与卡片数量

---

2. 按键功能下拉框

依据协议中的功能码 0x00 ~ 0x0F：

• 不设置（0x00）
• 普通按键（0x01）
• 清理按键（0x02）
• 投诉按键（0x03）
• 预留（0x04）
• 预留（0x05）
• ...
• 预留（0x0F）

页面展示建议使用：

• 普通按键 (0x01)
• 投诉按键 (0x03)

---

3. 映射下拉框

映射选项需根据当前按键类型动态生成。

例如：

• 当前为 4 键：只允许映射 键值1 ~ 键值4
• 当前为 8 键：允许映射 键值1 ~ 键值8

映射校验规则

根据协议要求：

• 不同硬件位置不能映射到相同键值
• 映射值必须落在当前按键类型范围内

因此页面在设置前必须校验：

1. 是否存在重复映射
2. 是否存在越界映射
3. 是否存在未配置映射

---

七、协议交互设计

---

1. 读取版本号（0x01）

发送

• Frame_Type = 0x01
• P0 = 0x01

回包

• P0 = 软件版本号
• P1 = 硬件版本号

页面交互

• 点击 读取版本
• 成功回包后更新：
  • 软件版本
  • 硬件版本

---

2. 设置蓝牙名称（0x05）

发送

• Frame_Type = 0x05
• P0 = 名称长度
• P1~Pn = ASCII字符

回包

• P0 = 0x01：设置成功
• P0 = 0x02：设置失败

页面交互

• 输入名称
• 点击 设置蓝牙名称
• 成功后提示并刷新名称显示

---

3. 读取按键配置（0x04）

前置条件

• 已连接设备
• 已选择按键类型

发送

• Frame_Type = 0x04
• P0 = 0x01

回包

• P0 = 硬件按键总数
• P1~P8 = 各硬件按键配置字节

配置字节解析规则

每个配置字节：

• Bit0~3：映射键值
• Bit4~7：按键功能

页面处理

• 自动解析并回填每张卡片的：
  • mappedKey
  • functionCode

---

4. 设置按键配置（0x02）

协议规定 0x02 分为两个子命令：

子命令 1：设置按键功能

• P0 = 0x01
• P1~P8 = 逻辑键值功能码

子命令 2：设置按键映射

• P0 = 0x02
• P1~P8 = 硬件位置映射到的键值

页面交互流程

用户点击 设置按键配置 后，执行以下步骤：

第一步：前端校验

检查：

1. 是否已选择按键类型
2. 是否存在重复映射
3. 是否存在越界映射
4. 是否存在未配置映射
5. 功能配置是否完整

第二步：弹出二次确认框

场景 A：存在未配置映射按键

弹窗提示示例：

以下按键未配置映射：按键2、按键5
若继续下发，将保持这些按键当前设备返回值不变。
是否继续？

场景 B：无缺失项

弹窗提示示例：

确认下发当前按键功能与映射配置？

第三步：用户确认后继续下发（方案 B）

执行顺序建议为：

1. 先下发功能配置（P0 = 0x01）
2. 再下发映射配置（P0 = 0x02）

第四步：未配置映射项处理策略（采纳建议）

对于未配置映射的按键，不直接写入空值或 0x00，而是：

• 保持设备当前返回值不变

即：

• 页面在成功读取配置后缓存设备原始映射值
• 用户未配置映射的项，设置时继续带上原设备返回值

该策略的优点：

• 最稳妥
• 避免把设备有效映射误清空
• 与“允许继续”的方案 B 兼容

第五步：结果反馈

• 两条命令都成功：提示 设置成功
• 任一命令失败：提示 设置失败
• 日志中记录失败发生在功能设置还是映射设置阶段

---

5. 按键控制（0x06）

交互逻辑

用户通过映射下拉框配置卡片映射值后，点击某个按键卡片中的控制按钮时：

• 发送的不是硬件按键序号
• 而是该卡片当前映射到的逻辑键值

示例

• 硬件按键1 当前映射为键值3
• 点击“按键1”的控制按钮
• 实际发送键值3的模拟触发命令

发送

• Frame_Type = 0x06
• P0 = 1
• P1 = 1 << (mappedKey - 1)

回包

• P0 = 0x01：成功
• P0 = 0x02：失败

限制

• 未连接不可触发
• 未配置映射不可触发
• 点击未映射按键时提示：当前按键未配置映射

---

八、日志设计

1. 日志分类

建议日志类型：

• UI：用户操作
• CFG：状态变化
• TX：发送命令
• RX：接收回包
• WARN：警告
• ERR：错误

2. 日志内容建议

每条日志包含：

• 时间戳
• 日志类型
• 命令字
• Hex 内容
• 文本说明

示例

• [TX][0x04] 读取按键配置
• [RX][0x04] 返回4键配置
• [WARN] 未配置映射：按键2、按键5，继续按原设备值下发
• [TX][0x06] 触发键值3

3. 日志功能

顶部功能按钮：

• 清空日志
• 导出日志

4. 导出格式

允许导出为 txt 文件。

建议文件名：

BLV_RQ_Log_yyyyMMdd_HHmmss.txt

导出内容建议包含：

• 当前设备信息
• 当前连接参数
• 全量日志内容

---

九、推荐数据模型

data: {
  bleInfo: {
    devName: '',
    mac: '',
    serviceId: '',
    txCharId: '',
    rxCharId: '',
    connected: false,
    rssi: null,
    signalText: '-'
  },

  deviceInfo: {
    model: 'BLV_RQ',
    softwareVersion: '-',
    hardwareVersion: '-'
  },

  keyConfig: {
    selectedKeyCount: 0,
    keyCountOptions: ['请选择按键类型', '1键', '2键', '3键', '4键', '5键', '6键', '7键', '8键'],
    keys: [
      {
        hwIndex: 1,
        mappedKey: 1,
        functionCode: 1,
        functionLabel: '普通按键',
        originalMappedKey: 1
      }
    ]
  },

  logs: []
}

其中：

• hwIndex：硬件按键位置
• mappedKey：当前界面配置映射值
• originalMappedKey：设备读取回来的原始映射值，用于方案 B 放行时保留原值

---

十、测试范围

1. 蓝牙信息栏

• 能显示蓝牙名称、MAC、特征值、连接状态、信号
• 断开按钮有效
• 重连按钮有效

2. 蓝牙名称设置

• 非英文数字不可通过
• 超过 8 字节不可通过
• 合法名称可设置成功
• 成功失败提示正确

3. 版本读取

• 可正常读取软件版本、硬件版本

4. 按键配置读取

• 未选按键类型时按钮禁用
• 选定后可读取
• 返回值可正确解析
• 设备返回键数与页面选择不一致时可自动修正

5. 按键配置设置

• 功能可正确下发
• 映射可正确下发
• 重复映射必须拦截
• 越界映射必须拦截
• 未配置映射时弹窗提示并允许继续
• 未配置映射项按原设备值下发

6. 按键控制

• 点击卡片时基于映射后的逻辑键值发送命令
• 未配置映射不可触发

7. 日志

• TX / RX / WARN / ERR 记录完整
• 清空日志可用
• 导出日志可用

---

十一、首版实施范围

首版实施包含：

1. 新建 BLVRQPage
2. BLE 信息展示
3. 断开 / 重连
4. 读取版本
5. 设置蓝牙名称
6. 选择按键类型
7. 读取按键配置
8. 设置按键功能
9. 设置按键映射
10. 按映射执行单键控制
11. 日志显示 / 清空 / 导出

首版暂不做：

1. 多键同时触发
2. 批量压测模式
3. 原始报文自由编辑器

---

十二、建议实施顺序

第 1 阶段：页面骨架

• 新建 BLVRQPage
• 搭建静态页面结构
• 接收 BLE 上下文参数

第 2 阶段：基础蓝牙能力

• 连接信息展示
• 断开 / 重连
• RSSI 刷新
• 蓝牙名称设置
• 版本读取

第 3 阶段：按键配置能力

• 按键类型下拉
• 配置读取
• 卡片渲染
• 功能与映射编辑
• 二次确认弹窗
• 方案 B 放行逻辑

第 4 阶段：控制与日志增强

• 单键触发
• 日志导出
• 异常处理优化

---

十三、结论

本实施文档已完成以下关键决策固化：

• BLV_RQ 单独新建页面
• 设备型号固定为 BLV_RQ
• 页面支持按键功能与映射双配置
• 设置时采用二次确认
• 未配置映射按键采用 方案 B：允许继续
• 继续时采纳建议：未配置映射项保持设备当前返回值不变
• 页面整体不滚动，仅日志区允许内部滚动

该文档可作为后续代码实现的直接依据。