Gateway Connection Issues

The SAMMI Web Gateway bridges the SAMMI RTE to web clients via WebSocket. When the Gateway connection fails, DDOs show default values and no live data flows.

Symptoms

Connection indicator shows red (disconnected) in RuntimeWeb
DDOs display 0 or default values
Browser console shows WebSocket connection errors
Gateway process shows errors in its terminal

Quick Checklist

✅ Is the Gateway process running?
✅ Is it listening on the correct port (default: 3100)?
✅ Is the SAMMI RTE running?
✅ Is the firewall allowing WebSocket connections?
✅ Is the browser connecting to the correct Gateway URL?

Starting the Gateway

cd apps/gateway
npm exec tsx watch src/index.ts

The Gateway should output:

Gateway listening on ws://0.0.0.0:3100

Diagnosis Steps

Step 1: Verify Gateway is Running

ps aux | grep gateway
# or check the terminal where you started it

If not running, start it as shown above.

Step 2: Check the Port

# Verify port 3100 is in use
ss -tlnp | grep 3100

If nothing is listening on 3100, the Gateway failed to start or is using a different port.

Step 3: Test WebSocket Connection

Open browser DevTools (F12 → Console) and run:

const ws = new WebSocket('ws://localhost:3100');
ws.onopen = () => console.log('Connected!');
ws.onerror = (e) => console.log('Error:', e);

Step 4: Check SAMMI RTE

The Gateway connects to the SAMMI RTE. If the RTE isn’t running, the Gateway can start but won’t receive data:

# Check if SAMMI processes are running
ps aux | grep s2_event
ps aux | grep s2_stream

If not running:

s2_sysinit  # Start the SAMMI RTE

Step 5: Check Firewall

If accessing from another machine, ensure the Gateway port is open:

# Check if port 3100 is accessible
firewall-cmd --list-ports
# or
iptables -L -n | grep 3100

Step 6: Check Browser URL

RuntimeWeb must connect to the correct Gateway URL. Check:

Local development: ws://localhost:3100
LAN access: ws://<server-ip>:3100
Behind nginx: Check the proxy configuration in deploy/nginx/sammi.conf

Common Causes

Cause	Solution
Gateway not started	Start with `npm exec tsx watch src/index.ts`
Port already in use	Kill the existing process or use a different port
SAMMI RTE not running	Start with `s2_sysinit`
Firewall blocking port	Open port 3100 in firewall
Wrong WebSocket URL	Verify the URL in RuntimeWeb config
Gateway crashed	Check terminal for error messages, restart
`libsammi_web_adapter.so` not found	Copy to `$SAMMI/lib/` and add to `LD_LIBRARY_PATH`

Gateway Logs

The Gateway logs to its terminal. Look for:

Log Message	Meaning
`Gateway listening on ws://...`	Started successfully
`Client connected`	Browser connected
`Client disconnected`	Browser disconnected
`SAMMI connection established`	Connected to SAMMI RTE
`SAMMI connection lost`	Lost connection to SAMMI RTE

Known Issues

s2_event CPU spin: If s2_event spins at ~100% CPU, it may be stuck in an RPC retry loop for a missing peer. Kill and restart SAMMI.
Stale connections: After a Gateway restart, hard-refresh the browser (Ctrl+Shift+R) to establish a fresh WebSocket connection.