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**

   .. code-block:: bash

       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 :ref:`using-raisin-cli` for details):

   .. code-block:: bash

       # 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**

   .. code-block:: yaml

       mapping:
         extrinsic_est_en: true  # Enable online calibration

2. **Tune Noise Parameters**

   .. code-block:: yaml

       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 :ref:`using-raisin-cli` for connection details):

   .. code-block:: bash

       # 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**

   .. code-block:: yaml

       autonomyMode: true

2. **Verify Odometry**

   Open ``raisin_cli`` and check odometry (see :ref:`using-raisin-cli` for connection details):

   .. code-block:: bash

       # 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**

   .. code-block:: yaml

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

2. **Tune Terrain Analysis**

   .. code-block:: yaml

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

Robot Moves Too Slow
^^^^^^^^^^^^^^^^^^^^

**Solutions:**

1. **Increase Speed Limits**

   .. code-block:: yaml

       maxSpeed: 4.0
       autonomySpeed: 2.0

2. **Adjust Slowdown Distance**

   .. code-block:: yaml

       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:

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``

.. code-block:: bash

    # In raisin_cli
    list                       # Shows available servers

Example output:

.. code-block:: text

    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``:

.. code-block:: bash

    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):**

.. code-block:: bash

    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:

.. code-block:: bash

    # 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:

.. code-block:: yaml

    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