Bring-up order and a debugging checklist

16.1 Bring it up in this order

Each stage below is a place where a fault is easy to find. Assemble everything first and the faults compound.

Stage one: the Teensy alone. Blink an LED. Confirm you can program it, that the USB serial link works, and that the clock speed is what you think. Ten minutes.

Stage two: one driver, on the bench, no arm. One TMC2209, one motor, a bench supply, nothing mechanical attached. Get UART communication working and verify it by reading IFCNT and watching it increment. Then use the VACTUAL register to spin the motor from the driver's own internal step generator, which exercises power, wiring, current setting, and the driver without involving your step-generation code. Only when that works, switch to STEP/DIR pulses from the Teensy.

Stage three: one driver, tuning. Still on the bench, with the motor coupled to something with a bit of inertia. Set current properly and check the motor's temperature after ten minutes of running. Try StealthChop and SpreadCycle and listen to the difference. Log SG_RESULT while loading the shaft by hand, to get a feel for the numbers.

Stage four: six drivers. Add the rest, with addresses strapped correctly. Confirm you can talk to each individually: read a distinctive register value back from each and check you get six different answers rather than the same one six times, which is what wrong addressing looks like. Run all six motors simultaneously and check your step ISR timing with the cycle counter and, ideally, an oscilloscope on the step lines.

Stage five: one joint, mechanically assembled. Now attach a motor to an actual joint. Verify direction. Verify that the commanded angle matches the measured angle — put a protractor on it, command 90°, and measure. Gear ratio errors show up here, and are otherwise invisible until the IK produces nonsense. Home the joint and check repeatability over twenty cycles.

Stage six: the full arm, joint space only. All six joints, homing sequence working, joint-space moves working, soft limits enforced. No IK yet. Move each joint through its range and confirm nothing collides.

Stage seven: forward kinematics. Command a set of joint angles, compute where the FK says the tool should be, and measure it. A ruler and a fixed reference point are enough to catch a gross error. Do this at several poses across the workspace.

Stage eight: inverse kinematics. Round-trip test in software first — thousands of random poses, FK then IK then FK, confirming the poses match. Only then command Cartesian moves on the real arm — slowly, in open space, away from anything you mind hitting.

Stage nine: speed and tuning. Now raise velocities and accelerations, tune the profiles, and find where the arm starts to lose steps or wobble. Back off from that point with margin.

16.2 Symptom-to-cause checklist

Motor makes noise but does not turn, or vibrates in place. Usually a coil pairing error, with one coil split across the two driver outputs. Power off, measure resistance between wire pairs, and re-pair them. Can also be a current setting far too low.

Motor turns but loses steps under load. Current too low, acceleration too high, supply voltage too low, or the motor undersized for the load. Try in that order. Raising the supply voltage helps specifically at speed.

Motor gets very hot. Current too high, or hold current not being reduced at standstill. Check IHOLD and TPOWERDOWN, against the PETG thermal limits.

Driver does nothing at all, no response over UART. Check IFCNT. If it does not increment, the UART is not getting through: check the 1 kΩ series resistor, check the address straps on MS1/MS2, check that VIO is powered, check RX/TX are not swapped. If IFCNT does increment but the motor is dead, check that TOFF in CHOPCONF is non-zero and that EN is actually low.

Driver was working, now unresponsive. Read GSTAT. If the reset flag is set, the driver has restarted and lost its configuration, so detect that and reconfigure. If the driver-error flag is set, read DRV_STATUS for the specific fault.

Intermittent UART corruption. Usually noise coupling from motor wiring, or a ground loop. Separate the cables. Check the star ground. Lower the baud rate as a diagnostic — if it fixes it, you have a signal integrity problem, not a protocol problem.

StallGuard never triggers. TCOOLTHRS not set, so stall detection is disabled — the most common cause by some margin. Then homing speed outside the usable band. Then SGTHRS set too low, higher being more sensitive.

StallGuard triggers immediately. Probably armed during acceleration. Wait until you reach constant homing speed. Also check that DIAG is not signalling a driver error rather than a stall.

Arm reaches the right position but the wrong orientation. Euler angle convention mismatch, or a sign error in one of the α values in the DH table. Check the wrist frames specifically.

IK works in some poses and not others. Usually the "out of reach" branch is unhandled and a NaN from acos is propagating; add explicit range checks. Can also be joint limits filtering out all eight solutions, which should return "unreachable in this configuration" rather than failing silently.

The arm makes a sudden large motion mid-path. A configuration change: the IK jumped between solution branches. Add continuity preference to your solution selection.

Motion is jerky or the arm wobbles at the end of a move. Trapezoidal profile with infinite jerk exciting the structure. Switch to S-curve. Also check that your segment queue is not underrunning.

Position drifts over many moves. Rounding accumulation. Make integer microstep counts authoritative, as in Chapter 13.2.