Troubleshooting

Common issues and solutions for the autonomous navigation system.

LiDAR Issues

No Point Cloud Data

Symptoms:

  • /ouster/points or /livox/lidar topic not publishing

  • Empty point cloud visualizations

Solutions:

  1. Check Network Connection

    ping 169.254.16.143  # Ouster default IP
ping 192.168.1.100   # Livox default IP

  2. Verify Topic Publishing

    Open raisin_cli and connect to the robot (see Using raisin_cli for details):

    # In raisin_cli
list                  # Check available servers and get server_id
con <server_id>       # Connect using server_id from list output
list                  # List all available topics
sub <topic> <time>    # e.g., sub /ouster/points 10

  3. Check IP Configuration

    • Ouster: Set sensor_hostname to correct IP

    • Livox: Verify lidar_configs.ip matches sensor

  4. Network Interface

    • Ensure computer IP is on same subnet as sensor

    • Check firewall allows UDP traffic

Point Cloud Distorted

Symptoms:

  • Twisted or warped point clouds

  • Points don’t align properly

Solutions:

  1. Check LiDAR-IMU time synchronization

  2. Verify extrinsic calibration (extrinsic_T, extrinsic_R)

  3. Reduce robot motion during calibration

  4. Check IMU data quality

FAST-LIO Issues

High Odometry Drift

Symptoms:

  • Robot position drifts over time

  • Map becomes inconsistent

Solutions:

  1. Calibrate Extrinsics

    mapping:
  extrinsic_est_en: true  # Enable online calibration

  2. Tune Noise Parameters

    mapping:
  acc_cov: 0.1  # Increase if accelerometer noisy
  gyr_cov: 0.1  # Increase if gyroscope noisy

  3. Check IMU Quality

    • Verify IMU is properly mounted

    • Check for vibrations or interference

SLAM Fails to Initialize

Symptoms:

  • No odometry output

  • /Odometry/base topic not publishing

Solutions:

  1. Verify Input Topics

    Open raisin_cli and check topic rates (see Using raisin_cli for connection details):

    # In raisin_cli
list                       # Check available servers and get server_id
con <server_id>            # Connect using server_id from list output
sub <topic> <time>         # e.g., sub /ouster/points 10

  2. Check Configuration

    • Ensure lid_topic and imu_topic match actual topics

    • Verify lidar_type matches sensor (1=Livox, 2=Velodyne, 3=Ouster)

  3. Sufficient Motion

    • FAST-LIO needs initial motion to calibrate

    • Move robot slightly to trigger initialization

Autonomy Issues

Robot Doesn’t Move to Waypoint

Symptoms:

  • Waypoints set but robot stationary

  • No path published

Solutions:

  1. Check Autonomy Mode

    autonomyMode: true

  2. Verify Odometry

    Open raisin_cli and check odometry (see Using raisin_cli for connection details):

    # In raisin_cli
list                   # Check available servers and get server_id
con <server_id>        # Connect using server_id from list output
sub <topic> <time>     # e.g., sub /Odometry/base 10

  3. Check Waypoint Service

    • Ensure waypoints were sent successfully

    • Verify waypoint coordinates are valid

Robot Avoids Valid Paths

Symptoms:

  • Robot stops unnecessarily

  • Valid terrain marked as obstacle

Solutions:

  1. Adjust Height Thresholds

    localPlanner:
  heightGapThre: 0.3       # Increase for rougher terrain
  obstacleHeightThre: 0.25

  2. Tune Terrain Analysis

    terrainAnalysis:
  minRelZ: -2.0  # Allow lower terrain
  maxRelZ: 1.0   # Allow higher terrain

Robot Moves Too Slow

Solutions:

  1. Increase Speed Limits

    maxSpeed: 4.0
autonomySpeed: 2.0

  2. Adjust Slowdown Distance

    pathFollower:
  slowDwnDisThre: 1.0  # Reduce to slow later

Map Window Issues

Map Tiles Not Loading

Symptoms:

  • Blank map background

  • Tiles fail to load

Solutions:

  1. Check internet connectivity

  2. Verify tile server URL is accessible

  3. Clear tile cache and restart

Robot Position Not Updating

Symptoms:

  • Robot icon doesn’t move on map

  • Position stuck at origin

Solutions:

  1. Verify odometry is publishing

  2. Check coordinate frame settings (local vs GPS)

  3. Ensure Map Window is subscribed to correct topics

General Tips

Using raisin_cli

raisin_cli is the command-line tool for monitoring and debugging the RAISIN system.

Connecting to Robot:

  1. Open raisin_cli in terminal

  2. Use list to see available servers and their IDs

  3. Connect using the server_id

# In raisin_cli
list                       # Shows available servers

Example output:

Server on     IP             ID                            Device Type    Port
--------------------------------------------------------------------------------
Server        192.168.10.21  railab_raibo-2781268307830    raibo2%ouster32 d455_front  40121

Connect using the server_id:

con <server_id>    # Connect using server_id from list

Note

The server_id (e.g., railab_raibo-2781268307830) is assigned dynamically and may change between sessions. Always run list first to check the current server_id before connecting.

Common Commands (after connecting):

list                       # List all available topics
sub <topic_name> time      # Subscribe to topic and show timing info
sub <topic_name>           # Subscribe to topic and show data

Checking System Health

Use raisin_cli to verify system health:

# In raisin_cli
list                       # Check available servers and get server_id
con <server_id>            # Connect using server_id from list output
list                       # List all available topics
sub <topic> <time>         # e.g., sub /Odometry/base 10

Monitor System Load:

  • Check CPU usage isn’t maxed

  • Verify sufficient memory available

Logging

Enable detailed logging for debugging:

runtime_pos_log_enable: true

Check logs for error messages and warnings.

Getting Help

If issues persist:

  1. Collect relevant log files

  2. Note exact error messages

  3. Document configuration files used

  4. Record topic publication rates