# FastBee-App

**Repository Path**: beecue/fastbee-app

## Basic Information

- **Project Name**: FastBee-App
- **Description**: FastBee App 是一个基于 UniApp 开发的多平台物联网设备管理应用程序，核心功能是实现对智能设备的便捷配网、实时监控与集中管理。
- **Primary Language**: JavaScript
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://fastbee.cn/doc/
- **GVP Project**: No

## Statistics

- **Stars**: 106
- **Forks**: 148
- **Created**: 2024-08-07
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: iot

**Tags**: None

## README

### Language
[中文](./README.md) | [English](./README.en.md)

| WeChat Mini Program | Android | iOS | H5 | Vue2 |
|:---:|:---:|:---:|:---:|:---:|
| √ | √ | √ | √ | √ |

---

### 1. Project Overview

FastBee App is a multi-platform IoT device management application built with UniApp.  
Its core capabilities include convenient device provisioning, real-time monitoring, and centralized management.

**Core Highlights:**
- **Cross-platform support**: One codebase for WeChat Mini Program, Android, iOS, and H5.
- **Real-time data monitoring**: MQTT integrated with WebSocket-based real-time data push and status updates.
- **Unified device management**: Supports QR-code onboarding and Wi-Fi provisioning for quick account-device binding.
- **Modern developer experience**: Uses uView UI and Easycom conventions for auto-imported components and better maintainability.

**Main Tech Stack and Architecture:**
- **Framework**: UniApp
- **UI**: uView 2.0
- **State Management**: Vuex
- **Chart Library**: uChart (optimized for multi-platform scenarios)
- **Networking**: HTTP module with request/response interceptors
- **Real-time Communication**: MQTT over WebSocket / WXS
- **Project Structure**: Modular layout with API management, shared utilities, components, and state storage

**Key Features:**
1. **Device provisioning**: Supports single-device setup (all platforms) and multi-device setup (WeChat Mini Program only), writing Wi-Fi settings to device hardware.
2. **QR-code onboarding**: Scan a device QR code (including device number, product ID, etc.) to quickly bind devices to user accounts.
3. **Environment configuration**: Configure API and MQTT server endpoints in `env.config.js` for development/production.
4. **Multi-end adaptation**: Auto-adapts networking protocols for H5, Mini Program, and App (e.g., WS, WSS, WXS).

**Notes:**
1. Recommended IDE: HBuilder 3.3+.
2. Before running the project, execute `npm install` to install dependencies.

---

### 2. Project Structure

```text
├─apis                  // API management
│  ├─modules            // Modular API directory
│  │  └─device.js       // Device API endpoints
│  ├─http.api.js        // API definitions
│  └─http.interceptor   // HTTP interceptor
├─common                // Shared files
│  ├─mqttTool           // MQTT utilities
│  ├─extend             // Prototype extensions
│  ├─filters            // Global filters
│  └─tools              // Common utility methods
├─components            // Shared component library
│  ├─cl-test            // Easycom test component
│  ├─cl-icon            // Iconfont component
│  ├─deviceMonitor      // Real-time device monitor component
│  └─other...           // Other components
├─pages                 // Page directory
│  ├─public             // Shared pages
│  └─tarbar             // Bottom tab pages
│      ├─home           // Home-related pages
│      ├─trend          // Trends/news pages
│      └─user           // User center pages
├─static                // Static assets
├─store                 // Vuex store
│  ├─$u.mixin           // Global store mixin
│  └─index              // Global state entry
├─uni_modules           // Uni plugin marketplace modules
│  └─uview-ui           // uView UI
├─env.config.js         // API and MQTT config
├─mainfest.json         // Platform configuration
```

---

### 3. Basic Configuration

