fastbee/yack-mini

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. 导入项目

1. 下载并安装 微信开发者工具
2. 打开微信开发者工具，选择「导入项目」
3. 项目目录选择 yack-mini
4. 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 - 应用 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（真机需 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 调试

1. 使用真机调试
2. 查看 Console 日志，前缀 [BLE]
3. 使用 nRF Connect 等工具验证 BLE 设备

MQTT 调试

1. 查看 Console 日志，前缀 [MQTT]
2. 使用 MQTT 客户端工具验证连接
3. 确保 wxs:// 域名已在微信公众平台配置

注意事项

1. 蓝牙权限：iOS 无需额外授权，Android 可能需要位置权限
2. MQTT 协议：真机必须用加密 WebSocket —— wxs://（EMQX 默认 8084）或 wss://； ws://（EMQX 默认 8083）只在开发者工具里可用，真机会直接握手失败
3. 数据格式：BLE 数据需转换为十六进制字符串上报
4. 包体积：主包控制在 1.5MB 以内

相关文档

• 微信小程序蓝牙 API
• mqtt.js 文档
• yack 文档

License

MIT