HoverBot - Autonomous Indoor Mapping Robot

An autonomous mobile robot built on a hoverboard platform with ROS 2, RPLidar A1 for SLAM mapping, and Nav2 for autonomous navigation.

🚀 Quick Start: Choose Your Platform

HoverBot supports multiple hardware platforms. Choose yours to get started:

Platform	Status	Best For	Quick Link
🥧 Raspberry Pi 5	✅ Documented	Best performance & latest software	Setup Guide →
🥧 Raspberry Pi 4	✅ Active/Production	Budget-friendly, proven stability	Setup Guide →
🤖 Jetson Nano	⚠️ Experimental	AI/Vision applications	Setup Guide →

Not sure which to choose? See the Platform Comparison Guide

🎯 What This Repository Contains

This repo has everything you need - complete working files for each component:

platforms/ - Platform-specific configurations (Pi4, Pi5, Jetson Nano)
ros2_ws/ - Complete ROS 2 workspace (platform-independent)
firmware/ - STM32 hoverboard controller configuration (platform-independent)
hardware/ - Wiring diagrams and hardware documentation
docs/ - Comprehensive documentation and guides

Platform-specific files are in platforms/{platform}/ - ROS 2 code is universal!

📁 Repository Structure

hoverbot/
│
├── platforms/                     # 🎯 PLATFORM-SPECIFIC FILES
│   ├── common/                    # Shared utilities for all platforms
│   │   ├── scripts/              # Generic test scripts
│   │   ├── config/               # Config templates
│   │   └── README.md
│   │
│   ├── raspberry-pi5/             # ✅ Raspberry Pi 5 (Documented)
│   │   ├── config/
│   │   │   └── hoverbot_driver.yaml  # Pi5 serial port config
│   │   ├── scripts/
│   │   │   ├── setup_uart.sh     # Pi5 UART setup
│   │   │   └── test_serial.py    # Serial tester
│   │   ├── docs/
│   │   │   └── SETUP.md          # Complete Pi5 setup guide
│   │   └── README.md             # Pi5 overview
│   │
│   ├── raspberry-pi4/             # ✅ Raspberry Pi 4 (Active/Production)
│   │   ├── config/
│   │   │   └── hoverbot_driver.yaml  # Pi4 serial port config
│   │   ├── scripts/
│   │   │   └── setup_uart.sh     # Pi4 UART setup
│   │   ├── docs/
│   │   │   └── SETUP.md          # Complete Pi4 setup guide
│   │   └── README.md             # Pi4 overview
│   │
│   └── jetson-nano/               # ⚠️ Jetson Nano (Experimental)
│       ├── config/
│       │   └── hoverbot_driver.yaml  # Jetson serial port config (/dev/ttyTHS1)
│       ├── scripts/
│       │   └── setup_uart.sh     # Jetson UART setup
│       ├── docs/
│       │   └── SETUP.md          # Jetson setup guide (TODO)
│       └── README.md             # Jetson overview
│
├── ros2_ws/                       # 🤖 ROS 2 WORKSPACE (Platform-Independent!)
│   └── src/
│       ├── hoverbot_description/ # Robot URDF model & Gazebo simulation
│       ├── hoverbot_driver/      # Serial driver node (works on all platforms)
│       └── hoverbot_bringup/     # Launch files
│
├── firmware/                      # 🔧 STM32 HOVERBOARD FIRMWARE (Platform-Independent!)
│   ├── config/
│   │   └── config.h              # Complete working config.h
│   ├── bin/
│   │   └── firmware.bin          # Pre-compiled binary (ready to flash)
│   └── README.md
│
├── hardware/                      # 📐 HARDWARE DOCUMENTATION
│   ├── wiring/                   # Connection diagrams
│   ├── schematics/               # Pinouts and schematics
│   └── README.md
│
├── docs/                          # 📚 DOCUMENTATION
│   ├── PLATFORM_SETUP_GUIDE.md   # Platform comparison & selection
│   ├── SERIAL_PORT_GUIDE.md      # Cross-platform serial config
│   ├── FIRMWARE.md               # Firmware configuration
│   └── JOURNAL.md                # Development log
│
└── README.md                      # This file

