Gateway Quick Start

Page Guide

Use CasesGet fastbee-gateway running on a development machine and complete a minimal closed-loop experience covering Web login, MQTT connection, and device/Tag configuration.

PrerequisitesDocker and Docker Compose installed (or a CMake source-build environment), with access to Gitee to pull the source code.

Action PathStart the Docker environment → log in to the Web UI and change the password → configure MQTT → add a driver/device/Tag → verify reads and writes with the debug API.

Acceptance Criteria`/api/health` returns normally, the Web UI is accessible, MQTT status shows connected, and the debug API returns Tag data.

Development Preview and Current Blockers

This page is not a verified successful end-to-end tutorial. Its content is compiled from a static source audit of commit b1a16cbc; no Docker, browser, MQTT broker, or physical-device acceptance test was executed for this page.

Current blockers include: the application does not create configured drivers and register them with TagEngine; production code does not call subscribeFunction; the default Compose broker address differs from the gateway configuration, and the configuration directory is mounted read-only even though it must accept secret keys and saved configuration. The device, Tag, reporting, and reverse-control sections below serve only as a development configuration checklist and integration-testing reference.

1. Environment Requirements

• Operating system: Linux (Debian 12 recommended) / macOS / Windows (for development and debugging; WSL2 also works)
• Docker approach: Docker ≥ 20.10, Docker Compose ≥ 2.0
• Source approach: GCC 9+ / Clang 10+ / MSVC 2019+, CMake 3.16+, pkg-config, OpenSSL; real Modbus requires libmodbus, real GPIO requires libgpiod

2. Inspect the Docker Startup Assets

Run commands from the fastbee-gateway source root. The image uses a multi-stage Alpine 3.19 build; tests, GPIO, OPC UA, and BACnet are disabled by default, the Modbus driver is built, and web-src is copied into the image.

Before startup, inspect and address the following issues instead of assuming the shipped Compose file is a self-contained demo:

1. The broker service in docker-compose.yml is named mosquitto, but config/gateway.json points to 192.168.1.100:1883 by default.
2. ./config is mounted read-only, while startup may create .secret.key and the MQTT configuration endpoint attempts to save files; the read-only mount prevents these writes from persisting.
3. The ENC(...) ciphertext in the configuration depends on the matching key and cannot be treated as portable default credentials. Replace it with development configuration for your own environment and keep the key safe.
4. The default drivers array is empty, with no preconfigured devices or Tags.

The source provides these development startup commands:

git clone https://gitee.com/beecue/fastbee-gateway.git
cd fastbee-gateway
docker compose up -d --build
docker compose logs -f gateway

From another terminal, check the process and the health endpoint:

curl -fsS http://localhost:8080/api/health

Stop the development environment:

docker compose down

These commands inspect the current source; they do not constitute a claim that the acquisition pipeline is operational. The health endpoint only reflects process and module state, not successful physical-device communication.

3. Open the Web UI and Handle Default Credentials

The Web UI/API is at http://localhost:8080. The current code uses plain HTTP; although Docker exposes 8443, no corresponding HTTPS service is configured, so do not treat https://localhost:8443 as a working entry point.

The first startup creates the default user admin/admin123, and the login page may prefill this credential. Use it only in an isolated development environment, change the password immediately through user management/API, and never expose port 8080 directly to an untrusted network. The current authentication middleware primarily checks token presence and validity; do not claim on this basis that role permissions are enforced across every route.

Main pages of the Web management UI:

Page	Description
Overview Dashboard	System resource usage, device online statistics, traffic charts, alarm list
Device Management	Sub-device CRUD, Tag configuration, protocol parameter settings
GPIO Management	DI real-time status, DO manual control, AI engineering-value display, LED configuration
MQTT Configuration	Broker address/port/authentication, TLS certificates, connection status
Online Debugging	Real-time Tag data viewing, manual read/write tests, MQTT message monitoring
System Management	User management, log viewing, configuration import/export, OTA upgrade, time settings

Note: the Web device page currently supports device add/delete and a read-only Tag list, with no reliable "Add Tag" form; device fields and MQTT save behavior also differ between the UI and the API. The device and Tag JSON below therefore follows the runtime parsers rather than the UI fields.

4. Configure a Development MQTT Connection

Edit the mqtt section in config/gateway.json. A self-contained Compose development environment must at least change the broker host to the service name and remove the unusable ciphertext placeholders:

{
  "mqtt": {
    "broker": "mosquitto",
    "port": 1883,
    "clientId": "fastbee-gw-dev-001",
    "productId": "fastbee-gateway",
    "deviceNum": "gw001",
    "username": "",
    "password": "",
    "keepAliveSec": 60,
    "qos": 1,
    "tls": false
  }
}

This example is only suitable for a controlled development environment. The bundled docker/mosquitto.conf sets allow_anonymous true on both the 1883 and 8883 listeners, and no TLS certificates are configured for 8883; do not expose anonymous MQTT or non-TLS ports to production or untrusted networks. A production deployment requires separately configured authentication, encryption, access control, and writable secret storage.

You can observe the property topic with the following command; replace the placeholders with your actual configuration and add parameters as required by the broker's authentication:

