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

---

Self-healing port discovery

OctoMY™ nodes automatically work around port collisions and address-book staleness. You don't usually have to think about this, but understanding the behavior helps when diagnosing odd intermittent issues.

What it does

When two nodes of the same type start on the same machine (typical during dev/test), they compete for the same default UDP port. One wins; the other falls back to an alternate port (e.g. 8124 → 8224). The same can happen on a real device after a reboot if the OS hands a different port out.

The node that fell back:

1. Records the actual bound port locally.
2. Broadcasts it via LAN discovery so peers learn the new port.
3. Peers merge the learned address into their address book.
4. The next connection attempt tries both the old stored address and the freshly-learned one (in parallel).
5. Whichever address responds first wins; its success gets recorded and it gets preferred next time.

You'll see log lines like these if you're watching:

COMMS: pushing actual bound port 8224 into LocalAddressList (carrier fallback)
DiscoveryClient: Updated address for existing LAN peer ABCD1234
CREATE SESSION: SUCCESS for "ABCD1234" ... candidates= 2
SYN FAN-OUT: sent to 2 candidates for ABCD1234
FANOUT WINNER: session "ABCD1234" won by candidate ::ffff:10.0.0.244:8224 (numSuccessful= 1)

candidates= N shows how many distinct addresses the node will try in parallel. FANOUT WINNER ... numSuccessful increments each time that address works — the score formula uses this to prefer paths that have actually delivered.

When it can't help

The self-healing flow needs LAN (Network) discovery enabled on both nodes for peers to learn each other's actual ports. Fresh-paired or recently-nuked nodes start with all discovery channels OFF (since commit a446f33b2). Enable Network discovery in each node's connection settings (or directly from the migration screen if you're in that flow — the inline channel toggles let you flip it without leaving the screen).

If LAN discovery is on and connection still fails, see the No connection section above for the regular troubleshooting flow.

Forcing a fresh path discovery

If a peer's address-book entry has gone stale and the self-healing hasn't kicked in yet (e.g. you just changed the peer's network), you can speed things up by:

1. Turn Network discovery off then on in ☰ Menu → Connection settings. This re-broadcasts the LAN discovery beacon.
2. Or restart the peer process — LocalAddressList is rebuilt at startup with the actual bound port.

You shouldn't need to delete or re-pair anything.

---

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

---