--- name: robotics-design-patterns description: > Architecture patterns, design principles, and proven recipes for building robust robotics software. Use this skill when designing robot software architectures, choosing between behavioral frameworks, structuring perception-planning-control pipelines, implementing state machines, designing safety systems, or architecting multi-robot systems. Trigger whenever the user mentions behavior trees, finite state machines, subsumption architecture, sensor fusion, robot safety, watchdogs, heartbeats, graceful degradation, hardware abstraction layers, real-time constraints, or software architecture for robots. Also applies to sim-to-real transfer, digital twins, and robot fleet management. ---

# Robotics Design Patterns

## When to Use This Skill - Designing robot software architecture from scratch - Choosing between behavior trees, FSMs, or hybrid approaches - Structuring perception → planning → control pipelines - Implementing safety systems and watchdogs - Building hardware abstraction layers (HAL) - Designing for sim-to-real transfer - Architecting multi-robot / fleet systems - Making real-time vs. non-real-time tradeoffs

## Pattern 1: The Robot Software Stack

Every robot system follows this layered architecture, regardless of complexity:

``` ┌─────────────────────────────────────────────┐ │ APPLICATION LAYER │ │ Mission planning, task allocation, UI │ ├─────────────────────────────────────────────┤ │ BEHAVIORAL LAYER │ │ Behavior trees, FSMs, decision-making │ ├─────────────────────────────────────────────┤ │ FUNCTIONAL LAYER │ │ Perception, Planning, Control, Estimation │ ├─────────────────────────────────────────────┤ │ COMMUNICATION LAYER │ │ ROS2, DDS, shared memory, IPC │ ├─────────────────────────────────────────────┤ │ HARDWARE ABSTRACTION LAYER │ │ Drivers, sensor interfaces, actuators │ ├─────────────────────────────────────────────┤ │ HARDWARE LAYER │ │ Cameras, LiDARs, motors, grippers, IMUs │ └─────────────────────────────────────────────┘ ```

**Design Rule**: Information flows UP through perception, decisions flow DOWN through control. Never let the application layer directly command hardware.

## Pattern 2: Behavior Trees (BT)

Behavior trees are the **recommended default** for robot decision-making. They're modular, reusable, and easier to debug than FSMs for complex behaviors.

### Core Node Types

``` Sequence (→) : Execute children left-to-right, FAIL on first failure Fallback (?) : Execute children left-to-right, SUCCEED on first success Parallel (⇉) : Execute all children simultaneously Decorator : Modify a single child's behavior Action (leaf) : Execute a robot action Condition (leaf) : Check a condition (no side effects) ```

### Example: Pick-and-Place BT

``` → Sequence / | \ → Check → Pick → Place / \ / | \ / | \ Battery Obj Open Move Close Move Open Release OK? Found? Grip To Grip To Grip per Obj per Goal per ```

### Implementation Pattern

```python import py_trees

class MoveToTarget(py_trees.behaviour.Behaviour): """Action node: Move robot to a target pose"""

def __init__(self, name, target_key="target_pose"): super().__init__(name) self.target_key = target_key self.action_client = None

def setup(self, **kwargs): """Called once when tree is set up — initialize resources""" self.node = kwargs.get('node') # ROS2 node self.action_client = ActionClient( self.node, MoveBase, 'move_base')

def initialise(self): """Called when this node first ticks — send the goal""" bb = self.blackboard target = bb.get(self.target_key) self.goal_handle = self.action_client.send_goal(target) self.logger.info(f"Moving to {target}")

def update(self): """Called every tick — check progress""" if self.goal_handle is None: return py_trees.common.Status.FAILURE

status = self.goal_handle.status if status == GoalStatus.STATUS_SUCCEEDED: return py_trees.common.Status.SUCCESS elif status == GoalStatus.STATUS_ABORTED: return py_trees.common.Status.FAILURE else: return py_trees.common.Status.RUNNING

def terminate(self, new_status): """Called when node exits — cancel if preempted""" if new_status == py_trees.common.Status.INVALID: if self.goal_handle: self.goal_handle.cancel_goal() self.logger.info("Movement cancelled")

# Build the tree def create_pick_place_tree(): root = py_trees.composites.Sequence("PickAndPlace", memory=True)

# Safety checks (Fallback: if any fails, abort) safety = py_trees.composites.Sequence("SafetyChecks", memory=False) safety.add_children([ CheckBattery("BatteryOK", threshold=20.0), CheckEStop("EStopClear"), ])

pick = py_trees.composites.Sequence("Pick", memory=True) pick.add_children([ DetectObject("FindObject"), MoveToTarget("ApproachObject", target_key="object_pose"), GripperCommand("CloseGripper", action="close"), ])

place = py_trees.composites.Sequence("Place", memory=True) place.add_children([ MoveToTarget("MoveToPlace", target_key="place_pose"), GripperCommand("OpenGripper", action="open"), ])

root.add_children([safety, pick, place]) return root ```

### Blackboard Pattern

```python # The Blackboard is the shared memory for BT nodes bb = py_trees.blackboard.Blackboard()

# Perception nodes WRITE to blackboard class DetectObject(py_trees.behaviour.Behaviour): def update(self): detections = self.perception.detect() if detections: self.blackboard.set("object_pose", detections[0].pose) self.blackboard.set("object_class", detections[0].label) return Status.SUCCESS return Status.FAILURE

# Action nodes READ from blackboard class MoveToTarget(py_trees.behaviour.Behaviour): def initialise(self): target = self.blackboard.get("object_pose") self.send_goal(target) ```

