How to Configure Navigation Strategies in DimOS: A* Planning and Frontier Exploration

DimOS provides two primary navigation strategies—Replanning A for goal-directed path planning and Wavefront Frontier Exploration for autonomous mapping—which you configure through GlobalConfig environment variables, module constructor parameters, and blueprint composition.*

DimOS (Dimensional OS) is an open-source robotics operating system that enables complex navigation behaviors for mobile robots. The framework ships with complementary navigation modules located in dimos/navigation/replanning_a_star/ and dimos/navigation/frontier_exploration/, allowing developers to switch between precise waypoint tracking and autonomous environment exploration. This guide demonstrates how to configure these navigation strategies using the three-layer configuration system found in dimos/core/global_config.py and the blueprint composition API.

Understanding the Two Navigation Strategies

DimOS implements navigation as modular components that expose LCM/RPC interfaces. You can enable either strategy individually or compose them together in a single blueprint.

Replanning A* Planner

The Replanning A* strategy, implemented in dimos/navigation/replanning_a_star/module.py, provides fast, width-aware path planning on a gradient costmap. It continuously replans whenever the robot deviates from the path, becomes stuck, or receives a new goal. This strategy is ideal for goal-directed navigation where you need the robot to travel to specific waypoints or follow predetermined paths.

Key implementation details reside in dimos/navigation/replanning_a_star/global_planner.py, which handles the low-level path generation, safe-goal search, and replanning logic.

Wavefront Frontier Exploration

The Wavefront Frontier Exploration strategy, found in dimos/navigation/frontier_exploration/wavefront_frontier_goal_selector.py, enables autonomous mapping of unknown environments. It detects frontier cells—boundaries between known free space and unknown areas—in the 2-D costmap, ranks them using a multi-criteria scoring system, and publishes the best frontier as an exploration goal. This strategy is essential for applications requiring the robot to independently explore and map its surroundings.

Configuration Layers in DimOS

DimOS organizes navigation configuration into three distinct layers: GlobalConfig for environment-wide settings, module-level parameters for strategy-specific tuning, and blueprint composition for runtime behavior.

GlobalConfig Settings

The GlobalConfig class in dimos/core/global_config.py manages global flags and environment variables that affect all navigation modules. You can set these via CLI flags when launching a blueprint or through a .env file in the repository root.

Common navigation-related GlobalConfig settings include:

# CLI flags when running a blueprint

dimos run unitree-go2-agentic \
    --robot-model=unitree_go2 \
    --n-workers=6

# .env file settings

DIMOS_ROBOT_ROTATION_DIAMETER=0.4   # Used by A* safe-goal search

DIMOS_FRONTIER_MIN_PERIMETER=0.5    # Meters, used by frontier explorer

Module-Level Parameters

Each navigation strategy exposes constructor arguments that allow fine-grained control over behavior.

Replanning A* Parameters

While the ReplanningAStarPlanner class in dimos/navigation/replanning_a_star/module.py accepts no public constructor arguments, it reads tunable values from GlobalConfig and exposes private attributes that can be modified after instantiation:

Attribute	Default	Description
_safe_goal_tolerance	4.0 m	Maximum distance to search for a safe spot near the requested goal
_goal_tolerance	0.2 m	Distance threshold for considering the robot arrived
_rotation_tolerance	15° (radians)	Angular tolerance for goal arrival
_max_path_deviation	0.9 m	Distance threshold that triggers replanning when deviated from path
_max_replan_attempts	10	Maximum consecutive replans before aborting

You can override these after creating the planner instance:

from dimos.navigation.replanning_a_star.module import replanning_a_star_planner

planner = replanning_a_star_planner()
planner._safe_goal_tolerance = 6.0          # Allow farther safe-goal search

planner._max_path_deviation = 1.2          # Be more tolerant to drift

planner.start()

Wavefront Frontier Explorer Parameters

The wavefront_frontier_explorer in dimos/navigation/frontier_exploration/wavefront_frontier_goal_selector.py accepts extensive constructor arguments:

from dimos.navigation.frontier_exploration import wavefront_frontier_explorer

explorer = wavefront_frontier_explorer(
    min_frontier_perimeter=0.5,   # Meters (default)

    occupancy_threshold=99,       # Costmap cell value threshold for "occupied"

    safe_distance=3.0,            # Meters for obstacle-distance scoring

    lookahead_distance=5.0,       # Desired distance from robot when selecting frontier

    max_explored_distance=10.0,   # Bonus for frontiers far from visited goals

    info_gain_threshold=0.03,     # Percentage of new map information required

    num_no_gain_attempts=2,       # Stop after consecutive low-gain attempts

    goal_timeout=15.0,            # Seconds to wait for frontier goal arrival

)

These parameters control three distinct phases:

• Frontier detection: min_frontier_perimeter and occupancy_threshold determine which cells qualify as frontiers
• Goal ranking: safe_distance, lookahead_distance, and max_explored_distance score candidate frontiers
• Exploration termination: info_gain_threshold, num_no_gain_attempts, and goal_timeout prevent infinite exploration

Blueprint Composition

Navigation strategies in DimOS are composed using the autoconnect function from dimos.core.blueprints. The order of modules matters because it determines which component supplies the cmd_vel and path streams.

