tinynav logo

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

Homepage | Documentation | Discord

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

looper

[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

Check the environment

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:

✅ 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.

Open the project in VS Code

- Launch VS Code and open the tinynav folder. - Install the Dev Containers extension if prompted. - Reopen the folder inside the container.

Run the example

Once inside the container, start the demo:

bash /tinynav/scripts/run_rosbag_examples.sh

You should see an RViz window displaying the live planning process:

tinynav logo

📜 What `run_rosbag_examples.sh` Does

The script automates the entire demo workflow:

Plays dataset

Streams a recorded dataset from this ROS bag.

Runs TinyNav pipeline

- perception_node.py → Performs localization and builds the local map. - planning_node.py → Computes the robot’s optimal path. - 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

Open the tinynav folder in Visual Studio Code.
Ensure the Dev Containers extension is installed.
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
💻

_{xinghan li}
💻

_{Xiaole Fang}
💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Sponsors ❤️

Thanks to our sponsor(s) for supporting the development of this project:

DeepMirror - https://www.deepmirror.com/

Looper Robotics - https://looper-robotics.com/

UniflexAI/tinynav: TinyNav: A lightweight, hackable system to guide your robots anywhere.

Homepage | Documentation | Discord

Bounties

Stereo Cameras

[v0.3] What's Changed

🚀 Features

🔧 Improvements

🐞 Bug Fixes

[v0.2] What's Changed

🚀 Features

🔧 Improvements

🐞 Bug Fixes

[v0.1] What's Changed

🚀 Features

🔧 Improvements

🐞 BugFix

Highlight (Our Design Goals)

Tiny

Robust

Multiple Robots Platform

Multiple Chips Platform

Project Structure

Getting Started

Prerequisites

🚀 Quick Start

📜 What run_rosbag_examples.sh Does

Developer Guide

Using Dev Containers

Using VS Code

Using the Dev Container CLI

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

Start the Dev Container

Open a shell inside the container

First-Time Setup (Inside the Dev Container)

Optional Dependencies

LeKiwi robot support

3D Gaussian Splatting (3DGS) map support

Next Steps

📊 Line of Code

Team

Contributors ✨

Sponsors ❤️

Reading Mode

Related Stories

Matt Mullenweg tells Automattic staff in Slack he's back in control after ouster

Show HN: Hacker News, without AI

HuggingFace: Security.txt

Show HN: Clawfight.ai MCP-driven agentic game play

Houthis 'take control' of key island in global shipping route

Related Stories

📜 What `run_rosbag_examples.sh` Does