# 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` 导出内容建议包含： - 当前设备信息 - 当前连接参数 - 全量日志内容 --- ## 九、推荐数据模型 ```js 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：允许继续** - 继续时采纳建议：**未配置映射项保持设备当前返回值不变** - 页面整体不滚动，仅日志区允许内部滚动 该文档可作为后续代码实现的直接依据。