Skip to content

Troubleshooting Guide

Common issues and solutions for Conduit.

Which transport are you using? Check Settings → Transport in the Conduit app. Zenoh and DDS have different failure modes. Zenoh issues are under "## Connection Issues" and "## Topic Issues" below; DDS-specific issues are in "## DDS Transport Issues" at the bottom of this page.

Connection Issues

"Connection Failed: Timeout"

Problem: App cannot reach the Zenoh router.

Solutions:

  1. Verify router is running: 

    # On ROS 2 system
ps aux | grep rmw_zenohd

# If not running, start it
source /opt/ros/jazzy/setup.bash
export RMW_IMPLEMENTATION=rmw_zenoh_cpp
ros2 run rmw_zenoh_cpp rmw_zenohd

  2. Check IP address: 

    # Get your ROS 2 system's IP
ip addr show | grep "inet "  # Linux
ifconfig | grep "inet "      # macOS

  3. Update router address in app Settings

  4. Verify same network: iPhone and ROS 2 system must be on same WiFi/LAN

  5. Test connectivity: 

    # From iPhone, ping ROS 2 system
# Or from ROS 2 system, ping iPhone
ping <device-ip>

"Connection Refused"

Problem: Router is not listening on port 7447.

Solutions:

  1. Check router is running: See "Timeout" solutions above

  2. Verify port: 

    # Check if port 7447 is listening
netstat -an | grep 7447
lsof -i :7447

  3. Check firewall: 

    # Ubuntu/Linux
sudo ufw status
sudo ufw allow 7447/tcp

# macOS
# System Settings → Network → Firewall → Allow port 7447

  4. Try different port: If 7447 is blocked, configure router with different port

"Network Unreachable"

Problem: No network connectivity.

Solutions:

  1. Enable WiFi on iPhone: Settings → WiFi

  2. Connect to same network as ROS 2 system

  3. Check router running: iPhone → Settings → WiFi → (i) → Router address

  4. Restart network:

  5. Toggle WiFi off/on
  6. Restart iPhone
  7. Restart router

Topic Issues

Topic doesn't appear in ros2 topic list

Problem: Conduit is publishing but topic is invisible.

Solutions:

  1. Verify domain IDs match (most common issue): 
    # Check ROS 2 system domain ID
echo $ROS_DOMAIN_ID

# Check Docker container domain ID
docker exec ros_jazzy_zenoh bash -c "echo \$ROS_DOMAIN_ID"
  2. Domain ID in app Settings must match ROS_DOMAIN_ID on host
  3. Valid range: 0-232 (RTPS specification limit)

  4. Default is 0 if not set

  5. Verify RMW_IMPLEMENTATION: 

    echo $RMW_IMPLEMENTATION
# Must be: rmw_zenoh_cpp

  6. Check wire mode:

  7. App Settings → Wire Mode should match your ROS 2 version

  8. Try "Auto-detect" first

  9. Restart Zenoh router: 

    # Kill existing router
pkill rmw_zenohd

# Restart with correct domain ID
export ROS_DOMAIN_ID=0  # Match app's domain ID
ros2 run rmw_zenoh_cpp rmw_zenohd

  10. Check app connection state: Should show "Publishing"

Topic appears but ros2 topic echo shows no data

Problem: Topic exists but no messages received.

Solutions:

  1. Verify sensor is publishing:
  2. Check message count in app (should be increasing)

  3. Rate should be > 0 Hz

  4. Check QoS compatibility:

  5. App uses: Reliability=BestEffort, History=KeepLast(10) by default

  6. Try adjusting in sensor settings

  7. Restart app: Stop and restart publishing

  8. Check wire format:

  9. Ensure wire mode matches your ROS 2 version
  10. Try switching between Humble/Jazzy modes

Sensor Issues

"Camera Permission Denied"

Solutions:

  1. Grant permission:
  2. iOS Settings → Privacy & Security → Camera

  3. Find "Conduit" and enable

  4. Restart app after granting permission

"LiDAR Not Available"

Reasons:

  1. Device doesn't have LiDAR:
  2. Required: iPhone 12 Pro, iPhone 13 Pro, iPhone 14 Pro, iPhone 15 Pro
  3. iPad Pro 2020 or newer

  4. Apple Vision Pro

  5. Camera permission required: LiDAR uses ARKit which requires camera access

  6. Premium unlock required: LiDAR is a premium feature

