工业机器人控制终端 - Taro 小程序/App

基于 Taro 框架开发的工业机器人控制终端应用，支持微信小程序和 App 多端运行。

项目结构

├── config/              # Taro 配置文件
│   ├── index.js        # 主配置文件
│   ├── dev.js          # 开发环境配置
│   └── prod.js         # 生产环境配置
├── src/
│   ├── app.tsx         # 应用入口
│   ├── app.scss        # 全局样式
│   ├── components/     # 组件目录
│   │   └── Icons/      # 图标组件
│   ├── config/         # 配置文件
│   │   └── mqtt.ts     # MQTT 配置
│   ├── services/       # 服务层
│   │   └── mqttService.ts  # MQTT 服务
│   ├── utils/          # 工具类
│   │   └── mqttClient.ts   # MQTT 客户端
│   └── pages/          # 页面目录
│       └── index/      # 首页
│           ├── index.tsx
│           ├── index.scss
│           └── index.config.ts
├── app.config.ts       # 小程序/App 配置
├── package.json        # 项目依赖
└── tsconfig.json       # TypeScript 配置

功能特性

• ✅ 设备列表展示
• ✅ 设备详情查看
• ✅ GPS 定位显示
• ✅ 运行状态监控
• ✅ 参数设置与配置
• ✅ 数据下发功能
• ✅ 统计信息展示
• ✅ MQTT 实时通信
• ✅ 设备状态订阅
• ✅ 控制命令发布

开发

安装依赖

npm install

开发小程序

npm run dev:weapp

开发 H5

npm run dev:h5

开发 App (React Native)

npm run dev:rn

构建

构建小程序

npm run build:weapp

构建 H5

npm run build:h5

构建 App

npm run build:rn

技术栈

• Taro 3.6.0 - 多端统一开发框架
• React 18 - UI 框架
• TypeScript - 类型支持
• SCSS - 样式预处理器
• MQTT.js 5.3.0 - MQTT 客户端库

页面说明

首页

• 显示设备总数、在线数、运行中数量
• 设备列表，包含设备状态、电量、运行模式等信息

详情页

• 设备基本信息
• GPS 定位地图
• 运行状态（行走、滚刷、跨桥速度）
• 累计数据（运行时长、里程）
• 快捷控制按钮

设置页

• 基本设置（公司代码、产品型号等）
• 检测设置（到边检测、跨桥检测等）
• 速度设置（行走、滚刷、跨桥速度）
• 时间组设置
• 数据下发功能

统计页

• 累计清扫面积
• 设备统计数据

MQTT 功能

配置信息

MQTT 客户端配置位于 src/config/mqtt.ts：

• 服务器地址: 218.2.130.246
• 端口: 8083 (WebSocket端口)
• 协议: ws:// (WebSocket)
• 用户名: admin
• 密码: njzt888
• 客户端ID: 动态生成 (client_ + 随机字符串)

MQTT 主题

根据交互数据协议定义：

• 设备设置控制 (Downlink): RAILCAR/R/-PD{deviceID} - 服务器向小车发送64字节设置控制数据
• 设备状态 (Uplink): RAILCAR/S/GG0{deviceID} - 小车向服务器发送64字节状态数据

例如：

• 设备ID为 250001 的设置主题: RAILCAR/R/-PD250001
• 设备ID为 250001 的状态主题: RAILCAR/S/GG0250001

数据格式

设置控制数据 (64字节)

• 公司代码 (8字节 ASCII)
• 产品型号 (4字节 ASCII)
• 设备ID (6字节 ASCII)
• 工作方式 (2字节 UInt16)
• 时间组1-4 (各6字节 BCD/Hex)
• 控制模式 (2字节 UInt16)
• 使能模式 (2字节 UInt16)
• 检测参数 (6字节 UInt16)
• 速度参数 (6字节 UInt16)
• 心跳设置 (2字节 UInt16)
• 备用 (2字节 UInt16)

状态数据 (64字节)

• 基本信息 (18字节)
• 当前任务时间 (6字节)
• 运行时长和里程 (8字节)
• GPS坐标 (8字节)
• 运行状态 (2字节)
• 电池电量 (2字节)
• 当前速度 (6字节)
• 心跳状态 (2字节)
• 备用 (2字节)

使用方法

