Tune navigation behavior

The navigation service ships with defaults tuned for slow outdoor robots running standard GPS. Once you start testing in your environment, four parameters account for almost all the tuning you will do: two speeds, plan_deviation_m, and the two polling frequencies. This page covers each in the order you should tune them.

All parameters can be changed on the CONFIGURE tab 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

The service polls two things independently: the robot’s position and each obstacle detector. Both default to 1 Hz.

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.

Replan cost factor

replan_cost_factor complements plan_deviation_m. plan_deviation_m tells the service when to consider replanning; replan_cost_factor tells it how strongly to prefer the current plan once it starts evaluating a new one.

When to increase: the robot replans too eagerly after small deviations, producing oscillation or backtracking. Raise the factor (for example, to 2.0 or 3.0) so the current plan remains preferred unless the deviation is significant.

When to decrease: the robot sticks to outdated plans too long after conditions change. Lower the factor (for example, to 0.5) so it adopts new plans more readily.

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 robot’s marker on the navigation service card’s map, and check the LOGS tab for replan events.
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.