# blufi_app

**Repository Path**: cyhuaxiang/blufi_app

## Basic Information

- **Project Name**: blufi_app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blufi调试工具

> 一款专业的ESP32蓝牙设备调试微信小程序，支持BLUFI协议，提供便捷的设备配置、命令控制和日志查看功能。

## 📱 项目简介

**Blufi调试工具**是一款基于微信小程序开发的ESP32蓝牙设备调试工具，通过BLE（低功耗蓝牙）与ESP32设备进行通信，支持BLUFI协议，为开发者提供便捷的设备调试、配置和监控功能。

### 核心特性

- 🔍 **智能设备扫描** - 快速扫描并发现附近的蓝牙设备
- 📷 **扫码快速连接** - 支持通过扫描二维码快速连接设备（支持设备名称、设备ID、MAC地址等多种格式）
- 💬 **命令控制台** - 丰富的命令模板，支持自定义命令发送
- 📊 **实时日志查看** - 实时显示设备返回的日志信息，支持系统日志和用户日志分类
- 🔄 **智能设备切换** - 连接新设备时自动断开已连接设备，无需手动操作
- 🎨 **简洁美观界面** - 现代化的UI设计，操作简单直观

## ✨ 主要功能

### 1. 设备扫描与连接

- **蓝牙设备扫描**
  - 自动扫描附近的蓝牙设备
  - 实时显示设备列表（设备名称、信号强度）
  - 支持设备名称过滤，快速定位目标设备
  - 显示设备连接状态

- **多种连接方式**
  - 手动选择设备连接
  - 扫码快速连接（支持设备名称、设备ID、MAC地址、JSON格式等）
  - 智能设备切换，自动断开已连接设备

- **连接状态管理**
  - 实时显示连接状态
  - 支持手动断开连接
  - 连接状态持久化

### 2. 命令控制台

- **丰富的命令模板**
  - **基础命令**：查询版本、任务信息、网络状态、内存信息、重启设备、查询应用版本
  - **充电相关**：查询充电会话、计量信息、错误信息
  - **日志配置**：调试模式开关、输出方式配置
  - **事件日志**：查询最近30分钟/1小时/12小时/24小时的事件日志
  - **4G模组**：查询SIM卡号、小区服务、信号强度、模组版本和信息
  - **卡管理**：查询卡列表
  - **预约计划**：查询预约条目
  - **实时时钟**：查询时间

- **云端模板管理**
  - 支持从微信云开发数据库动态加载命令模板
  - 无需重新发布小程序即可更新命令模板
  - 本地缓存模板数据，提升加载速度（7天有效期）
  - 版本检查和自动更新机制
  - 云端加载失败时自动降级到默认模板

- **自定义命令**
  - 支持输入自定义文本命令
  - 命令历史记录
  - 实时显示命令执行结果

- **命令模板管理**
  - 分类管理命令模板
  - 一键使用常用命令
  - 命令说明和参数提示

### 3. 实时日志查看

- **日志分类显示**
  - 系统日志：蓝牙连接/断开、设备状态变化等
  - 用户日志：设备返回的普通日志信息
  - 自动分类和标识

- **日志管理**
  - 实时滚动显示最新日志
  - 支持清空日志
  - 日志自动保存

## 🛠️ 技术栈

- **开发框架**：微信小程序原生框架
- **通信协议**：BLUFI协议（ESP32官方蓝牙配置协议）
- **蓝牙技术**：BLE（低功耗蓝牙）
- **云开发**：微信小程序云开发（命令模板云端管理）
- **开发语言**：JavaScript
- **样式方案**：WXSS（微信小程序样式）

## 📂 项目结构

```
blufi_app/
├── app.js                 # 小程序入口文件
├── app.json              # 小程序配置文件（包含云开发配置）
├── app.wxss              # 全局样式文件
├── project.config.json   # 微信开发者工具项目配置（包含AppID和云开发设置）
├── project.private.config.json # 私有配置文件（不提交到版本控制）
├── sitemap.json          # 小程序索引配置文件
├── pages/                # 页面目录
│   ├── scan/            # 扫描页面（设备扫描与连接）
│   ├── console/         # 控制台页面（命令控制）
│   └── logs/            # 日志页面（日志查看）
├── utils/                # 工具类目录
│   ├── bluetooth.js     # 蓝牙管理工具类
│   ├── blufi-protocol.js # BLUFI协议封装
│   └── cloud-template.js # 云模板服务类（云端命令模板加载）
├── doc/                  # 项目文档
└── images/               # 图片资源
```

### 配置文件说明

#### app.json
小程序全局配置文件，包含以下重要配置：
- **pages**: 页面路径配置
- **window**: 窗口配置（导航栏、背景色等）
- **tabBar**: 底部导航栏配置
- **cloud**: 云开发开关（`"cloud": true`）- 启用微信云开发功能

#### project.config.json
微信开发者工具项目配置文件，包含：
- **appid**: 小程序AppID（`wx3edc95db51adfc6f`）
- **libVersion**: 基础库版本（`2.32.3`）
- **compileType**: 编译类型（`miniprogram`）
- **setting**: 编译设置（ES6、代码压缩等）

#### 云开发配置
- **云开发环境**: 需要在微信开发者工具中开通云开发服务
- **云数据库**: 使用 `command_templates` 集合存储命令模板
- **环境ID**: 在 `utils/cloud-template.js` 中配置（当前使用默认环境）

## 🚀 快速开始

### 环境要求

- 微信开发者工具（最新版本）
- 微信小程序账号（用于真机调试）
- 支持BLE的ESP32设备

