Skip to content

Troubleshooting Guide

Common issues and solutions for ARVOS.

Connection Issues

Can't Connect from iPhone

Symptoms: - Connection fails immediately - "Connection Failed" error - Timeout errors

Solutions:

  1. Check Network:
  2. Ensure both devices on same Wi-Fi
  3. Try pinging: ping <iphone-ip>

  4. Verify network connectivity

  5. Check Firewall:

  6. macOS: System Settings → Firewall → Allow Python
  7. Linux: sudo ufw allow <port>

  8. Windows: Windows Defender → Allow Python

  9. Check Port: 

    # Test if port is open
nc -l 9090

  10. Verify Protocol:

  11. Ensure protocol matches server
  12. Check port number
  13. Verify server is running

QR Code Not Scanning

Solutions: - Increase terminal font size - Use manual IP entry - Check QR code contains correct IP - Ensure good lighting

Protocol-Specific Connection Issues

gRPC

  • Requires iOS 18+ - Update iOS if needed
  • Check port 50051 is open
  • Verify protobuf code generated

MQTT

  • Broker must be running: mosquitto -c mosquitto.conf
  • Check broker listening on all interfaces (not just localhost)
  • Verify broker port (default 1883)

HTTP/REST

  • Use actual LAN IP (not 0.0.0.0)
  • Check App Transport Security settings
  • Verify firewall allows port 8080

Bluetooth LE

  • Enable Bluetooth on both devices
  • Ensure app is advertising (BLE toggle on)
  • Check Python script has Bluetooth permissions
  • Verify devices are within range (~10m)

QUIC/HTTP3

  • Generate TLS certificates
  • Install aioquic: pip install aioquic
  • For local testing, install self-signed certificate on iPhone
  • Verify port 4433 is not blocked

Data Issues

No Data Received

Symptoms: - Connected but no data - Callbacks not firing - Empty statistics

Solutions:

  1. Check Streaming:
  2. Ensure "START STREAMING" tapped in app
  3. Verify streaming mode selected

  4. Check sensor rates not zero

  5. Check Callbacks:

  6. Verify callbacks registered
  7. Check callback function signatures

  8. Ensure async/sync matches

  9. Check Protocol:

  10. Verify protocol matches server
  11. Check server is receiving data
  12. Review server logs

Incomplete Data

Symptoms: - Missing sensor types - Partial messages - Corrupted data

Solutions:

  1. Check Streaming Mode:
  2. Verify mode includes desired sensors
  3. Check sensor availability on device

  4. Review mode configuration

  5. Check Network:

  6. Network instability can cause data loss
  7. Try different protocol

  8. Check signal strength

  9. Check Bandwidth:

  10. High-frequency data may overwhelm network
  11. Reduce sensor rates
  12. Use lower quality settings

Performance Issues

High Latency

Symptoms: - Delayed data arrival - Lag in visualization - Stale timestamps

Solutions:

  1. Network:
  2. Use wired connection for computer
  3. Optimize Wi-Fi settings

  4. Try QUIC/HTTP3 protocol

  5. Protocol:

  6. Use gRPC for maximum performance
  7. Avoid HTTP/REST for high-frequency data

  8. Consider QUIC/HTTP3

  9. Processing:

  10. Process data asynchronously
  11. Don't block in callbacks
  12. Use batch processing

Dropped Frames

Symptoms: - Missing camera frames - Incomplete point clouds - Gaps in data

Solutions:

  1. Reduce Rates:
  2. Lower camera frame rate
  3. Reduce sensor frequencies

  4. Disable unused sensors

  5. Network:

  6. Improve Wi-Fi signal
  7. Use wired connection

  8. Try different protocol

  9. Processing:

  10. Process frames faster
  11. Skip some frames if needed
  12. Use async processing

High CPU Usage

Solutions:

  1. Optimize Code:
  2. Use NumPy vectorized operations
  3. Process asynchronously

  4. Batch operations

  5. Reduce Processing:

  6. Skip unnecessary processing
  7. Downsample data

  8. Use lower quality

  9. Protocol:

  10. Use efficient protocols (gRPC)
  11. Avoid HTTP for high-frequency data

Protocol-Specific Issues

MQTT: Broker Issues

Problem: "Connection refused"

Solution: 

# Check broker is running
ps aux | grep mosquitto

# Check broker config
cat mosquitto.conf
# Should have: listener 1883 0.0.0.0

gRPC: Version Issues

Problem: "Method not implemented"

Solution: - Regenerate protobuf code - Check grpcio version compatibility - Verify iOS 18+ on device

QUIC/HTTP3: Certificate Issues

Problem: "Certificate verification failed"

Solution: - Generate valid certificates - Install certificate on iPhone - For local testing, trust self-signed cert

BLE: Connection Issues

Problem: "Device not found"

Solution: - Ensure app is advertising - Check Bluetooth is enabled - Verify devices are nearby - Restart Bluetooth on both devices

Getting Help

Check Documentation

Report Issues

  • GitHub Issues: arvos-sdk/issues
  • Include:
  • Protocol used
  • Error messages
  • Network setup
  • Device information

Next Steps