Robotics Control Lab

Testable reference implementations for two control problems from student robotics prototypes: range-sensor obstacle avoidance and gyroscope-driven self-balancing control for a two-wheel robot.

Problem

Hardware demos are difficult for reviewers to reproduce. This repository extracts the controller logic from the prototype context and puts it behind deterministic simulations, tests, and machine-readable outputs.

Architecture

flowchart LR
    A["Left, front, right range sensors"] --> B["Avoidance state machine"]
    B --> C["Linear and angular command"]
    D["Gyroscope tilt estimate"] --> E["PID with anti-windup"]
    E --> F["Motor torque command"]
    F --> G["Low-order balance model"]
    G --> D

Loading

Obstacle Avoidance

The controller uses stop/release hysteresis to prevent rapid state changes near a distance threshold. It turns toward the side with more clearance and reverses when all three directions are blocked.

Self-Balancing

The balance loop uses a limited PID controller with integral anti-windup. A disclosed low-order unstable pendulum model provides a reproducible software test; it is not presented as a high-fidelity digital twin of the original robot.

Reproducible Simulation Result

With the default model, controller, 10 ms timestep, and initial lean of 0.18 rad:

• final absolute angle is below 0.005 rad;
• the response remains within +/-0.02 rad after 0.65 seconds;
• commanded torque remains within the configured +/-10 limit.

These are simulation checks enforced by tests. They are not fabricated hardware measurements.

Run

python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
robotics-control-lab --csv outputs/balance_response.csv

Generate the response plot:

python -m pip install -e '.[plot]'
robotics-control-lab \
  --csv outputs/balance_response.csv \
  --plot docs/balance-response.png

Tech Stack

Python, PID control, finite-state control, numerical simulation, pytest, Ruff, Matplotlib, and GitHub Actions.

Hardware Integration

The controller interfaces are deliberately small. A hardware adapter should:

1. convert ultrasonic or ToF readings into RangeScan values in meters;
2. convert IMU orientation into a signed tilt error in radians;
3. map normalized linear/angular commands or torque into motor-driver outputs;
4. add watchdog, emergency-stop, saturation, and sensor-validity handling.

Limitations

• The balance model omits wheel slip, backlash, battery sag, sensor delay, and chassis parameter identification.
• Controller gains require system identification and safe retuning before use on physical hardware.
• This software must not be used as the only safety layer on a robot.

License

MIT