## Pattern 3: Finite State Machines (FSM)

Use FSMs for **simple, well-defined sequential behaviors** with clear states. Prefer BTs for anything complex.

```python from enum import Enum, auto import smach # ROS state machine library

class RobotState(Enum): IDLE = auto() NAVIGATING = auto() PICKING = auto() PLACING = auto() ERROR = auto() CHARGING = auto()

# SMACH implementation class NavigateState(smach.State): def __init__(self): smach.State.__init__(self, outcomes=['succeeded', 'aborted', 'preempted'], input_keys=['target_pose'], output_keys=['final_pose'])

def execute(self, userdata): # Navigation logic result = navigate_to(userdata.target_pose) if result.success: userdata.final_pose = result.pose return 'succeeded' return 'aborted'

# Build state machine sm = smach.StateMachine(outcomes=['done', 'failed']) with sm: smach.StateMachine.add('NAVIGATE', NavigateState(), transitions={'succeeded': 'PICK', 'aborted': 'ERROR'}) smach.StateMachine.add('PICK', PickState(), transitions={'succeeded': 'PLACE', 'aborted': 'ERROR'}) smach.StateMachine.add('PLACE', PlaceState(), transitions={'succeeded': 'done', 'aborted': 'ERROR'}) smach.StateMachine.add('ERROR', ErrorRecovery(), transitions={'recovered': 'NAVIGATE', 'fatal': 'failed'}) ```

**When to use FSM vs BT**: - FSM: Linear workflows, simple devices, UI states, protocol implementations - BT: Complex robots, reactive behaviors, many conditional branches, reusable sub-behaviors

## Pattern 4: Perception Pipeline

``` Raw Sensors → Preprocessing → Detection/Estimation → Fusion → World Model ```

### Sensor Fusion Architecture

```python class SensorFusion: """Multi-sensor fusion using a central world model"""

def __init__(self): self.world_model = WorldModel() self.filters = { 'pose': ExtendedKalmanFilter(state_dim=6), 'objects': MultiObjectTracker(), }

def update_from_camera(self, detections, timestamp): """Camera provides object detections with high latency""" for det in detections: self.filters['objects'].update( det, sensor='camera', uncertainty=det.confidence, timestamp=timestamp )

def update_from_lidar(self, points, timestamp): """LiDAR provides precise geometry with lower latency""" clusters = self.segment_points(points) for cluster in clusters: self.filters['objects'].update( cluster, sensor='lidar', uncertainty=0.02, # 2cm typical LiDAR accuracy timestamp=timestamp )

def update_from_imu(self, imu_data, timestamp): """IMU provides high-frequency attitude estimates""" self.filters['pose'].predict(imu_data, dt=timestamp - self.last_imu_t) self.last_imu_t = timestamp

def get_world_state(self): """Query the fused world model""" return WorldState( robot_pose=self.filters['pose'].state, objects=self.filters['objects'].get_tracked_objects(), confidence=self.filters['objects'].get_confidence_map() ) ```

### The Perception-Action Loop Timing

``` Camera (30Hz) ─┐ LiDAR (10Hz) ─┼──→ Fusion (50Hz) ──→ Planner (10Hz) ──→ Controller (100Hz+) IMU (200Hz) ─┘

RULE: Controller frequency > Planner frequency > Sensor frequency This ensures smooth execution despite variable perception latency. ```

## Pattern 5: Hardware Abstraction Layer (HAL)

**Never let application code talk directly to hardware.** Always go through an abstraction layer.

```python from abc import ABC, abstractmethod

class GripperInterface(ABC): """Abstract gripper interface — implement for each hardware type"""

@abstractmethod def open(self, width: float = 1.0) -> bool: ...

@abstractmethod def close(self, force: float = 0.5) -> bool: ...

@abstractmethod def get_state(self) -> GripperState: ...

@abstractmethod def get_width(self) -> float: ...

class RobotiqGripper(GripperInterface): """Concrete implementation for Robotiq 2F-85""" def __init__(self, port='/dev/ttyUSB0'): self.serial = serial.Serial(port, 115200) # ... Modbus RTU setup

def close(self, force=0.5): cmd = self._build_modbus_cmd(force=int(force * 255)) self.serial.write(cmd) return self._wait_for_completion()

class SimulatedGripper(GripperInterface): """Simulation gripper for testing""" def __init__(self): self.width = 0.085 # 85mm open self.state = GripperState.OPEN

def close(self, force=0.5): self.width = 0.0 self.state = GripperState.CLOSED return True

# Factory pattern for hardware instantiation def create_gripper(config: dict) -> GripperInterface: gripper_type = config.get('type', 'simulated') if gripper_type == 'robotiq': return RobotiqGripper(port=config['port']) elif gripper_type == 'simulated': return SimulatedGripper() else: raise ValueError(f"Unknown gripper type: {gripper_type}") ```

## Pattern 6: Safety Systems

### The Safety Hierarchy