Key Insight: Only platforms/ directory changes between hardware. ROS 2 code is universal!

✅ Current Status (January 2, 2026)

Software: ✅ Complete and validated (7 sensors integrated)

Driver communicating with hoverboard (99.3% success rate)
BNO055 IMU calibrated (9.80 m/s² gravity - perfect!)
Sensor fusion (EKF) fusing odometry + IMU at 50 Hz
RPLidar A1 scanning and publishing data at 7.6 Hz (with power management)
RealSense D435 publishing depth at 42 Hz (USB 3.0 upgrade)
ELP USB camera publishing RGB at 16 Hz
SLAM Toolbox creating maps at 0.1 Hz
Nav2 configured for autonomous navigation
V3 launch system with tmux automation
Multi-platform support (Pi4 production, Pi5 documented, Jetson experimental)
RViz real-time visualization working
Persistent device names (udev rules)
Gazebo simulation complete (URDF + launch files)

Hardware: ⏳ Assembly pending

Components tested individually
Bench testing successful
Awaiting physical robot construction

Active Platform: Raspberry Pi 4 (Ubuntu 22.04 + ROS 2 Humble)

🛠️ Hardware

Component	Model	Function	Status
Computer	Raspberry Pi 4 (4GB)	Main controller	✅ Working
Motors	Hoverboard (EFeru firmware)	Differential drive	✅ Working
Lidar	RPLidar A1	2D SLAM mapping	✅ Working
IMU	Adafruit BNO055	Orientation, sensor fusion	✅ Working
Depth Camera	Intel RealSense D435	3D obstacles (42 Hz)	✅ Working
RGB Camera	ELP USB GS1200P01	Visual tasks (16 Hz)	✅ Working
Platform	Hoverboard deck	Robot chassis	⏳ Assembly needed
Battery	Hoverboard 36V	Power supply	✅ Working

Wiring

UART: Pi GPIO14/15 (TX/RX) ↔ Hoverboard USART3 (115200 baud)
Power: Hoverboard battery → Pi via buck converter
Lidar: USB connection to Pi

Additional Sensors

IMU: BNO055 via I2C (address 0x28)
Depth Camera: RealSense D435 via USB 3.0
RGB Camera: ELP GS1200P01 via USB (persistent /dev/elp_camera)

See hardware/ for detailed wiring diagrams.

💻 Software Stack

OS: Ubuntu 22.04 LTS Server (ARM64)
ROS: ROS 2 Humble Hawksbill
SLAM: SLAM Toolbox (Karto SLAM)
Navigation: Nav2 (Navigation2)
Visualization: RViz2
Automation: Tmux session management

ROS 2 Packages

hoverbot/ros2_ws/src/
├── hoverbot_driver      # Serial communication with hoverboard
├── hoverbot_bringup     # Launch files and configurations
└── hoverbot_description # Robot URDF & Gazebo simulation

🚀 Quick Start

Prerequisites

Raspberry Pi 4 running Ubuntu 22.04 + ROS 2 Humble
RPLidar A1 connected via USB
Hoverboard with EFeru firmware via UART
Dev machine with ROS 2 Humble (for visualization)

Platform-Specific Setup

See your platform's setup guide:

Pi 4: platforms/raspberry-pi4/README.md
Pi 5: platforms/raspberry-pi5/README.md
Jetson: platforms/jetson-nano/README.md

One-Command Startup

# On the robot (Pi 4)
cd ~/hoverbot/scripts
./hoverbot_startup.sh

# Reattach anytime
tmux attach -t hoverbot

# Stop everything
tmux kill-session -t hoverbot

This launches all components automatically:

Hoverboard driver (odometry + motor control)
Static transforms (base_link → laser, camera)
IMU (BNO055)
Sensor fusion (EKF)
Cameras (RealSense D435 + ELP)
RPLidar node (with power management)
SLAM Toolbox (mapping)

Visualization

# On dev machine (after robot is running)
rviz2

# Add displays: TF, LaserScan, Map, Odometry
# Watch real-time mapping!

Save a Map

# After driving around and building a map
ros2 run nav2_map_server map_saver_cli -f ~/maps/my_map

📚 Documentation

All documentation in docs/:

