Mobile app

fastbeeAbout 3 min

1. Project overview

The FastBee mobile project is built with uni-app and targets WeChat Mini Program, Android, iOS, and H5. Other platforms have not been fully tested.

WeChat Mini Program	Android	iOS	H5	Vue 2
Supported	Supported	Supported	Supported	Supported

Technology stack and conventions:

The UI framework is uView 2.0.
Components use the easycom convention. When a component is placed under components or uni_modules and follows the components/component-name/component-name.vue structure, it can be used directly without manual import or registration.
The recommended development tool is HBuilderX.
The project structure will continue to be optimized during upgrades. Because the legacy codebase is large, structural cleanup is being handled gradually.

2. Project structure

├─apis                  // API management
│  ├─modules            // Modular API directory
│  │  └─device.js       // Device API addresses
│  ├─http.api.js        // API definition file
│  └─http.interceptor   // Interceptor
├─common                // Shared files
│  ├─mqttTool           // MQTT utilities
│  ├─extend             // Prototype extensions
│  ├─filters            // Global filters
│  └─tools              // Global utilities
├─components            // Project component library
│  ├─cl-test            // easycom test component
│  ├─cl-icon            // Iconfont component
│  ├─deviceMonitor      // Real-time device monitoring component
│  └─other...           // Other components
├─pages                 // Page directory
│  ├─public             // Shared pages
│  └─tarbar             // Bottom-tab pages
│      ├─home           // Home pages
│      ├─scene          // Scene automation pages
│      ├─trend          // News pages
│      └─user           // User center pages
├─static                // Static assets
├─store                 // Vuex
│  ├─$u.mixin           // Global store mixin
│  └─index              // Global state management
├─uni_modules           // uni-app plugin directory
│  └─uview-ui           // uView UI
├─env.config.js         // API and MQTT address configuration
├─manifest.json         // Platform configuration

3. Basic configuration

3.1 Configure application IDs

Open manifest.json in the project root:

Set the basic App ID to your own uni-app application identifier.
Set the WeChat Mini Program AppID to your own WeChat Mini Program AppID.

3.2 Configure API and MQTT addresses

Open env.config.js in the project root and update the backend API address and EMQX message server address.

// H5 development and production protocols.
let protocalDev = "ws://";
let protocalProd = "wss://";

// Conditional compilation: WeChat and App use wxs.
// #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",
  },
};

Notes:

Mini Program API calls must use HTTPS. You can apply for a free certificate from common cloud providers. For Nginx HTTPS and WSS configuration, see the official FastBee applet guide.
H5 can use ws for unencrypted WebSocket or wss for encrypted WebSocket.
WeChat Mini Program and App use the wxs protocol and require domain configuration. If the App fails to connect through wss, check the mqtt.js version and platform packaging settings.

4. MQTT protocols

Protocol	Common port	Description
mqtt	1883	Unencrypted TCP connection, commonly used by hardware and backend services.
mqtts	8883	Encrypted TCP connection, commonly used by hardware and backend services.
ws	8083	Unencrypted WebSocket connection, used by frontend and mobile clients.
wss	8084	Encrypted WebSocket connection, usually proxied to port 8083.
wxs	8084	WeChat Mini Program connection, usually proxied to port 8083.
alis	8084	Alipay Mini Program connection, usually proxied to port 8083.

5. Usage notes

The project uses uCharts. Some charts use canvas2d mode to reduce Mini Program layering issues and drag lag. Charts may render incorrectly in WeChat DevTools, but they work after publishing.
WeChat Mini Program supports multi-device provisioning. Enable the location API in manifest.json before using it. Device provisioning on WeChat Mini Program must be tested on a real device.
WeChat Mini Program video requires permission from the WeChat platform. Android and iOS packaging uses Wap2App; the current player does not support native App playback.
Weather forecast uses the Seniverse weather API. Apply for an API key and configure the Mini Program domain. Other weather APIs can also be used, but the custom weather component data format must be adjusted. To keep H5 location working reliably across browsers, apply for a Tencent Maps key when needed.

6. Device provisioning and QR-code binding

There are two common cases:

The device does not exist in the system. After provisioning or scanning, the system creates the device under the user account.
The device already exists in the system. After provisioning or scanning, the system binds the device to the user account.

Provisioning writes Wi-Fi information to the device and creates the device under the user account. H5, WeChat Mini Program, Android, and iOS support single-device provisioning. Multi-device provisioning is currently supported only by WeChat Mini Program.

During single-device provisioning, the user manually switches the phone Wi-Fi to the device hotspot, then completes provisioning.

QR-code binding creates or binds a device under the current user account. Each device has a QR code, which can be viewed in the device detail summary. The QR-code content uses this JSON format:

// type is fixed to 1, meaning scan-to-add.
// type, deviceNumber, and productId are required. productName is optional.
// If the device does not yet exist in the system, use a unique device number without special characters.
{
  "type": 1,
  "deviceNumber": "D888666",
  "productId": 5,
  "productName": "Smart plug"
}

8. Run the project

Install dependencies before running the project:

npm install