Gateway Operations

Development Preview

This page is for inspecting the current process and locating problems; it provides no production availability guarantee. A successful monitoring response, a successful Stub write, or a successful upload endpoint response cannot replace acceptance with real devices and failure scenarios. The endpoint behavior described here is based on the registered routes at commit b1a16cbc.

1. Routine Checks

Docker environment:

docker compose ps
docker compose logs -f gateway
curl -fsS http://127.0.0.1:8080/api/health
curl -fsS http://127.0.0.1:8080/api/metrics

GET /api/health returns health data such as process version, uptime, MQTT connection status, and Tag count; GET /api/metrics returns Prometheus text format. These two endpoints currently require no token; restrict access through listen scope, firewall, or reverse proxy to avoid exposing system information.

If you have corrected and verified the systemd installation paths yourself, you can check:

systemctl status fastbee-gateway
journalctl -u fastbee-gateway

The paths in the shipped installation script and unit are not yet unified; do not assume the service is correctly installed.

2. Log Management

2.1 Log Locations

Log source	Path / method	Notes
systemd journal	journalctl -u fastbee-gateway	Service lifecycle logs
Application logs	spdlog output (console/file sink)	Runtime logs
In-memory log tail	GET /api/debug/logs	Roughly the last 50 entries, for remote diagnostics

2.2 Viewing and Filtering

sudo journalctl -u fastbee-gateway -f                 # follow in real time
sudo journalctl -u fastbee-gateway -n 100             # last 100 lines
sudo journalctl -u fastbee-gateway -p err             # errors only
sudo journalctl -u fastbee-gateway --since "2026-10-01" --until "2026-10-02"

2.3 Log Levels

Supported levels (from most to least verbose): trace → debug → info → warn → error → critical → off. How to change:

# Config file: gateway.json → "system": { "logLevel": "debug" }
# Or a startup argument:
fastbee-gateway --log-level debug

3. Runtime Information After Authentication

After logging in and carrying a Bearer token, you can use:

Endpoint	Operational use and limitations
GET /api/mqtt/status	View connection status, broker, publish/subscribe statistics, and error/reconnect counters; counters do not mean data was reliably delivered
GET /api/overview/status	View system resources (CPU/memory/temperature/disk) and runtime status
GET /api/overview/devices	View internal device totals and online/offline statistics; the current online model does not equal physical communication acceptance
GET /api/overview/traffic	View MQTT byte, message, publish, subscribe, and reconnect statistics
GET /api/drivers/health	View the driver health summary; it cannot be used to judge fieldbus health while drivers are not registered
GET /api/debug/tags	Actively perform one pollOnce() and return Tags and statistics
GET /api/debug/logs	Returns roughly the last 50 in-memory log entries, not a complete persistent log archive

4. Monitoring and Alerting Integration

4.1 Prometheus / Grafana

The gateway provides a Prometheus-compatible metrics endpoint (no authentication required):

curl http://<gateway-ip>:8080/api/metrics

Example Prometheus scrape configuration:

scrape_configs:
  - job_name: 'fastbee-gateway'
    scrape_interval: 15s
    static_configs:
      - targets: ['<gateway-ip>:8080']
    metrics_path: '/api/metrics'

4.2 Recommended Alert Thresholds

Metric	Warning threshold	Critical threshold	Action
CPU usage	>70%	>90%	Check whether the polling interval is too short
Memory usage	>80%	>95%	Check the SQLite cache size
Disk usage	>80%	>95%	Clean up logs and caches
CPU temperature	>70°C	>85°C	Check heat dissipation / ambient temperature
MQTT disconnection	>1min	>10min	Check the network and broker
Device offline	>5min	>30min	Check field devices / wiring

4.3 Alarm Engine Monitoring

The industrial alarm engine (AlarmEngine) supports 5 alarm types and is linked to TagEngine through TagChangeObserver:

# View active alarms / statistics / rule list
curl -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/alarms/active
curl -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/alarms/stats
curl -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/alarms/rules

# Acknowledge an alarm (operator response)
curl -X POST -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/alarms/<ruleId>/ack

Alarm types: LEVEL (threshold, supporting HH/H/L/LL four levels), DEVIATION (deviation), RATE_OF_CHANGE (rate of change), QUALITY (quality), DIGITAL (digital). The alarm state machine is NORMAL → ACTIVE → ACKED → RETURNED → NORMAL.

4.4 Driver Health Monitoring

The driver health monitor (DriverHealthMonitor) uses a 6-state connection state machine:

DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → FAILED → ISOLATED

curl -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/drivers/health
curl -H "Authorization: Bearer $TOKEN" http://<gateway-ip>:8080/api/drivers/<name>/health

Health metrics: state (connection state), consecutiveErrors (consecutive errors), avgLatencyMs (average latency), lastHeartbeat (last heartbeat), isolated (whether automatically isolated). After consecutive errors reach the threshold the driver enters FAILED; after a sustained timeout it enters ISOLATED, then automatically attempts recovery on the autoRecoverMs schedule (default 60 seconds).

5. Configuration and Data Backup

5.1 Backup Scope

• The gateway.json actually in use, user data, and any subsequently modified configuration.
• Secret material such as .secret.key; it must be isolated from public documentation, images, and logs, and stored according to the organization's secret management policy.
• Business data, logs, and certificates in Compose named volumes; first confirm the mapping between volumes and real paths.
• Custom systemd units, reverse proxy, and broker authentication/TLS configuration.

5.2 Export and Import

The configuration export/import endpoints are genuinely available in the current code (via ConfigManager):

# Export
curl -H "Authorization: Bearer <token>" \
  http://<gateway-ip>:8080/api/system/config -o gateway-backup.json

# Import
curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @gateway-backup.json \
  http://<gateway-ip>:8080/api/system/config

