robotics-software-principles

Robotics Software Design Principles

Why Robotics Software Is Different

Robotics code operates under constraints that most software never faces:

1. Physical consequences — A bug doesn't just crash a process, it crashes a robot into a wall
2. Real-time deadlines — Missing a 1ms control loop deadline can cause oscillation or damage
3. Sensor uncertainty — All inputs are noisy, delayed, and occasionally wrong
4. Hardware diversity — Same algorithm must work on 10 different grippers from 5 vendors
5. Sim-to-real gap — Code must run identically in simulation and on real hardware
6. Long-running operation — Robots run for hours/days; memory leaks and drift matter
7. Safety criticality — Some failures must NEVER happen, regardless of software state

These constraints demand disciplined design. Below are principles that account for them.

Principle 1: Single Responsibility — One Module, One Job

Every module (node, class, function) should have exactly ONE reason to change.

Why it matters in robotics: A perception module that also does control means a camera driver update can break your arm controller. In safety-critical systems, this coupling is unacceptable.

# ❌ BAD: God module — perception + planning + control + logging
class RobotController:
    def __init__(self):
        self.camera = RealSenseCamera()
        self.detector = YOLODetector()
        self.planner = RRTPlanner()
        self.arm = UR5Driver()
        self.logger = DataLogger()

    def run(self):
        image = self.camera.capture()
        objects = self.detector.detect(image)
        path = self.planner.plan(objects[0].pose)
        self.arm.execute(path)
        self.logger.log(image, objects, path)
        # If ANY of these changes, you touch this class

# ✅ GOOD: Separated responsibilities with clear interfaces
class PerceptionModule:
    """ONLY responsibility: raw sensor data → detected objects"""
    def __init__(self, camera: CameraInterface, detector: DetectorInterface):
        self.camera = camera
        self.detector = detector

    def get_detections(self) -> List[Detection]:
        image = self.camera.capture()
        return self.detector.detect(image)

class PlanningModule:
    """ONLY responsibility: goal + world state → trajectory"""
    def __init__(self, planner: PlannerInterface):
        self.planner = planner

    def plan_to(self, target: Pose, obstacles: List[Obstacle]) -> Trajectory:
        return self.planner.plan(target, obstacles)

class ExecutionModule:
    """ONLY responsibility: trajectory → hardware commands"""
    def __init__(self, arm: ArmInterface):
        self.arm = arm

    def execute(self, trajectory: Trajectory) -> ExecutionResult:
        return self.arm.follow_trajectory(trajectory)