``` Level 0: Hardware E-Stop (physical button, cuts power) Level 1: Safety-rated controller (SIL2/SIL3, hardware watchdog) Level 2: Software watchdog (moni

--- name: robotics-design-patterns description: > Architecture patterns, design principles, and proven recipes for building robust robotics software. Use this skill when designing robot software architectures, choosing between behavioral frameworks, structuring perception-planning-control pipelines, implementing state machines, designing safety systems, or architecting multi-robot systems. Trigger whenever the user mentions behavior trees, finite state machines, subsumption architecture, sensor fusion, robot safety, watchdogs, heartbeats, graceful degradation, hardware abstraction layers, real-time constraints, or software architecture for robots. Also applies to sim-to-real transfer, digital twins, and robot fleet management. ---

# Robotics Design Patterns

## When to Use This Skill - Designing robot software architecture from scratch - Choosing between behavior trees, FSMs, or hybrid approaches - Structuring perception → planning → control pipelines - Implementing safety systems and watchdogs - Building hardware abstraction layers (HAL) - Designing for sim-to-real transfer - Architecting multi-robot / fleet systems - Making real-time vs. non-real-time tradeoffs

## Pattern 1: The Robot Software Stack

Every robot system follows this layered architecture, regardless of complexity:

``` ┌─────────────────────────────────────────────┐ │ APPLICATION LAYER │ │ Mission planning, task allocation, UI │ ├─────────────────────────────────────────────┤ │ BEHAVIORAL LAYER │ │ Behavior trees, FSMs, decision-making │ ├─────────────────────────────────────────────┤ │ FUNCTIONAL LAYER │ │ Perception, Planning, Control, Estimation │ ├─────────────────────────────────────────────┤ │ COMMUNICATION LAYER │ │ ROS2, DDS, shared memory, IPC │ ├─────────────────────────────────────────────┤ │ HARDWARE ABSTRACTION LAYER │ │ Drivers, sensor interfaces, actuators │ ├─────────────────────────────────────────────┤ │ HARDWARE LAYER │ │ Cameras, LiDARs, motors, grippers, IMUs │ └─────────────────────────────────────────────┘ ```

**Design Rule**: Information flows UP through perception, decisions flow DOWN through control. Never let the application layer directly command hardware.

## Pattern 2: Behavior Trees (BT)

Behavior trees are the **recommended default** for robot decision-making. They're modular, reusable, and easier to debug than FSMs for complex behaviors.

### Core Node Types

``` Sequence (→) : Execute children left-to-right, FAIL on first failure Fallback (?) : Execute children left-to-right, SUCCEED on first success Parallel (⇉) : Execute all children simultaneously Decorator : Modify a single child's behavior Action (leaf) : Execute a robot action Condition (leaf) : Check a condition (no side effects) ```

### Example: Pick-and-Place BT

``` → Sequence / | \ → Check → Pick → Place / \ / | \ / | \ Battery Obj Open Move Close Move Open Release OK? Found? Grip To Grip To Grip per Obj per Goal per ```

### Implementation Pattern

```python import py_trees

class MoveToTarget(py_trees.behaviour.Behaviour): """Action node: Move robot to a target pose"""

def __init__(self, name, target_key="target_pose"): super().__init__(name) self.target_key = target_key self.action_client = None

def setup(self, **kwargs): """Called once when tree is set up — initialize resources""" self.node = kwargs.get('node') # ROS2 node self.action_client = ActionClient( self.node, MoveBase, 'move_base')

def initialise(self): """Called when this node first ticks — send the goal""" bb = self.blackboard target = bb.get(self.target_key) self.goal_handle = self.action_client.send_goal(target) self.logger.info(f"Moving to {target}")

def update(self): """Called every tick — check progress""" if self.goal_handle is None: return py_trees.common.Status.FAILURE

status = self.goal_handle.status if status == GoalStatus.STATUS_SUCCEEDED: return py_trees.common.Status.SUCCESS elif status == GoalStatus.STATUS_ABORTED: return py_trees.common.Status.FAILURE else: return py_trees.common.Status.RUNNING

def terminate(self, new_status): """Called when node exits — cancel if preempted""" if new_status == py_trees.common.Status.INVALID: if self.goal_handle: self.goal_handle.cancel_goal() self.logger.info("Movement cancelled")

# Build the tree def create_pick_place_tree(): root = py_trees.composites.Sequence("PickAndPlace", memory=True)

# Safety checks (Fallback: if any fails, abort) safety = py_trees.composites.Sequence("SafetyChecks", memory=False) safety.add_children([ CheckBattery("BatteryOK", threshold=20.0), CheckEStop("EStopClear"), ])

pick = py_trees.composites.Sequence("Pick", memory=True) pick.add_children([ DetectObject("FindObject"), MoveToTarget("ApproachObject", target_key="object_pose"), GripperCommand("CloseGripper", action="close"), ])

place = py_trees.composites.Sequence("Place", memory=True) place.add_children([ MoveToTarget("MoveToPlace", target_key="place_pose"), GripperCommand("OpenGripper", action="open"), ])

root.add_children([safety, pick, place]) return root ```

### Blackboard Pattern

```python # The Blackboard is the shared memory for BT nodes bb = py_trees.blackboard.Blackboard()

# Perception nodes WRITE to blackboard class DetectObject(py_trees.behaviour.Behaviour): def update(self): detections = self.perception.detect() if detections: self.blackboard.set("object_pose", detections[0].pose) self.blackboard.set("object_class", detections[0].label) return Status.SUCCESS return Status.FAILURE

# Action nodes READ from blackboard class MoveToTarget(py_trees.behaviour.Behaviour): def initialise(self): target = self.blackboard.get("object_pose") self.send_goal(target) ```

