Home Screen (/ui/main) — Complete Guide to Cards / Actions / Refresh Intervals
This is the main page of the gateway web UI. It shows all operational states of the gateway as cards on a single screen. The cards refresh by re-fetching values from the backend (/monitor/bean) at a 1-second interval, while only the Sparkplug B card refreshes separately at a 5-second interval (/api/v1/transfer).
Access it via the PlantPulse logo at the top left, or go directly to http://<gateway>/ui/main.
- MQTT / Sparkplug B / OPC UA Server cards: directly look up the
*.enable/host/port/userkeys inapp.properties. Since install.sh generates a random password per box, the user may appear empty or differ from box to box. - Docker card: requires the
/var/run/docker.sockmount.plantpulse-edgeexcludes itself — it is not shown in the list (safely blocking start/stop/delete). - Network cards (LAN1/LAN2/WiFi/GSM/VPN/Management): mapped from
edge.net.<role>.ifacevalues. If the interface uses a systemd predictable name such asenp1s0 / enp2s0 / tailscale0(as on a dev box), set it directly inapp.properties(it can be applied automatically via theLAN1_IFACE=...env in install.sh). - One-line component health check:
curl http://localhost/api/v1/system/health(no authentication required, 8-component status map + 503 branching).
Cards at a Glance (~30 total)
A 6-column grid. There are 3 card types:
| Type | Color | Meaning |
|---|---|---|
| action_box (white background, large icon) | Gray border | Click to move to the corresponding menu |
| black_box (black background) | Gray text | Static gateway information |
| gray_box (white background, gray header) | Light gray | Real-time monitoring — values refresh every second |
1. Top Actions / Information (Row 1)
1.1 엣지 정보 (black_box)
What it shows: The unchanging identity information of this gateway. Measured once at boot time and fixed on screen.
| Field | Meaning | Source |
|---|---|---|
| HOST name | OS hostname (e.g. pe-edge-01) | EdgeContext.hostname |
| O/S | OS name + architecture (e.g. Linux (amd64)) | os.name + os.arch |
| Kernel | Kernel version (e.g. 5.14.0-...) | os.version |
| Version | Gateway SW version (e.g. V2026.05.08) | app.properties |
| Build date | Artifact build date (e.g. 2026-05-08) | BUILD_DATE |
⚠ HOST name and O/S information change only when the OS has changed after a gateway restart.
1.2 프로토콜 연결 하기 (action_box)
→ Clicking moves to /ui/connect/connect. This is the screen for adding a new PLC / OPC-UA / MQTT / simulator connection.
1.3 연결된 목록 (N) (action_box)
→ Clicking opens /ui/connect/list. The N in parentheses is the number of currently registered OPCs (connections) (monitor.opc_count).
1.4 애플리케이션 (action_box)
→ /ui/apps. Start, stop, and manage Docker-based user applications.
1.5 노-코드 플로우 (action_box)
→ /ui/flow (embedded Node-RED).
For detailed usage: Flow (Node-RED)
1.6 환경 설정 (action_box)
→ /ui/system/config. Direct editing of app.properties plus system restart / reboot / backup / temporary file cleanup, and more.
2. Gateway Identification (3 cards)
2.1 엣지 시작 시간 (gray_box)
What it shows: The exact time the gateway (Tomcat) last booted — yyyy년 MM월 dd일 [a] HH시 mm분 ss초 (KST).
If you suspect a restart occurred, use this value to confirm the "last restart".
2.2 엣지 ID (gray_box)
What it shows: The unique ID of this gateway (e.g. EDGE_00303). It is the basis for all identification including Sparkplug, REST API, and the OPC-UA node tree. Comes from edge.id in app.properties.
2.3 배포 사이트 ID (gray_box)
What it shows: Which site (plant / line) this edge is deployed at (e.g. SITE_00001). Used to determine the Group ID for external SCADA / Sparkplug. Comes from site.id in app.properties.
3. Network Status (6 cards)
Each card shows a link status icon + IP or DISCONNECTED (gray).
3.1 인터넷 (gray_box)
Whether the gateway can ping the external internet. Icon color:
- Green globe: connected normally
- Red globe: connection failed
The ping target is monitor.ping.targets in app.properties (e.g. 8.8.8.8).
3.2 이더넷 (gray_box) — split into two panes
- Left: 1 WAN (external network NIC,
net_1_ip) - Right: 2 PLC (PLC network NIC,
net_2_ip)
The color of each pane changes together according to the internet ping result (a simplified indication).
3.3 WIFI (gray_box)
wifi-1 icon + IP, or wifi-slash in gray (DISCONNECTED).
3.4 3G/4G/5G (gray_box)
The GSM modem's IP or DISCONNECTED. SIM card icon.
3.5 VPN (gray_box)
shield-check icon. Shows the IP when the VPN is connected; gray + DISCONNECTED when it is down.
3.6 관리 포트 (gray_box)
wrench icon. IP of the USB / dedicated management NIC. Typically a diagnostic channel separated from the site network.
4. System Resources (5 cards)
4.1 온도 (gray_box)
CPU temperature. At 90°C or above, red + temperature-high icon (danger); below that, green + temperature-low. In industrial environments this is the first signal of a blocked fan / high-temperature alarm.
4.2 CPU (gray_box)
Gauge (0–100%) + total core count. Uses the JustGage library. Refreshes every second.
If it consistently exceeds 90%, review the PLC polling interval / number of tags.
4.3 물리 메모리 (gray_box)
Gauge + 사용 / 전체 (automatic KB/MB/GB units). RSS usage, separate from swap.
4.4 가상 메모리 (gray_box)
Swap usage. Gauge + 사용 / 전체. Normally 0–10%; if it stays above 30%, RAM may be insufficient.
4.5 디스크 (gray_box)
Usage of /data1 (or the gateway home). Gauge + 사용 / 전체.
If it exceeds 90%, immediately run the Cleanup / Cleaning (clean.sh / node-cleanup.sh) procedure.
5. Network Traffic (1 card)
5.1 네트워크 사용량 (gray_box)
- Download (RX) — cumulative received bytes
- Upload (TX) — cumulative transmitted bytes
Automatic KB/MB/GB units. Cumulative values since boot.
6. Collection / Processing (4 cards)
6.1 연결 | 태그 건수 (gray_box)
- Large number on top: number of connections (OPCs) (
opc_count) - Large number below: number of tags (
tag_count)
The total count of OPCs/tags known to the gateway. System tags (EDGE_*) are included.
6.2 PLC 연결 및 수집 상태 (gray_box) — 2x4 matrix
| Left (connection) | Meaning |
|---|---|
| 🟢 Connected | Number of OPCs with a healthy TCP/UDP connection (plc_con_connected_count) |
| 🔴 Disconnected | Number of OPCs that failed to connect (plc_con_disconnected_count) |
| Right (collection) | Meaning |
|---|---|
| 🟢 Normal | Collection started + reads succeeding (plc_scan_start_count) |
| 🟧 Abnormal | Collection started but reads have failed for some time (plc_scan_not_collect_count) |
| ⬜ Stopped | OPCs the user has stopped (plc_scan_stop_count) |
Connection and collection are different: even if TCP is alive (connection ✅), if no reads come in for any reason, it is classified as a collection fault.
6.3 PLC 읽기/쓰기 결과 (gray_box)
Cumulative read/write counters from the collector / REST API. Displayed compactly in K/M/B units.
| Success | Failure | |
|---|---|---|
| Read (R) | plc_value_read_success_count | plc_value_read_error_count |
| Write (W) | plc_value_write_success_count | plc_value_write_error_count |
Clicking the ↻ refresh icon at the top right → calls /connect/reset-read-error → resets only the failure counters to 0. Use this when you want to start counting fresh from the next cycle after clearing alarms.
6.4 MPS (gray_box)
Messages Per Second — number of data points processed per second (monitor.mps).
Directly below is a sparkline (mini chart of the recent trend), so you can see load changes at a glance.
If a site that normally runs at 100 mps suddenly drops to 0 → PLC connection or collection fault.
7. Transmission / Storage (5 cards)
7.1 대기 큐 (gray_box)
Size of the point queue waiting to be transmitted (queue_size).
Normally 0 to a few dozen. If external transmission is blocked (Sparkplug disconnection, etc.) it grows rapidly → overflows to the disk queue (
queue_disk_size). If this card keeps increasing, external communication needs inspection.
7.2 포인트 전송 건수 (gray_box)
Cumulative number of points successfully transmitted externally since boot (sended_point_count).
7.3 포인트 전송량 (gray_box)
Cumulative transmitted bytes since boot (sended_point_bytes). Automatic units. Useful as a reference for data usage billing.
7.4 데이터 저장량 (gray_box)
Total time series size stored in the Cassandra keyspace pe (MBytes input → automatic unit conversion). Review it together with remaining disk space.
7.5 데이터 저장 기간 (gray_box)
The TTL (Time-To-Live) in days for tm_tag_point (system_db_ttl, default 30 days). Data expires automatically after this number of days. Change it in app.properties.
8. System Errors (1 card)
8.1 시스템 오류 (오늘) (gray_box)
Number of ERROR-level system log entries that occurred today (00:00–now) (system_error_count). Shown as a large red number.
Click the number → moves to /system/log/list to view the actual log content.
9. External Services / Integration (5 cards)
Each card has a status bar (green/red/gray) + a connection information table.
9.1 플랫폼 API 서버 (gray_box)
Connection status with the upstream PlantPulse Platform API. Clicking the external-link icon at the top right opens that server in a new window.
| Row | Meaning |
|---|---|
| Bar | 🟢 Connection succeeded / 🔴 Connection failed (monitor.api) |
| HOST/IP | server.host |
| PORT | server.port |
| USER | server.username |
9.2 OPC-UA 서버 (gray_box)
Information about the gateway's built-in OPC-UA server. External SCADA systems connect here to subscribe to tags.
| Row | Meaning |
|---|---|
| Bar | 🟢 Enabled (the server always runs) |
| HOST/IP | opc.ua.server.host |
| PORT | opc.ua.server.tcp.port (default 12000) |
| USER | opc.ua.server.user |
For the detailed node tree / time series charts: Using the OPC-UA Node Viewer
9.3 MQTT 서버 (gray_box)
Information about the built-in HiveMQ + the topic to which Sparkplug and other data is published.
| Row | Meaning |
|---|---|
| Bar | 🟢 Enabled / ⬜ Disabled (mqtt.enable) |
| HOST/IP | mqtt.server.host |
| PORT | mqtt.server.port (default 1883) |
| USER | mqtt.server.user |
| TOPIC | mqtt.server.topic (Sparkplug spBv1.0/... or a user topic) |
9.4 Sparkplug B (gray_box)
Real-time status of the Sparkplug publishing component (5-second refresh, the Sparkplug item of /api/v1/transfer).
| Row | Meaning |
|---|---|
| Bar | 🟢 Enabled (connected) / 🔴 Disconnected (enabled but the broker connection is down) / ⬜ Disabled (sparkplug.enable=false) |
| GROUP | Sparkplug Group ID (e.g. Plant1) |
| NODE | Edge Node ID (e.g. EDGE_00303) |
| Session # | bdSeq (device birth/death sequence — number of reconnections) |
| Message # | seq (current published message number — cycles 0–255) |
If Message # is frozen, publishing has stopped. If Session # increases frequently, the broker connection is unstable.
9.5 도커 (gray_box)
Docker daemon status + user application container statistics.
| Row | Meaning |
|---|---|
| Bar | 🟢 Running / 🔴 Stopped (monitor.docker_on) |
| Count | Number of [ 살아있는 / 전체 ] containers (docker_container_up_count / docker_container_total_count) |
See at a glance whether all applications registered in /ui/apps are alive.
10. Footer (common to all pages)
The following is displayed at the bottom of the screen.
- PlantPulse Edge text + license
- ☁ Software upgrade icon — clicking calls
upgrade.sh(after a confirmation dialog)- Badge next to the icon:
- Red "Upgrade available!" → a new version exists on the download server
- Gray "Cannot connect to download server" → external network /
product.kopens.ioaccess failed - (no badge) → the current version is the latest
- Badge next to the icon:
- External port shortcuts — open other external services (e.g. Grafana 3000) in a new window
Internally, /config/upgrade/check fetches https://product.kopens.io/.../VERSION.JSON server-to-server and compares → the badge is displayed cleanly without CORS errors.
11. Refresh Intervals / Data Sources
| Area | Refresh interval | Endpoint |
|---|---|---|
| Gauges / resources / network / counters / queue / storage / errors | 1 second | GET /monitor/bean |
| Sparkplug B card | 5 seconds | GET /api/v1/transfer |
| Upgrade badge | Once at page load | GET /config/upgrade/check |
| Black information cards (HOST name/OS/version, etc.) | Not refreshed (value at page load) | EdgeContext (determined at server boot) |
12. Common Patterns
| Screen signal | Suspicion / action |
|---|---|
| Temperature red (90°C↑) | Blocked fan / ambient temperature — inspect immediately |
| CPU sustained 90%+ | Polling interval too fast / too many tags |
| Disk 90%+ | Cleanup / Cleaning — clean.sh + node-cleanup.sh |
| PLC disconnections count suddenly rising | PLC network cable / switch / PLC power |
| Collection faults > 0 | Connection is OK but reads fail — check address format / PLC firmware |
| MPS drops to 0 | All PLCs failing reads, or the collector has stopped |
| Pending queue keeps growing | External transmission (Sparkplug / MQTT) is blocked — check cards 9.3/9.4 |
| System errors red number | Click → view the content in /system/log/list |
| Sparkplug Message # not changing | Publishing stopped — inspect sparkplug.* in app.properties |
| Docker red | Check the daemon status in systemctl status docker |
13. Learn More
- Adding a connection: Add a New PLC Connection
- Connection list / tag screen: Viewing Real-Time Values
- OPC-UA node viewer: Using the OPC-UA Node Viewer
- Flow automation: Getting Started with Flow (Node-RED)
- System configuration / operations scripts: Operations — At a Glance