Project files

Hexapod-ROS

Introduction

Project Overview

Hexapod-ROS is an open-source hexapod robot platform (currently under development in spare time). The robot uses a dual-processor architecture—LubanCat Zero (RK3566) running ROS2 Humble, responsible for high-level perception, path planning, and motion control; STM32F405RGT6 running FreeRTOS with MicroROS, responsible for real-time IMU data publishing, charging control, temperature monitoring, and publishing battery and other hardware information. The 18 servos directly controlled by LubanCat use disassembled servos from UBTECH, and details about the servos can be found in "Cheap Servo from Taobao (opens in a new tab)".

Main features include:

• 18 degrees-of-freedom motion control, supporting inverse kinematics calculations and multiple gait patterns
• SLAM mapping and autonomous navigation (Navigation2) based on a 360° 2D LiDAR
• Real-time IMU attitude estimation and battery management

System Architecture

The system is divided into three layers: software layer, hardware layer, and power layer. The following architecture diagram provides a complete system overview.

Hardware Architecture

The source file for the architecture diagram is located at docs/diagrams/hardware_architecture.drawio.

Software Architecture

TODO: Awaiting full development completion

Power Architecture

The source file for the architecture diagram is located at docs/diagrams/power_architecture.drawio.

Quick Start

Environment Dependencies

Compiling the Project

1. Clone the Repository

git https://github.com/greenhand520/hexapod_ros.git
cd hexapod_ros
git submodule init
git submodule update --remote --checkout

2. Install Required Packages

# YDLIDAR SDK
git clone https://github.com/YDLIDAR/YDLidar-SDK.git
cd YDLidar-SDK
mkdir build
cd build
cmake ..
make
sudo make install

# microros agent
cd software/hexapod_ros_ws/
chmod +x ./install_microros_agent.sh
./install_microros_agent.sh

3. Compile the ROS2 Workspace

cd software/hexapod_ros_ws/
rosdep install --from-paths src --ignore-src -r -y
chmod +x ./colcon_build.sh
./colcon_build.sh
source install/setup.bash
# Start
ros2 launch hexapod_bringup start.launch.py
# Add auto-start service
TODO

4. Compile and Flash the STM32 Firmware

cd software/hexapod_ros_ws/
chmod +x lib_microros_generation.sh
# Compile the microros static library and copy related files to hexapod_stm32f405
./lib_microros_generation.sh -r

Open software/hexapod_stm32f405/ in CLion, compile the project, and flash it via ST-Link.

Hardware

Control Board

Peripherals and Sensors

Power System

PCB Design

All PCBs (main control board, expansion board, power board, and battery protection board) are designed using JLCEDA Pro (opens in a new tab). The corresponding project files are located in the hardware directory.

The latest PCB project files that can be viewed directly online are available at the oshwhub release page (opens in a new tab) (pending completion of all PCB tests).

3D Printing and Mechanical Structure

The body design is based on the classic hexapod project (opens in a new tab) structure. After referencing the STL files, it was completely rebuilt to accommodate UBTECH servos and 4S 21700 batteries. The parts are 3D printed, with modeling parameters optimized for PETG material and the Bambu Lab A1 printer. Other materials and printers have not been tested, so structural strength and dimensions cannot be guaranteed. The print files and bill of materials (BOM) are located in the mechanism directory:

mechanism/
├── stl/                    # Latest printable STL files
├── step/                   # STEP files for generating URDF
├── BOM.md                  # Bill of Materials (fasteners, bearings, etc.) (TODO)
└── assembly_guide.md       # Assembly guide (TODO)

Access the latest print files on the Makeword release page (opens in a new tab) (coming soon).

Software

The software is divided into two main parts: the STM32 firmware handles real-time hardware driving, while the ROS2 workspace runs on LubanCat for perception, planning, and control.

STM32 Firmware (software/hexapod_stm32f405/)

The STM32 firmware runs on FreeRTOS and the STM32 HAL library, communicating with Lubancat via MicroROS over UART.

Main responsibilities:

• Publish IMU data from the MPU6500 (/imu/data topic)
• Publish battery status from the BQ40Z50 (/battery/status topic)
• Collect and publish onboard temperature, voltage data, and charging status from the BQ24725 via ADC (/sensor/board_state topic)

ROS2 Workspace (software/hexapod_ros_ws/)

The ROS2 workspace contains all high-level packages running on LubanCat Zero (RK3566). The system is based on Ubuntu 22.04 + ROS2 Humble.

software/hexapod_ros_ws/
├── src
│   ├── hexapod_bringup
│   ├── hexapod_description
│   ├── hexapod_interface
│   ├── hexapod_sensor_interface
│   ├── hexapod_test_ubtech_servo
│   ├── hexapod_test_ubtech_servo_interface
│   ├── hexapod_ubtech_ros2_control
│   └── ydlidar_ros2_driver
├── CMakeLists.txt
├── colcon_build.sh
├── env.sh
└── generate_and_deploy_microros.sh

Package Descriptions

Development Progress and Roadmap

• Hardware design (PCB, schematic)
• 3D-printed body design (PETG, Bambu Lab A1)
• Basic ROS2 bringup and ros2_control
• STM32 firmware and MicroROS integration
• Inverse kinematics and triangular gait
• YDLIDAR X2 driver and SLAM integration
• Navigation2 path planning
• RL training environment (Gazebo + PyBullet)
• RL motion strategy training (PPO / SAC)
• Simulation-to-real policy deployment
• Multi-gait RL switching (triangular gait, ripple gait, wave gait)
• RL + Nav2 joint autonomous exploration
• Documentation and assembly video tutorials

Contributing

Contributions are welcome! Please read the following guidelines:

TODO

Open Source License

This project is open-sourced under the GNU General Public License v3.0—see the LICENSE file for details.

The hardware design (PCB schematics, 3D models) is open-sourced under the CERN Open Hardware Licence v2 (CERN-OHL-P-2.0).

Acknowledgments

No particular order

• ROS2 (opens in a new tab) — Robot Operating System 2
• Xiaomi MiMo Token Plan (opens in a new tab) — Xiaomi MiMo Large Model Token Subscription Plan
• CLion (opens in a new tab) — Cross-platform C/C++ integrated development environment designed for smooth workflows and efficient development
• MicroROS (opens in a new tab) — ROS2 for microcontrollers
• Navigation2 (opens in a new tab) — ROS2 navigation framework
• YDLIDAR (opens in a new tab) — LiDAR SDK
• LubanCat (opens in a new tab) — LubanCat Zero single-board computer
• JLCEDA (opens in a new tab) — PCB design tool (LCEDA)
• Bambu Lab (opens in a new tab) — 3D printing platform