"Microphone Permission Denied"

Solutions:

  1. Grant permission:
  2. iOS Settings → Privacy & Security → Microphone

  3. Find "Conduit" and enable

  4. Restart app after granting permission

"GPS Location Services Disabled"

Solutions:

  1. Enable location services:

  2. iOS Settings → Privacy & Security → Location Services → ON

  3. Grant app permission:

  4. iOS Settings → Privacy & Security → Location Services → Conduit

  5. Select "While Using the App"

  6. Restart app

Sensor shows 0 Hz rate

Problem: Sensor enabled but not publishing data.

Solutions:

  1. Check connection state: Must show "Publishing"

  2. Verify sensor permission: Check iOS Settings → Privacy

  3. Try different sensor: Test if other sensors work

  4. Restart publishing: Stop and start again

  5. Check logs: Look for error messages in app

Platform-Specific Issues

visionOS: No GPS Sensor

Expected behavior: Vision Pro doesn't have GPS hardware (indoor device).

Workaround: Use WiFi positioning if available, or use iPhone/iPad for GPS data.

tvOS: Most Sensors Unavailable

Expected behavior: Apple TV only has Game Controller support.

Reason: Apple TV is a stationary device without motion/location sensors.

macOS: IMU Not Available

Expected behavior: Macs don't have accelerometer/gyroscope.

Workaround: Use iPhone/iPad for IMU data.

Simulator: Mock Data Only

Expected behavior: Simulator generates synthetic sensor data.

Note: Useful for development/testing, but not real sensor readings.

ros2 topic echo /conduit/audio fails with "unknown type"

Problem: audio_common_msgs package is not installed on the ROS 2 system.

Solutions:

  1. Use the pre-built Docker image (includes audio_common_msgs): 

    docker run -d -p 7447:7447 --name ros_jazzy_zenoh ghcr.io/youtalk/conduit-support:jazzy
docker exec ros_jazzy_zenoh bash -c \
  "source /opt/ros/jazzy/setup.bash && \
   source /ros2_ws/install/setup.bash && \
   export RMW_IMPLEMENTATION=rmw_zenoh_cpp && \
   ros2 topic echo /conduit/audio audio_common_msgs/msg/AudioData"

  2. Install on native ROS 2: 

    sudo apt install ros-jazzy-audio-common   # Jazzy
sudo apt install ros-humble-audio-common  # Humble

  3. Build from source if apt package is unavailable: 

    cd ~/ros2_ws/src
git clone --branch ros2 --depth 1 https://github.com/ros-drivers/audio_common.git
cd ~/ros2_ws && colcon build --packages-select audio_common_msgs
source install/setup.bash

Performance Issues

High battery drain

Causes:

  1. Too many sensors enabled: Disable unused sensors

  2. High publishing rates: Reduce rate for non-critical sensors

  3. Camera/LiDAR active: These consume significant power

Solutions:

  • Enable only sensors you need
  • Reduce rates (e.g., GPS 1Hz instead of 10Hz)
  • Disable camera when not needed

App becomes unresponsive

Solutions:

  1. Memory warning: iOS killed background sensors
  2. Check Console logs

  3. Reduce number of active sensors

  4. Network issues: Connection lost

  5. Verify router still running

  6. Check WiFi signal strength

  7. Restart app: Force quit and relaunch

Data Issues

Data rate lower than configured

Possible reasons:

  1. Hardware limitation: Some sensors have max rates
  2. IMU: 100 Hz max
  3. Camera: 30 Hz max

  4. GPS: 1-10 Hz typical

  5. Network congestion: Local network can't handle bandwidth

  6. CPU load: iOS throttling due to thermal/battery

Solutions:

  • Reduce rates for non-critical sensors
  • Reduce number of active sensors
  • Check network bandwidth

Timestamps seem incorrect

Check:

  1. System time: Ensure iOS device clock is accurate

  2. Timezone: ROS 2 uses UTC, iOS uses local time

  3. Timestamp source: Verify using correct time source (system vs sensor)

DDS Transport Issues

No topics appear when using DDS

Problem: App shows "Publishing" but ros2 topic list on the ROS 2 host returns nothing.

