Troubleshoot Connection

Diagnose and fix connection problems between OctoMY™ nodes.

Pro Tip

Before diving into complex diagnostics, check the basics: Is the other device running? Are they on the same network? Is the firewall allowing UDP traffic? 90% of issues are one of these.

---

Quick diagnosis

---

No connection

Symptom

Nodes can't connect even after pairing.

Step 1: Verify both nodes running

# On Agent device
ps aux | grep agent

# On Remote device
ps aux | grep remote

Step 2: Check network connectivity

# Ping test
ping <other-device-ip>

# If ping fails, check:
# - Same network?
# - WiFi connected?
# - Ethernet cable?

Step 3: Check UDP ports

# On Agent device
ss -ulnp | grep 8124

# Expected: udp UNCONN 0 0 *:8124 *:* users:(("agent",...))

If nothing shows:

• Agent might not be running
• Agent might be on a different port
• Check with --port flag used at startup

Step 4: Test UDP connectivity

# On Agent device (start listener)
nc -u -l 8124

# On Remote device (send test)
echo "test" | nc -u <agent-ip> 8124

# The Agent terminal should show "test"

Step 5: Check firewall

# Linux - check rules
sudo iptables -L -n | grep 8124
sudo ufw status | grep 8124

# Windows - check rules
netsh advfirewall firewall show rule name=all | findstr 8124

Step 6: Verify both nodes see each other

In each node's UI:

1. ☰ Menu → Utilities → Debug → Discovery
2. Check if the other node appears in the list

---

Connection drops

Symptom

Connection works initially but drops after some time.

Cause 1: NAT timeout

NAT routers drop idle UDP mappings:

# Check keepalive settings
./agent --personality MyRobot --keepalive-interval 3000

Decrease interval if drops happen frequently.

Cause 2: WiFi power saving

Mobile devices may sleep the WiFi:

Android:

• Settings → WiFi → Advanced → Keep WiFi on during sleep → Always

Linux:

# Disable WiFi power management
sudo iwconfig wlan0 power off

Cause 3: Network switches

Some switches drop idle UDP flows:

# Increase traffic frequency
./agent --personality MyRobot --keepalive-interval 1000

Cause 4: ISP UDP filtering

Some ISPs filter UDP after idle periods:

• Enable TCP fallback in settings
• Use Zoo relay mode
• Try a VPN

---

High latency

Symptom

Connection works but commands are delayed.

Step 1: Measure latency

# Basic ping test
ping <other-device-ip>

# Expected: < 50ms for local network

Step 2: Check connection type

In UI: ☰ Menu → Utilities → Connection Info

Step 3: If relayed

Force direct connection attempt:

./remote --personality MyController --prefer-direct

Or try port forwarding (see NAT Traversal).

Step 4: Check route

# Trace path to device
traceroute <other-device-ip>

# Many hops = high latency

Step 5: Check for QoS issues

If network has QoS, ensure UDP 8124-8126 is prioritized:

• Access router admin
• Set high priority for these ports

---

Packet loss

Symptom

Data is incomplete, sensors missing readings, controls skip.

Step 1: Measure packet loss

# Long ping test
ping -c 100 <other-device-ip>

# Check "X% packet loss" at end
# Should be 0% on good networks

Step 2: Check WiFi signal

# Linux - check signal strength
iwconfig wlan0 | grep -i signal

# Should be > -70 dBm

Poor signal solutions:

• Move closer to router
• Use ethernet instead
• Upgrade router/antenna

Step 3: Check network congestion

# Monitor network traffic
iftop -i wlan0

# Look for high bandwidth usage

If congested:

• Reduce sensor update frequency
• Disable video streaming
• Schedule heavy traffic for off-peak

Step 4: Check for interference

WiFi interference from:

• Microwaves
• Other WiFi networks
• Bluetooth devices
• USB 3.0 hubs

Solutions:

• Change WiFi channel
• Use 5GHz instead of 2.4GHz
• Move away from interference sources

Step 5: UDP buffer issues

# Check for buffer overruns
netstat -su | grep -i error

# If errors present, increase buffers
sudo sysctl -w net.core.rmem_max=26214400

---

Connection test commands

Full diagnostic script

#!/bin/bash
TARGET=$1

echo "=== OctoMY Connection Diagnostic ==="
echo ""

echo "1. Ping test:"
ping -c 5 $TARGET
echo ""

echo "2. Traceroute:"
traceroute $TARGET
echo ""

echo "3. UDP port test:"
nc -zvu $TARGET 8124 2>&1
echo ""

echo "4. Local UDP listener:"
ss -ulnp | grep "812[3-6]"
echo ""

echo "5. Firewall rules:"
sudo iptables -L -n | grep -E "812[3-6]|ACCEPT.*udp"
echo ""

echo "6. Network interface:"
ip addr show | grep "inet "
echo ""

echo "=== End Diagnostic ==="

Save as diagnose.sh, run with:

chmod +x diagnose.sh
./diagnose.sh 192.168.1.105

Monitor connection in real-time

# Watch packets on OctoMY ports
sudo tcpdump -i any udp port 8124 or port 8125

# With packet contents
sudo tcpdump -i any -X udp port 8124

---

Common error messages

"Connection refused"

Meaning: Target port isn't listening
Check:
- Is the node running?
- Is it on the right port?
- Is it bound to the right interface?

"Network unreachable"

Meaning: No route to target
Check:
- Is target IP correct?
- Are you on the same network?
- Is your gateway configured?

"Connection timed out"

Meaning: No response received
Check:
- Is target online?
- Is firewall blocking?
- Is NAT configured correctly?

"Host unreachable"

Meaning: Router can't reach target
Check:
- Is target device online?
- Is target on same subnet?
- Check ARP table: arp -a

"Permission denied"

Meaning: Usually port < 1024 or security policy
Check:
- OctoMY uses ports 8123+ (no root needed)
- AppArmor/SELinux policies

---

Reset connection

Sometimes starting fresh helps:

On agent

# Stop Agent
pkill agent

# Clear connection state
rm -rf ~/.local/share/OctoMY™/OctoMY\ Agent/<personality>/connection_cache/

# Restart
./agent --personality MyRobot

On remote

# Stop Remote
pkill remote

# Clear connection state
rm -rf ~/.local/share/OctoMY™/OctoMY\ Remote/<personality>/connection_cache/

# Restart
./remote --personality MyController

---

Debug logging

Enable verbose logging for detailed diagnosis:

# Full debug output
./agent --personality MyRobot --debug 2>&1 | tee agent-debug.log

# Filter connection-related messages
./agent --personality MyRobot --debug 2>&1 | grep -iE "connect|socket|udp|packet"

Log locations

---

When all else fails

1. Try different network

Test on a simple network (mobile hotspot) to rule out network issues:

# Connect both devices to phone hotspot
# If it works there, original network has issues

2. Try different transport

# Force TCP mode (slower but more reliable)
./agent --personality MyRobot --transport tcp

3. Use Zoo Relay

# Force relay mode
./remote --personality MyController --force-relay

4. Report issue

If problems persist:

1. Collect debug logs from both devices
2. Run the diagnostic script
3. Note network setup (home/corporate/mobile)
4. Report at https://github.com/mrdeveloperdude/OctoMY/issues

---