8.0 KiB
8.0 KiB
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 包装层（状态 / 断开 / 自动连接语义）
│ ├── gateway.js # 应用级常驻采集网关（BLE + 上报 + 离线补传）
│ └── command-manager.js # BLE 命令发送（限频 + 发送历史）
│
├── utils/ # 工具函数
│ ├── hex.js # 十六进制转换
│ ├── storage.js # 本地存储
│ ├── auth.js # MQTT 凭证获取
│ ├── measure-point.js # 测点ID + 采集模式
│ └── request.js # HTTP 请求（仅登录流程）
│
├── components/ # 公共组件
│ └── device-card/ # 设备卡片组件
│
├── libs/ # 第三方库
│ └── mqtt-wx.min.js # 自研「微信小程序 MQTT 适配库 v2.0」（不是 mqtt.js）
│
└── assets/ # 静态资源
└── images/ # 图片
快速开始
1. 导入项目
- 下载并安装 微信开发者工具
- 打开微信开发者工具，选择「导入项目」
- 项目目录选择
yack-mini - AppID 使用测试号或填写正式 AppID
2. 配置环境
编辑 miniprogram/env.config.js，配置 yack 平台地址：
// 开发环境
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- 应用 Logodevice.png/device-active.png- TabBar 图标device-empty.png- 空状态图ble-scan.png- 扫描页图标default-avatar.png- 默认头像
4. 真机调试
蓝牙功能必须在真机上测试：
- 点击「真机调试」
- 使用手机扫码预览
- 确保手机蓝牙已开启
核心功能
1. 登录认证
- yack 账号密码登录
- 获取 Token 和用户信息（含 userId）
- 登录态持久化存储
2. BLE 设备扫描
- 初始化蓝牙适配器
- 扫描周边 BLE 设备
- 支持按 Service UUID 过滤
3. 设备配置
配置设备参数：
- 设备名称
- 设备编号（SN）
- 产品 ID
- 产品密钥（用于 MQTT 认证）
- BLE 服务 UUID（可选）
4. 实时数据采集
- BLE 连接与数据监听
- 十六进制数据展示
- 自动/手动上报到 yack
5. MQTT 数据上报
- 连接 yack MQTT Broker（真机需
wss://或wxs://，ws://仅开发者工具可用） - 测点数据上报到
/{productId}/{sn}/{measurePointId}/measure/post - 自动连接：凭证填一次即持久化，之后打开小程序 / 切回前台 / 网络恢复都会自动连接
- 连接自愈：心跳（PINGREQ/PINGRESP）超时判定链路已死并自动重连，不会"假在线"
- 投递保证：QoS1 等待 PUBACK，超时按 DUP 重发（默认 3 次）；重试用尽或链路断开 即回调失败，由网关落离线缓存待补传（至少一次投递）
- 上报失败自动进离线缓存，MQTT 恢复后自动补传
MQTT 连接与断开语义
| 场景 | 行为 |
|---|---|
| 打开小程序 / 切回前台 / 网络恢复 | 有已保存凭证时自动连接（幂等，不会重复建连） |
| 网络抖动 / 服务端断开 | 底层按 reconnectPeriod（5s）自动重连，UI 显示"连接中" |
| 心跳超时（假在线） | 判死后按 reconnectPeriod 重连，connected 不再为 true |
| 「我的」页点断开 | 终止性断开：置用户意图标记，自动连接不再拉起它，需手动再点「连接」 |
| 退出登录 | 停网关 + 断 MQTT + 清全部本地数据；重新登录后恢复自动连接 |
| 凭证错误（CONNACK 4/5） | 不重试（避免 5s 一次无限撞 broker），提示核对凭证 |
⚠️
libs/mqtt-wx.min.js是自研适配库，不是 mqtt.js：end(force)的force无意义、 不存在reconnecting属性。包装层services/mqtt-client.js是唯一的连接语义出口， 请勿在页面里直接调用底层库。
MQTT 认证说明
设备连接 yack MQTT Broker 的凭证格式：
| 参数 | 格式 | 示例 |
|---|---|---|
| clientId | S&{设备编号}&{产品ID}&{用户ID} |
S&BLE001&1&100 |
| username | {设备编号} |
BLE001 |
| password | {产品密钥} |
abc123 |
数据上报格式
BLE 设备数据以十六进制字符串上报：
// 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 调试
- 使用真机调试
- 查看 Console 日志，前缀
[BLE] - 使用 nRF Connect 等工具验证 BLE 设备
MQTT 调试
- 查看 Console 日志，前缀
[MQTT] - 使用 MQTT 客户端工具验证连接
- 确保
wxs://域名已在微信公众平台配置
注意事项
- 蓝牙权限：iOS 无需额外授权，Android 可能需要位置权限
- MQTT 协议：真机必须用加密 WebSocket ——
wxs://（EMQX 默认 8084）或wss://；ws://（EMQX 默认 8083）只在开发者工具里可用，真机会直接握手失败 - 数据格式：BLE 数据需转换为十六进制字符串上报
- 包体积：主包控制在 1.5MB 以内
相关文档
License
MIT