Skip to the lesson
FixTheRobot Explore Robotics / Navigation / M9 Navigation in the Real World / M9-T2

Navigation · Theory · M9

M9-T2 — Tuning a Navigation Stack

Tuning is an experiment with a written hypothesis, not a search for values that feel good.

  • Lesson 2 of 6
  • Module 9: Navigation in the Real World
  • Theory
  • About 9 minutes to read

Every navigation parameter file is a pile of old decisions. A value that rescued one corridor breaks another door, and nobody remembers why it is there. The remedy is a method: decide what “good” means as checks, test against the worst places in the building, change one thing at a time, and keep a record. The parameters themselves then fall into place from a few formulas.

Learning objectives

After this lesson, you should be able to:

  • Set the inflation radius and cost scaling from the footprint, the narrowest door and the clearance you want.
  • Choose a lookahead and a top speed from latency, stopping distance and corner cutting.
  • Pick tolerances and a costmap resolution, and say what each costs.
  • Apply a one-change-at-a-time method with written checks and worst-case scenarios.

The intuition

Tuning a robot resembles setting the seat, mirrors and steering of a car you share with others. There is no universal setting; there is a driver, a road and a list of things that must not happen. You adjust one thing, drive the same test road, and see what changed. If you change the seat and the mirror together and the view improves, you do not know which one helped.

A navigation stack has two families of parameters. The geometry parameters (footprint, inflation radius, cost scaling, resolution) describe the robot and what it should keep away from; they are checked against the building. The dynamics parameters (speed, lookahead, acceleration, tolerances, frequencies) describe how quickly the robot may act and how long it takes the world to answer; they are checked against latency, braking and the mission clock. Mixing the two families in one experiment is the commonest way to learn nothing.

The tuning loopA loop of five steps: write the acceptance checks, run the worst scenarios, change one parameter, record which check moved, and keep or revert. The loop repeats until all checks pass with a margin.1 Checks2 Worst scenarios3 Change ONE thing4 Record what moved5 Keep or revert repeat until every check passes with a margin on the worst scenario A parameter is only “tuned” relative to a check you wrote down first.
The tuning loop. The change step is deliberately small: one parameter, one hypothesis, one record.

The mathematics

Geometry: inflation and cost scaling

With inscribed radius rin and the desired body clearance c from a wall (lesson M2-T2), the path should sit about rin + c from the wall. The cost beyond the inscribed radius is 252 · e−k(d − rin) up to the inflation radius.

Inflation rules of thumb
rinfl≥rin+c+marginr_{\text{infl}}\ge r_{\text{in}}+c+\text{margin}
the cost field must reach where you want the path to feel the wall
rinfl≤narrowest door width2r_{\text{infl}}\le \frac{\text{narrowest door width}}{2}
below this, the two sides never overlap on the door centre line
cost at door centre=252⋅exp⁡(−k⋅(w2−rin))\text{cost at door centre}=252\cdot \exp (-k\cdot (\frac{w}{2}-r_{\text{in}}))
if rinfl≥w2\text{if}\,r_{\text{infl}}\ge \frac{w}{2}

If you need a larger radius than half the door, make the decay steep enough that the centre-line cost is acceptable: the first line says how far the planner feels a wall, the third says how much it costs to stand where two walls overlap.

Dynamics: lookahead, speed, stopping

A pure-pursuit-style controller steers towards a point a distance L ahead on the path. With command latency τ at speed v, the robot travels vτ before a command takes effect. Stability needs L comfortably above that; corner cutting needs L not too long; stopping needs room.

stability
L>v⋅τ(with margin, e.g.L≥2 v τ)  corner cutL>v\cdot \tau (\text{with margin},\,e.g.L\ge 2\,v\,\tau )\;\mathrm{corner\ cut}
grows with L (the robot aims past the bend)
stopping
dstop=v⋅(treact+τ)+v22 a≤distance availabled_{\text{stop}}=v\cdot (t_{\text{react}}+\tau )+\frac{v^{2}}{2\,a}\le \text{distance available}
mission
v≥leg lengthtime allowedv\ge \frac{\text{leg length}}{\text{time allowed}}
L
lookahead distance (m); in Regulated Pure Pursuit, lookahead_dist or the velocity-scaled range between min and max.
τ
command latency (s): from decision to motion, including communication, smoothing and actuation.
a
deceleration the robot can actually achieve (m/s²), including its payload.
treact
time to perceive a hazard and begin braking (s).

