RobotGuide

Engineering practice · topic F5 · 25 hours

Debugging methodology

Robot failures are usually many causes, one symptom. With the wrong method you will spend two weeks fixing a problem that only «looks fixed».

Engineering stage · Intermediate
Algorithm · Hands-on System software · Proficient Embedded & controls · Proficient Mechanical · Hands-on

Tools
Tools

What to learn

  • Bisection localization: cut the chain in the middle to decide whether the problem is in the first half or the second
  • Minimal reproduction: compress the problem to its shortest path
  • Log levels and choosing where to place instrumentation
  • The hypothesis–verification loop: change one variable at a time

The lesson · plain words

Debugging methodology is the most valuable and hardest-to-teach thing in engineering. This page gives three reusable patterns: bisection, minimal reproduction, and «suspect your own code first».

Bisection: finding the boundary is the fastest blade

Find the one commit out of 16 that introduced a bug: test the middle, go left if bad and right if good, and 4 tests pin it down. See the figure below. git bisect automates exactly this — you only supply a script that judges good or bad.

Bisection variants are everywhere: parameter bisection (start speed at 0.5× and double it rung by rung, find where it breaks), data bisection (which image category triggers the false detections), chain bisection (camera → network → algorithm, disconnect segment by segment). Any «fault inside a range» is this problem.

Interactive figure · drag it and see

What this figure shows: a row of 16 commits marked good → bad, each round testing the middle version and discarding half the candidates until the culprit commit is found — 4 tests for 16 (log2(16)=4), with a «move the bad commit» button that shifts the bug and replays the hunt. Takeaway: bisection squeezes 16 candidates into 4 tests and 64 into 6; «find the boundary» is always the fastest blade.

Minimal reproduction: strip the environment to the bone

If you cannot reproduce it, you cannot fix it. A minimal reproduction = the smallest scenario where the bug still lives after stripping everything irrelevant: least code, simplest input, most stable environment. Writing the minimal reproduction is often the process of finding the answer.

Robotics-specific moves: fix the random seed + record sensor data and replay it (F4's replay testing) + shut down unrelated nodes. Most «happens occasionally» bugs become «happens always» through data replay.

Three counterintuitive principles

① Suspect your own code before the library/hardware (order by probability); ② change one variable, look at one result — changing two together makes the test worthless; ③ write logs at the «hypothesized boundary», not sprayed everywhere — logging is itself bisection.

One more discipline: after fixing, answer «why did nothing catch this earlier» — add a test (F4's replay) or a check. Otherwise the same bug comes back wearing new clothes.

How deep to go

You can demonstrate a full git bisect; convert an intermittent bug into «replay + minimal reproduction»; and restate the three principles to your team. Debugging skill is the scientific method made concrete for engineering — form a hypothesis, design the experiment, eliminate variables.

Three questions — do you really get it?

1. What is the principle behind git bisect?

  • AExhaustive testing
  • BBinary search for the commit that introduced the bug
  • CRandom sampling
Show answer

B. Each test halves the candidates. 16 commits take 4 tests, 64 take 6.

2. What is the main tool for turning an «intermittent bug» into a «deterministic one»?

  • AFix the seed + replay recorded data
  • BRun it more times
  • CReboot the machine
Show answer

A. Replay makes the inputs fully deterministic. Intermittency usually comes from timing or random inputs — replay eliminates both.

3. You changed two variables at once and the bug disappeared. What should you do?

  • ACommit and ship it
  • BRevert them one at a time to verify which one worked
  • CAssume both were effective
Show answer

B. Not knowing which change worked means the next bug cannot be fixed back. The single-variable rule is the floor of debugging.

Keep going deeper

Links without a marker stay on this site; the rest point to the Chinese edition until its translation batch lands.

How it fails in the field

  • Changing three parameters at once; the symptom disappears and nobody knows which change did it
  • No record of the debugging process; the same problem comes around and gets debugged from scratch again

You have learned enough when

You can localize a latency problem spanning three layers with bisection, and leave a reusable debugging record.

The Chinese edition carries the full topic page for Debugging methodology, including the complete outline, depth requirements per career track, and further derivations: robotguide.dev/k/F5/.