FastBee ARM Gateway Overview
Page Guide
Documentation Baseline and Implementation Status
The documents in this section are written against commit b1a16cbc on the master branch of the fastbee-gateway project (gitee.com/beecue/fastbee-gateway). The project is under active development: some protocol drivers and pipelines are still being wired up. Each page explicitly marks its status as "implemented / under development / designed but not yet connected"; evaluate usability based on these status labels.
1. Product Introduction
Factories are full of PLCs, sensors, meters, and air-conditioning controllers, each "speaking" a different language (Modbus, OPC UA, BACnet ...), while the cloud platform only understands MQTT. FastBee Gateway is the translator between them: it reads register data from field devices, converts everything into a unified standard Tag model, and reports it to the FastBee platform over MQTT in real time after deadband filtering, change detection, and batch merging. It also supports reverse control commands delivered from the cloud, providing a bidirectional "acquisition + control" channel.
As a native component of FastBee's integrated cloud-edge-device solution, its core value lies in connecting the full pipeline from ESP32 sensors → gateway → edge → cloud → dashboard. It is fully self-developed with zero commercial dependencies, and shares the same Thing Model and MQTT topic specifications with the FastBee open-source IoT platform and the device-side firmware.
2. Core Highlights
| Feature | Description |
|---|---|
| Multi-protocol support | Modbus RTU/TCP, OPC UA, BACnet IP, DLT645, S7comm, and IEC104, covering mainstream industrial field scenarios |
| Zero-code access | Configure devices and data points in the Web UI without writing code |
| Offline caching design | Local SQLite cache (up to 100,000 records) with retransmission after the network recovers (pipeline still being connected; see Section 8) |
| Bidirectional control | Cloud command delivery → gateway writes registers → device executes |
| GPIO hardware interfaces | DI/DO/AI for direct access to digital signals, relays, and analog sensors |
| Industrial alarm engine | 5 alarm types + deadband debounce + state machine + operator acknowledgment |
| Driver health monitoring | 6-state connection state machine + automatic isolation after consecutive errors + automatic recovery |
| Lightweight deployment | A single binary plus JSON configuration runs on low-memory devices |
3. Typical Use Cases
| Scenario | Description |
|---|---|
| Smart factory | Collect PLC/sensor data (temperature, pressure, flow) → report to cloud dashboards |
| Building automation | BACnet air-conditioning/lighting control → remote monitoring and energy management |
| Power monitoring | Modbus/DLT645 meters and protection devices → power usage analysis and alarms |
| Smart agriculture | Soil/weather sensors → automatic irrigation control |
| Equipment O&M | Equipment runtime status monitoring → predictive maintenance |
4. FastBee Ecosystem Architecture
The gateway's position in FastBee's integrated cloud-edge-device solution:
┌──────────────────────────────────────────────────────────────────────┐
│ fastbee-cloud (central cloud platform) │
│ Spring Boot + Vue3 + in-house MQTT server + MySQL + TDengine │
│ Global device mgmt · big data analytics · WAN access · OTA mgmt │
├──────────────────────────────────────────────────────────────────────┤
│ ↕ MQTT bridging (WAN/TLS) │
├──────────────────────────────────────────────────────────────────────┤
│ fastbee-edge (edge platform, multi-instance) │
│ FastBee Docker slim deployment · in-house MQTT server │
│ Local rule engine · low-latency LAN control │
│ Offline autonomy · local data processing │
├──────────────────────────────────────────────────────────────────────┤
│ ↕ MQTT (LAN) │
├───────────────────────────────────┬──────────────────────────────────┤
│ fastbee-gateway (this gateway) │ fastbee-arduino (ESP32 devices) │
│ C++17 · in-house protocol stacks │ C++ Arduino · WiFi MQTT direct │
│ Modbus/OPC UA/BACnet/DLT645 │ Smart switch/sensor/lock/RGB │
│ RS485/Ethernet → MQTT conversion │ Property report · cmd execution │
└───────────────────────────────────┴──────────────────────────────────┘5. Functional Modules
| Module | Function |
|---|---|
| Overview dashboard | System status (CPU/memory/temperature), device online statistics, data traffic, alarm overview |
| Network management | Ethernet WAN/LAN, WiFi STA/AP configuration, DHCP/DNS, status monitoring |
| Security authentication | User login + token sessions, multi-role permission model, MQTT TLS encryption options |
| Industrial protocol acquisition | Modbus RTU/TCP, OPC UA, BACnet IP, IEC104, DLT645, S7comm |
| Data acquisition/reporting | Scheduled polling, deadband filtering, change-triggered reporting, batch merging, MQTT reporting (AES authentication) |
| Reverse control/linkage | Cloud commands → register writes, DO control, threshold alarms, linkage rules, scheduled tasks |
| GPIO management | DI status/pulse counting, DO control, AI engineering-value conversion (4-20mA/0-10V), LED |
| Industrial alarm engine | 5 alarm types, deadband debounce, state machine (NORMAL→ACTIVE→ACKED→RETURNED) |
| Driver health monitoring | 6-state connection state machine, automatic isolation after consecutive errors, watchdog timeout, automatic recovery |
| Tag aggregation | MAX/MIN/AVG/TOTAL/DELTA/RATE sliding-window aggregation |
| Engineering-value conversion | Linear scaling, square-root scaling (differential-pressure flowmeters), reverse conversion (control delivery) |
| Online debugging | Real-time data viewing, manual read/write tests, MQTT/serial debugging, ping tests |
| System management | User management, log rotation, NTP time sync, configuration import/export, OTA upgrades |
| Fault tolerance and reliability | Offline cache retransmission design, MQTT exponential-backoff reconnection, systemd watchdog, crash self-healing |
The measured connection status of each module is marked in Section 8 and on the individual sub-pages.
6. Technical Architecture
| Item | Technology |
|---|---|
| Language | C++17 |
| Build system | CMake 3.16+ |
| HTTP service | cpp-httplib v0.18 |
| MQTT client | Eclipse Paho MQTT C++ |
| Logging | spdlog v1.14 |
| JSON | nlohmann/json v3.11 |
| Database | SQLite3 (local cache) |
| Encryption | OpenSSL (AES/HMAC) |
| Serial Modbus | libmodbus |
| OPC UA | open62541 (optional) |
| BACnet | BACnet Stack (optional) |
| GPIO | libgpiod (optional) |
| Testing | GoogleTest v1.15 |
Software architecture:
┌────────────────────────────────────────────────────────────────────────┐
│ fastbee-gateway (C++ daemon) │
│ │
│ ┌───────────┐ ┌───────────────┐ ┌───────────────────────────────┐ │
│ │ Web Admin │ │ TagEngine │ │ FastBee MQTT client │ │
│ │ (built-in │ │ acquisition │ │ → edge platform MQTT server │ │
│ │ HTTP) │ │ engine │ │ │ │
│ └───────────┘ └───────────────┘ └───────────────────────────────┘ │
│ ┌───────────┐ ┌───────────────┐ ┌───────────────────────────────┐ │
│ │ Device │ │ Config mgmt │ │ GpioManager (libgpiod) │ │
│ │ mgmt / │ │ JSON + SQLite │ │ DI / DO / AI / LED │ │
│ │ subdevice │ │ │ │ │ │
│ └───────────┘ └───────────────┘ └───────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Unified Tag model (TagConfig) │ │
│ │ ModbusTag / OpcUaTag / BacnetTag / GpioTag / SystemTag │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Protocol driver abstraction (IProtocolDriver) │ │
│ │ init() / readTags() / writeTag() / dynamic .so loading │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌────────────────────────┐ │
│ │ Modbus │ │ OPC UA │ │ BACnet │ │ IEC104 / DLT645 │ │
│ │ libmodbus │ │ open62541 │ │ BACnet St │ │ lib60870 / in-house │ │
│ └───────────┘ └───────────┘ └───────────┘ └────────────────────────┘ │
├────────────────────────────────────────────────────────────────────────┤
│ Linux HAL (ARM) │
│ /dev/ttyS* (multi-serial) /dev/i2c-* libgpiod ext4 │
└────────────────────────────────────────────────────────────────────────┘7. Supported Protocols
| Protocol | Transport | Dependency | Driver code status |
|---|---|---|---|
| Modbus RTU | RS485 serial | libmodbus | Implemented: connection, FC01/02/03/04 reads, FC05/06/15/16 writes |
| Modbus TCP | Ethernet | libmodbus | Implemented: same as above |
| DLT645 | RS485 serial | In-house | Frame format complete (both 1997/2007 versions); serial link integration in progress |
| Siemens S7 | Ethernet | Snap7 (optional) | Dual mode: real implementation / Stub simulation |
| OPC UA | Ethernet | open62541 | Dual mode: enable real communication with -DFASTBEE_ENABLE_OPCUA=ON; Stub by default |
| BACnet IP | Ethernet | BACnet Stack | Interface defined; currently a Stub simulated implementation |
| IEC 60870-5-104 | Ethernet | lib60870 (to be integrated) | Stub: frame format and 28 typical substation data points complete; real communication to be integrated |
For driver development details, see Protocol Driver Development.
8. Current Implementation Status and Limitations
The following conclusions come from a direct review of the source code at commit b1a16cbc, and are meant to prevent design capabilities from being mistaken for end-to-end usable capabilities:
- Driver wiring blocker:
GatewayApp::initDrivers()currently only loads and logs the number of driver configurations; it does not register the configured driver instances with TagEngine. Therefore, simply writingdriversconfiguration does not yet form a real acquisition loop. This is a shared application-layer blocker for all protocols. - Reverse control not closed: the MQTT client implements the
/{productId}/{deviceNum}/function/#subscription primitive, but no production code currently callssubscribeFunction, so the cloud reverse-control pipeline is not connected. The manual debug write endpointPOST /api/debug/writeis available. - Offline retransmission not connected: the active reporting callback logs and skips the current batch when MQTT is disconnected;
SqliteCachehas not yet been wired into the reporting pipeline. - Some system endpoints are placeholders: factory reset only logs and returns success; the OTA upload endpoint only acknowledges receipt of the file, without validation, installation, or rollback.
- Stub drivers: Stub implementations such as OPC UA/BACnet/IEC104 may return simulated success and cannot be used to accept real device communication.
These limitations do not affect the code paths of registered features such as Web management, device/Tag management, the alarm engine, alerts, peripherals, debugging, and monitoring. For the checklist to remove these blockers, see Section 7 of Quick Start.
9. Documentation Entry Points
- Quick Start: a development-preview checklist for Docker startup, Web login, MQTT configuration, and a Modbus device with a Tag.
- Deployment: hardware requirements, Docker, x86/Raspberry Pi/ARM cross-compilation, deb packages, systemd, and first-time network configuration.
- Configuration: configuration keys as implemented by the runtime code, driver/device/Tag fields, MQTT topics, and data formats.
- Operations: logs, monitoring, backup and recovery, troubleshooting scenarios, and performance tuning.
- API: a REST API reference organized by actually registered routes, with authentication and placeholder behavior notes.
- Peripherals and Linkage: the DI/DO/AI/AO/LED/buzzer/watchdog peripheral model and the peripheral execution rule engine.
- Protocol Driver Development: the IProtocolDriver interface, the driver registration mechanism, and implementation notes for each protocol driver.
10. FAQ
10.1 What is the relationship between the gateway and the ESP32 device-side firmware?
The two are complementary layers in FastBee's cloud-edge-device system: the ESP32 firmware (fastbee-arduino) lets an individual sensor or switch connect directly to the cloud platform over WiFi; fastbee-gateway is deployed on industrial gateways and aggregates field-bus devices that do not support IP protocols (RS485/PLC/meters), reporting them upstream over MQTT in a unified way. Both report using the same Thing Model and topic specifications, so the cloud does not need to distinguish between them.
10.2 Can I develop and debug without real industrial devices?
Yes. On an x86_64 development machine you can run the full pipeline with Stub drivers and simulated backends; for Modbus you can start a TCP simulator with pymodbus for joint debugging (see the simulated device section of Deployment); the Stub drivers for OPC UA/BACnet/IEC104 generate simulated data for UI and workflow verification.
10.3 Will data collected during a network outage be lost?
By design, no: the gateway has a built-in SQLite offline cache (default limit 100,000 records / 50MB) and retransmits in chronological order after recovery. However, in the current commit the cache has not yet been wired into the active reporting pipeline (data is skipped while MQTT is disconnected). Retransmission capability is subject to being connected in a later version; see Section 8.
10.4 How do I integrate a new industrial protocol?
Implement the IProtocolDriver interface (7 methods including init/readTags/writeTag), register it statically with the FASTBEE_REGISTER_DRIVER macro or compile it as a .so for dynamic loading, then add devices and Tags in the configuration. For the complete steps and the Modbus/OPC UA reference implementations, see Protocol Driver Development.