Tolerances, frequencies and resolution

ParameterToo tightToo loose
Goal tolerance (xy, yaw)The robot hunts around the goal, or never reports successStops short of the door it should enter or the dock it should mate with
Costmap resolutionMemory and compute grow with 1 / resolution²; updates fall behindDoors close: a 0.90 m door on a 0.25 m grid may be 3 or 4 cells, and rounding eats the margin
Controller frequencyNeeds CPU the robot does not have; missed cyclesCommands arrive late; stability needs a larger lookahead
Local costmap update frequencyWastes computePlans on a stale map: v / f metres of motion between updates
Progress checker windowFalse “failed to make progress” on slow startsA stuck robot waits a long time before recovering

The method

  1. Write the checks first. For example: at least 12 cm between body and obstacle, at least 70% of top speed in a doorway, under 5 cm of weaving, stop within 1.5 m, 40 m in 54 s.
  2. Choose the worst scenarios. The narrowest door, the closest cart, the slowest link, the heaviest load. A value that passes only the example is not tuned.
  3. Change one parameter, predict which check moves, run, and record the result with the value.
  4. Keep a margin. Choose the middle of the passing window, not its edge, because the world will drift.

A worked example

Scout’s corridor. Scout is 0.60 m × 0.40 m: rin = 0.20 m. A cart leaves a gap of 0.92 m and the pharmacy door is 0.90 m. The checks are the five above; the link latency is between 0.15 s and 0.35 s and braking is 0.55 to 0.70 m/s² (the numbers of lab M9-L1).

Step 1: geometry. To keep 12 cm from the cart the path must be at least 0.20 + 0.12 = 0.32 m from it, so the inflation radius must exceed 0.32 m with margin: 0.35 to 0.45 m. The door’s centre is 0.45 m from each post. Try rinfl = 0.45 and look at the cost on the door’s centre line for different decay factors:

k      cost at 0.45 m = trunc(252·exp(−k·0.25))     speed kept (1 − cost/252)
3.0    119                                          53 %   fails the 70 % check
6.0     56                                          78 %   passes
8.0     34                                          87 %   passes
10.0    20                                          92 %   passes, but the path hugs the cart more

A decay of 8 passes with room to spare. For a 0.85 m door (centre at 0.425 m) the cost with k = 8 is trunc(252·e−8·0.225) = 41: still fine.

Step 2: dynamics. At the worst latency of 0.35 s and 0.85 m/s, v·τ = 0.30 m, so a lookahead of 1.0 m is more than three times that. Stopping at the weakest brakes: dstop = 0.85 × (0.30 + 0.35) + 0.85² / (2 × 0.55) = 0.55 + 0.66 = 1.21 m, inside the 1.5 m of room; at 1.1 m/s it would be 1.1 × 0.65 + 1.1² / 1.1 = 0.72 + 1.10 = 1.82 m, which fails. A 40 m leg at 0.85 m/s takes 47 s, inside 54 s, so there is time to spare, and a lookahead of 1.0 m keeps the corner cut small. The set {0.45, 8, 1.0, 0.85} passes all checks on every hidden scenario in the lab.

What the method protected against. Had the lookahead and the decay been changed together, a weaving robot and an expensive door could not have been told apart. Each belongs to a different check, and each took one experiment.

Engineering implications and limitations

Keep a tuning log

For each change: the parameter, the old and new value, the hypothesis, the scenario, the result. A year later the log is the only way to know why a value is what it is. Commit it with the parameter file.

Tune in simulation first, then confirm on the robot

Simulation finds the gross errors cheaply (lesson M9-T3). It cannot know your floor, your wireless link or your load, so the final window must be confirmed on the real robot in the real corridor, with the same checks.

Tune the system, not the algorithm

Most problems blamed on “the controller” are a mismatch: a speed limit in the smoother below the controller’s desired speed, a costmap scaling factor that differs between the costmap and the controller, a footprint that differs between the two costmaps. Compare the numbers before you change the algorithm (lab M9-L2 checks several of these automatically).

