# FastBee-Gateway

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

## Basic Information

- **Project Name**: FastBee-Gateway
- **Description**: 工业 IoT 协议转换网关 —— 连接现场设备与云平台的桥梁。运行在 ARM Linux 工业网关上的 C++ 守护进程软件，定位为协议转换网关，用户开箱即用地实现从现场工业设备到云平台的端到端数据采集与反向控制。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://fastbee.cn/doc/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2026-07-30
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastBee Gateway

**工业 IoT 协议转换网关** —— 连接现场设备与云平台的桥梁

[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
[![C++](https://img.shields.io/badge/C%2B%2B-17-orange.svg)](https://en.cppreference.com/)
[![CMake](https://img.shields.io/badge/CMake-3.16%2B-green.svg)](https://cmake.org/)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg)]()

---

## 简介

**FastBee Gateway** 是运行在 Linux 工业网关硬件上的 **C++ 协议转换与数据采集软件**（对标 BL110 / InGateway / Neuron 同类产品）。

> 工厂里有大量 PLC、传感器、电表、空调控制器等设备，它们说着不同的"语言"（Modbus、OPC UA、BACnet……），而云平台只听懂 MQTT。
> **FastBee Gateway 就是它们之间的翻译官。**

它读取现场设备的寄存器数据，统一转换为标准 Tag 模型，经过死区过滤、变化检测、批量合并后，通过 MQTT 实时上报到 FastBee 平台。同时支持云端反向下发控制指令，实现"采集 + 控制"双向通道。

作为 FastBee 云边端一体化方案的**原生组件**，核心价值在于：从 ESP32 传感器 → 网关 → 边缘 → 云端 → 大屏的全链路打通，**全栈自研，零商业依赖**。

### 核心亮点

| 特性 | 说明 |
|------|------|
| 多协议支持 | Modbus RTU/TCP、OPC UA、BACnet IP、DLT645、S7comm，覆盖 90% 工业现场 |
| 零代码接入 | Web 界面配置设备和点位，无需写代码 |
| 断网不丢数据 | SQLite 本地缓存（10万条），网络恢复后自动补传 |
| 双向控制 | 云端下发指令 → 网关写寄存器 → 设备执行 |
| GPIO 硬件接口 | DI/DO/AI 直接接入开关量、继电器、模拟量传感器 |
| 工业报警引擎 | 5 种报警类型 + 死区防抖 + 状态机 + 操作员确认 |
| 驱动健康监控 | 6 态连接状态机 + 连续错误自动隔离 + 自动恢复 |
| 轻量部署 | 单个二进制 + JSON 配置，最低 64MB 内存即可运行 |

### 典型应用场景

| 场景 | 说明 |
|------|------|
| 🏭 智慧工厂 | 采集 PLC/传感器数据（温度、压力、流量）→ 上报云端看板 |
| 🏢 楼宇自控 | BACnet 空调/照明控制 → 远程监控与节能管理 |
| ⚡ 电力监控 | Modbus 电表/保护装置 → 用电分析与报警 |
| 🌾 智慧农业 | 土壤/气象传感器 → 自动灌溉控制 |
| 🔧 设备运维 | 设备运行状态监控 → 预测性维护 |

---

## FastBee 生态架构

```
┌──────────────────────────────────────────────────────────────────────┐
│  fastbee-cloud (云端中央平台)                                         │
│  Spring Boot + Vue3 + 自研 MQTT 服务端 + MySQL + TDengine            │
│  全局设备管理 · 大数据分析 · 外网访问 · OTA 管理                      │
├──────────────────────────────────────────────────────────────────────┤
│                        ↕ MQTT 桥接 (外网/TLS)                        │
├──────────────────────────────────────────────────────────────────────┤
│  fastbee-edge (边缘平台，可多实例)                                     │
│  FastBee Docker 精简部署 · 自研 MQTT 服务端 · 本地规则引擎            │
│  内网低延迟控制 · 断网自治 · 数据就近处理                              │
├──────────────────────────────────────────────────────────────────────┤
│                     ↕ MQTT (内网/局域网)                              │
├────────────────────────────────┬─────────────────────────────────────┤
│  fastbee-gateway (本网关)       │  fastbee-arduino (ESP32 直连设备)   │
│  C++17 · 自研协议栈             │  C++ Arduino · WiFi MQTT 直连       │
│  Modbus/OPC UA/BACnet/DLT645   │  智能开关/传感器/门锁/RGB灯带       │
│  RS485/以太网 → MQTT 转换       │  物模型属性上报 · 指令接收执行      │
└────────────────────────────────┴─────────────────────────────────────┘
```

---

## 功能模块

| 模块 | 功能 |
|------|------|
| **概览仪表盘** | 系统状态（CPU/内存/温度）、设备在线统计、数据流量、报警概览 |
| **网络管理** | 以太网 WAN/LAN、WiFi STA/AP 配网、DHCP/DNS、状态监控 |
| **安全认证** | 用户登录 + Token 会话、多角色权限、MQTT TLS 加密 |
| **工业协议采集** | Modbus RTU/TCP、OPC UA、BACnet IP、IEC104、DLT645、S7comm |
| **数据采集/上报** | 定时轮询、死区过滤、变化触发、批量合并、MQTT 上报（AES 认证） |
| **反向控制/联动** | 云端指令→写寄存器、DO 控制、阈值报警、AI→DO 联动、定时任务 |
| **GPIO 管理** | DI 状态/脉冲计数、DO 控制、AI 工程值转换（4-20mA/0-10V）、LED |
| **工业报警引擎** | 5 种报警类型、死区防抖、状态机（NORMAL→ACTIVE→ACKED→RETURNED） |
| **驱动健康监控** | 6 态连接状态机、连续错误自动隔离、Watchdog 超时、自动恢复 |
| **Tag 聚合计算** | MAX/MIN/AVG/TOTAL/DELTA/RATE 滑动窗口聚合 |
| **工程值转换** | 线性缩放、开方缩放（差压流量计）、反向转换（控制下发） |
| **在线调试** | 实时数据查看、手动读写测试、MQTT/串口调试、Ping 测试 |
| **系统管理** | 用户管理、日志轮转、NTP 时间同步、配置导入导出、OTA 升级 |
| **容错与可靠性** | 断网缓存补传、MQTT 指数退避重连、systemd watchdog、崩溃自愈 |

---

## 技术架构

| 项目 | 技术选型 |
|------|--------|
| 语言 | C++17 |
| 构建系统 | CMake 3.16+ |
| HTTP 服务 | cpp-httplib v0.18 |
| MQTT 客户端 | Eclipse Paho MQTT C++ |
| 日志 | spdlog v1.14 |
| JSON | nlohmann/json v3.11 |
| 数据库 | SQLite3（本地缓存） |
| 加密 | OpenSSL（AES/HMAC） |
| 串口 Modbus | libmodbus |
| OPC UA | open62541（可选） |
| BACnet | BACnet Stack（可选） |
| GPIO | libgpiod（可选） |
| 测试 | GoogleTest v1.15 |

### 软件架构图

```
┌───────────────────────────────────────────────────────────────┐
│              fastbee-gateway (C++ daemon)                     │
│                                                               │
│  ┌──────────┐  ┌────────────┐  ┌────────────────────────┐  │
│  │ Web 管理  │  │ TagEngine  │  │ FastBee MQTT 客户端      │  │
│  │ (nginx)  │  │ 采集引擎    │  │ → edge 平台 MQTT 服务端  │  │
│  └──────────┘  └────────────┘  └────────────────────────┘  │
│  ┌──────────┐  ┌────────────┐  ┌────────────────────────┐  │
│  │ 设备管理  │  │ 配置管理    │  │ GpioManager (libgpiod)  │  │
│  │ 子设备注册│  │ JSON+SQLite │  │ DI / DO / AI / LED      │  │
│  └──────────┘  └────────────┘  └────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐│
│  │          统一 Tag 模型 (TagConfig)                        ││
│  │  ModbusTag / OpcUaTag / BacnetTag / GpioTag / SystemTag  ││
│  └────────────────────────────────────────────────────────┘│
│  ┌────────────────────────────────────────────────────────┐│
│  │        协议驱动抽象层 (IProtocolDriver)                    ││
│  │  init() / readTags() / writeTag() / 动态加载 .so          ││
│  └────────────────────────────────────────────────────────┘│
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│  │ Modbus   │ │ OPC UA   │ │ BACnet   │ │ IEC104 / DLT645  ││
│  │ libmodbus│ │ open62541│ │ BACnet St│ │ lib60870 / 自研  ││
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘│
├───────────────────────────────────────────────────────────────┤
│              Linux HAL (ARM)                                  │
│  /dev/ttyS* (多串口) /dev/i2c-* libgpiod ext4               │
└───────────────────────────────────────────────────────────────┘
```

---

## 支持的协议

| 协议 | 传输方式 | 库 | 优先级 | 状态 |
|------|---------|-----|:------:|------|
| Modbus RTU | RS485 串口 | libmodbus | P0 | ✅ 已实现 |
| Modbus TCP | 以太网 | libmodbus | P0 | ✅ 已实现 |
| OPC UA | 以太网 | open62541 | P1 | 🔧 开发中 |
| BACnet IP | 以太网 | BACnet Stack | P1 | 🔧 开发中 |
| IEC 60870-5-104 | 以太网 | lib60870 | P2 | 🔧 Stub |
| DLT645 | RS485 串口 | 自实现 | P2 | ✅ 已实现 |
| Siemens S7 | 以太网 | 自实现 | P2 | ✅ 已实现 |

---

## 快速开始

### 环境要求

- **操作系统**：Linux（Debian 12 推荐）/ macOS / Windows（开发调试）
- **编译器**：GCC 9+ / Clang 10+ / MSVC 2019+
- **CMake**：3.16+
- **依赖库**：OpenSSL、pkg-config、libmodbus（可选）

### PC 开发环境（x86_64）

```bash
# 克隆仓库
git clone https://gitee.com/kerwincui/FastBee-Gatway.git
cd FastBee-Gatway

# 安装依赖（Ubuntu/Debian）
sudo apt install build-essential cmake pkg-config libssl-dev libmodbus-dev

# 编译
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j$(nproc)

# 运行
./bin/fastbee-gateway --config ../config/gateway.json --log-level debug
```

### 树莓派（ARM）

```bash
# 安装依赖
sudo apt install build-essential cmake pkg-config libssl-dev libmodbus-dev libgpiod-dev

# 编译（启用 GPIO）
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DFASTBEE_ENABLE_GPIO=ON
cmake --build . -j$(nproc)

# 安装为 systemd 服务
sudo cmake --install .
sudo systemctl enable fastbee-gateway
sudo systemctl start fastbee-gateway
```

### ARM 工业网关（交叉编译）

```bash
mkdir build && cd build
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/aarch64-toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DFASTBEE_ENABLE_GPIO=ON \
  -DFASTBEE_BUILD_TESTS=OFF

cmake --build . -j$(nproc)
```

---

## 编译构建

### CMake 选项

| 选项 | 默认值 | 说明 |
|------|:------:|------|
| `FASTBEE_BUILD_TESTS` | ON | 编译单元和集成测试 |
| `FASTBEE_BUILD_DRIVERS` | ON | 编译协议驱动动态库 |
| `FASTBEE_ENABLE_GPIO` | OFF | 启用真实 GPIO（libgpiod） |
| `FASTBEE_ENABLE_OPCUA` | OFF | 编译 OPC UA 驱动 |
| `FASTBEE_ENABLE_BACNET` | OFF | 编译 BACnet 驱动 |

### Docker 部署（推荐）

```bash
# 一键启动（Gateway + Mosquitto）
docker compose up -d --build

# 或单独构建
docker build -t fastbee-gateway:latest .
docker run -d --name fastbee-gw \
  -p 8080:8080 \
  -v ./config:/opt/fastbee/config:ro \
  fastbee-gateway:latest
```

### 生成 deb 包

```bash
cpack -G DEB
# 输出: fastbee-gateway-1.0.0-arm64.deb
```

---

## 配置说明

配置文件位于 `config/` 目录，详细参考见 [docs/configuration.md](docs/configuration.md)。

### gateway.json — 主配置（摘要）

```json
{
  "gateway": { "name": "fastbee-gateway", "webPort": 8080, "logLevel": "info" },
  "mqtt": {
    "broker": "192.168.1.100", "port": 1883,
    "clientId": "gateway-001",
    "productId": "P_GATEWAY", "deviceNum": "GW_A4CF12345678",
    "keepAlive": 60, "qos": 1, "tls": false
  },
  "devices": [
    {
      "deviceNum": "GW_A4CF12345678_01", "productId": "P002",
      "protocol": "modbus-rtu", "slaveAddress": 1,
      "serialPort": "/dev/ttyS1", "baudRate": 9600,
      "tags": ["..."]
    }
  ]
}
```

### gpio.json — GPIO 配置（摘要）

```json
{
  "di":  [{"channel": 0, "name": "door_sensor", "productId": "P003", "propertyId": "door"}],
  "do":  [{"channel": 0, "name": "relay_1", "productId": "P003", "propertyId": "relay"}],
  "ai":  [{"channel": 0, "name": "temp_sensor", "range": [4,20], "unit": "mA", "engMin": 0, "engMax": 100}],
  "led": [{"name": "power", "gpio": 17}, {"name": "network", "gpio": 27}, {"name": "fault", "gpio": 22}]
}
```

---

## Web 管理界面

网关内置 Web 管理界面，通过浏览器访问 `http://<网关IP>:8080`：

| 页面 | 功能描述 |
|------|--------|
| **概览仪表盘** | 系统资源使用率、设备在线统计、流量图表、报警列表 |
| **设备管理** | 子设备增删改查、Tag 配置、协议参数设置、批量导入导出 |
| **GPIO 管理** | DI 实时状态、DO 手动控制、AI 工程值显示、LED 配置 |
| **MQTT 配置** | Broker 地址/端口/认证、TLS 证书、连接状态 |
| **在线调试** | 实时 Tag 数据查看、手动读写测试、MQTT 消息监控 |
| **系统管理** | 用户管理、日志查看、配置导入导出、OTA 升级、时间设置 |

---

## 目录结构

```
FastBee-Gatway/
├── CMakeLists.txt              # CMake 主构建文件
├── README.md                   # 项目文档（本文件）
├── LICENSE                     # AGPL-3.0 许可证
├── FastBee云边端一体化解决方案.md
├── FastBee云边端一体化实施计划.md
├── src/
│   ├── main.cpp                # daemon 入口
│   ├── core/                   # 网关主类 + 全局配置
│   ├── mqtt/                   # MQTT 客户端 + AES 认证
│   ├── protocol/               # 驱动抽象接口 + 工厂 + Tag映射
│   ├── drivers/                # 协议驱动 (modbus/opcua/bacnet)
│   ├── engine/                 # 采集引擎 + 死区过滤 + 变化触发
│   ├── device/                 # 子设备管理
│   ├── config/                 # 配置管理 + SQLite 缓存
│   ├── web/                    # HTTP 服务 + API 路由
│   ├── system/                 # 日志/认证/用户/任务/系统信息
│   └── hal/                    # GPIO + 网络管理
├── include/fastbee/            # 全局类型/平台检测/Tag模型/版本
├── config/                     # 默认配置文件
├── scripts/systemd/            # systemd 服务文件
├── test/
│   ├── unit/                   # 单元测试（37 文件，510 用例）
│   └── integration/            # 集成测试（4 文件，30 用例）
├── docs/                       # 项目文档
├── cmake/                      # CMake 工具链文件
└── third_party/                # 第三方依赖
```

---

## 测试

> **说明**：当 SQLite3 amalgamation 不可用时（stub 模式），28 个测试自动跳过。典型结果：**482 通过、28 跳过、0 失败**。

```bash
cd build
cmake .. -DFASTBEE_BUILD_TESTS=ON
cmake --build . -j$(nproc)

# 运行所有测试
ctest --output-on-failure

# 运行指定用例
./bin/gateway_unit_tests --gtest_filter="DeadbandFilter*"
```

---

## 开发指南：添加新协议驱动

详见 [docs/protocol-drivers.md](docs/protocol-drivers.md)。快速步骤：

1. 创建 `src/drivers/myprotocol/MyProtocolDriver.cpp`，实现 `IProtocolDriver` 接口
2. 导出 `extern "C" createDriver() / destroyDriver()` 工厂函数
3. 使用 `FASTBEE_REGISTER_DRIVER("myprotocol", MyProtocolDriver)` 宏注册
4. 在 `CMakeLists.txt` 中添加驱动编译规则
5. 在 `gateway.json` 的 `devices` 数组中添加设备和 Tag 配置
6. 编写单元测试并通过调试接口验证

---

## 相关链接

| 文档 | 说明 |
|------|------|
| [云边端一体化解决方案](FastBee云边端一体化解决方案.md) | 整体架构设计 |
| [云边端一体化实施计划](FastBee云边端一体化实施计划.md) | 开发路线图 |
| [部署文档](docs/deployment.md) | Docker / systemd / 交叉编译 |
| [配置参考](docs/configuration.md) | 完整配置字段说明 |
| [运维手册](docs/operations.md) | 日志/监控/故障排查 |
| [Web API 文档](docs/api.md) | REST API 接口说明 |
| [协议驱动开发指南](docs/protocol-drivers.md) | 新协议接入教程 |
| [外设系统设计](docs/peripheral-system-design.md) | GPIO/传感器设计 |
| [优化路线图](docs/optimization-roadmap.md) | 性能优化计划 |

**生态项目：**
- [FastBee 主项目（云端平台）](https://gitee.com/kerwincui/FastBee)
- [FastBee-Arduino（ESP32 设备固件）](https://gitee.com/kerwincui/FastBee-Arduino)