mosquitto_sub -h <broker-host> -t '/<productId>/<deviceNum>/property/post' -v

Until the current blockers are resolved, receiving no property messages is one of the expected risks; this observation command must not be described as a successful acceptance test.

5. Development Preview: One Modbus TCP Device and Tag

5.1 Driver Configuration

The runtime reads a top-level drivers array, not the top-level devices array shown in older documentation. The example below configures a single Modbus TCP driver; 192.0.2.10 is a documentation-reserved address and must be replaced with the address of a controlled device or simulator:

{
  "drivers": [
    {
      "protocolName": "modbus",
      "connectionType": "tcp",
      "host": "192.0.2.10",
      "port": 502,
      "timeoutMs": 3000,
      "retryCount": 3,
      "pollIntervalMs": 1000
    }
  ]
}

The Modbus driver itself contains real libmodbus read/write code, but GatewayApp::initDrivers() currently only logs the number of configurations. This is the current device-access blocker: merely writing the JSON above does not create and register a driver.

5.2 Use a Modbus Simulator Instead of a Real Device

When no PLC is available on the development machine, you can start a Modbus TCP simulator with pymodbus and point the driver configuration's host/port at it:

pip install pymodbus

# Start a Modbus TCP simulator (listening on port 5020)
python -c "
from pymodbus.server import StartTcpServer
from pymodbus.datastore import ModbusSlaveContext, ModbusServerContext
store = ModbusSlaveContext()
context = ModbusServerContext(slaves=store, single=True)
StartTcpServer(context, address=('0.0.0.0', 5020))
"

Set "host": "127.0.0.1", "port": 5020 in the driver configuration to connect to the simulator. This approach only verifies link behavior and produces no real physical quantities.

5.3 One Sub-device

The runtime device parser uses deviceId and protocolType. The following is a development example to send to POST /api/devices; it is not a promise of Web-form compatibility:

{
  "deviceId": "modbus-dev-001",
  "productId": "demo-product",
  "deviceNum": "modbus-001",
  "deviceName": "Modbus development device 001",
  "protocolType": "modbus"
}

Log in and carry a Bearer Token before calling protected routes; see API. Do not reuse the id, protocol, or slaveAddress fields from older examples to infer the current device model.

5.4 One Tag

The following is an example of a single Modbus Tag sent to POST /api/devices/modbus-dev-001/tags:

{
  "id": "holding-0",
  "name": "Holding register 0",
  "sourceType": 0,
  "slaveAddr": 1,
  "registerAddr": 0,
  "registerCount": 1,
  "scale": 1,
  "offset": 0,
  "pollIntervalMs": 1000,
  "reportOnChange": false,
  "enabled": true
}

Here sourceType: 0 means Modbus, and registerAddr is passed directly to libmodbus using zero-based addressing: use 0 for the first holding register instead of writing 40001 directly. The current parser does not read the dataType, functionCode, byte-order, or pollInterval fields from older examples; use the fields actually read by the runtime, and do not treat unparsed fields as effective configuration.

Even if the API accepts a device or Tag, the unregistered driver still prevents real reads/writes from forming a closed loop.

6. Development Preview: Property Reporting

The property topic used by the active callback is:

/{productId}/{deviceNum}/property/post

Its active JSON structure combines the product/device topic from the gateway-level configuration with an internal deviceId and a tags array:

{
  "deviceId": "modbus-dev-001",
  "timestamp": 1700000000000,
  "tags": [
    { "id": "holding-0", "value": 25.5, "quality": 0 }
  ]
}

The source also provides TagMapper::buildPropertyPost(), which can generate FastBee-style params, but the active callback does not use it; do not mix the two formats. When MQTT is disconnected, the active callback logs and skips the batch. There is currently no production-ready offline caching and replay guarantee.

7. Development Preview: Reverse Control

The MQTT client implements a /{productId}/{deviceNum}/function/# subscription primitive, but production code does not call subscribeFunction. Publishing an MQTT function message therefore cannot be presented as proof that cloud reverse control is implemented.

There is also a manual debug-write route at POST /api/debug/write:

{
  "tagId": "holding-0",
  "value": 1
}

It calls TagEngine::writeTag() and still requires a valid Tag and a registered driver. A Stub returning success: true may only be a simulated result and does not prove that a physical relay or register has changed. Debug routes should be restricted to controlled networks and trusted users; in particular, never expose /api/debug/ping to untrusted callers.

8. Current Blockers to Resolve Before Integration Testing

• Create and initialize real drivers at the application layer, register them with TagEngine, and keep Stub results explicitly identifiable.
• Align Web, API, and runtime device/Tag/MQTT fields, and provide a reliable Tag configuration entry point.
• Fix the Compose broker, configuration-write, and secret-management setup; disable anonymous access and configure real TLS.
• Define a single active reporting format, and connect production function subscription and command handling.
• Implement and verify disconnected-data handling, configuration reconnect, factory reset, and OTA separately; make no production commitments before this work is complete.

9. Next Steps

• Deploy to a Raspberry Pi or ARM industrial gateway: see Deployment.
• Full configuration fields and MQTT data formats: see Configuration.
• Alarm engine, peripheral linkage, and driver health monitoring: see Peripherals and Linkage and Operations.