TinyNav : A lightweight, hackable system to guide your robots anywhere. Maintained by Uniflex AI.

[Homepage](https://github.com/UniflexAI/tinynav) | [Documentation](./docs) | [Discord](https://discord.gg/gnZKFJ8W9Q)

Unitree GO2	LeKiwi

Navigation with 3D Gaussian Splatting

Vision Only Mapping

Bounties

We’ve launched our bounty program! Check the list to see how you can contribute and the reward values for each task.

Stereo Cameras

we’re excited to add Looper as a first-class supported camera, alongside RealSense.

Looper is special because it provides built-in depth and visual–inertial odometry (VIO), enabling many new possibilities for perception and navigation.

 <img alt="looper" src="https://github.com/UniflexAI/tinynav/raw/main/docs/looper.jpg" width="50%" height="50%">

[v0.3] What's Changed

🚀 Features

• IMU–Visual Fusion in Perception Node

  Integrates IMU–visual fusion to significantly improve pitch-angle accuracy.

  This enhancement boosts overall robustness and enables reliable navigation across more robot platforms, especially those sensitive to pitch drift.

• Resilient Mapping Pipeline

  Upgraded map-building logic to gracefully handle message loss, improving stability in real-world communication conditions.

  Paired with a redesigned visualization module, developers can now observe the map-building process incrementally, making debugging and tuning far more intuitive.

• Unified Model Training for Perception + Planning

  We have begun training a single neural model that jointly supports both perception and planning tasks, paving the way for tighter integration and future performance gains. (TinyBEV)

🔧 Improvements

• Enhanced C++ CI & Code Quality

  The CI pipeline now includes: * clang-tidy static analysis * ASAN (Address Sanitizer) detection

  These additions ensure higher reliability, cleaner code, and safer memory usage across the C++ stack.

🐞 Bug Fixes

Dozens of internal fixes and refinements were merged this cycle, improving system stability, consistency, and developer experience.

[v0.2] What's Changed

🚀 Features

• 3D Gaussian Splatting (3DGS) Map Representation
  Provides high-quality visualization and an intuitive map editor, making it easy to inspect map details and place target POIs with precision.

• ESDF-based Obstacle Avoidance
  Enables more human-like navigation. Robots not only avoid obstacles but also keep a safe distance, improving path quality.

• Localization Benchmark
  Adds a benchmark for map-based localization, allowing clear and quantitative evaluation of improvements across versions.

• CUDA Graph Optimization
  Reduces inference overhead and achieves >20Hz on Jetson Nano, lowering latency for real-time closed-loop navigation.

🔧 Improvements

• Simplified First-Time Setup
  The postStartCommand command in the dev container now auto-generates platform-specific models, reducing errors and making setup more user-friendly.

• Expanded CI Testing
  Broader continuous integration coverage ensures higher build stability and code quality.

• Map Storage with KV Database
  Maps are now stored using shelve, resulting in shorter code and better performance.

🐞 Bug Fixes

• Over 50 pull requests merged since the last release, delivering numerous fixes and stability improvements.

[v0.1] What's Changed

🚀 Features

• Implemented map-based navigation with relocalization and global planning.
• Added support for Unitree robots.
• Added support for the Lewiki platform.
• Upgraded stereo depth model for a better speed–accuracy balance.
• Tuned Intel® RealSense™ exposure strategy, optimized for robotics tasks.
• Added Gazebo simulation environment
• CI: Docker image build & push pipeline.

🔧 Improvements

• Used Numba JIT to speed up key operations while keeping the code simple and maintainable.
• Adopted asyncio for concurrent model inference.
• Added gravity correction when velocity is zero.
• Mount /etc/localtime by default so ROS bag files use local time in their names.
• Optimized trajectory generation.

🐞 BugFix

• Various bug fixes and stability improvements.

Highlight (Our Design Goals)

We aim to make the system:

Tiny

• Compact (~2000 LOC) for clarity and ease of use.
• Supports fast prototyping and creative applications.
• Encourages community participation and maintenance.

Robust

• Designed to be reliable across diverse scenes and datasets.
• Ongoing testing for consistent performance in real-world conditions.

Multiple Robots Platform

• Targeting out-of-the-box support for various robot types.
• Initial focus: Lekiwi wheeled robot, Unitree GO2.
• Flexible architecture for future robot integration.

Multiple Chips Platform

• Compute support starts with Jetson Orin and Desktop.
• Planning support for cost-effective platforms like RK3588.
• Aims for broader accessibility and deployment options.

Project Structure

The repository is organized as follows:

• tinynav/core/
  Core Python modules for perception, mapping, planning, and control:
• perception_node.py – Processes sensor data for localization and perception.
• map_node.py – Builds and maintains the environment map.
• planning_node.py – Computes paths and trajectories using map and perception data.
• control_node.py – Sends control commands to actuate the robot.

• Supporting modules:

  • driver_node.py, math_utils.py, models_trt.py, stereo_engine.py.

• tinynav/cpp/
  C++ backend components and bindings for performance-critical operations.

• tinynav/models/
  Pretrained models and conversion scripts for perception and feature extraction.

• scripts/
  Shell scripts for launching demos, managing Docker containers, and recording datasets.

---

Getting Started

Prerequisites

Before you begin, make sure you have the following installed:

• git and git-lfs (for cloning and handling large files)
• Docker

Platform-specific requirements: - For x86_64 (PC): NVIDIA Container Toolkit (for GPU support) - For Jetson Orin: JetPack SDK version 6.2 or higher

🚀 Quick Start

1. Check the environment bash git clone https://github.com/UniflexAI/tinynav.git cd tinynav bash scripts/check_env.sh Follow the instructions to fix any environment issues until you see: bash ✅ Docker is installed. ✅ Docker daemon is running and accessible. ✅ NVIDIA runtime is available in Docker. ✅ Git LFS is installed. ✅ devcontainer.json patched for your x86 platform.

2. Open the project in VS Code

3. Launch VS Code and open the tinynav folder.
4. Install the Dev Containers extension if prompted.

5. Reopen the folder inside the container.

6. Run the example
   Once inside the container, start the demo: bash bash /tinynav/scripts/run_rosbag_examples.sh You should see an RViz window displaying the live planning process:

   

---

📜 What run_rosbag_examples.sh Does

The script automates the entire demo workflow:

1. Plays dataset
   Streams a recorded dataset from this ROS bag.

2. Runs TinyNav pipeline

3. perception_node.py → Performs localization and builds the local map.
4. planning_node.py → Computes the robot’s optimal path.
5. RViz → Visualizes the robot’s state and planned trajectory in real time.

---

✨ With these steps, you’ll have the full TinyNav system up and running in minutes.

Developer Guide

Using Dev Containers

TinyNav supports Dev Containers for a consistent and reproducible development experience.

Using VS Code

1. Open the tinynav folder in Visual Studio Code.
2. Ensure the Dev Containers extension is installed.
3. VS Code will automatically start the container and open a terminal inside it.

Using the Dev Container CLI

If you prefer the command line:

Recommended: install a newer Node.js/npm with nvm first

Some systems ship with an older npm. We recommend installing a newer Node.js/npm via nvm before installing the Dev Containers CLI:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts

Then install and use the Dev Containers CLI:

# Install the Dev Containers CLI
npm install -g @devcontainers/cli

# Start the Dev Container
devcontainer up --workspace-folder .

# Open a shell inside the container
devcontainer exec --workspace-folder . bash

---

First-Time Setup (Inside the Dev Container)

After entering the development container, set up the Python environment:

uv venv --system-site-packages
uv sync

This will create a virtual environment and install all required dependencies.

Optional Dependencies

Depending on your robot platform or map representation, install the corresponding extras:

# Unitree GO2 robot support
uv sync --extra unitree

# LeKiwi robot support
uv sync --extra lekiwi

# 3D Gaussian Splatting (3DGS) map support
uv sync --extra 3dgs

You can combine multiple extras in one command:

uv sync --extra unitree --extra 3dgs

Next Steps

• [ ] High Optimization NN models: Support real-time perception processing at >= 30fps.
• [ ] Map module enhancement: Improve consistency and accuracy for mapping and localization.
• [ ] End-To-End trajectories planning: Deliver robust and safe trajectories with integrated semantic information.

📊 Line of Code

------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          11            328            154           1959
C++                              3             49             32            292
Markdown                         2             76              6            167
Bourne Shell                     8              9              8            109
Dockerfile                       1             12             10             46
TOML                             1              6              0             33
JSON                             1              4              0             25
CMake                            1              4              0             16
XML                              1              0              0             13
-------------------------------------------------------------------------------
SUM:                            29            488            210           2660
-------------------------------------------------------------------------------

Team

We are a small, dedicated team with experience working on various robots and headsets.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

YANG Zhenfei 💻

junlinp 💻

heyixuan-DM 💻