Tune navigation behavior

The navigation service starts with defaults that work for slow outdoor robots with standard GPS. As you test in your environment, you’ll want to adjust these parameters.

All parameters can be changed in the Viam app without restarting viam-server. Changes take effect on the next navigation cycle.

Speed

When to increase speed: Your robot’s motors and terrain support faster movement, and your obstacle detection polling is fast enough to react at the higher speed. At 1 m/s with 1 Hz obstacle polling, the robot travels 1 meter between obstacle checks.

When to decrease speed: The robot overshoots waypoints, turns are too aggressive, or obstacle detection can’t keep up. Reduce angular speed first if turns are the problem.

Plan deviation

This is the most important tuning parameter. Set it relative to your GPS accuracy:

If it’s too low (below your GPS error), the robot replans constantly because normal GPS jitter looks like path deviation. You’ll see the robot stop and recalculate frequently, making slow progress.

If it’s too high, the robot tolerates large deviations before correcting. It might cut corners, drift off the intended path, or approach obstacles before replanning.

Polling frequencies

Position polling determines how quickly the service detects that the robot has deviated from its plan. At 1 Hz, a deviation takes up to 1 second to detect. For fast-moving robots, increase this.

Obstacle polling determines how quickly new obstacles are detected. Higher values improve reaction time but increase CPU and camera bandwidth usage. Balance against your robot’s speed: at 0.3 m/s and 1 Hz, the robot moves 30 cm between checks. At 1 m/s, it moves 1 meter.

Tuning workflow

1. Start with defaults. Navigate to a nearby waypoint in an open area with no obstacles.
2. Check for excessive replanning. If the robot stops frequently to recalculate, increase plan_deviation_m. Watch the Control tab map to see when replans happen.
3. Adjust speed. Increase meters_per_sec gradually. Watch for overshooting waypoints or unstable turns.
4. Add obstacle detection. Once basic navigation works, add obstacle detectors and test with known obstacles.
5. Adjust polling. If the robot doesn’t detect obstacles quickly enough, increase obstacle_polling_frequency_hz. If the robot is slow because of excessive polling, decrease it.

What’s next

• Navigation service configuration: full reference for all parameters.
• Monitor and troubleshoot: debug navigation problems using the Control tab and logs.