pid-scope

Live terminal plotter for robot serial telemetry. Tune your PID by watching the error curve, not the robot.

Built by WashingMachine, a RoboCup Junior Rescue Line team from ITIS A. Rossi, Vicenza. We got tired of guessing why the robot wobbled, so we made the wobble visible.

What it does

Your firmware prints comma-separated numbers over serial:

Serial.println(String(error) + "," + String(correction));

pid-scope turns that stream into live charts in your terminal, one per channel, with min/max/mean stats and optional CSV logging:

╭──────────────────────────────────────────────╮
│ error        -12.40   min -41.2 max 39.8 ... │
│ ▃▄▆█▇▅▃▂▁▂▃▅▆▇█▆▄▂▁▁▂▄▅▇█▇▅▃▂▁▂▃▅▆▇▆▄▃▂▂▃▄▆  │
╰──────────────────────────────────────────────╯

No GUI, no Processing sketch, no Arduino IDE plotter limits. Works over SSH.

Install

pip install git+https://github.com/WashingMachineRobocupJR/pid-scope

Usage

# real robot
pid-scope /dev/ttyUSB0 --baud 115200 --labels error,correction

# log every sample for later analysis
pid-scope /dev/ttyUSB0 --log run42.csv

# no robot handy? try the UI with simulated data
pid-scope --demo

Any line of comma or semicolon separated numbers is a sample. Lines that don't parse (boot messages, debug prints) are ignored, so you can leave your other logging in place.

Why we built it

When you tune a PID by watching the robot you see the symptom. When you watch the error curve you see the cause: oscillation that doesn't decay means too much P and not enough D, a constant offset on curves means you might want some I. Ten seconds of chart tells you what an afternoon of test runs doesn't.

License

MIT