# robovision2210/spiderx_ws architecture

> Architecture diagram of the GitHub repository robovision2210/spiderx_ws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robovision2210/spiderx_ws
- Repository: https://github.com/robovision2210/spiderx_ws

## Overview

SpiderX is a ROS 2 workspace for a 12-DOF quadruped. Its verified user-facing workflow launches the robot in Gazebo Fortress, publishes robot/joint state and lidar data, and supports simulation-only posture and kinematics validation. The controller also contains offline gait analysis, but gait playback and locomotion are not implemented. Localization, mapping, and navigation are configured future layers, documented as blocked pending locomotion and odometry. Some package capabilities are documented but their runtime wiring is not shown in the sampled source, so those links are cited to the README.

Main entry points: [`src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py`](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py) (Offline gait analysis), [`src/spiderx_bringup/launch/fortress.launch.py`](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress.launch.py) (Fortress launch), [`src/spiderx_controller/spiderx_controller/trajectory_client.py`](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/trajectory_client.py) (Trajectory client), [`src/spiderx_localization/launch/global_localization.launch.py`](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_localization/launch/global_localization.launch.py) (Localization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robot["Robot model"]
  node_model["Robot description"]
end

subgraph group_simulation["Simulation and bringup"]
  node_simlaunch["Fortress launch<br/>[fortress.launch.py]"]
  node_sim["Gazebo Fortress"]
  node_real["Real robot launch"]
  node_posturelaunch["Posture hold launch"]
  node_jointcontrol["Joint control launch"]
end

subgraph group_control["Control and analysis"]
  node_configcheck["Controller config checks<br/>[config_check.py]"]
  node_kinematics["Leg kinematics<br/>[leg_kinematics.py]"]
  node_pose["Pose targets and validation<br/>[m4_pose_targets.py]"]
  node_posevalidation["Pose runtime validation"]
  node_posture["Posture configuration<br/>[posture_config.py]"]
  node_trajectory["Trajectory client"]
  node_gaitconfig["Gait configuration<br/>[gait_config.py]"]
  node_gaitanalysis["Offline gait analysis"]
  node_gaittrajectory["Gait trajectory<br/>[gait_trajectory.py]"]
  node_gaitkinematics["Gait kinematics<br/>[gait_kinematics.py]"]
  node_gaitmetrics["Gait metrics<br/>[gait_metrics.py]"]
  node_gaitreport["Gait reports<br/>[gait_report.py]"]
end

subgraph group_sensing["Sensors and diagnostics"]
  node_lidar["Lidar launch<br/>[lidar.launch.py]"]
  node_diagnostics["Sensor diagnostics<br/>[read_lidar.py]"]
  node_jointreader["Joint-state reader"]
end

subgraph group_autonomy["Autonomy configuration"]
  node_localization["Localization"]
  node_mapping["SLAM mapping<br/>[slam.launch.py]"]
  node_navigation["Nav2 navigation"]
end

node_operator(("Operator"))
node_jointstates["Joint states"]
node_scan["Lidar scan"]
node_tf["TF tree"]
node_controller["Joint trajectory controller"]

node_operator -->|"launches"| node_simlaunch
node_simlaunch -->|"starts simulation"| node_sim
node_simlaunch -->|"loads model"| node_model
node_sim -->|"publishes"| node_jointstates
node_sim -->|"publishes"| node_scan
node_sim -->|"publishes"| node_tf
node_operator -->|"launches"| node_real
node_real -->|"starts lidar"| node_lidar
node_operator -->|"launches"| node_jointcontrol
node_jointcontrol -->|"configures"| node_controller
node_operator -->|"launches"| node_posturelaunch
node_posturelaunch -->|"uses simulation"| node_sim
node_operator -->|"checks configuration"| node_configcheck
node_configcheck -->|"validates against"| node_model
node_kinematics -->|"reads geometry"| node_model
node_pose -->|"solves IK"| node_kinematics
node_posevalidation -->|"validates targets"| node_pose
node_posevalidation -->|"sends trajectory"| node_trajectory
node_trajectory -->|"reads"| node_jointstates
node_trajectory -->|"sends goal"| node_controller
node_posture -->|"reuses safety checks"| node_configcheck
node_gaitanalysis -->|"loads gait specs"| node_gaitconfig
node_gaitanalysis -->|"evaluates gaits"| node_gaitmetrics
node_gaitanalysis -->|"writes reports"| node_gaitreport
node_gaittrajectory -->|"provides samples"| node_gaitkinematics
node_gaitkinematics -->|"provides IK samples"| node_gaitmetrics
node_lidar -->|"publishes"| node_scan
node_diagnostics -->|"reads"| node_scan
node_jointreader -->|"reads"| node_jointstates
node_localization -.->|"uses state"| node_jointstates
node_localization -.->|"publishes odometry TF"| node_tf
node_mapping -.->|"uses scans"| node_scan
node_mapping -.->|"uses localization"| node_localization
node_navigation -.->|"uses map"| node_mapping

click node_model "https://github.com/robovision2210/spiderx_ws/tree/main/src/spiderx_description"
click node_simlaunch "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress.launch.py"
click node_real "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/real_robot.launch.py"
click node_posturelaunch "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress_posture_hold.launch.py"
click node_jointcontrol "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress_control.launch.py"
click node_configcheck "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/config_check.py"
click node_kinematics "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/leg_kinematics.py"
click node_pose "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_pose_targets.py"
click node_posevalidation "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_pose_validation.py"
click node_posture "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/posture_config.py"
click node_trajectory "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/trajectory_client.py"
click node_gaitconfig "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_config.py"
click node_gaitanalysis "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py"
click node_gaittrajectory "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_trajectory.py"
click node_gaitkinematics "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_kinematics.py"
click node_gaitmetrics "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_metrics.py"
click node_gaitreport "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_report.py"
click node_lidar "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_firmware/launch/lidar.launch.py"
click node_diagnostics "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_scripts/spiderx_scripts/read_lidar.py"
click node_jointreader "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_scripts/spiderx_scripts/read_joint_states.py"
click node_localization "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_localization/launch/global_localization.launch.py"
click node_mapping "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_mapping/launch/slam.launch.py"
click node_navigation "https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_navigation/launch/navigation.launch.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model toneBlue
class node_simlaunch,node_sim,node_real,node_posturelaunch,node_jointcontrol toneAmber
class node_configcheck,node_kinematics,node_pose,node_posevalidation,node_posture,node_trajectory,node_gaitconfig,node_gaitanalysis,node_gaittrajectory,node_gaitkinematics,node_gaitmetrics,node_gaitreport toneMint
class node_lidar,node_diagnostics,node_jointreader toneRose
class node_localization,node_mapping,node_navigation,node_operator,node_jointstates,node_scan,node_tf,node_controller toneIndigo
```

## Components

### Robot model

- [Robot description](https://github.com/robovision2210/spiderx_ws/tree/main/src/spiderx_description): `src/spiderx_description`

### Simulation and bringup

- [Fortress launch](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress.launch.py): `src/spiderx_bringup/launch/fortress.launch.py`
- **Gazebo Fortress**
- [Real robot launch](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/real_robot.launch.py): `src/spiderx_bringup/launch/real_robot.launch.py`
- [Posture hold launch](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress_posture_hold.launch.py): `src/spiderx_bringup/launch/fortress_posture_hold.launch.py`
- [Joint control launch](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_bringup/launch/fortress_control.launch.py): `src/spiderx_bringup/launch/fortress_control.launch.py`

### Control and analysis

- [Controller config checks](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/config_check.py): `src/spiderx_controller/spiderx_controller/config_check.py`
- [Leg kinematics](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/leg_kinematics.py): `src/spiderx_controller/spiderx_controller/leg_kinematics.py`
- [Pose targets and validation](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_pose_targets.py): `src/spiderx_controller/spiderx_controller/m4_pose_targets.py`
- [Pose runtime validation](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_pose_validation.py): `src/spiderx_controller/spiderx_controller/m4_pose_validation.py`
- [Posture configuration](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/posture_config.py): `src/spiderx_controller/spiderx_controller/posture_config.py`
- [Trajectory client](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/trajectory_client.py): `src/spiderx_controller/spiderx_controller/trajectory_client.py`
- [Gait configuration](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_config.py): `src/spiderx_controller/spiderx_controller/gait_config.py`
- [Offline gait analysis](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py): `src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py`
- [Gait trajectory](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_trajectory.py): `src/spiderx_controller/spiderx_controller/gait_trajectory.py`
- [Gait kinematics](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_kinematics.py): `src/spiderx_controller/spiderx_controller/gait_kinematics.py`
- [Gait metrics](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_metrics.py): `src/spiderx_controller/spiderx_controller/gait_metrics.py`
- [Gait reports](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_controller/spiderx_controller/gait_report.py): `src/spiderx_controller/spiderx_controller/gait_report.py`

### Sensors and diagnostics

- [Lidar launch](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_firmware/launch/lidar.launch.py): `src/spiderx_firmware/launch/lidar.launch.py`
- [Sensor diagnostics](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_scripts/spiderx_scripts/read_lidar.py): `src/spiderx_scripts/spiderx_scripts/read_lidar.py`
- [Joint-state reader](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_scripts/spiderx_scripts/read_joint_states.py): `src/spiderx_scripts/spiderx_scripts/read_joint_states.py`

### Autonomy configuration

- [Localization](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_localization/launch/global_localization.launch.py): `src/spiderx_localization/launch/global_localization.launch.py`
- [SLAM mapping](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_mapping/launch/slam.launch.py): `src/spiderx_mapping/launch/slam.launch.py`
- [Nav2 navigation](https://github.com/robovision2210/spiderx_ws/blob/main/src/spiderx_navigation/launch/navigation.launch.py): `src/spiderx_navigation/launch/navigation.launch.py`

### Other components

- **Operator**
- **Joint states**
- **Lidar scan**
- **TF tree**
- **Joint trajectory controller**

## Connections

- Operator → Fortress launch: launches (evidence: `README.md`)
- Fortress launch → Gazebo Fortress: starts simulation (evidence: `README.md`)
- Fortress launch → Robot description: loads model (evidence: `README.md`)
- Gazebo Fortress → Joint states: publishes (evidence: `README.md`)
- Gazebo Fortress → Lidar scan: publishes (evidence: `README.md`)
- Gazebo Fortress → TF tree: publishes (evidence: `README.md`)
- Operator → Real robot launch: launches (evidence: `README.md`)
- Real robot launch → Lidar launch: starts lidar (evidence: `README.md`)
- Operator → Joint control launch: launches (evidence: `README.md`)
- Joint control launch → Joint trajectory controller: configures (evidence: `README.md`)
- Operator → Posture hold launch: launches
- Posture hold launch → Gazebo Fortress: uses simulation
- Operator → Controller config checks: checks configuration (evidence: `README.md`)
- Controller config checks → Robot description: validates against (evidence: `src/spiderx_controller/spiderx_controller/config_check.py`)
- Leg kinematics → Robot description: reads geometry (evidence: `src/spiderx_controller/spiderx_controller/leg_kinematics.py`)
- Pose targets and validation → Leg kinematics: solves IK (evidence: `src/spiderx_controller/spiderx_controller/m4_pose_targets.py`)
- Pose runtime validation → Pose targets and validation: validates targets (evidence: `src/spiderx_controller/spiderx_controller/m4_pose_validation.py`)
- Pose runtime validation → Trajectory client: sends trajectory (evidence: `src/spiderx_controller/spiderx_controller/m4_pose_validation.py`)
- Trajectory client → Joint states: reads (evidence: `src/spiderx_controller/spiderx_controller/trajectory_client.py`)
- Trajectory client → Joint trajectory controller: sends goal (evidence: `src/spiderx_controller/spiderx_controller/trajectory_client.py`)
- Posture configuration → Controller config checks: reuses safety checks (evidence: `src/spiderx_controller/spiderx_controller/posture_config.py`)
- Offline gait analysis → Gait configuration: loads gait specs (evidence: `src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py`)
- Offline gait analysis → Gait metrics: evaluates gaits (evidence: `src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py`)
- Offline gait analysis → Gait reports: writes reports (evidence: `src/spiderx_controller/spiderx_controller/m4_5_gait_analysis.py`)
- Gait trajectory → Gait kinematics: provides samples (evidence: `src/spiderx_controller/spiderx_controller/gait_kinematics.py`)
- Gait kinematics → Gait metrics: provides IK samples (evidence: `src/spiderx_controller/spiderx_controller/gait_metrics.py`)
- Lidar launch → Lidar scan: publishes (evidence: `README.md`)
- Sensor diagnostics → Lidar scan: reads (evidence: `README.md`)
- Joint-state reader → Joint states: reads (evidence: `README.md`)
- Localization → Joint states: uses state (evidence: `README.md`)
- Localization → TF tree: publishes odometry TF (evidence: `README.md`)
- SLAM mapping → Lidar scan: uses scans (evidence: `README.md`)
- SLAM mapping → Localization: uses localization (evidence: `README.md`)
- Nav2 navigation → SLAM mapping: uses map (evidence: `README.md`)