### 安装步骤

1. **克隆项目**
   ```bash
   git clone https://gitee.com/cyhuaxiang/blufi_app.git
   cd blufi_app
   ```

2. **打开项目**
   - 使用微信开发者工具打开项目目录
   - 配置小程序AppID（可在微信公众平台获取）

3. **配置云开发（可选）**
   - 在微信开发者工具中点击"云开发"按钮
   - 开通云开发服务并创建环境
   - 在云开发控制台创建数据库集合 `command_templates`
   - 添加文档ID为 `default`，包含命令模板数据
   - 如果未开通云开发，小程序会自动使用默认模板（功能不受影响）

4. **真机调试**
   - 在微信开发者工具中点击"预览"
   - 使用微信扫描二维码在真机上测试
   - 确保手机蓝牙已开启

### 使用说明

1. **连接设备**
   - 打开小程序，进入"扫描"页面
   - 点击"开始扫描"搜索附近的蓝牙设备
   - 选择目标设备进行连接
   - 或使用"扫码连接"功能快速连接

2. **发送命令**
   - 进入"控制台"页面
   - 点击"命令模板"选择常用命令
   - 或直接输入自定义命令
   - 点击"发送"执行命令

3. **查看日志**
   - 进入"日志"页面
   - 实时查看设备返回的日志信息
   - 系统日志和用户日志会自动分类显示

## 📖 命令参考

### 基础命令

| 命令 | 说明 |
|------|------|
| `bsp version` | 查询设备版本信息 |
| `bsp tasklist` | 查询设备任务列表信息 |
| `comm state` | 查询设备网络连接状态 |
| `os memory` | 查询设备内存使用情况 |
| `bsp reboot` | 重启设备 |

### 充电相关命令

| 命令 | 说明 |
|------|------|
| `charging get_session` | 查询当前充电会话信息 |
| `charging get_elec` | 查询充电计量信息 |
| `charging get_error` | 查询充电错误信息 |

### 事件日志查询

| 命令 | 说明 |
|------|------|
| `record event_log query2 30` | 查询最近30分钟的事件日志 |
| `record event_log query 1` | 查询最近1小时的事件日志 |
| `record event_log query 12` | 查询最近12小时的事件日志 |
| `record event_log query 24` | 查询最近24小时的事件日志 |

更多命令请参考小程序内的命令模板。

## 🔧 扫码连接格式

支持以下二维码格式：

1. **设备名称**：`TFAE202407231413`
2. **设备ID（UUID）**：`4E623A35-9432-CE40-9628-A901136C2C1D`
3. **JSON格式**：`{"deviceId":"...","name":"..."}`
4. **BLUFI格式**：`BLUFI:DEVICE_ID:设备ID`
5. **MAC地址**：`AA:BB:CC:DD:EE:FF`

## 📚 文档

- [项目文档](./doc/README.md) - 完整的项目文档索引
- [开发指南](./doc/02-开发指南.md) - 开发环境搭建和开发指南
- [用户手册](./doc/05-用户手册.md) - 详细的使用说明
- [API文档](./doc/03-API文档.md) - API接口说明
- [故障排查](./doc/07-故障排查.md) - 常见问题解决方案

## 🎯 适用场景

- **ESP32设备开发调试** - 快速连接和调试ESP32设备
- **充电桩设备管理** - 查询充电状态、计量信息等
- **物联网设备监控** - 实时查看设备日志和状态
- **设备配置管理** - 通过命令配置设备参数
- **故障诊断** - 查看事件日志，定位问题

## ⚙️ 技术特点

- **BLUFI协议支持** - 完整实现ESP32 BLUFI协议
- **智能连接管理** - 自动处理设备连接和断开
- **静默扫描优化** - 扫码连接时静默扫描，不干扰用户
- **实时数据通信** - 支持双向数据通信
- **云端模板管理** - 命令模板云端存储，动态加载，无需重新发布小程序
- **智能缓存机制** - 模板数据本地缓存，版本检查和自动更新
- **错误处理机制** - 完善的错误处理和用户提示，支持降级方案

## 📝 版本历史

### v1.3.0（当前版本）

- ☁️ **新增云端命令模板功能** - 支持从微信云开发数据库动态加载命令模板
- 🚀 **模板管理优化** - 无需重新发布小程序即可更新命令模板
- 💾 **本地缓存机制** - 模板数据本地缓存（7天有效期），提升加载速度
- 🔄 **版本检查机制** - 自动检查模板更新，后台静默更新
- 🛡️ **降级方案** - 云端加载失败时自动使用默认模板，确保功能可用
- 📋 **扩展命令分组** - 新增4G模组、卡管理、预约计划、实时时钟等命令组

### v1.2.0

- ✨ 新增扫码连接蓝牙功能，支持设备名称扫码
- 🔧 优化扫码连接流程，静默扫描不显示中间过程
- 🔄 支持自动断开已连接设备，切换设备更便捷
- 📋 扩展命令模板：基础命令和事件日志组
- 📁 整理项目文档结构

### v1.0.0

- 🎉 首次发布
- ✅ 基础功能：设备扫描、连接、命令控制、日志查看

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

本项目采用 MIT 许可证。

## 📞 联系方式

- 项目地址：https://gitee.com/cyhuaxiang/blufi_app
- 问题反馈：请在 Gitee 上提交 Issue

## 🙏 致谢

- ESP32 BLUFI 协议文档
- 微信小程序开发文档

---

**Blufi调试工具** - 让ESP32设备调试更简单！ 🚀