1. Open `mainfest.json` in the project root.  
Set the base `AppId` to your own [uni-app application ID](https://ask.dcloud.net.cn/article/35907), and set the WeChat Mini Program `AppId` to your own [WeChat Mini Program AppId](https://mp.weixin.qq.com/).

2. Open `env.config.js` and update backend API and EMQX broker endpoints:

```javascript
// Protocols for H5 in development and production
let protocalDev = "ws://";
let protocalProd = "wss://";

// Conditional compilation: use WXS in WeChat Mini Program and App
// #ifdef MP-WEIXIN || APP-PLUS
protocalDev = "wxs://";
protocalProd = "wxs://";
// #endif

const CONFIG = {
  // Development environment
  development: {
    baseUrl: "http://localhost:8080",
    mqttServer: protocalDev + "localhost:8083/mqtt",
  },
  // Production environment
  production: {
    baseUrl: "https://domain.com/prod-api/",
    mqttServer: protocalProd + "domain.com/mqtt",
  },
};
```

- Mini Program APIs must use HTTPS. You can apply for certificates from Aliyun, Tencent Cloud, Baidu Cloud, etc. For Nginx HTTPS/WSS setup, see [official docs](https://fastbee.cn/doc/pages/applet/).
- H5 uses `ws` (non-encrypted) or `wss` (encrypted).
- WeChat Mini Program and App use `wxs`; domain configuration is required.

---

### 4. MQTT Protocols

| Protocol | Common Port | Description |
|:-----|:----------|:------------------|
| mqtt | 1883 | Non-encrypted TCP, used by device and server |
| mqtts | 8883 | Encrypted TCP, used by device and server |
| ws | 8083 | Non-encrypted WebSocket, used by frontend/mobile |
| wss | 8084 | Encrypted WebSocket, used by frontend/mobile, proxied to 8083 |
| wxs | 8084 | WeChat Mini Program connection, proxied to 8083 |
| alis | 8084 | Alipay Mini Program connection, proxied to 8083 |

---

### 5. Usage Notes

1. The project uses uChart. Some charts use `canvas2d` to reduce Mini Program rendering and drag performance issues. Display may look incorrect in WeChat DevTools but works after publishing.
2. Multi-device provisioning is available for WeChat Mini Program only. Enable location-related APIs in `mainfest.json` for Mini Program provisioning. Real-device debugging is required.
3. Mini Program video playback requires official WeChat permissions. Android and iOS require Wap2App packaging. The current player does not support native App mode.
4. The weather module uses the Seniverse API by default. You can replace it with another weather API, but `weather` data adaptation will be required. For some browser compatibility issues on H5, you can apply for a Tencent Map key for positioning.

---

### 6. Device Provisioning / QR-Code Onboarding

1. There are two cases:
   - The device does not exist in the system: provisioning/scanning creates a new device under the user account.
   - The device already exists in the system: provisioning/scanning associates it with the user account.
2. Device provisioning writes Wi-Fi information to the device and creates/binds the device to the user account. Single-device provisioning is supported on H5, WeChat Mini Program, Android, and iOS. Multi-device provisioning is currently WeChat Mini Program only.
3. QR-code onboarding creates/binds devices by scanning device QR codes. Each device has a QR code in its details summary. QR payload format:

```json
{
  "type": 1,
  "deviceNumber": "D888666",
  "productId": 5,
  "productName": "Smart Socket"
}
```

---

### 7. Related Docs
[uView 2.0 Docs >>](https://www.uviewui.com/components/intro.html)  
[UniApp Docs >>](https://uniapp.dcloud.io/tutorial/)  
[Easycom Guide >>](https://uniapp.dcloud.io/component/#easycom%E7%BB%84%E4%BB%B6%E8%A7%84%E8%8C%83)  
[uChart 2.0 Docs >>](https://www.ucharts.cn/v2/#/guide/index)  
[Wap2App Packaging](https://code.wumei.live/ultimate/wumei-smart/-/wikis/Wap2App%E6%89%93%E5%8C%85)

---

### 8. Screenshots

![Image](https://oscimg.oschina.net/oscnet/up-972dea7b54eca705dcc8bf2fe0680b12c09.png)

![Image](https://oscimg.oschina.net/oscnet/up-6d89f1558797a9becf07c20f92c1407a13a.png)