205 lines
6.0 KiB
Markdown
205 lines
6.0 KiB
Markdown
# yack-mini
|
||
|
||
yack 蓝牙网关微信小程序，采集 BLE 设备数据透传上报至 yack 平台。
|
||
|
||
## 项目定位
|
||
|
||
- **技术栈**：原生微信小程序
|
||
- **目标**：轻量化蓝牙网关，透传数据至 yack
|
||
- **与 yack-app 区别**：yack-app 是全功能移动端（UniApp），yack-mini 是轻量蓝牙网关（原生小程序）
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
┌─────────────┐ BLE ┌──────────────────┐ wxs ┌─────────────────┐
|
||
│ BLE 设备 │ ←──────→ │ yack-mini │ ←──────→ │ yack 平台 │
|
||
│ (传感器) │ │ (微信小程序) │ MQTT │ (数据存储) │
|
||
└─────────────┘ └──────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
yack-mini/
|
||
├── project.config.json # 项目配置
|
||
└── miniprogram/ # 小程序源码
|
||
├── app.js # 应用入口
|
||
├── app.json # 全局配置
|
||
├── app.wxss # 全局样式
|
||
├── env.config.js # 环境配置（API/MQTT 地址）
|
||
├── sitemap.json # 站点地图
|
||
│
|
||
├── pages/ # 页面
|
||
│ ├── login/ # 登录页
|
||
│ ├── index/ # 首页（设备列表）
|
||
│ └── device/
|
||
│ ├── scan/ # 扫描设备页
|
||
│ └── detail/ # 设备详情/实时数据页
|
||
│
|
||
├── services/ # 核心服务模块
|
||
│ ├── ble.js # 蓝牙采集模块
|
||
│ └── mqtt-client.js # MQTT 连接模块
|
||
│
|
||
├── utils/ # 工具函数
|
||
│ ├── hex.js # 十六进制转换
|
||
│ ├── storage.js # 本地存储
|
||
│ ├── auth.js # MQTT 凭证获取
|
||
│ └── request.js # HTTP 请求
|
||
│
|
||
├── components/ # 公共组件
|
||
│ └── device-card/ # 设备卡片组件
|
||
│
|
||
├── libs/ # 第三方库
|
||
│ └── mqtt.min.js # mqtt.js (4.3.7, 支持微信小程序)
|
||
│
|
||
└── assets/ # 静态资源
|
||
└── images/ # 图片
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 导入项目
|
||
|
||
1. 下载并安装 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
|
||
2. 打开微信开发者工具，选择「导入项目」
|
||
3. 项目目录选择 `yack-mini`
|
||
4. AppID 使用测试号或填写正式 AppID
|
||
|
||
### 2. 配置环境
|
||
|
||
编辑 `miniprogram/env.config.js`，配置 yack 平台地址：
|
||
|
||
```javascript
|
||
// 开发环境
|
||
const DEV_CONFIG = {
|
||
baseUrl: 'http://localhost:8080',
|
||
mqttServer: 'wxs://localhost:8084/mqtt',
|
||
};
|
||
|
||
// 生产环境
|
||
const PROD_CONFIG = {
|
||
baseUrl: 'https://your-domain.com/prod-api',
|
||
mqttServer: 'wxs://your-domain.com/mqtt',
|
||
};
|
||
```
|
||
|
||
### 3. 替换图片资源
|
||
|
||
`miniprogram/assets/images/` 目录下的图片为占位图，请替换为实际图片：
|
||
|
||
- `logo.png` - 应用 Logo
|
||
- `device.png` / `device-active.png` - TabBar 图标
|
||
- `device-empty.png` - 空状态图
|
||
- `ble-scan.png` - 扫描页图标
|
||
- `default-avatar.png` - 默认头像
|
||
|
||
### 4. 真机调试
|
||
|
||
蓝牙功能必须在真机上测试：
|
||
1. 点击「真机调试」
|
||
2. 使用手机扫码预览
|
||
3. 确保手机蓝牙已开启
|
||
|
||
## 核心功能
|
||
|
||
### 1. 登录认证
|
||
|
||
- yack 账号密码登录
|
||
- 获取 Token 和用户信息（含 userId）
|
||
- 登录态持久化存储
|
||
|
||
### 2. BLE 设备扫描
|
||
|
||
- 初始化蓝牙适配器
|
||
- 扫描周边 BLE 设备
|
||
- 支持按 Service UUID 过滤
|
||
|
||
### 3. 设备配置
|
||
|
||
配置设备参数：
|
||
- 设备名称
|
||
- 设备编号（SN）
|
||
- 产品 ID
|
||
- 产品密钥（用于 MQTT 认证）
|
||
- BLE 服务 UUID（可选）
|
||
|
||
### 4. 实时数据采集
|
||
|
||
- BLE 连接与数据监听
|
||
- 十六进制数据展示
|
||
- 自动/手动上报到 yack
|
||
|
||
### 5. MQTT 数据上报
|
||
|
||
- 连接 yack MQTT Broker（`wxs://` 协议）
|
||
- 发布属性数据到 `/{productId}/{sn}/property/post`
|
||
- 支持订阅下发指令
|
||
|
||
## MQTT 认证说明
|
||
|
||
设备连接 yack MQTT Broker 的凭证格式：
|
||
|
||
| 参数 | 格式 | 示例 |
|
||
|:---|:---|:---|
|
||
| clientId | `S&{设备编号}&{产品ID}&{用户ID}` | `S&BLE001&1&100` |
|
||
| username | `{设备编号}` | `BLE001` |
|
||
| password | `{产品密钥}` | `abc123` |
|
||
|
||
## 数据上报格式
|
||
|
||
BLE 设备数据以十六进制字符串上报：
|
||
|
||
```javascript
|
||
// Modbus 帧示例
|
||
mqttClient.publish('/1/BLE001/property/post', '010304009A005B8B7C');
|
||
|
||
// 私有协议示例
|
||
mqttClient.publish('/1/BLE002/property/post', '009A005B');
|
||
```
|
||
|
||
yack 平台通过规则脚本或 Modbus 配置解析数据。
|
||
|
||
## 微信小程序配置
|
||
|
||
### 服务器域名
|
||
|
||
在微信公众平台配置：
|
||
|
||
- **socket 合法域名**：`wxs://your-domain.com`
|
||
- **request 合法域名**：`https://your-domain.com`
|
||
|
||
### 权限说明
|
||
|
||
- `scope.bluetooth`：蓝牙权限（部分设备需要用户授权）
|
||
- `scope.userLocation`：部分 Android 设备扫描 BLE 需要位置权限
|
||
|
||
## 开发调试
|
||
|
||
### BLE 调试
|
||
|
||
1. 使用真机调试
|
||
2. 查看 Console 日志，前缀 `[BLE]`
|
||
3. 使用 nRF Connect 等工具验证 BLE 设备
|
||
|
||
### MQTT 调试
|
||
|
||
1. 查看 Console 日志，前缀 `[MQTT]`
|
||
2. 使用 MQTT 客户端工具验证连接
|
||
3. 确保 `wxs://` 域名已在微信公众平台配置
|
||
|
||
## 注意事项
|
||
|
||
1. **蓝牙权限**：iOS 无需额外授权，Android 可能需要位置权限
|
||
2. **MQTT 协议**：微信小程序必须使用 `wxs://` 协议（端口 8084）
|
||
3. **数据格式**：BLE 数据需转换为十六进制字符串上报
|
||
4. **包体积**：主包控制在 1.5MB 以内
|
||
|
||
## 相关文档
|
||
|
||
- [微信小程序蓝牙 API](https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.openBluetoothAdapter.html)
|
||
- [mqtt.js 文档](https://github.com/mqttjs/MQTT.js)
|
||
- [yack 文档](../CLAUDE.md)
|
||
|
||
## License
|
||
|
||
MIT |