Gateway Deployment

Development Preview

This page is compiled from the build and runtime source code and project deployment documentation at commit b1a16cbc; it is not a production deployment acceptance report. The Docker assets genuinely exist, but the default configuration, driver wiring, and several system routes are still blocked (see Quick Start); a running process does not mean the acquisition and control paths are usable.

1. Hardware Requirements

Specification	Minimum	Recommended
CPU	ARM Cortex-A53 (quad-core 1.0GHz)	ARM Cortex-A72 (quad-core 1.5GHz+)
Memory	512MB RAM	1GB RAM
Storage	4GB eMMC	8GB eMMC + SD card expansion
Serial Ports	1× RS485	3× RS485 + 1× RS232
Ethernet	1× 100M	2× 1000M (WAN + LAN)
WiFi	Optional	2.4GHz 802.11n
GPIO	Optional	8×DI + 8×DO + 4×AI
USB	1× USB 2.0	2× USB 2.0
Indicators	—	Power/Run/Network/Fault
Power Supply	DC 9-36V wide input	DC 12-24V

Supported hardware platforms:

• Raspberry Pi 4B / 5 (for development/testing)
• FriendlyARM NanoPi R5S / T4
• ARM industrial gateways from Advantech, EVOC, TouchThink, and similar vendors
• Any Cortex-A53/A72 device running Debian 12 ARM64

2. Software Requirements

Item	Version Requirement
Operating System	Debian 12 (Bookworm) ARM64
Kernel	Linux 5.10+
systemd	252+
OpenSSL	3.0+
libmodbus	3.1.6+
SQLite3	3.40+

System dependency packages (on the ARM target):

sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev gpiod \
  chrony curl wget jq

3. Docker Compose Deployment

Suitable for quick evaluation and development/testing environments, providing an all-in-one orchestration of the Gateway plus a Mosquitto MQTT Broker.

Run from the source root:

docker compose up -d --build
docker compose ps
docker compose logs -f gateway

Stop the services:

docker compose down

The image uses a multi-stage Alpine 3.19 build; the runtime entry point is ./bin/fastbee-gateway with working directory /opt/fastbee. The default build disables tests, GPIO, OPC UA, and BACnet, and builds the Modbus driver; this does not turn Stub protocols into real drivers.

Service composition:

Service	Image	Ports	Description
gateway	Self-built (Alpine 3.19)	8080, 8443	FastBee Gateway main service
mosquitto	eclipse-mosquitto:2	1883, 8883	MQTT Broker

Data persistence volumes:

Volume	Container Path	Description
gateway-data	/opt/fastbee/data	SQLite database, historical records
gateway-logs	/opt/fastbee/logs	Log files
gateway-certs	/opt/fastbee/certs	TLS certificates
mosquitto-data	/mosquitto/data	MQTT persistent data

Common operations:

docker compose down                  # Stop services
docker compose up -d --build         # Rebuild after code updates
docker exec -it fastbee-gateway sh   # Enter the container for debugging
docker stats fastbee-gateway fastbee-mosquitto   # Check resource usage

3.1 Configuration issues to resolve before startup

• Broker mismatch: the Compose service is named mosquitto, but the default config/gateway.json points to 192.168.1.100:1883. Adjust mqtt.broker, mqtt.port, and credentials for your actual network.
• Read-only configuration: ./config:/opt/fastbee/config:ro prevents .secret.key creation and MQTT configuration saving. In development, deliberately design writable configuration/secret directories on a controlled copy; in production, do not open the entire configuration directory for writing indiscriminately.
• Non-portable encrypted values: ENC(...) values depend on the corresponding key and cannot be treated as valid defaults when decryption fails. Replace the placeholders and back up the key separately.
• Empty acquisition configuration: the default drivers is empty with no devices or Tags; even after completing the JSON, the application has still not finished driver registration—see Current Blockers in Quick Start.

3.2 Ports and protocols

Port	Current meaning and limitation
8080	Plaintext HTTP listener for the Web UI/API, bound to 0.0.0.0; do not expose it directly to untrusted networks
8443	A port labeled and exposed by Docker/Compose, but there is currently no corresponding HTTPS server; it is not a usable HTTPS entry point
1883	MQTT port of the bundled Mosquitto; the development configuration allows anonymous access
8883	The second Mosquitto listener, with no TLS certificates/options; must not be described as working MQTT TLS
502	Common default port of a target device for the Modbus TCP driver; not necessarily a service port the gateway itself listens on
5020	Example port for the Modbus simulator, for controlled development integration only

The bundled Mosquitto sets allow_anonymous true on both listeners. In production or shared networks, authentication, TLS, and least-privilege access must be configured separately; the default admin/admin123 credentials must also be changed immediately.