## Pattern 3: Finite State Machines (FSM)

Use FSMs for **simple, well-defined sequential behaviors** with clear states. Prefer BTs for anything complex.

```python from enum import Enum, auto import smach # ROS state machine library

class RobotState(Enum): IDLE = auto() NAVIGATING = auto() PICKING = auto() PLACING = auto() ERROR = auto() CHARGING = auto()

# SMACH implementation class NavigateState(smach.State): def __init__(self): smach.State.__init__(self, outcomes=['succeeded', 'aborted', 'preempted'], input_keys=['target_pose'], output_keys=['final_pose'])

def execute(self, userdata): # Navigation logic result = navigate_to(userdata.target_pose) if result.success: userdata.final_pose = result.pose return 'succeeded' return 'aborted'

# Build state machine sm = smach.StateMachine(outcomes=['done', 'failed']) with sm: smach.StateMachine.add('NAVIGATE', NavigateState(), transitions={'succeeded': 'PICK', 'aborted': 'ERROR'}) smach.StateMachine.add('PICK', PickState(), transitions={'succeeded': 'PLACE', 'aborted': 'ERROR'}) smach.StateMachine.add('PLACE', PlaceState(), transitions={'succeeded': 'done', 'aborted': 'ERROR'}) smach.StateMachine.add('ERROR', ErrorRecovery(), transitions={'recovered': 'NAVIGATE', 'fatal': 'failed'}) ```

**When to use FSM vs BT**: - FSM: Linear workflows, simple devices, UI states, protocol implementations - BT: Complex robots, reactive behaviors, many conditional branches, reusable sub-behaviors

## Pattern 4: Perception Pipeline

``` Raw Sensors → Preprocessing → Detection/Estimation → Fusion → World Model ```

### Sensor Fusion Architecture

```python class SensorFusion: """Multi-sensor fusion using a central world model"""

def __init__(self): self.world_model = WorldModel() self.filters = { 'pose': ExtendedKalmanFilter(state_dim=6), 'objects': MultiObjectTracker(), }

def update_from_camera(self, detections, timestamp): """Camera provides object detections with high latency""" for det in detections: self.filters['objects'].update( det, sensor='camera', uncertainty=det.confidence, timestamp=timestamp )

def update_from_lidar(self, points, timestamp): """LiDAR provides precise geometry with lower latency""" clusters = self.segment_points(points) for cluster in clusters: self.filters['objects'].update( cluster, sensor='lidar', uncertainty=0.02, # 2cm typical LiDAR accuracy timestamp=timestamp )

def update_from_imu(self, imu_data, timestamp): """IMU provides high-frequency attitude estimates""" self.filters['pose'].predict(imu_data, dt=timestamp - self.last_imu_t) self.last_imu_t = timestamp

def get_world_state(self): """Query the fused world model""" return WorldState( robot_pose=self.filters['pose'].state, objects=self.filters['objects'].get_tracked_objects(), confidence=self.filters['objects'].get_confidence_map() ) ```

### The Perception-Action Loop Timing

``` Camera (30Hz) ─┐ LiDAR (10Hz) ─┼──→ Fusion (50Hz) ──→ Planner (10Hz) ──→ Controller (100Hz+) IMU (200Hz) ─┘

RULE: Controller frequency > Planner frequency > Sensor frequency This ensures smooth execution despite variable perception latency. ```

## Pattern 5: Hardware Abstraction Layer (HAL)

**Never let application code talk directly to hardware.** Always go through an abstraction layer.

```python from abc import ABC, abstractmethod

class GripperInterface(ABC): """Abstract gripper interface — implement for each hardware type"""

@abstractmethod def open(self, width: float = 1.0) -> bool: ...

@abstractmethod def close(self, force: float = 0.5) -> bool: ...

@abstractmethod def get_state(self) -> GripperState: ...

@abstractmethod def get_width(self) -> float: ...

class RobotiqGripper(GripperInterface): """Concrete implementation for Robotiq 2F-85""" def __init__(self, port='/dev/ttyUSB0'): self.serial = serial.Serial(port, 115200) # ... Modbus RTU setup

def close(self, force=0.5): cmd = self._build_modbus_cmd(force=int(force * 255)) self.serial.write(cmd) return self._wait_for_completion()

class SimulatedGripper(GripperInterface): """Simulation gripper for testing""" def __init__(self): self.width = 0.085 # 85mm open self.state = GripperState.OPEN

def close(self, force=0.5): self.width = 0.0 self.state = GripperState.CLOSED return True

# Factory pattern for hardware instantiation def create_gripper(config: dict) -> GripperInterface: gripper_type = config.get('type', 'simulated') if gripper_type == 'robotiq': return RobotiqGripper(port=config['port']) elif gripper_type == 'simulated': return SimulatedGripper() else: raise ValueError(f"Unknown gripper type: {gripper_type}") ```

## Pattern 6: Safety Systems

### The Safety Hierarchy

