Debug the Layer, Not the Symptom

A robot drifts left.

That is a symptom.

Possible causes exist in several layers:

mission
  ↓
software command
  ↓
control loop
  ↓
sensor measurement
  ↓
motor driver
  ↓
motor / gearbox
  ↓
wheel / traction
  ↓
frame alignment

Changing code before locating the layer can make the system worse.

Evidence ladder

Start with observations that separate branches.

For a drift problem:

1. Are left/right target commands equal?
2. Are measured wheel speeds equal?
3. Are motor outputs equal?
4. Do unloaded wheel speeds differ?
5. Is wheel diameter/traction different?
6. Is chassis alignment correct?

Each answer removes possibilities.

Fault injection

A powerful way to understand a system is to create a safe, simulated fault.

Examples:

• add encoder scale error;
• delay one message;
• reduce one motor's maximum output;
• introduce sensor noise;
• shift the robot's center of mass.

Then observe which signals reveal the problem first.

Logs need meaning

A thousand lines of telemetry are not useful if nothing is tied to a question.

Log values that support a diagnosis:

timestamp, state, target, measurement, output, fault

That set can reconstruct many control failures.

Build a diagnostic path

Choose one symptom:

• robot does not move;
• robot drifts;
• arm overshoots;
• vision is intermittent;
• autonomous mission freezes.

Create a decision tree with at least three layers and one observable check at each branch.

Do not put "replace part" as the first check.

Find the first wrong boundary

A robot veers left.

That symptom does not tell you which subsystem is wrong.

Trace the chain:

path target
   ↓
wheel velocity targets
   ↓
motor commands
   ↓
motor outputs
   ↓
wheel motion
   ↓
robot motion

Now compare expected and observed values at each boundary.

The first major disagreement appears between motor command and measured wheel motion, not in the path planner.

Investigate that layer: friction, gearing, motor health, sensor conversion, mechanical drag.

Do not erase the evidence

Changing gains before saving the trace destroys a useful baseline.

A good debug cycle is:

preserve failure → localize boundary → change one cause → rerun same test

A fix is more defensible when the same test that exposed the problem demonstrates that it changed.