IoT System

Q: Startup reports patch-package related errors after npm install?

Cause: node_modules is not fully installed or a cache issue. # Clear the cache and reinstall rm -rf node_modules package-lock.json npm cache clean --force npm install

Q: APIs return 404 in the development environment?

Check whether VUE_APP_SERVER_API_URL in .env.development correctly points to the backend, and confirm the backend has been started.

Q: MQTT connection fails?

Confirm that VUE_APP_MQTT_SERVER_URL is configured correctly (ws://localhost:8083/mqtt in the development environment) Confirm that the built-in Broker is started (server.broker.enabled: true + server.broker.websocket-port: 8083) Check whether the Token is valid (mqttTool uses the Token as the MQTT password)

Q: vue-treeselect has a version conflict?

The project uniformly uses @riophae/vue-treeselect@0.4.0; do not mix other versions.

Q: The vue-qr component import reports an error?

// ✅ Correct way (default import) import vueQr from 'vue-qr'; // ❌ Wrong way (named import fails) import { VueQr } from 'vue-qr';

Q: Startup reports license related errors?

Configure the correct certificate path in application-dev.yml: license: subject: common licensePath: classpath:license.lic Apply to the official team for the certificate file (license.lic) and place it in the resources directory.

The FastBee IoT platform is a feature-rich IoT solution designed specifically for small and medium-sized enterprises and individual users. By providing a series of easy-to-use tools and features, the platform enables users to effectively manage and control various smart devices. The following is a detailed introduction to the FastBee IoT platform:

Page Guide

What This Page CoversAn overall introduction to the FastBee IoT platform: project background, system features, tech stack, application scenarios, and system architecture.

Use CasesFor readers learning about the commercial edition's capabilities and architecture for the first time, to build a complete picture of the product.

PrerequisitesNone; afterwards, continue with the architecture design and installation chapters along the recommended path.

Edition Comparison

FastBee offers three editions: Open Source, Commercial, and Cluster. The key differences are listed below; for the full licensing policy and itemized feature list, see Commercial License.

Dimension	Open Source	Commercial	Cluster
License	AGPL v3, free for non-commercial use	Perpetual commercial license (certificate-based)	Perpetual commercial license (certificate-based)
Source & Updates	Public source, updated via Gitee/GitHub	Private Git server updates after licensing, one year of source updates included	Same as Commercial
Deployment	One-click single-node deployment with Docker Compose	Single-node deployment (Docker Compose quick install supported)	FMQ server cluster + Web cluster, with Kafka and load balancing for high availability
Access Protocols	MQTT, GB/T 28181 (live streaming only)	Adds TCP, UDP, CoAP, HTTP, Modbus, JT808, and more	Same as Commercial
Feature Scope	Core capabilities: product/device/thing-model management, rule scripts, access control	Adds visual dashboard, alert center, multi-tenancy, OTA updates, data bridge, work orders, IoT SIM card management, and more (SCADA and smart speaker are optional modules)	Same features as Commercial, differs in supported device scale
Use Cases	Personal learning and non-commercial use	Commercial projects of small and medium-sized enterprises	Commercial projects with large device scale and high-availability requirements

1. Platform Introduction

Project Background: Originally named Wumei Smart (wumei-smart), later renamed FastBee. This change not only reflects the brand's update, but also marks its development in the IoT field and the expansion of its service scope.
Main Support: The platform backend adopts the Spring Boot framework and the frontend uses Vue technology. The selection of these technologies ensures the platform's usability and a good user experience.

2. System Functions

Product Management: Supports product details, Thing Models, classification, and device authorization, helping enterprises better organize and manage their smart products.
Device Management: Provides management functions such as device details, grouping, logging, and real-time status monitoring, ensuring efficient and secure device operation.
Thing Model Management: Allows defining device properties, functions, and events to achieve effective interaction between devices and the cloud.
Rule Engine: Supports writing rules based on Groovy (same syntax as Java), enabling the system to automatically handle complex business logic.
Scene Linkage: Supports direct or visual configuration of automation scenes, enabling seamless collaboration between smart devices.
Alert Center: Integrates with multiple communication methods such as voice, SMS, and Enterprise WeChat to promptly notify device abnormalities or failures, ensuring quick response.
Multi-tenant System: Supports data isolation and independent configuration, suitable for multi-tenant environments, enhancing system flexibility and security.
Video Surveillance Access: Supports surveillance devices using the GB/T28181 protocol, providing live streaming, recording playback, and PTZ control for security monitoring needs.
Scene Management: Supports aggregating multiple devices for display, and can be extended with input and computed variables to support complex data operations.
Data Bridging: Acts as a bridge to external data systems, supporting data input and output.
Data Center: Supports generating data reports, viewing historical data, and analyzing device data.
Communication Protocols: Supports a rich set of device communication protocols, including MQTT, Modbus, TCP, GB28182, HTTP, CoAP, and more.
IoT Cards: Manages the SIM cards connecting devices, supports integration with different reseller platforms, and provides card status and traffic views with traffic alerts.
Work Order Management: Supports automated, intelligent, and full-process management of maintenance, repair, inspection, and other tasks for devices or assets.

3. Technology Stack

Backend Technologies: Include Spring Boot, MyBatis, Spring Security, Jwt, Redis, TDengine, and more, ensuring the stability and efficiency of backend services.
Frontend Technologies: Use modern frontend technologies such as ES6, ES7, Vue, Vuex, uView, and H5, enhancing the interactivity and visual experience of the user interface.
Mobile Support: Supports multiple mobile platforms such as WeChat Mini Programs, Android, and iOS, and enables cross-platform application development through Uniapp, making it convenient for users to operate and manage on different devices.

4. Application Scenarios

FastBee is suitable for various scenarios such as smart homes, smart offices, smart communities, agricultural monitoring, water conservancy monitoring, and industrial control. These application scenarios cover a wide range of needs from home to industrial levels, demonstrating the extensive potential of FastBee in the IoT field.

5. System Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        Browser / Mobile                          │
│         Vue2 Web (PC)    +    Vant (H5 / Mini Program)           │
└───────────────────────────────┬──────────────────────────────────┘
                                │ HTTP REST / WebSocket(MQTT)
                                ▼
┌──────────────────────────────────────────────────────────────────┐
│                       Nginx (Reverse Proxy)                      │
│           /  → static frontend assets    /prod-api/ → backend    │
└───────────────────────────────┬──────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────┐
│                  Spring Boot Service (8080)                      │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                fastbee-open-api (Controller layer)         │  │
│  │  device / product / ruleEngine / media / system / ...     │  │
│  └────────────────────────┬───────────────────────────────────┘  │
│  ┌─────────────────────────▼──────────────────────────────────┐  │
│  │               fastbee-service (Service layer)              │  │
│  │     IotService / SceneService / NotifyService / ...        │  │
│  └────────────────────────┬───────────────────────────────────┘  │
│  ┌─────────────────────────▼──────────────────────────────────┐  │
│  │               fastbee-server (protocol access)             │  │
│  │   MQTT Broker(1883) / HTTP(8081) / CoAP(5683) / TCP(8888) │  │
│  └────────────────────────────────────────────────────────────┘  │
└───────────┬──────────────────┬────────────────────┬──────────────┘
            │                  │                    │
         MySQL              Redis              TDengine
     (metadata/config)   (cache/real-time)  (time-series history)

6. Code Structure

fastbee/
├── vue/                        ← Frontend Vue2 project
│   ├── src/
│   │   ├── api/                ← API request functions for each module
│   │   ├── assets/             ← Static assets (images/icons/styles)
│   │   ├── components/         ← Global common components (28)
│   │   ├── directive/          ← Global custom directives
│   │   ├── lang/               ← Internationalization language packs
│   │   ├── layout/             ← Main framework layout
│   │   ├── plugins/            ← Vue plugin registration
│   │   ├── router/             ← Router configuration
│   │   ├── store/              ← Vuex state management
│   │   ├── utils/              ← Utility functions (request/mqttTool, etc.)
│   │   └── views/              ← Business page views
│   ├── package.json
│   └── vue.config.js
│
├── springboot/                 ← Backend Spring Boot multi-module project
│   ├── fastbee-admin/          ← Admin controllers + configuration
│   ├── fastbee-open-api/       ← Open API layer (IoT business Controllers)
│   ├── fastbee-service/        ← Business service layer (iot-service / system-service)
│   ├── fastbee-server/         ← Protocol access services
│   │   ├── iot-server-core/    ← IoT core service logic
│   │   ├── mqtt-broker/        ← Built-in Netty MQTT Broker
│   │   ├── http-server/        ← HTTP device access
│   │   ├── coap-server/        ← CoAP device access
│   │   ├── sip-server/         ← SIP video access
│   │   └── boot-strap/         ← Startup entry
│   ├── fastbee-protocol/       ← Protocol parsing (Modbus/custom)
│   ├── fastbee-mq/             ← Message queue integration
│   ├── fastbee-notify/         ← Notification service (SMS/email/WeChat, etc.)
│   ├── fastbee-plugs/          ← Plugins (OSS/OAuth/Quartz/code generation)
│   ├── fastbee-iot-data/       ← IoT data processing
│   ├── fastbee-record/         ← Recording service
│   ├── fastbee-common-extend/  ← Common utility extensions
│   └── sql/                    ← Database initialization/upgrade scripts
│
├── docker/                     ← Docker Compose deployment files
└── sdk/                        ← Device-side SDK

7. Functional Module Descriptions

Device Management

Function	Description
Device registration/import	Add devices manually or import them in batches via Excel
Device assignment/recycling	Assign devices by organization/user dimension, with recycling support
Real-time status refresh	Update online/offline status in real time by subscribing to `/+/{sn}/status/post` over MQTT
Device QR code	Generate binding QR codes with printing support
OTA firmware upgrade	Version management + upgrade task delivery
Command delivery	Thing Model property delivery / function invocation
Shadow mode	Cache the latest values in the shadow while the device is offline

Page route: /iot/device/list → views/iot/device/index.vue

Product Management

Function	Description
Product template	Define device types and Thing Models
Thing Model	The three elements: Property / Function / Event
Protocol configuration	MQTT / HTTP / CoAP / TCP / Modbus / JT808
Product release	After release, the Thing Model of devices can no longer be modified
Drag-and-drop editor	Visually configure the device running status panel

Rule Engine

Function	Description
Scene Linkage	Visual orchestration of trigger → condition → action (driven by LiteFlow)
Device alerts	Triggered by threshold/range/boolean, with silence period support
Rule scripts	Groovy/JavaScript scripts for processing raw data
One-click trigger	Manually trigger a scene linkage

Data Center

Function	Description
Real-time data	The latest Thing Model values reported by devices (Redis cache)
Historical data	Query by time range (TDengine time-series database)
Data reports	Generate Excel files on a schedule, with email notification support
Data export	Download historical data

Video Surveillance

Function	Description
Device access	Supports the GB28181 (SIP) protocol
Live playback	RTMP / RTSP / FLV / HLS / WebRTC
Recording playback	Query historical recordings by time range (ZLMediaKit)
PTZ control	PTZ command delivery
Voice intercom	SIP TCP active mode

Notification Service

Supported channels: SMS (Alibaba Cloud/Tencent), email, WeChat Official Account, Enterprise WeChat, DingTalk, HTTP push, MQTT push.

System Management

Users / roles / organizations (multi-tenant) / menus / dictionaries / logs / system monitoring / code generation.

8. API Documentation

The complete API documentation is available through Swagger: http://localhost:8080/swagger-ui/index.html (development environment)

All APIs use a unified response format:

json

{
  "code": 200,
  "msg": "Operation successful",
  "data": { ... }
}

Paged list response format:

json

{
  "code": 200,
  "msg": "Operation successful",
  "rows": [ ... ],
  "total": 100
}

Authentication APIs

Method	Path	Description
POST	`/login`	Account password login
POST	`/register`	User registration
POST	`/logout`	Logout
GET	`/getInfo`	Get current user information
GET	`/captchaImage`	Get image captcha
POST	`/auth/sms/login`	SMS code login
GET	`/auth/login/{loginId}`	Third-party social login
POST	`/auth/ssoLogin`	SSO single sign-on

Login example:

bash

POST /login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123",
  "code": "1234",
  "uuid": "xxx-xxx-xxx",
  "sourceType": 1
}