``` Level 0: Hardware E-Stop (physical button, cuts power) Level 1: Safety-rated controller (SIL2/SIL3, hardware watchdog) Level 2: Software watchdog (moni

--- name: robotics-design-patterns description: > Architecture patterns, design principles, and proven recipes for building robust robotics software. Use this skill when designing robot software architectures, choosing between behavioral frameworks, structuring perception-planning-control pipelines, implementing state machines, designing safety systems, or architecting multi-robot systems. Trigger whenever the user mentions behavior trees, finite state machines, subsumption architecture, sensor fusion, robot safety, watchdogs, heartbeats, graceful degradation, hardware abstraction layers, real-time constraints, or software architecture for robots. Also applies to sim-to-real transfer, digital twins, and robot fleet management. ---

# Robotics Design Patterns

## When to Use This Skill - Designing robot software architecture from scratch - Choosing between behavior trees, FSMs, or hybrid approaches - Structuring perception → planning → control pipelines - Implementing safety systems and watchdogs - Building hardware abstraction layers (HAL) - Designing for sim-to-real transfer - Architecting multi-robot / fleet systems - Making real-time vs. non-real-time tradeoffs

## Pattern 1: The Robot Software Stack

Every robot system follows this layered architecture, regardless of complexity:

``` ┌─────────────────────────────────────────────┐ │ APPLICATION LAYER │ │ Mission planning, task allocation, UI │ ├─────────────────────────────────────────────┤ │ BEHAVIORAL LAYER │ │ Behavior trees, FSMs, decision-making │ ├─────────────────────────────────────────────┤ │ FUNCTIONAL LAYER │ │ Perception, Planning, Control, Estimation │ ├─────────────────────────────────────────────┤ │ COMMUNICATION LAYER │ │ ROS2, DDS, shared memory, IPC │ ├─────────────────────────────────────────────┤ │ HARDWARE ABSTRACTION LAYER │ │ Drivers, sensor interfaces, actuators │ ├─────────────────────────────────────────────┤ │ HARDWARE LAYER │ │ Cameras, LiDARs, motors, grippers, IMUs │ └─────────────────────────────────────────────┘ ```

**Design Rule**: Information flows UP through perception, decisions flow DOWN through control. Never let the application layer directly command hardware.

## Pattern 2: Behavior Trees (BT)

Behavior trees are the **recommended default** for robot decision-making. They're modular, reusable, and easier to debug than FSMs for complex behaviors.

### Core Node Types

``` Sequence (→) : Execute children left-to-right, FAIL on first failure Fallback (?) : Execute children left-to-right, SUCCEED on first success Parallel (⇉) : Execute all children simultaneously Decorator : Modify a single child's behavior Action (leaf) : Execute a robot action Condition (leaf) : Check a condition (no side effects) ```

### Example: Pick-and-Place BT

``` → Sequence / | \ → Check → Pick → Place / \ / | \ / | \ Battery Obj Open Move Close Move Open Release OK? Found? Grip To Grip To Grip per Obj per Goal per ```

### Implementation Pattern

```python import py_trees

class MoveToTarget(py_trees.behaviour.Behaviour): """Action node: Move robot to a target pose"""

def __init__(self, name, target_key="target_pose"): super().__init__(name) self.target_key = target_key self.action_client = None

def setup(self, **kwargs): """Called once when tree is set up — initialize resources""" self.node = kwargs.get('node') # ROS2 node self.action_client = ActionClient( self.node, MoveBase, 'move_base')

def initialise(self): """Called when this node first ticks — send the goal""" bb = self.blackboard target = bb.get(self.target_key) self.goal_handle = self.action_client.send_goal(target) self.logger.info(f"Moving to {target}")

def update(self): """Called every tick — check progress""" if self.goal_handle is None: return py_trees.common.Status.FAILURE

status = self.goal_handle.status if status == GoalStatus.STATUS_SUCCEEDED: return py_trees.common.Status.SUCCESS elif status == GoalStatus.STATUS_ABORTED: return py_trees.common.Status.FAILURE else: return py_trees.common.Status.RUNNING

def terminate(self, new_status): """Called when node exits — cancel if preempted""" if new_status == py_trees.common.Status.INVALID: if self.goal_handle: self.goal_handle.cancel_goal() self.logger.info("Movement cancelled")

# Build the tree def create_pick_place_tree(): root = py_trees.composites.Sequence("PickAndPlace", memory=True)

# Safety checks (Fallback: if any fails, abort) safety = py_trees.composites.Sequence("SafetyChecks", memory=False) safety.add_children([ CheckBattery("BatteryOK", threshold=20.0), CheckEStop("EStopClear"), ])

pick = py_trees.composites.Sequence("Pick", memory=True) pick.add_children([ DetectObject("FindObject"), MoveToTarget("ApproachObject", target_key="object_pose"), GripperCommand("CloseGripper", action="close"), ])

place = py_trees.composites.Sequence("Place", memory=True) place.add_children([ MoveToTarget("MoveToPlace", target_key="place_pose"), GripperCommand("OpenGripper", action="open"), ])

root.add_children([safety, pick, place]) return root ```

### Blackboard Pattern

```python # The Blackboard is the shared memory for BT nodes bb = py_trees.blackboard.Blackboard()

# Perception nodes WRITE to blackboard class DetectObject(py_trees.behaviour.Behaviour): def update(self): detections = self.perception.detect() if detections: self.blackboard.set("object_pose", detections[0].pose) self.blackboard.set("object_class", detections[0].label) return Status.SUCCESS return Status.FAILURE

# Action nodes READ from blackboard class MoveToTarget(py_trees.behaviour.Behaviour): def initialise(self): target = self.blackboard.get("object_pose") self.send_goal(target) ```

