astra_controller - dingdongdengdong/astra_ws GitHub Wiki

Astra Controller Documentation

Component Documentation

Core Controllers

Motion Planning & Control

Perception & Interface

Main Controller

Documentation Structure

Each component's documentation follows this standard structure:

  1. Class Structure

    • Class diagrams showing attributes and methods
    • Relationships between classes

  2. Component Interaction

    • Flowcharts showing internal components
    • External interfaces and dependencies
    • Data flow between components

  3. Control/Data Flow

    • Sequence diagrams for main operations
    • State machines for component lifecycle
    • Processing pipelines where applicable

  4. Configuration

    • Parameter diagrams and descriptions
    • Default values and valid ranges
    • Configuration file formats

  5. Topics & Services

    • Published Topics
    • Subscribed Topics
    • Service Definitions
    • Message Types

  6. Error Handling

    • Error types and recovery
    • Safety measures
    • Fault tolerance

  7. Dependencies

    • ROS2 Package Dependencies
    • Python Library Dependencies
    • Version Requirements

  8. Notes & Features

    • Key Capabilities
    • Implementation Details
    • Usage Guidelines

Style Guide

Mermaid Diagrams

  1. Class Diagrams
classDiagram
    class Example {
        -private_attr
        +public_attr
        +public_method()
        -private_method()
    }
Loading
  1. Flowcharts
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Alternative]
Loading
  1. State Machines
stateDiagram-v2
    [*] --> State1
    State1 --> State2: Event
    State2 --> [*]: End
Loading

Color Schemes

  • Internal Components: fill:#bbf
  • External Interfaces: fill:#fbb
  • Data/Topics: fill:#fbf

Parameter Documentation

parameter_name:
  type: <data_type>
  default: <default_value>
  description: >
    Detailed description of the parameter's
    purpose and usage.

Cross-Component Interactions

System Overview

graph TD
    AC[Arm Controller] --> IK[IK Node]
    IK --> MR[MoveIt Relay]
    TW[Teleop Web] --> AC
    CN[Camera Node] --> TW
    HC[Head Controller] --> TW
    LC[Lift Controller] --> TW
    BC[Base Controller] --> TW
    
    subgraph Control Flow
        AC & HC & LC & BC
    end
    
    subgraph Planning
        IK & MR
    end
    
    subgraph Interface
        TW & CN
    end
    
    style Control Flow fill:#bbf
    style Planning fill:#fbf
    style Interface fill:#fbb
Loading

Data Flow Architecture

flowchart TD
    subgraph User Interface
        TW[Teleop Web]
        TN[Teleop Node]
    end

    subgraph Perception
        CN[Camera Node]
        subgraph Image Pipeline
            IR[Image Reception]
            IP[Image Processing]
            IS[Image Streaming]
        end
    end

    subgraph Motion Planning
        IK[IK Node]
        MR[MoveIt Relay]
        DR[Dry Run Node]
    end

    subgraph Controllers
        AC[Arm Controller]
        HC[Head Controller]
        LC[Lift Controller]
        BC[Base Controller]
    end

    TW & TN -->|Commands| Controllers
    CN -->|Video Feed| TW
    Controllers -->|State| TW & TN
    Controllers -->|Joint States| IK
    IK -->|Solutions| MR
    MR -->|Trajectories| DR
    DR -->|Validated Trajectories| Controllers

    style User Interface fill:#bbf,stroke:#333,stroke-width:2px
    style Perception fill:#fbb,stroke:#333,stroke-width:2px
    style Motion Planning fill:#fbf,stroke:#333,stroke-width:2px
    style Controllers fill:#bfb,stroke:#333,stroke-width:2px
Loading

Message Topics Flow