Solutions:

  1. Restart the cached ros2 daemon first — if you changed RMW_IMPLEMENTATION, ROS_DOMAIN_ID, or CYCLONEDDS_URI in this shell, the daemon is still running with the old context and will lie to you. Run ros2 daemon stop before any of the checks below. See ros2 CLI shows stale topics after changing RMW_IMPLEMENTATION or CYCLONEDDS_URI for the full failure mode.

  2. Verify RMW implementation: 

    echo $RMW_IMPLEMENTATION
# Must be: rmw_cyclonedds_cpp

  3. Check domain IDs match (0-232 valid range for DDS/RTPS): 

    echo $ROS_DOMAIN_ID
    Must match the Domain ID field in Conduit Settings.

  4. Verify network interface binding on iOS:

  5. Conduit Settings → Transport → DDS → Network Interface must be en0 (WiFi).

  6. Leaving this as "auto" frequently fails because iOS may select a cellular or VPN interface.

  7. Multicast blocked by WiFi AP:

  8. Many consumer access points enable "AP isolation" or drop multicast.

  9. Workaround: switch Discovery Mode to Unicast and add the ROS 2 host IP to the Unicast Peers list in Settings.

  10. Firewall on ROS 2 host:

  11. DDS uses UDP ports starting at 7400 + 250 * domain_id (for domain 0: 7400, 7401, 7410, 7411).
  12. Allow UDP on those ports, or disable the firewall for the test LAN.

ros2 CLI shows stale topics after changing RMW_IMPLEMENTATION or CYCLONEDDS_URI

Problem: You switched transports (e.g. Zenoh → DDS) or updated CYCLONEDDS_URI (peers, interface, tracing), but ros2 topic list keeps returning the previous transport's results or an empty list.

Cause: The ros2 CLI talks to a long-lived background daemon (_ros2_daemon). The daemon is started with whatever RMW_IMPLEMENTATION / DDS config was in effect at first launch and caches its RMW context — later env-var changes in your shell are ignored until the daemon is restarted.

Fix: Stop the daemon, then let the next CLI invocation start a fresh one in the new environment:

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_DOMAIN_ID=123
export CYCLONEDDS_URI='<CycloneDDS>…</CycloneDDS>'

ros2 daemon stop
ros2 daemon start          # optional — `ros2 topic list` will also autostart it
ros2 topic list

Any time you change RMW_IMPLEMENTATION, ROS_DOMAIN_ID, CYCLONEDDS_URI, or the Peer list, re-run ros2 daemon stop before the next command. This also applies when switching back to rmw_zenoh_cpp.

Topics appear but ros2 topic echo shows no data (DDS)

Problem: Discovery works but data does not flow.

Solutions:

  1. QoS mismatch: Conduit uses BestEffort reliability for high-rate sensors (IMU, camera). If your subscriber requests Reliable, it will not match. Use --qos-profile sensor_data or --qos-reliability best_effort on the subscriber: 

    ros2 topic echo /conduit/imu --qos-reliability best_effort

  2. CameraInfo reliability: CameraInfo uses BestEffort with TransientLocal (latchedBestEffort). Standard image_transport subscribers expect Reliable — override the subscriber QoS.

  3. Large messages (Camera, LiDAR): Use Unicast discovery. Multicast reassembly of fragmented RTPS data over consumer WiFi is unreliable — see known-issues.md.

Disconnect takes several seconds (DDS)

Problem: Pressing Stop in the app causes a 2-5 second delay before "Publishing" clears.

Expected behavior: DDS disconnect is serialized to avoid an iOS-specific participant-delete deadlock. See known-issues.md.

iOS cannot reach the ROS 2 host (DDS over LAN)

Problem: ping from iOS to host works, but DDS discovery fails.

Solutions: - Confirm both devices are on the same subnet; DDS default transport is UDP, which does not cross routers without configuration. - Corporate networks often block multicast and inter-client UDP. Use a dedicated test LAN or phone hotspot. - On macOS Docker Desktop, the Docker container cannot receive DDS from iOS because Docker Desktop does not provide true host networking. Run the subscriber on Linux, a Parallels VM, or natively on macOS instead.

Getting More Help

If your issue isn't listed here:

  1. Check Known Issues
  2. Search existing issues
  3. Ask in Discussions
  4. Create new issue with details