## Pattern 3: Finite State Machines (FSM)

Use FSMs for **simple, well-defined sequential behaviors** with clear states. Prefer BTs for anything complex.

```python from enum import Enum, auto import smach # ROS state machine library

class RobotState(Enum): IDLE = auto() NAVIGATING = auto() PICKING = auto() PLACING = auto() ERROR = auto() CHARGING = auto()

# SMACH implementation class NavigateState(smach.State): def __init__(self): smach.State.__init__(self, outcomes=['succeeded', 'aborted', 'preempted'], input_keys=['target_pose'], output_keys=['final_pose'])

def execute(self, userdata): # Navigation logic result = navigate_to(userdata.target_pose) if result.success: userdata.final_pose = result.pose return 'succeeded' return 'aborted'

# Build state machine sm = smach.StateMachine(outcomes=['done', 'failed']) with sm: smach.StateMachine.add('NAVIGATE', NavigateState(), transitions={'succeeded': 'PICK', 'aborted': 'ERROR'}) smach.StateMachine.add('PICK', PickState(), transitions={'succeeded': 'PLACE', 'aborted': 'ERROR'}) smach.StateMachine.add('PLACE', PlaceState(), transitions={'succeeded': 'done', 'aborted': 'ERROR'}) smach.StateMachine.add('ERROR', ErrorRecovery(), transitions={'recovered': 'NAVIGATE', 'fatal': 'failed'}) ```

**When to use FSM vs BT**: - FSM: Linear workflows, simple devices, UI states, protocol implementations - BT: Complex robots, reactive behaviors, many conditional branches, reusable sub-behaviors

## Pattern 4: Perception Pipeline

``` Raw Sensors → Preprocessing → Detection/Estimation → Fusion → World Model ```

### Sensor Fusion Architecture

```python class SensorFusion: """Multi-sensor fusion using a central world model"""

def __init__(self): self.world_model = WorldModel() self.filters = { 'pose': ExtendedKalmanFilter(state_dim=6), 'objects': MultiObjectTracker(), }

def update_from_camera(self, detections, timestamp): """Camera provides object detections with high latency""" for det in detections: self.filters['objects'].update( det, sensor='camera', uncertainty=det.confidence, timestamp=timestamp )

def update_from_lidar(self, points, timestamp): """LiDAR provides precise geometry with lower latency""" clusters = self.segment_points(points) for cluster in clusters: self.filters['objects'].update( cluster, sensor='lidar', uncertainty=0.02, # 2cm typical LiDAR accuracy timestamp=timestamp )

def update_from_imu(self, imu_data, timestamp): """IMU provides high-frequency attitude estimates""" self.filters['pose'].predict(imu_data, dt=timestamp - self.last_imu_t) self.last_imu_t = timestamp

def get_world_state(self): """Query the fused world model""" return WorldState( robot_pose=self.filters['pose'].state, objects=self.filters['objects'].get_tracked_objects(), confidence=self.filters['objects'].get_confidence_map() ) ```

### The Perception-Action Loop Timing

``` Camera (30Hz) ─┐ LiDAR (10Hz) ─┼──→ Fusion (50Hz) ──→ Planner (10Hz) ──→ Controller (100Hz+) IMU (200Hz) ─┘

RULE: Controller frequency > Planner frequency > Sensor frequency This ensures smooth execution despite variable perception latency. ```

## Pattern 5: Hardware Abstraction Layer (HAL)

**Never let application code talk directly to hardware.** Always go through an abstraction layer.

```python from abc import ABC, abstractmethod

class GripperInterface(ABC): """Abstract gripper interface — implement for each hardware type"""

@abstractmethod def open(self, width: float = 1.0) -> bool: ...

@abstractmethod def close(self, force: float = 0.5) -> bool: ...

@abstractmethod def get_state(self) -> GripperState: ...

@abstractmethod def get_width(self) -> float: ...

class RobotiqGripper(GripperInterface): """Concrete implementation for Robotiq 2F-85""" def __init__(self, port='/dev/ttyUSB0'): self.serial = serial.Serial(port, 115200) # ... Modbus RTU setup

def close(self, force=0.5): cmd = self._build_modbus_cmd(force=int(force * 255)) self.serial.write(cmd) return self._wait_for_completion()

class SimulatedGripper(GripperInterface): """Simulation gripper for testing""" def __init__(self): self.width = 0.085 # 85mm open self.state = GripperState.OPEN

def close(self, force=0.5): self.width = 0.0 self.state = GripperState.CLOSED return True

# Factory pattern for hardware instantiation def create_gripper(config: dict) -> GripperInterface: gripper_type = config.get('type', 'simulated') if gripper_type == 'robotiq': return RobotiqGripper(port=config['port']) elif gripper_type == 'simulated': return SimulatedGripper() else: raise ValueError(f"Unknown gripper type: {gripper_type}") ```

## Pattern 6: Safety Systems

### The Safety Hierarchy

