Connectivity Tests

Verify communication between your hub and spoke devices

Before You Start Ensure your hub is running and at least one spoke device is registered. See Hub Installation and Spoke Setup.

Quick Health Check

Run the comprehensive health check on both hub and spoke:

On the Hub

bash

cd /opt/seaclip
pnpm cli doctor

$ pnpm cli doctor
SeaClip Health Check
====================

✓ Node.js version: 20.11.0
✓ pnpm version: 8.15.0
✓ Database: connected (PostgreSQL)
✓ Server: running on port 51842
✓ WebSocket: active (3 clients)
✓ Ollama: connected (http://localhost:11434)
✓ Devices: 2 online, 0 offline

All checks passed! SeaClip is healthy.

On the Spoke

bash

cd /opt/seaclip-spoke
pnpm spoke doctor

Test 1: Network Connectivity

Verify the spoke can reach the hub over the network:

Ping Test

bash — Run on spoke

# Replace with your hub IP
HUB_IP="192.168.1.100"

# Basic ping
ping -c 3 $HUB_IP

# Check port is open
nc -zv $HUB_IP 51842

$ ping -c 3 192.168.1.100
PING 192.168.1.100 (192.168.1.100): 56 data bytes
64 bytes from 192.168.1.100: icmp_seq=0 ttl=64 time=1.234 ms
64 bytes from 192.168.1.100: icmp_seq=1 ttl=64 time=0.987 ms
64 bytes from 192.168.1.100: icmp_seq=2 ttl=64 time=1.102 ms

--- 192.168.1.100 ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss

HTTP Health Endpoint

bash — Run on spoke

curl -s http://$HUB_IP:51842/api/health | jq

$ curl -s http://192.168.1.100:51842/api/health | jq
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "database": "connected",
  "websocket": "active"
}

Test 2: Device Registration

Verify the spoke is properly registered with the hub:

Check Registration Status

bash — Run on spoke

pnpm spoke status

$ pnpm spoke status
Spoke Status
============

Device ID: dev_abc123
Device Name: pi-kitchen
Hub URL: http://192.168.1.100:51842
Status: online
Health Score: 95
Last Heartbeat: 12 seconds ago
Uptime: 2h 34m 12s

Agents Running: 1
- agent_xyz789 (ollama) - idle

List Devices on Hub

bash — Run on hub

pnpm cli device list

Test 3: Telemetry Flow

Verify telemetry data is flowing from spoke to hub:

Send Test Telemetry

bash — Run on spoke

pnpm spoke telemetry --send-now

Check Telemetry on Hub

bash — Run on hub

# Get latest telemetry for a device
curl -s "http://localhost:51842/api/companies/default/devices/dev_abc123/telemetry?limit=1" | jq

$ curl -s "http://localhost:51842/api/companies/default/devices/dev_abc123/telemetry?limit=1" | jq
{
  "data": [{
    "timestamp": "2025-03-07T20:15:00.000Z",
    "cpuPercent": 23.5,
    "ramUsedGb": 2.1,
    "ramTotalGb": 8.0,
    "diskUsedGb": 45.2,
    "diskTotalGb": 128.0,
    "cpuTempC": 52.0,
    "uptimeSeconds": 9252
  }]
}

Test 4: WebSocket Connection

Verify real-time WebSocket communication:

Test WebSocket from Spoke

bash — Run on spoke

# Install websocat if needed
# sudo apt install websocat

# Connect to WebSocket
websocat "ws://$HUB_IP:51842/ws?companyId=default"

You should see events like device:telemetry and agent:heartbeat streaming in real-time.

Test 5: Agent Communication

Test that agents can receive and execute tasks:

Ping an Agent

bash — Run on hub

pnpm cli agent ping agent_xyz789

$ pnpm cli agent ping agent_xyz789
Pinging agent agent_xyz789...

✓ Agent responded in 45ms
Status: idle
Device: pi-kitchen (dev_abc123)
Adapter: ollama
Model: llama3:8b

Invoke a Test Task

bash — Run on hub

pnpm cli agent invoke agent_xyz789 --test

Automated Test Suite

Run the full connectivity test suite:

bash — Run on hub

pnpm cli test connectivity

$ pnpm cli test connectivity
SeaClip Connectivity Test Suite
================================

Testing device: pi-kitchen (dev_abc123)

✓ Network reachable (1.2ms)
✓ HTTP API accessible
✓ Device registered
✓ Telemetry flowing (last: 8s ago)
✓ WebSocket connected
✓ Agent ping successful (45ms)

Testing device: jetson-garage (dev_def456)

✓ Network reachable (2.1ms)
✓ HTTP API accessible
✓ Device registered
✓ Telemetry flowing (last: 3s ago)
✓ WebSocket connected
✓ Agent ping successful (38ms)

================================
All tests passed! 2/2 devices healthy.

Common Issues

Issue	Cause	Solution
Connection refused	Hub not running or firewall blocking	Check hub status, open port 51842
Device shows offline	Telemetry not sending	Check spoke service: `systemctl status seaclip-spoke`
Agent ping timeout	Agent not running on spoke	Restart spoke: `pnpm spoke restart`
WebSocket disconnects	Network instability	Check network, increase timeout

See Troubleshooting for more detailed solutions.

Next Steps

→

Telemetry Verification

Deep dive into telemetry data and metrics

→

Agent Communication

Test task assignment and execution