You can also copy the configuration file directly, or schedule backups with crontab:

#!/bin/bash
# /usr/local/bin/fastbee-backup.sh — back up the configuration every early morning
BACKUP_DIR="/backup/fastbee-gateway"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
cp /etc/fastbee-gateway/gateway.json "$BACKUP_DIR/gateway-$DATE.json"
find "$BACKUP_DIR" -name "*.json" -mtime +30 -delete

During restore, also verify configuration paths, key matching, file ownership, and write permissions. A read-only configuration mount blocks .secret.key and API configuration writes; the problem cannot be masked by repeated restarts alone.

6. Firmware Upgrade (OTA)

The designed upgrade flow is: download firmware → verify → back up the current version → install the new version → restart the service → verify startup, with rollback on failure. Currently POST /api/system/upgrade only acknowledges receipt of the file and returns uploading; verification, installation, and rollback are not implemented. Until then, upgrade manually with the deb package:

scp fastbee-gateway-1.1.0-arm64.deb root@<gateway-ip>:/tmp/
ssh root@<gateway-ip> "dpkg -i /tmp/fastbee-gateway-1.1.0-arm64.deb && systemctl restart fastbee-gateway"

Version check:

fastbee-gateway --version
curl -H "Authorization: Bearer <token>" http://<gateway-ip>:8080/api/system/info

7. Common Troubleshooting

7.1 The Web UI Does Not Open or Static Assets Are Missing

• Confirm you are accessing http://<host>:8080, not 8443, for which no HTTPS service is implemented.
• Confirm the actively read key is web.port, and check port mapping and firewall (ss -tlnp | grep 8080, ufw status).
• Source runs use the relative web-src; start from the source root to avoid working-directory errors.
• Path differences between the installation script's web/ and the real web-src/, and between systemd's /opt and CMake's /usr, must be corrected first.

7.2 MQTT Does Not Connect or Changes Do Not Take Effect After Saving

• The default configuration points to 192.168.1.100, not the Compose service name mosquitto.
• Check in order: ping <broker_ip> → nc -zv <broker_ip> 1883 → DNS/routing → broker process and logs.
• Check whether ENC(...) values have a matching key; ciphertext that fails decryption cannot be used as credentials. The FastBee AES authentication password is generated on the platform side in Device Management.
• Check that anonymous access is limited to an isolated development environment, and that production broker authentication/TLS is consistent.
• PUT /api/mqtt/config saves only a subset of fields and does not reconnect; verify the real configuration and restart in a controlled window.
• Client auto-reconnect options do not equal offline data replay; the active callback currently skips data while disconnected.

7.3 No Collected Values or Writes Fail

• Check that drivers, devices, and Tags use runtime fields rather than legacy UI/documentation fields.
• Modbus addresses use zero-based registerAddr; confirm real libmodbus results rather than Stub results.
• The current primary code blocker is that the application does not register configured drivers with TagEngine; correct configuration cannot bypass this problem.
• Use the debug APIs to locate the issue: GET /api/debug/tags actively collects once, and POST /api/debug/write performs a manual write test.
• Serial link checks: RS485 A/B wiring, termination resistors, baud rate / slave address consistency, and bus load.

7.4 Alarms Do Not Trigger or Flap Frequently

• Check whether the rule is enabled (enabled in GET /api/alarms/rules), whether the Tag has data updates, and whether the threshold is reasonable.
• If an alarm flaps near the threshold, increase deadband (for example, with a threshold of 80°C and a deadband of 5°C, the value must fall below 75°C after triggering before the alarm returns to normal).

7.5 A Driver Is Automatically Isolated

Check isolated and the consecutive error count in GET /api/drivers/health, and inspect the serial connection, device power supply, bus address, and baud rate configuration; after fixing the underlying communication problem, the driver will retry according to the automatic recovery mechanism.

8. Performance Tuning

Optimization	Configuration	Effect
Deadband filtering	Tag configuration deadband	Reduces invalid reporting
Tiered polling intervals	Critical Tags 100-500ms, regular Tags 1000-5000ms	Avoids polling low-frequency data at high frequency
Batch reads	Merge consecutive registers into one read	Reduces Modbus transactions
QoS tiers	QoS 0 for properties, QoS 1 for events	Balances reliability and performance
Heartbeat interval	Increase keepAliveSec appropriately	Reduces heartbeat overhead

On low-memory devices, shrink the log and cache footprint; for non-critical Tags, increase pollIntervalMs appropriately.

9. Debug Endpoint Security Boundaries

• POST /api/debug/read currently ignores the device/Tag IDs in the request and performs a full pollOnce(); on real devices this can trigger extra bus load.
• POST /api/debug/write is a manual debug entry point, not cloud MQTT reverse control; production code does not call subscribeFunction.
• POST /api/debug/ping concatenates host directly into a std::system() command, creating a command injection risk. Do not open it to untrusted users or networks; fix the input handling or isolate the endpoint first.
• POST /api/system/reboot actually triggers a system reboot command; strictly limit the token and network exposure surface.
• The authentication middleware mainly verifies the token; do not infer from it that admin, operator, and read-only roles are enforced on every sensitive route.

10. Features That Must Not Be Treated as Completed Operational Capabilities

• Offline replay: the active reporting path does not use SqliteCache to save and resend disconnected batches.
• Configuration reconnect: the MQTT PUT does not perform the automatic reconnect implied by the UI; client reconnect primitives do not constitute a complete operational guarantee either.
• Factory reset: the current endpoint only logs and returns resetting; no configuration cleanup is performed.
• OTA: the current upload endpoint only returns the file name, size, and uploading; firmware verification, installation, and rollback are not performed.
• Reverse control: the production function subscription and command execution chain is not connected.