``` Level 0: Hardware E-Stop (physical button, cuts power) Level 1: Safety-rated controller (SIL2/SIL3, hardware watchdog) Level 2: Software watchdog (moni

--- name: robotics-design-patterns description: > Architecture patterns, design principles, and proven recipes for building robust robotics software. Use this skill when designing robot software architectures, choosing between behavioral frameworks, structuring perception-planning-control pipelines, implementing state machines, designing safety systems, or architecting multi-robot systems. Trigger whenever the user mentions behavior trees, finite state machines, subsumption architecture, sensor fusion, robot safety, watchdogs, heartbeats, graceful degradation, hardware abstraction layers, real-time constraints, or software architecture for robots. Also applies to sim-to-real transfer, digital twins, and robot fleet management. ---

# Robotics Design Patterns

## When to Use This Skill - Designing robot software architecture from scratch - Choosing between behavior trees, FSMs, or hybrid approaches - Structuring perception → planning → control pipelines - Implementing safety systems and watchdogs - Building hardware abstraction layers (HAL) - Designing for sim-to-real transfer - Architecting multi-robot / fleet systems - Making real-time vs. non-real-time tradeoffs

## Pattern 1: The Robot Software Stack

Every robot system follows this layered architecture, regardless of complexity:

``` ┌─────────────────────────────────────────────┐ │ APPLICATION LAYER │ │ Mission planning, task allocation, UI │ ├─────────────────────────────────────────────┤ │ BEHAVIORAL LAYER │ │ Behavior trees, FSMs, decision-making │ ├─────────────────────────────────────────────┤ │ FUNCTIONAL LAYER │ │ Perception, Planning, Control, Estimation │ ├─────────────────────────────────────────────┤ │ COMMUNICATION LAYER │ │ ROS2, DDS, shared memory, IPC │ ├─────────────────────────────────────────────┤ │ HARDWARE ABSTRACTION LAYER │ │ Drivers, sensor interfaces, actuators │ ├─────────────────────────────────────────────┤ │ HARDWARE LAYER │ │ Cameras, LiDARs, motors, grippers, IMUs │ └─────────────────────────────────────────────┘ ```

**Design Rule**: Information flows UP through perception, decisions flow DOWN through control. Never let the application layer directly command hardware.

## Pattern 2: Behavior Trees (BT)

Behavior trees are the **recommended default** for robot decision-making. They're modular, reusable, and easier to debug than FSMs for complex behaviors.

### Core Node Types

``` Sequence (→) : Execute children left-to-right, FAIL on first failure Fallback (?) : Execute children left-to-right, SUCCEED on first success Parallel (⇉) : Execute all children simultaneously Decorator : Modify a single child's behavior Action (leaf) : Execute a robot action Condition (leaf) : Check a condition (no side effects) ```

### Example: Pick-and-Place BT

``` → Sequence / | \ → Check → Pick → Place / \ / | \ / | \ Battery Obj Open Move Close Move Open Release OK? Found? Grip To Grip To Grip per Obj per Goal per ```

### Implementation Pattern

```python import py_trees

class MoveToTarget(py_trees.behaviour.Behaviour): """Action node: Move robot to a target pose"""

def __init__(self, name, target_key="target_pose"): super().__init__(name) self.target_key = target_key self.action_client = None

def setup(self, **kwargs): """Called once when tree is set up — initialize resources""" self.node = kwargs.get('node') # ROS2 node self.action_client = ActionClient( self.node, MoveBase, 'move_base')

def initialise(self): """Called when this node first ticks — send the goal""" bb = self.blackboard target = bb.get(self.target_key) self.goal_handle = self.action_client.send_goal(target) self.logger.info(f"Moving to {target}")

def update(self): """Called every tick — check progress""" if self.goal_handle is None: return py_trees.common.Status.FAILURE

status = self.goal_handle.status if status == GoalStatus.STATUS_SUCCEEDED: return py_trees.common.Status.SUCCESS elif status == GoalStatus.STATUS_ABORTED: return py_trees.common.Status.FAILURE else: return py_trees.common.Status.RUNNING

def terminate(self, new_status): """Called when node exits — cancel if preempted""" if new_status == py_trees.common.Status.INVALID: if self.goal_handle: self.goal_handle.cancel_goal() self.logger.info("Movement cancelled")

# Build the tree def create_pick_place_tree(): root = py_trees.composites.Sequence("PickAndPlace", memory=True)

# Safety checks (Fallback: if any fails, abort) safety = py_trees.composites.Sequence("SafetyChecks", memory=False) safety.add_children([ CheckBattery("BatteryOK", threshold=20.0), CheckEStop("EStopClear"), ])

pick = py_trees.composites.Sequence("Pick", memory=True) pick.add_children([ DetectObject("FindObject"), MoveToTarget("ApproachObject", target_key="object_pose"), GripperCommand("CloseGripper", action="close"), ])

place = py_trees.composites.Sequence("Place", memory=True) place.add_children([ MoveToTarget("MoveToPlace", target_key="place_pose"), GripperCommand("OpenGripper", action="open"), ])

root.add_children([safety, pick, place]) return root ```

### Blackboard Pattern

```python # The Blackboard is the shared memory for BT nodes bb = py_trees.blackboard.Blackboard()

# Perception nodes WRITE to blackboard class DetectObject(py_trees.behaviour.Behaviour): def update(self): detections = self.perception.detect() if detections: self.blackboard.set("object_pose", detections[0].pose) self.blackboard.set("object_class", detections[0].label) return Status.SUCCESS return Status.FAILURE

# Action nodes READ from blackboard class MoveToTarget(py_trees.behaviour.Behaviour): def initialise(self): target = self.blackboard.get("object_pose") self.send_goal(target) ```

