Codebase Overview

This page explains how the FYP repository is organized from a source-code point of view, with emphasis on what was kept from upstream repositories and what was changed for this project.

1. Overall Structure

The repository is not a single original codebase written from scratch. It is a ROS workspace assembled from several upstream packages and then adapted for:

• Livox MID-360
• Intel RealSense D455
• FAST-LIVO2-based mapping
• HDL localization against a prepared point cloud map
• multi-floor navigation
• Unitree Go2 execution

The main packages fall into three groups:

• upstream packages with local modifications
• custom integration packages
• configuration-heavy deployment packages

2. Upstream Packages With Local Modifications

The main upstream repositories used in this project are:

• livox_ros_driver2 Upstream: https://github.com/Livox-SDK/livox_ros_driver2
• FAST-LIVO2 Upstream: https://github.com/hku-mars/FAST-LIVO2
• hdl_localization Upstream: https://github.com/koide3/hdl_localization
• hdl_global_localization Upstream: https://github.com/koide3/hdl_global_localization

In this FYP, the most meaningful source-code changes compared with the original repositories are concentrated in:

• Livox driver synchronization and MID-360 integration
• FAST-LIVO2 launch/configuration for the MID-360 + D455 setup
• HDL localization frame and map integration

3. Custom Integration Packages

Some packages in the repository are mainly custom integration work rather than direct upstream forks:

• fastlivo2_bringup
• navigation_manager
• robot_bringup
• unitree

These packages are the glue that turns independent mapping, localization, navigation, and robot-control components into one runnable system.

4. Where The Main Logic Lives

The most important FYP-specific behavior is concentrated in the following files:

• fastlivo2_bringup/launch/fastlivo2_full.launch This is the sensor and mapping bringup layer.
• hdl_localization/launch/hdl_localization.launch This connects HDL localization to the FAST-LIVO2 frame chain and prepared map.
• navigation_manager/launch/start_nav_logic.launch This starts the multi-floor navigation logic.
• navigation_manager/config/waypoints.yaml This stores floor maps, stairs, goals, and height offsets.
• navigation_manager/scripts/floor_manager.py This contains the multi-floor mission logic.
• navigation_manager/scripts/hdl_killer.py This handles localization freezing and height-offset compensation.
• unitree/scripts/go2_ros_bridge.py This bridges ROS velocity commands to the Unitree Go2 SDK.
• robot_bringup/launch/1.launch This is the final runtime entry point.

5. What Was Changed In Practice

At a high level, the source changes fall into these categories:

• changing sensor topics and frames so FAST-LIVO2, HDL localization, and navigation all agree
• introducing a Livox-camera synchronization path for MID-360 and D455
• creating a dedicated MID-360 + D455 FAST-LIVO2 mode
• replacing single-floor assumptions with multi-floor routing, map switching, and height offsets
• bridging ROS navigation output to a physical Unitree Go2 with execution safeguards

6. How To Read The Following Pages

The next pages explain the codebase in layers:

• Livox Driver Changes What changed in the Livox ROS driver, especially the synchronization path.
• FAST-LIVO2 Changes How the upstream FAST-LIVO2 package was adapted to the MID-360 + D455 setup.
• HDL Localization Changes How localization was connected to the FYP map files and frame chain.
• Navigation And Config How the navigation stack and multi-floor mission configuration were tuned for this project.
• Robot Bringup And Unitree How the final launch chain and Go2 bridge turn the navigation result into robot motion.