Boonlive_RD_Web/Wx_BLWConfigTools_V02_Prod
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加蓝牙调试页面的初始实现

Browse Source 
- 新增 BLVRQPage.json 配置文件，设置导航栏样式。
- 新增 BLVRQPage.wxml 文件，构建蓝牙设备信息展示和操作界面。
- 新增 BLVRQPage.wxss 文件，定义页面样式和布局。
This commit is contained in:
chenzhihao
2026-03-20 18:18:49 +08:00
parent 5010b1bdbb
commit f94cf21e7a
13 changed files with 3127 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

682
Document/BLV_RQ蓝牙通信控制页面实施文档.md Normal file
View File

@@ -0,0 +1,682 @@
# 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：允许继续**
- 继续时采纳建议：**未配置映射项保持设备当前返回值不变**
- 页面整体不滚动，仅日志区允许内部滚动
该文档可作为后续代码实现的直接依据。

192
Document/RF_RQ2603 蓝牙通讯协议.md Normal file
View File

@@ -0,0 +1,192 @@
# RF_RQ2603 蓝牙通讯协议
## 一、设备与通讯基础
- **主控蓝牙模块**：清月 BT201 (型号：KT1025A)
- **通讯模式**：BLE 透传模式
- **默认 BLE 名称**：BT201-BLE
- **BLE 单包最大数据**：20 Byte
- **串口参数 (MCU ↔ 蓝牙模块)**：115200, 8N1
## 二、数据帧格式
所有数据包遵循以下结构：
| 字节位置 | 字段 | 长度 | 说明 |
| --- | --- | --- | --- |
| B0~B1 | Head (帧头) | 2 | 固定为 `0xDD 0xD0` |
| B2 | Len (长度) | 1 | 整包总字节数（包含 Head 和 CRC） |
| B3~B4 | CRC (校验) | 2 | CRC16；计算时此处填 `0x00` |
| B5 | Frame_Type (命令字) | 1 | 指令代码 |
| B6~B19 | PARA (参数) | ≤14 | 指令相关参数（可变长） |
> **注意**
> - `Len`：从 B0 到包尾的总字节数。
> - `CRC` 计算范围：B0/B1/B2/B5/B6…（包尾），计算时 **B3~B4 需填 0x00**。
## 三、指令集明细
### 3.1 读取版本号（0x01）
**PC → MCU**
| 字段 | 值 |
| --- | --- |
| Frame_Type | `0x01` |
| P0 | `0x01`（读取） |
**MCU → PC**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x01` |
| P0 | 软件版本号 |
| P1 | 硬件版本号 |
---
### 3.2 设置蓝牙名称（0x05）
**PC → MCU**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x05` |
| P0 | 有效名称字节长度 N（1~12） |
| P1~P(N) | 名称字符（ASCII） |
> 默认名称：`BLV_RQ_XXXXXXXX`，最多支持 8 字节自定义名称。
**MCU → PC**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x05` |
| P0 | `0x01`：设置成功<br>`0x02`：设置失败 |
---
### 3.3 读取按键配置（0x04）
**PC → MCU**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x04` |
| P0 | `0x01`（读取） |
**MCU → PC**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x04` |
| P0 | 硬件按键总数（0x01~0x08） |
| P1~P8 | 硬件按键 1~8 配置（每项 1 字节） |
**按键配置字节结构**
- Bit0~3：映射键值（0x1~0x8）
- Bit4~7：按键功能
**按键功能码（Bit4~7）**
- `0x00`：不设置（保持原功能）
- `0x01`：普通按键
- `0x02`：清理按键（带二次确认）
- `0x03`：投诉按键（带二次确认）
- `0x04~0x0F`：预留/其他功能
---
### 3.4 设置按键配置（0x02）
**PC → MCU**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x02` |
| P0 | 硬件按键数量（`0x01~0x08`） |
| P1 | 按键1功能 |
| P2 | 按键2功能 |
| P3 | 按键3功能 |
| P4 | 按键4功能 |
| P5 | 按键5功能 |
| P6 | 按键6功能 |
| P7 | 按键7功能 |
| P8 | 按键8功能 |
> 说明：
> - `P0` 为实际需要配置的硬件按键数量 `N`
> - 只需发送前 `N+1` 个字节（`P0~PN`）
> - 例如：`P0=0x04`（4个按键），则只需发送 `P0, P1, P2, P3, P4` 共 5 个字节
> - 未使用的 `P5~P8` 可省略
**按键功能码定义**
| 功能码 | 功能名称 | 行为说明 |
| --- | --- | --- |
| `0x00` | 不设置 | 保持该按键原有功能不变 |
| `0x01` | 普通按键 | 标准按键功能，按下即触发 |
| `0x02` | 清理按键 | 带二次确认的功能按键 |
| `0x03` | 投诉按键 | 带二次确认的功能按键 |
| `0x04` | 功能4 | 预留功能4 |
| `0x05` | 功能5 | 预留功能5 |
| `0x06` | 功能6 | 预留功能6 |
| `0x07` | 功能7 | 预留功能7 |
| `0x08` | 功能8 | 预留功能8 |
| `0x09` | 功能9 | 预留功能9 |
| `0x0A` | 功能10 | 预留功能10 |
| `0x0B` | 功能11 | 预留功能11 |
| `0x0C` | 功能12 | 预留功能12 |
| `0x0D` | 功能13 | 预留功能13 |
| `0x0E` | 功能14 | 预留功能14 |
| `0x0F` | 功能15 | 预留功能15 |
**MCU → PC**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x02` |
| P0 | `0x01`：设置成功<br>`0x02`：设置失败 |
---
### 3.5 模拟按键触发（0x06）
**PC → MCU**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x06` |
| P0 | 模拟按键数量 K |
| P1 | 按键状态位图（Bit0~Bit7）：<br>`Bit0=1`：键值1按下<br>`Bit1=1`：键值2按下<br>`...`<br>`Bit7=1`：键值8按下 |
> P0 的值应与 P1 中置 1 的位数一致。
**MCU → PC**
| 字段 | 说明 |
| --- | --- |
| Frame_Type | `0x06` |
| P0 | `0x01`：成功<br>`0x02`：失败 |
---
## 四、关键概念
- **硬件按键**：设备上固定的物理按钮（位置 1~8）。
- **映射键值**：物理按键实际触发的逻辑按键编号（1~8），映射可配置。
### 功能与读取配置的关系
- 设置按键功能（Command `0x02`）作用于 **硬件按键位置**。
- `P0` 为当前实际配置的硬件按键数量。
- 读取配置（Command `0x04`）返回每个硬件位置当前的映射键值及其功能。
### 其它说明
- 参数区（PARA）最大 14 字节，需确保单包数据不超限。
### 默认状态
- 蓝牙名称：`BLV_RQ_XXXXXXXX`
- 按键功能：默认为“普通按键”（0x01）
- 按键映射：默认硬件位置 n 映射到键值 n（1 对 1 映射）