## Pattern 3: Finite State Machines (FSM)

Use FSMs for **simple, well-defined sequential behaviors** with clear states. Prefer BTs for anything complex.

```python from enum import Enum, auto import smach # ROS state machine library

class RobotState(Enum): IDLE = auto() NAVIGATING = auto() PICKING = auto() PLACING = auto() ERROR = auto() CHARGING = auto()

# SMACH implementation class NavigateState(smach.State): def __init__(self): smach.State.__init__(self, outcomes=['succeeded', 'aborted', 'preempted'], input_keys=['target_pose'], output_keys=['final_pose'])

def execute(self, userdata): # Navigation logic result = navigate_to(userdata.target_pose) if result.success: userdata.final_pose = result.pose return 'succeeded' return 'aborted'

# Build state machine sm = smach.StateMachine(outcomes=['done', 'failed']) with sm: smach.StateMachine.add('NAVIGATE', NavigateState(), transitions={'succeeded': 'PICK', 'aborted': 'ERROR'}) smach.StateMachine.add('PICK', PickState(), transitions={'succeeded': 'PLACE', 'aborted': 'ERROR'}) smach.StateMachine.add('PLACE', PlaceState(), transitions={'succeeded': 'done', 'aborted': 'ERROR'}) smach.StateMachine.add('ERROR', ErrorRecovery(), transitions={'recovered': 'NAVIGATE', 'fatal': 'failed'}) ```

**When to use FSM vs BT**: - FSM: Linear workflows, simple devices, UI states, protocol implementations - BT: Complex robots, reactive behaviors, many conditional branches, reusable sub-behaviors

## Pattern 4: Perception Pipeline

``` Raw Sensors → Preprocessing → Detection/Estimation → Fusion → World Model ```

### Sensor Fusion Architecture

```python class SensorFusion: """Multi-sensor fusion using a central world model"""

def __init__(self): self.world_model = WorldModel() self.filters = { 'pose': ExtendedKalmanFilter(state_dim=6), 'objects': MultiObjectTracker(), }

def update_from_camera(self, detections, timestamp): """Camera provides object detections with high latency""" for det in detections: self.filters['objects'].update( det, sensor='camera', uncertainty=det.confidence, timestamp=timestamp )

def update_from_lidar(self, points, timestamp): """LiDAR provides precise geometry with lower latency""" clusters = self.segment_points(points) for cluster in clusters: self.filters['objects'].update( cluster, sensor='lidar', uncertainty=0.02, # 2cm typical LiDAR accuracy timestamp=timestamp )

def update_from_imu(self, imu_data, timestamp): """IMU provides high-frequency attitude estimates""" self.filters['pose'].predict(imu_data, dt=timestamp - self.last_imu_t) self.last_imu_t = timestamp

def get_world_state(self): """Query the fused world model""" return WorldState( robot_pose=self.filters['pose'].state, objects=self.filters['objects'].get_tracked_objects(), confidence=self.filters['objects'].get_confidence_map() ) ```

### The Perception-Action Loop Timing

``` Camera (30Hz) ─┐ LiDAR (10Hz) ─┼──→ Fusion (50Hz) ──→ Planner (10Hz) ──→ Controller (100Hz+) IMU (200Hz) ─┘

RULE: Controller frequency > Planner frequency > Sensor frequency This ensures smooth execution despite variable perception latency. ```

## Pattern 5: Hardware Abstraction Layer (HAL)

**Never let application code talk directly to hardware.** Always go through an abstraction layer.

```python from abc import ABC, abstractmethod

class GripperInterface(ABC): """Abstract gripper interface — implement for each hardware type"""

@abstractmethod def open(self, width: float = 1.0) -> bool: ...

@abstractmethod def close(self, force: float = 0.5) -> bool: ...

@abstractmethod def get_state(self) -> GripperState: ...

@abstractmethod def get_width(self) -> float: ...

class RobotiqGripper(GripperInterface): """Concrete implementation for Robotiq 2F-85""" def __init__(self, port='/dev/ttyUSB0'): self.serial = serial.Serial(port, 115200) # ... Modbus RTU setup

def close(self, force=0.5): cmd = self._build_modbus_cmd(force=int(force * 255)) self.serial.write(cmd) return self._wait_for_completion()

class SimulatedGripper(GripperInterface): """Simulation gripper for testing""" def __init__(self): self.width = 0.085 # 85mm open self.state = GripperState.OPEN

def close(self, force=0.5): self.width = 0.0 self.state = GripperState.CLOSED return True

# Factory pattern for hardware instantiation def create_gripper(config: dict) -> GripperInterface: gripper_type = config.get('type', 'simulated') if gripper_type == 'robotiq': return RobotiqGripper(port=config['port']) elif gripper_type == 'simulated': return SimulatedGripper() else: raise ValueError(f"Unknown gripper type: {gripper_type}") ```

## Pattern 6: Safety Systems

### The Safety Hierarchy

``` Level 0: Hardware E-Stop (physical button, cuts power) Level 1: Safety-rated controller (SIL2/SIL3, hardware watchdog) Level 2: Software watchdog (moni