Resolution is a safety parameter

Halving the resolution cell size quadruples the cells. Doors are a few cells wide; with a coarse grid the inscribed band can swallow a door. Choose the resolution from the narrowest passage you must use, then check the compute budget.

Parameter names change

The parameters named here exist in the Nav2 documentation at the time of writing (inflation_radius and cost_scaling_factor in the inflation layer; lookahead_dist and desired_linear_vel for the Regulated Pure Pursuit controller), but names and defaults can change between releases. Check the Nav2 Configuration Guide and tuning notes for your distribution.

Common misconceptions

“A bigger inflation radius is safer.”

Past the inscribed radius it only changes preferences, and it raises the cost of doors and narrow corridors. Safety comes from the inscribed radius being right and from the collision monitor.

“A longer lookahead is always smoother.”

It is more stable, and it also cuts corners and follows turns late. There is a window between the stability limit and the corner limit.

“If it works on my test corridor it is tuned.”

It is tuned for that corridor. Tune against the worst scenario, and keep a margin.

“Change several things at once to save time.”

You save a day and lose the ability to explain the result. One change, one record.

Engineering takeaways

  1. Write acceptance checks before touching a parameter, and test on the worst scenarios.
  2. Geometry parameters (inflation, scaling, resolution) are checked against the building; dynamics parameters (lookahead, speed, tolerances) against latency, braking and the clock.
  3. Inflation radius: beyond inscribed radius plus clearance, and below half the narrowest door unless the decay is steep.
  4. Lookahead must exceed v·τ with margin but not cut corners; stopping distance is v·(treact + τ) + v²/2a.
  5. Change one thing at a time, keep a log, choose the middle of the passing window, and check the documentation of your release for parameter names.

References and further reading

The Nav2 configuration and tuning documentation, and the papers behind the controllers.

  • Nav2 documentation, “Configuration Guide” and “Navigation Plugins” (costmap 2D, inflation layer, Regulated Pure Pursuit controller), docs.nav2.org.
  • S. Macenski, F. Martín, R. White and J. Ginés Clavero, “The Marathon 2: A Navigation System”, IEEE/RSJ IROS, 2020.
  • R. C. Coulter, “Implementation of the Pure Pursuit Path Tracking Algorithm”, Carnegie Mellon University Robotics Institute, CMU-RI-TR-92-01, 1992.
  • D. Fox, W. Burgard and S. Thrun, “The Dynamic Window Approach to Collision Avoidance”, IEEE Robotics & Automation Magazine, 1997.

Knowledge check

Three conceptual questions. Write an answer, then reveal the explanation. Your answers stay in your browser.

Question 1

A door is 0.80 m wide, the inscribed radius is 0.20 m and the decay factor is 4. What is the cost on the door’s centre line when the inflation radius is 0.60 m?

Explanation

The centre is 0.40 m from each post: trunc(252 · e^(−4 · (0.40 − 0.20))) = trunc(252 · e^(−0.8)) = 113. Raising the decay to 8 would give 50.

Question 2

Latency is 0.30 s and the speed is 1.0 m/s. A colleague sets the lookahead to 0.25 m and the robot weaves. Why, and what are two fixes?

Explanation

The robot travels 0.30 m before a command takes effect, further than the lookahead, so each correction overshoots. Raise the lookahead well above 0.30 m (for example to 0.6 to 1.0 m) or lower the speed.

Question 3

You change the inflation radius, the lookahead and the speed in one run, and the robot now stops 20 cm short of a door. What can you conclude?

Explanation

Nothing reliable: three parameters changed, and each could be responsible. Revert, change one at a time, and record the effect of each against your checks.

What’s next

Next: the frame and clock problems that look like navigation bugs, and how to test before the hardware.

Practice this lesson

Tune the Inflation Radius

Choose the inflation radius, cost scaling and lookahead for a footprint and a top speed, and see the trade-off.

Next lesson

M9-T3 — Frames, Timing and Simulation

Find frame and clock problems that show up as navigation failures, and test in simulation before hardware.

Nothing below is required to finish this lesson.