import mqttService from '@/services/mqttService'
import { MQTT_TOPICS } from '@/config/mqtt'
import { encodeConfig, decodeStatus, DeviceConfig } from '@/utils/dataEncoder'

// 连接 MQTT
await mqttService.init(
  () => console.log('连接成功'),
  (topic, message) => {
    // 接收64字节二进制状态数据
    if (Buffer.isBuffer(message) && message.length === 64) {
      const status = decodeStatus(new Uint8Array(message))
      console.log('设备状态:', status)
    }
  },
  (error) => console.error('错误:', error)
)

// 订阅设备状态主题
await mqttService.subscribe(MQTT_TOPICS.deviceStatus('250001'), 1)

// 发布设置控制数据
const config: DeviceConfig = {
  companyCode: 'ZTZN-PVC',
  model: '-D01',
  deviceID: '250001',
  // ... 其他配置
}
const buffer = encodeConfig(config)
await mqttService.publish(MQTT_TOPICS.deviceSet('250001'), buffer, 1, false)

// 断开连接
mqttService.disconnect()

MQTTClient 类方法

• connect(): 连接 MQTT 服务器
• subscribe(topic, qos): 订阅主题
• publish(topic, message, qos, retain): 发布消息
• unsubscribe(topic): 取消订阅
• disconnect(): 断开连接
• getConnected(): 获取连接状态

事件回调

• onConnect: 连接成功回调
• onMessage: 接收消息回调
• onError: 错误处理回调

注意事项

1. 本项目使用 Taro 3.x 版本，需要 Node.js 14+ 环境
2. 小程序开发需要安装微信开发者工具
3. App 开发需要配置 React Native 环境
4. 样式使用 rpx 单位，适配不同屏幕尺寸
5. MQTT 连接在应用启动时自动建立，组件卸载时自动断开
6. 小程序环境可能需要配置域名白名单

📚 文档导航

快速开始

文档	用途	阅读时间
开发者指南	项目概览和开发环境设置	10分钟
App部署步骤	H5 + Capacitor 完整部署	15分钟
小程序部署	微信小程序发布流程	10分钟

构建与部署

文档	用途
构建方案选择	RN vs Capacitor 方案对比
快速构建APK	命令行快速构建
一行完成构建	最快构建命令
构建验证	构建后测试清单
小程序测试	小程序发布前检查

问题排查

文档	问题类型
白屏调试指南	Android App 白屏问题
综合修复步骤	ChunkLoadError 等常见问题
MQTT 故障排查	MQTT 连接和消息问题
Java版本修复	Java 版本不兼容
中文路径修复	Gradle 编码问题
手动修复脚本	PublicPath 手动修复

MQTT 相关

文档	用途
MQTT 协议规范	官方协议完整规范 (900行)
小程序 MQTT 机制	小程序环境特性 (650行)
MQTT 故障排查	常见错误和解决方案
实现验证报告	当前实现验证

React Native

文档	用途
RN 快速开始	React Native 快速开始
RN 设置指南	React Native 环境配置
RN 部署指南	RN 版本部署流程

开发环境

文档	用途
Android Studio 设置	IDE 安装配置
开发者指南	完整开发指南

---

🎯 文档使用流程

新手入门
├─ README.md (本文档)
├─ DEVELOPER-GUIDE.md
└─ 选择开发方向:
   ├─ 小程序开发
   │  ├─ DEPLOYMENT_GUIDE.md
   │  ├─ TEST_DEPLOYMENT.md
   │  └─ MQTT_WEAPP_GUIDE.md
   │
   └─ App 开发
      ├─ APP_BUILD_GUIDE.md (方案选择)
      ├─ APP_DEPLOY_STEPS.md (部署)
      ├─ DEBUG_WHITE_SCREEN.md (问题排查)
      └─ MQTT_TROUBLESHOOTING.md (MQTT调试)

---

⚠️ 遇到问题？

按优先级查看：

1. 白屏 → DEBUG_WHITE_SCREEN.md
2. 资源加载失败 → FINAL_FIX_STEPS.md
3. MQTT 连接问题 → MQTT_TROUBLESHOOTING.md
4. 构建失败 → APP_BUILD_GUIDE.md + 相关修复文档
5. Java/Gradle 问题 → JAVA_VERSION_FIX.md + CHINESE_PATH_FIX.md

许可证

MIT