Dharma

A robot-agnostic ROS 2 autonomy stack for legged and wheeled service robots: LiDAR-inertial odometry, fiducial localization, occupancy mapping with sites, path finding and following, a safety mux with a protective field, health monitoring and a simulator. This repository is the hub of the stack and the template a robot product starts from.

Repositories · Architecture · Quick start · Bringup · Scripts · Guide · Manual (PDF) · Paper (PDF)

---

Dharma knows nothing about a particular robot: geometry, limits and frames come from one robot profile (robot.* parameters) that a product passes to every node, and the robot driver is a separate package in the product. A product (a tour guide, an inspection robot, ...) is a repository made from this template: its bringup package, its robot profile and its own features.

Repositories

One repository per part, all at version 0.2.0, listed in dharma.repos:

Repository
dharma_utils	math, typed configuration, the robot profile, the braking model, file IO, grids, DharmaNode, test helpers
dharma_interfaces	typed status messages, sector scans, waypoints and the services of the stack
dharma_odometry	FAST-LIO / Leg-KILO (or an external estimator) behind a still-start gate, and the odometry monitor
dharma_localization	gravity-aligned odometry bridge, fiducial-anchored SE(2) EKF over map -> odom, scan matching
dharma_perception	LiDAR to front (avoidance) and 360° (safety) sector scans, fail-safe when blind; AprilTag throttle
dharma_mapping	occupancy grids per site, crash-safe maps, sites (map, fiducials, routes), route recorder
dharma_navigation	planner, route loader, path follower, obstacle avoidance; dharma_control: the safety mux
dharma_health	sensor rates and stamp ages, TF ages, stack states and the computer as one HealthStatus
dharma_rviz	RViz panels and the robot layout
dharma_sim	software-in-the-loop robot: kinematic body, ray-cast Mid-360, drifting odometry, scenarios

external.repos adds the Livox driver and FAST-LIO (and optionally Leg-KILO).

Architecture

            ┌──────────────────────────────────────────────────────────────┐   ┌────────────────┐
 product    │ application: the product's features (tours, inspection, ...) │   │ safety         │
            ├──────────────────────────────────────────────────────────────┤   │                │
 navigation │ planner · route loader · path follower · obstacle avoidance  │   │ control mux:   │
            ├──────────────────────────────────────────────────────────────┤   │ the only       │
 world      │ occupancy grid · sites (map, fiducials, routes)              │   │ cmd_vel, e-stop│
            ├──────────────────────────────────────────────────────────────┤   │ protective     │
 estimation │ LiDAR-inertial odometry · localization (EKF) · sector scans  │   │ field          │
            ├──────────────────────────────────────────────────────────────┤   │ health monitor │
 robot      │ the robot driver (product package) or dharma_sim             │   │ speed scale    │
            └──────────────────────────────────────────────────────────────┘   └────────────────┘
 base         dharma_utils (robot profile, config, math, DharmaNode) · dharma_interfaces

• Every node subclasses DharmaNode: typed parameters validated on start and on every ros2 param set, the shared robot profile, structured logs, guarded timers.
• Safety on the side: navigation publishes control/nav_cmd_vel; the control mux arbitrates it against operator sources, applies the protective field on the 360° safety scan and the health speed scale, and is the only publisher of the driver's cmd_vel.
• Frames from robot.frames (map -> odom -> base_link); relative topic names; the product namespaces the driver (/<ns>/cmd_vel, /<ns>/odom).

Quick start

A new product: on GitHub, Use this template, then

git clone https://github.com/<owner>/<MyRobot>.git && cd <MyRobot>
scripts/init_project.py --name MyRobot --package my_robot_bringup --robot-ns my_robot
pre-commit run --all-files          # re-pads the tables the rename made longer
git add -A && git commit -m "chore: init from the Dharma template"

Dev container (Linux / macOS, no local ROS needed):

scripts/dev.sh up                  # imports the stack into src/, builds the image, starts it
scripts/dev.sh build               # colcon build (humble; --distro foxy|jazzy for the others)
scripts/dev.sh test
scripts/dev.sh shell               # then: ros2 launch robot_bringup sim.launch.py rviz:=true
scripts/dev.sh vnc                 # the desktop: vnc://localhost:5901 or noVNC on :6080

Foxy, Humble and Jazzy run side by side (--distro foxy: ports 5903 / 6082, --distro jazzy: 5902 / 6081), each with its own build, install and log volumes. VS Code: Reopen in Container (.devcontainer/, .devcontainer/foxy/).

Natively (Ubuntu 20.04 + Foxy, 22.04 + Humble or 24.04 + Jazzy, also the robot computer):

scripts/setup.sh check                        # what is there, what is missing
scripts/setup.sh install                      # tools, repos, livox, rosdep, build
ros2 launch robot_bringup sim.launch.py       # the whole stack on the simulator

Bringup

src/robot_bringup is the placeholder product package (init_project.py renames it):

File
config/robot.yaml	the robot profile (/**: ros__parameters: robot: ...), validated at launch
config/stack.yaml	per-node overrides of the package defaults for this robot
config/sim.yaml	what differs on the simulator
launch/robot.launch.py	odometry, localization, perception, mapping, navigation, control, health; driver with robot_driver:=<pkg>[/<file>]
launch/sim.launch.py	the same stack on dharma_sim (odometry external)
robot_bringup/stack.py	the composition: which package launch files, with which arguments

Details in the package README.

Scripts

Script
scripts/dev.sh	dev container: up, shell, build, test, vnc, down, clean, import; --distro foxy|humble|jazzy
scripts/setup.sh	robot / dev machine: check, install ros tools repos livox rosdep build service
scripts/start_tmux.sh	tmux session with one window per subsystem (robot or sim layout in scripts/tmux/)
scripts/init_project.py	turn the template into a product
scripts/sync_tooling.sh	maintainers: copy tooling/ (lint configuration, per-repository CI) into every dharma_* checkout

Docs

• Guide: getting started, architecture, safety, every subsystem, operation and development (Markdown, renders on GitHub).
• Technical manual (PDF) and paper (PDF); their LaTeX sources and the diagrams are in docs/ (make -C docs pdf). Conventions for code, commits and releases: CONTRIBUTING.md; changes: CHANGELOG.md.

Dharma is released under the Apache License 2.0.