4. PC Development Machine Deployment (x86_64)

Suitable for feature development, driver debugging, and integration testing—no real industrial gateway hardware required. Ubuntu 22.04 or Windows 11 WSL2 (Ubuntu 22.04) is recommended, with a 4-core CPU and 8GB+ RAM.

Install dependencies:

sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev curl wget jq

Configure and compile from the source root (launching from the source root ensures the relative path web-src is found correctly):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DFASTBEE_BUILD_TESTS=ON
cmake --build build -j"$(nproc)"
./build/bin/fastbee-gateway --config ./config/gateway.json --log-level debug

CMake automatically detects the platform as x86_64 and defines the FASTBEE_PLATFORM_X86=1 macro; a simulated backend is used when the PC has no GPIO hardware. Optionally run the unit tests:

cd build && ctest --output-on-failure

Development debugging tips:

# GDB debugging
gdb ./build/bin/fastbee-gateway
(gdb) run --config ./config/gateway.json

# Valgrind memory check
valgrind --leak-check=full ./build/bin/fastbee-gateway --config ./config/gateway.json

# AddressSanitizer build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer"

5. Raspberry Pi Deployment (ARM64)

The Raspberry Pi 4B (4GB+) / 5 is an ideal lightweight edge gateway platform, running Raspberry Pi OS (64-bit, based on Debian 12).

System preparation:

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev gpiod curl wget jq

5.1 Method 1: Native compilation

git clone https://gitee.com/beecue/fastbee-gateway.git
cd fastbee-gateway

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DFASTBEE_ENABLE_GPIO=ON \
  -DFASTBEE_BUILD_TESTS=OFF \
  -DFASTBEE_BUILD_DRIVERS=ON

# About 10-15 minutes on Pi 4B, about 3-5 minutes on Pi 5
cmake --build build -j4
sudo cmake --install build

5.2 Method 2: Cross-compilation (build on PC, deploy to Raspberry Pi)

# === Development PC (x86_64) ===
sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

cmake -S . -B build-rpi \
  -DCMAKE_TOOLCHAIN_FILE=./cmake/aarch64-toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DFASTBEE_ENABLE_GPIO=ON \
  -DFASTBEE_BUILD_TESTS=OFF
cmake --build build-rpi -j"$(nproc)"