DEVELOPMENT_CONTEXT.md - Complete session context for AI handoff
CLAUDE_CODE_WORKFLOW.md - Development workflow guide
PROJECT_ROADMAP.md - Next steps and priorities
PLATFORM_SETUP_GUIDE.md - Platform comparison
SERIAL_PORT_GUIDE.md - Cross-platform serial configuration
FIRMWARE.md - Hoverboard firmware details

Platform-specific docs in platforms/{platform}/docs/:

Pi4 Project Status - Detailed Pi4 status
SLAM Testing Results - Test results
RViz Setup - Visualization setup
Nav2 Setup - Navigation guide

🔧 Development Setup

Clone Repository

git clone https://github.com/Dasovon/hoverbot.git
cd hoverbot

Build on Raspberry Pi

cd ~/hoverbot/ros2_ws
colcon build
source install/setup.bash

Development Machine Setup

# Install ROS 2 Humble
sudo apt install ros-humble-desktop

# Install RViz
sudo apt install ros-humble-rviz2

# Configure for robot communication
echo "export ROS_DOMAIN_ID=0" >> ~/.bashrc
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

📊 Performance Metrics

Metric	Target	Actual	Status
Serial Success Rate	>95%	99.3%	✅
Odometry Rate	50 Hz	50 Hz	✅
Lidar Scan Rate	10 Hz	7.6 Hz	✅
SLAM Map Rate	0.1 Hz	0.1 Hz	✅
Depth Camera	30 Hz	42 Hz	✅
RGB Camera	30 Hz	16 Hz	✅
EKF Fusion	50 Hz	49 Hz	✅

🎓 Learning Resources

This project covers:

ROS 2 ecosystem (nodes, topics, services, actions)
SLAM algorithms (Karto SLAM, loop closure)
Path planning (NavFn, DWB controller)
Differential drive kinematics
Sensor fusion (lidar + odometry + IMU)
Embedded systems (UART communication, firmware)
Robot visualization (RViz, TF frames)
Multi-platform robotics development

🐛 Known Issues

RPLidar Buffer Overflow - Workaround via sequential launch with delays (tmux automation)
SLAM Initial Dropping - Messages drop for ~5s during startup (self-resolves)
Map Save Timing - Must time map_saver with 10s publish cycle
RViz Yellow Overlay - Disable odometry covariance visualization (see docs/RVIZ2_TROUBLESHOOTING.md)

See full issue list in docs/pi4/PROJECT_STATUS.md

🗺️ Roadmap

Phase 1: Software (✅ Complete)

Phase 2: Simulation & Testing (⏳ In Progress)

Gazebo URDF creation
Gazebo simulation validation
Nav2 parameter tuning in simulation
Unit tests for driver components
Power distribution system design

Phase 3: Hardware Assembly (⏳ Next)

Mount all sensors on chassis
Install power distribution system
Secure wiring and components
Verify mechanical clearances
Add emergency stop button

Phase 4: Real-World Testing

Phase 5: Advanced Features

Visual odometry integration
Web interface
Mobile app control
Return-to-home capability

🤝 Contributing

See CONTRIBUTING.md for development workflow and guidelines.

This project follows trunk-based development with small, fast PRs. See docs/CLAUDE_CODE_WORKFLOW.md for details.

🔐 Security

See SECURITY.md for security policy and vulnerability reporting.

📄 License

MIT License - See LICENSE file

🙏 Acknowledgments

EFeru Hoverboard Firmware - Motor control firmware
SLAMTEC - RPLidar A1
ROS 2 - Robot Operating System
Nav2 - Navigation framework
SLAM Toolbox - SLAM implementation

📞 Contact

GitHub: @Dasovon
Repository: github.com/Dasovon/hoverbot

Built with ❤️ and lots of learning

Last updated: January 2, 2026

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
.github		.github
.scratchpad		.scratchpad
config		config
docs		docs
firmware-source		firmware-source
firmware		firmware
hardware		hardware
platforms		platforms
ros2_ws		ros2_ws
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
critical_fixes.sh		critical_fixes.sh
hoverbot_cleanup.sh		hoverbot_cleanup.sh

License

Dasovon/hoverbot-old

Folders and files

Latest commit

History

Repository files navigation