json

{
  "code": 200,
  "msg": "Operation successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Subsequent requests must carry the header: Authorization: Bearer {token}

Device APIs (`/iot/device`)

Method	Path	Permission	Description
GET	`/iot/device/list`	`iot:device:list`	Device paged list
GET	`/iot/device/shortList`	`iot:device:list`	Device short list (home page)
GET	`/iot/device/all`	`iot:device:list`	Short list of all devices
GET	`/iot/device/{deviceId}`	`iot:device:query`	Device details
GET	`/iot/device/getDeviceBySerialNumber/{sn}`	`iot:device:query`	Query by serial number
POST	`/iot/device`	`iot:device:add`	Add device
PUT	`/iot/device`	`iot:device:edit`	Edit device
DELETE	`/iot/device/{deviceId}`	`iot:device:remove`	Delete device
POST	`/iot/device/export`	`iot:device:export`	Export Excel
POST	`/iot/device/assignment`	`iot:device:assignment`	Assign device to organization
POST	`/iot/device/user/assignment`	`iot:device:assignment`	Assign device to user
POST	`/iot/device/recovery`	`iot:device:recovery`	Recycle device
GET	`/iot/device/runningStatus`	`iot:device:query`	Running status
GET	`/iot/device/thingsModelValue/{deviceId}`	`iot:device:query`	Thing Model real-time values
GET	`/iot/device/statistic`	-	Monitoring data statistics

Product APIs (`/iot/product`)

Method	Path	Description
GET	`/iot/product/list`	Product paged list
GET	`/iot/product/shortList`	Product short list
GET	`/iot/product/{productId}`	Product details
POST	`/iot/product`	Add product
PUT	`/iot/product`	Edit product
DELETE	`/iot/product/{productId}`	Delete product
PUT	`/iot/product/status`	Publish/unpublish product
POST	`/iot/product/copy?productId=`	Copy product

Thing Model APIs (`/iot/thingsModel`)

Method	Path	Description
GET	`/iot/thingsModel/list`	Thing Model list
POST	`/iot/thingsModel`	Add Thing Model
PUT	`/iot/thingsModel`	Edit Thing Model
DELETE	`/iot/thingsModel/{modelId}`	Delete Thing Model
POST	`/iot/thingsModel/sync`	Sync to devices

Rule Engine APIs (`/iot/scene`)

Method	Path	Description
GET	`/iot/scene/list`	Scene linkage list
POST	`/iot/scene`	Add scene
PUT	`/iot/scene`	Edit scene
DELETE	`/iot/scene/{sceneId}`	Delete scene
POST	`/iot/scene/trigger/{sceneId}`	Manual trigger

Data Center APIs (`/iot/datacenter`)

Method	Path	Description
GET	`/iot/datacenter/latestData`	Latest data
GET	`/iot/datacenter/historyData`	Historical data

9. Development Standards

Frontend Naming Conventions

Type	Convention	Example
Files/directories	kebab-case	`device-edit.vue`
Component names	PascalCase	`DeviceCard`
Variables/methods	camelCase	`deviceList`, `handleQuery()`
Constants	UPPER_CASE	`MAX_PAGE_SIZE`
API files	camelCase	`device.js`, `product.js`
CSS class names	kebab-case	`.device-item`

Backend Naming Conventions

Type	Convention	Example
Package names	All lowercase, dot-separated	`com.fastbee.iot.service`
Class names	PascalCase	`DeviceServiceImpl`
Interface names	I + PascalCase	`IDeviceService`
Method names	camelCase	`listDeviceByGroup()`
Constants	UPPER_SNAKE	`MAX_RETRY_COUNT`
Database tables	Lowercase with underscores	`iot_device`
Database fields	Lowercase with underscores	`serial_number`

API Design Conventions

RESTful style; resource names use plural nouns
Unified route prefixes: /iot/ (IoT module), /system/ (system module)
Controllers extend BaseController and use @PreAuthorize for permission checks
Use the @Log annotation to record operation logs
Return uniformly with AjaxResult.success() / getDataTable()

java

@PreAuthorize("@ss.hasPermi('iot:device:add')")
@Log(title = "Device", businessType = BusinessType.INSERT)
@PostMapping
@ApiOperation("Add device")
public AjaxResult add(@Validated @RequestBody Device device) {
    return toAjax(deviceService.insertDevice(device));
}

10. FAQ

Frontend

Q: Startup reports patch-package related errors after npm install?

Cause: node_modules is not fully installed or a cache issue.

bash

# Clear the cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Q: APIs return 404 in the development environment?

Check whether VUE_APP_SERVER_API_URL in .env.development correctly points to the backend, and confirm the backend has been started.

Q: The Element UI dialog (MessageBox) cannot pop up?

Confirm that the component is registered globally. The project completes registration through Vue.use(Element) in main.js; no separate import is needed.

Q: MQTT connection fails?

Confirm that VUE_APP_MQTT_SERVER_URL is configured correctly (ws://localhost:8083/mqtt in the development environment)
Confirm that the built-in Broker is started (server.broker.enabled: true + server.broker.websocket-port: 8083)
Check whether the Token is valid (mqttTool uses the Token as the MQTT password)

Q: vue-treeselect has a version conflict?

The project uniformly uses @riophae/vue-treeselect@0.4.0; do not mix other versions.

Q: The vue-qr component import reports an error?

javascript

// ✅ Correct way (default import)
import vueQr from 'vue-qr';
// ❌ Wrong way (named import fails)
import { VueQr } from 'vue-qr';

Backend

Q: Startup reports license related errors?

Configure the correct certificate path in application-dev.yml:

yaml

license:
  subject: common
  licensePath: classpath:license.lic

Apply to the official team for the certificate file (license.lic) and place it in the resources directory.

Q: TDengine reports a connection timeout?

Confirm that TDengine is started (default port 6041)
Check the taos data source configuration in application-dev.yml
If the time-series database is not needed, set taos.enabled: false to skip it

Q: The rule engine does not trigger?

Confirm that the scene linkage status is "Enabled"
Check the trigger conditions (value range, comparison operators)
Check the LiteFlow execution chain in the logs

Q: The device is online but the backend does not show the online status?

Check MQTT authentication (EMQX Webhook configuration)
Confirm that the device serialNumber matches the one entered in the system
Check whether the backend logs contain device status processing records

Q: How to switch between EMQX and the built-in Broker?

yaml

# application.yml
server:
  broker:
    enabled: true   # true = built-in Netty Broker
                    # false = use external EMQX (requires spring.mqtt.host-url)

Q: How is multi-tenant data isolation implemented?

The platform isolates data through the tenant_id (organization ID) field. The Controller layer obtains the current login user's organization information from SecurityUtils.getLoginUser(), and the Service layer filters automatically when querying.

Q: How to access the Druid monitoring page?

Visit http://localhost:8080/druid/index.html in a browser. The default account and password are both fastbee (can be modified in application.yml).

IoT System ​

Page Guide ​

Edition Comparison ​

1. Platform Introduction ​

2. System Functions ​

3. Technology Stack ​

4. Application Scenarios ​

5. System Architecture ​

6. Code Structure ​

7. Functional Module Descriptions ​

Device Management ​

Product Management ​

Rule Engine ​

Data Center ​

Video Surveillance ​

Notification Service ​

System Management ​

8. API Documentation ​

Authentication APIs ​

Device APIs (/iot/device) ​

Product APIs (/iot/product) ​

Thing Model APIs (/iot/thingsModel) ​

Rule Engine APIs (/iot/scene) ​

Data Center APIs (/iot/datacenter) ​

9. Development Standards ​

Frontend Naming Conventions ​

Backend Naming Conventions ​

API Design Conventions ​

10. FAQ ​

Frontend ​

Backend ​

IoT System

Page Guide

Edition Comparison

1. Platform Introduction

2. System Functions

3. Technology Stack

4. Application Scenarios

5. System Architecture

6. Code Structure

7. Functional Module Descriptions

Device Management

Product Management

Rule Engine

Data Center

Video Surveillance

Notification Service

System Management

8. API Documentation

Authentication APIs

Device APIs (`/iot/device`)

Product APIs (`/iot/product`)

Thing Model APIs (`/iot/thingsModel`)

Rule Engine APIs (`/iot/scene`)

Data Center APIs (`/iot/datacenter`)

9. Development Standards

Frontend Naming Conventions

Backend Naming Conventions

API Design Conventions

10. FAQ

Frontend

Backend