# Transfer to the Raspberry Pi
scp build-rpi/bin/fastbee-gateway pi@<pi-ip>:/tmp/
scp build-rpi/lib/*.so pi@<pi-ip>:/tmp/
scp -r config/ pi@<pi-ip>:/tmp/fastbee-config/

# === Raspberry Pi ===
sudo mv /tmp/fastbee-gateway /usr/bin/
sudo mv /tmp/*.so /usr/lib/
sudo mkdir -p /etc/fastbee-gateway
sudo cp -r /tmp/fastbee-config/* /etc/fastbee-gateway/
sudo chmod +x /usr/bin/fastbee-gateway

5.3 GPIO verification

With real GPIO enabled, verify using the gpiod tools:

gpiodetect                  # Example output: gpiochip0 [pinctrl-bcm2712] (54 lines)
gpioinfo gpiochip0          # Inspect pins
gpioset gpiochip0 17=1      # Set GPIO17 high
gpioget gpiochip0 18        # Read GPIO18 level

Raspberry Pi GPIO uses 3.3V logic levels; use a level-shifting module when connecting peripherals such as RS485 or relays. For GPIO channel configuration, see the gpio.json section in Configuration.

5.4 Serial port configuration (USB-RS485)

ls -l /dev/ttyUSB*                    # List converter devices, usually /dev/ttyUSB0
sudo usermod -aG dialout pi           # Serial port permission
stty -F /dev/ttyUSB0 9600 cs8 -cstopb -parenb   # Verify serial parameters

The hardware serial port /dev/ttyAMA0 on the Raspberry Pi 40-pin header is occupied by Bluetooth by default; adjust it in raspi-config if you need to use it.

6. Installation Methods Summary

6.1 Build and install from source

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \
  -DFASTBEE_ENABLE_GPIO=ON -DFASTBEE_BUILD_TESTS=OFF
cmake --build build -j"$(nproc)"
sudo cmake --install build

6.2 deb package installation

The project supports generating deb packages with CPack:

cd build && cpack -G DEB
# Output: fastbee-gateway-1.0.0-arm64.deb

sudo dpkg -i fastbee-gateway-1.0.0-arm64.deb
sudo apt install -f        # Fix dependencies (if any)
fastbee-gateway --version

6.3 Cross-compilation + SCP deployment

See Section 5.2; the same process applies to any ARM industrial gateway.

7. systemd Service Management

The project provides systemd service files (scripts/systemd/). A typical configuration:

[Unit]
Description=FastBee Industrial IoT Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/fastbee-gateway --config /etc/fastbee-gateway/gateway.json
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
WatchdogSec=30
User=root
WorkingDirectory=/etc/fastbee-gateway
ProtectSystem=strict
ReadWritePaths=/etc/fastbee-gateway /var/log/fastbee-gateway /var/lib/fastbee-gateway
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

Common commands:

sudo systemctl daemon-reload
sudo systemctl enable fastbee-gateway
sudo systemctl start fastbee-gateway
sudo systemctl status fastbee-gateway
sudo journalctl -u fastbee-gateway -f

7.1 Current differences in the systemd/install scripts

Do not copy the old installation instructions verbatim:

• scripts/install.sh looks for web/, while the actual static asset directory is web-src.
• The bundled systemd unit expects /opt/fastbee-gateway/..., while the CMake install and old documentation use /usr paths.
• Web assets are resolved as web-src relative to the process working directory, so the service's working directory and launch arguments must match the final installation layout.

Until these paths are corrected and actually verified, this page does not provide an "install-and-it-works" systemd tutorial. If you have corrected the unit yourself, use journalctl -u fastbee-gateway to inspect the logs.

8. First-Time Configuration Process

8.1 AP provisioning

By design, on first deployment the gateway automatically starts a WiFi AP hotspot for configuration:

SSID:     FastBee-GW-XXXX (last four digits of the MAC address)
Password: 12345678
IP:       192.168.4.1
Admin UI: http://192.168.4.1:8080

Connect to this WiFi with a computer or phone and open the admin page in a browser; the default administrator account is admin / admin123.

8.2 Configure WiFi STA / Ethernet

In the Web admin UI → Network Management → WiFi STA: scan available WiFi networks, select one and enter the password to connect, record the assigned IP (use this IP for subsequent access); the AP hotspot then shuts down. You can also use Ethernet directly to skip WiFi configuration.

8.3 Configure the MQTT connection

In the Web admin UI → MQTT Configuration, fill in the broker address, port, authentication credentials, productId/deviceNum, etc. MQTT authentication uses the FastBee AES encryption authentication method; the key is generated in device management on the platform side.

8.4 Add sub-devices and Tags

In the Web admin UI → Device Management, add sub-devices (protocol, slave address, serial/network parameters), then add Tag points in the device details (register address, data type, scaling, acquisition period). The actual parsing behavior of the fields is governed by Configuration.

9. Network Configuration (Target Machine)

# Static IP on the WAN port
sudo nmcli con add type ethernet con-name wan ifname eth0 \
  ipv4.addresses 192.168.1.100/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "8.8.8.8,114.114.114.114" \
  ipv4.method manual

# WiFi connection
sudo nmcli device wifi connect "SSID" password "password" ifname wlan0

# Allow the Web port through the firewall
sudo ufw allow 8080/tcp

10. Pre-Production Security Checklist

• Change the default administrator password, and recognize that the current middleware cannot prove that every route enforces role authorization.
• Disable anonymous MQTT and configure real TLS; do not mistake exposing 8883 for completed encryption.
• Put port 8080 behind a controlled network boundary and a properly configured HTTPS reverse proxy, instead of using the unimplemented 8443 entry point.
• Restrict all debug routes; /api/debug/ping concatenates input into a system command, which is a command-injection risk—it must be fixed or isolated first and must not be offered to untrusted users.
• Do not treat a successful Stub write, an OTA upload receipt, or a successful factory-reset response as evidence that a physical operation completed.
• Verify backups, configuration secrets, logs, and real-device integration separately; at present, do not promise production availability for offline re-reporting, configuration auto-reconnect, factory reset, OTA, or MQTT reverse control.

11. Common Deployment Issues

11.1 Build failure: libmodbus not found

sudo apt install libmodbus-dev
# Or build in stub mode (no real Modbus hardware)
cmake -S . -B build -DLIBMODBUS_FOUND=OFF

11.2 Serial port cannot be opened

ls -l /dev/ttyS* /dev/ttyUSB*
sudo chmod 666 /dev/ttyS1      # Or add the user to the dialout group
fuser /dev/ttyS1               # Check whether another process is using it

11.3 Out of memory (OOM)

free -h
ps aux | grep fastbee-gateway
# Temporarily add swap
sudo fallocate -l 1G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile

11.4 Exits immediately after startup

journalctl -u fastbee-gateway --no-pager -n 200
sudo /usr/bin/fastbee-gateway --config /etc/fastbee-gateway/gateway.json --log-level debug
cat /etc/fastbee-gateway/gateway.json | jq .   # Validate JSON syntax

For more runtime troubleshooting scenarios, see Operations.