flowchart LR
    subgraph Commands
        direction TB
        CMD1[/cmd_joint/]
        CMD2[/cmd_pose/]
        CMD3[/cmd_vel/]
    end

    subgraph States
        direction TB
        ST1[/joint_states/]
        ST2[/robot_state/]
        ST3[/tf/]
    end

    subgraph Planning
        direction TB
        PL1[/trajectory/]
        PL2[/plan_motion/]
        PL3[/compute_ik/]
    end

    subgraph Sensors
        direction TB
        SN1[/camera/image_raw/]
        SN2[/camera/info/]
    end

    TW[Teleop Web] --> CMD1 & CMD2 & CMD3
    CN[Camera Node] --> SN1 & SN2
    IK[IK Node] --> PL3
    MR[MoveIt Relay] --> PL1 & PL2
    AC[Arm Controller] --> ST1 & ST2 & ST3

    style Commands fill:#bbf
    style States fill:#fbb
    style Planning fill:#fbf
    style Sensors fill:#bfb
Loading

Control Hierarchy

graph TD
    subgraph HighLevelControl
        AST[Astra Controller]
        TW[Teleop Web]
        MR[MoveIt Relay]
    end

    subgraph MidLevelControl
        IK[IK Node]
        DR[Dry Run]
        CN[Camera Node]
    end

    subgraph LowLevelControl
        AC[Arm Controller]
        HC[Head Controller]
        LC[Lift Controller]
        BC[Base Controller]
    end

    AST -->|Commands| MidLevelControl
    TW -->|User Input| AST
    MR -->|Plans| AST
    MidLevelControl -->|Processed Commands| LowLevelControl
    LowLevelControl -->|Feedback| AST

    style AST fill:#bbf
    style TW fill:#bbf
    style MR fill:#bbf

    style IK fill:#fbf
    style DR fill:#fbf
    style CN fill:#fbf

    style AC fill:#fbb
    style HC fill:#fbb
    style LC fill:#fbb
    style BC fill:#fbb
Loading

Safety and Error Handling

flowchart TD
    subgraph SafetyMonitors
        SM1[Arm Safety]
        SM2[Head Safety]
        SM3[Lift Safety]
        SM4[Base Safety]
    end

    subgraph ErrorHandlers
        EH1[Joint Limits]
        EH2[Collision]
        EH3[Velocity]
        EH4[Hardware]
    end

    subgraph EmergencySystems
        ES1[E-Stop]
        ES2[Safe State]
        ES3[Recovery]
    end

    Controllers -->|State| SafetyMonitors
    SafetyMonitors -->|Violations| ErrorHandlers
    ErrorHandlers -->|Critical| EmergencySystems
    EmergencySystems -->|Commands| Controllers

    style SM1 fill:#bbf
    style SM2 fill:#bbf
    style SM3 fill:#bbf
    style SM4 fill:#bbf

    style EH1 fill:#fbf
    style EH2 fill:#fbf
    style EH3 fill:#fbf
    style EH4 fill:#fbf

    style ES1 fill:#fbb
    style ES2 fill:#fbb
    style ES3 fill:#fbb
Loading

Runtime Dependencies

graph TD
    subgraph Required
        R1[ROS2 Core]
        R2[Hardware Interface]
        R3[State Publishers]
    end

    subgraph Optional
        O1[Web Server]
        O2[Camera Driver]
        O3[MoveIt]
    end

    subgraph Features
        F1[Teleoperation]
        F2[Motion Planning]
        F3[Visual Feedback]
    end

    R1 --> AC & HC & LC & BC
    R2 --> AC & HC & LC & BC
    R3 --> TW & MR
    O1 --> F1
    O2 --> F3
    O3 --> F2

    style Required fill:#bbf
    style Optional fill:#fbf
    style Features fill:#fbb
Loading

These diagrams provide different views of how the components interact:

  1. Data Flow Architecture: Shows how data moves through the system
  2. Message Topics Flow: Illustrates ROS2 topic connections
  3. Control Hierarchy: Depicts the control layers
  4. Safety and Error Handling: Shows how safety is managed across components
  5. Runtime Dependencies: Maps required and optional component dependencies
⚠️ **GitHub.com Fallback** ⚠️