Combining Both Strategies

The canonical Unitree Go2 blueprint demonstrates composing both A* and frontier exploration:

from dimos.core.blueprints import autoconnect
from dimos.robot.unitree.go2.blueprints.basic import unitree_go2_basic
from dimos.mapping.voxels import voxel_mapper
from dimos.mapping.costmapper import cost_mapper
from dimos.navigation.replanning_a_star.module import replanning_a_star_planner
from dimos.navigation.frontier_exploration import wavefront_frontier_explorer

unitree_go2 = autoconnect(
    unitree_go2_basic,                # Robot connection + visualization

    voxel_mapper(voxel_size=0.05),    # 3-D voxel map

    cost_mapper(),                    # 2-D costmap

    replanning_a_star_planner(),      # A* path planner (goal-directed)

    wavefront_frontier_explorer(),    # Frontier explorer (exploration)

).global_config(n_workers=6, robot_model="unitree_go2")

In this composition, replanning_a_star_planner provides the cmd_vel stream that drives the robot, while wavefront_frontier_explorer publishes exploration goals to the planner's goal_request input.

Strategy-Specific Blueprints

To use only goal-directed navigation without exploration:

from dimos.core.blueprints import autoconnect
from dimos.robot.unitree.go2.blueprints.basic import unitree_go2_basic
from dimos.mapping.voxels import voxel_mapper
from dimos.mapping.costmapper import cost_mapper
from dimos.navigation.replanning_a_star.module import replanning_a_star_planner

pure_nav = autoconnect(
    unitree_go2_basic,
    voxel_mapper(),
    cost_mapper(),
    replanning_a_star_planner(),   # Only A* planner

)

To create a pure exploration robot without waypoint navigation:

from dimos.core.blueprints import autoconnect
from dimos.robot.unitree.go2.blueprints.basic import unitree_go2_basic
from dimos.mapping.voxels import voxel_mapper
from dimos.mapping.costmapper import cost_mapper
from dimos.navigation.frontier_exploration import wavefront_frontier_explorer

explorer_only = autoconnect(
    unitree_go2_basic,
    voxel_mapper(),
    cost_mapper(),
    wavefront_frontier_explorer(min_frontier_perimeter=0.8),
)

Runtime Control via RPC and CLI

Both navigation modules expose RPC methods that allow runtime control through the DimOS CLI or MCP/LLM agent interface.

Sending Navigation Commands

Use the dimos agent-send CLI to interact with active navigation strategies:

# Send a waypoint to the A* planner

dimos agent-send "go to 2.5 meters forward and 1.0 meters left"

# Start autonomous frontier exploration

dimos agent-send "start exploration"

# Cancel current navigation goal

dimos agent-send "cancel goal"

Querying Navigation State

The navigation interface exposes get_state() which returns a NavigationState enum indicating whether the system is IDLE, PLANNING, NAVIGATING, or STOPPED.

# Query via agent

dimos agent-send "what is the navigation state?"

Summary

Configuring navigation strategies in DimOS involves three complementary approaches:

• GlobalConfig manages environment-wide settings like DIMOS_ROBOT_ROTATION_DIAMETER and DIMOS_FRONTIER_MIN_PERIMETER through CLI flags or .env files
• Module parameters allow fine-tuning of specific behaviors, such as setting _max_path_deviation for the A* planner or info_gain_threshold for frontier exploration
• Blueprint composition determines which strategies are active and how they interact, using autoconnect to wire together mappers, planners, and explorers

Both strategies expose unified RPC interfaces, enabling runtime control via the DimOS CLI or MCP agent for dynamic switching between goal-directed navigation and autonomous exploration.

Frequently Asked Questions

How do I switch between A* planning and frontier exploration at runtime?

You can toggle between strategies by sending commands through the DimOS agent interface. The wavefront_frontier_explorer publishes goals to the same goal_request stream that replanning_a_star_planner consumes, so sending "start exploration" activates frontier mode while "go to x, y" triggers A* waypoint navigation. For hard switching, create separate blueprints omitting the unused strategy.

What is the difference between _safe_goal_tolerance and _goal_tolerance in the A* planner?

_safe_goal_tolerance defines how far the planner will search for a collision-free cell near your requested goal (default 4.0 m), ensuring the robot doesn't attempt to navigate into occupied space. _goal_tolerance determines when the robot considers itself arrived at the target (default 0.2 m). The first handles goal feasibility, while the second handles goal completion.

How do I prevent the frontier explorer from running indefinitely?

Configure the termination parameters in wavefront_frontier_explorer. Set info_gain_threshold to require a minimum percentage of new map information per frontier (default 0.03), and num_no_gain_attempts to limit consecutive low-gain explorations (default 2). Additionally, set goal_timeout (default 15.0 s) to abort frontiers that take too long to reach.

Can I use both navigation strategies simultaneously in the same blueprint?

Yes. The canonical Unitree Go2 blueprint demonstrates this composition. When both replanning_a_star_planner() and wavefront_frontier_explorer() are included in the same autoconnect call, the explorer publishes frontier goals to the planner's goal_request input, while the planner provides the cmd_vel output that drives the robot. This allows seamless switching between autonomous exploration and directed waypoints without restarting the system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}