# caleb-pace/stability-aware-robotic-dog architecture

> Architecture diagram of the GitHub repository caleb-pace/stability-aware-robotic-dog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caleb-pace/stability-aware-robotic-dog
- Repository: https://github.com/caleb-pace/stability-aware-robotic-dog

## Overview

This repository is a Python control prototype for a Unitree Go2 robotic dog. In the main runtime, a gamepad supplies stick input to the controller entry point, which updates a gait engine; its clock generates foot positions, solves inverse kinematics, and sends motor commands through an output abstraction (the sampled entry point uses a dummy output). Separate capabilities include gait definitions, forward/inverse kinematics, interpolation, and plotting. The graph reflects sampled calls and documented project scope; unsampled implementations are represented only where the tree supports their paths, and their wiring is omitted where uncertain.

Main entry points: [`py_src/kinematic_controller/main.py`](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/main.py) (Controller entry), [`py_src/kinematic_controller/gait_engine.py`](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gait_engine.py) (Gait engine), [`py_src/hardware_abstraction_layer/gamepad_controller.py`](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/gamepad_controller.py) (Gamepad polling), [`py_src/visualisation/main.py`](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/main.py) (Visualisation entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Control runtime"]
  node_runtime_main["Controller entry<br/>[main.py]"]
  node_gait_engine["Gait engine<br/>[gait_engine.py]"]
  node_controller_input["Controller data"]
end

subgraph group_motion["Motion and kinematics"]
  node_gaits["Gait presets<br/>[gaits.py]"]
  node_gait_definition["Gait definition<br/>[gait_definition.py]"]
  node_stepper["Foot stepping<br/>[stepper.py]"]
  node_ik_solver["Inverse kinematics<br/>[ik_solver.py]"]
  node_fk_solver["Forward kinematics<br/>[fk_solver.py]"]
  node_data_structures["Geometry types"]
end

subgraph group_io["Hardware interface"]
  node_gamepad["Gamepad polling"]
  node_input_layer["Input interface<br/>[input_layer.py]"]
  node_output_layer["Output interface<br/>[output_layer.py]"]
  node_dummy_output["Dummy output<br/>[dummy_out.py]"]
end

subgraph group_analysis["Interpolation and visualisation"]
  node_interpolation_base["Interpolator API<br/>[base.py]"]
  node_catmull_rom["Catmull-Rom"]
  node_lagrange["Lagrange interpolation<br/>[lagrange.py]"]
  node_visualisation_main["Visualisation entry<br/>[main.py]"]
  node_gait_visualisation["Gait plots"]
  node_curve_visualisation["Curve plots"]
  node_angle_visualisation["Joint-angle plots<br/>[graph_angle.py]"]
end

node_operator(("Operator"))

node_operator -->|"moves sticks"| node_gamepad
node_runtime_main -->|"polls input"| node_gamepad
node_gamepad -->|"builds data"| node_controller_input
node_runtime_main -->|"passes input"| node_gait_engine
node_runtime_main -->|"selects preset"| node_gaits
node_gait_engine -->|"requests foot positions"| node_stepper
node_gait_engine -->|"solves positions"| node_ik_solver
node_gait_engine -->|"sends commands"| node_output_layer
node_runtime_main -->|"constructs output"| node_dummy_output
node_dummy_output -->|"implements"| node_output_layer
node_catmull_rom -->|"implements"| node_interpolation_base
node_visualisation_main -->|"plots gait"| node_gait_visualisation
node_visualisation_main -->|"supplies TROT"| node_gaits

click node_runtime_main "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/main.py"
click node_gait_engine "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gait_engine.py"
click node_controller_input "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/data_structures/controller_input.py"
click node_gamepad "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/gamepad_controller.py"
click node_input_layer "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/input_layer.py"
click node_output_layer "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/output_layer.py"
click node_dummy_output "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/dummy_out.py"
click node_gaits "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gaits.py"
click node_gait_definition "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gait_definition.py"
click node_stepper "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/stepper.py"
click node_ik_solver "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/ik_solver.py"
click node_fk_solver "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/fk_solver.py"
click node_data_structures "https://github.com/caleb-pace/stability-aware-robotic-dog/tree/main/py_src/data_structures"
click node_interpolation_base "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/base.py"
click node_catmull_rom "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/catmull_rom_spline.py"
click node_lagrange "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/lagrange.py"
click node_visualisation_main "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/main.py"
click node_gait_visualisation "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_3d_kinematics.py"
click node_curve_visualisation "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_3d_interpolated_curves.py"
click node_angle_visualisation "https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_angle.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_runtime_main,node_gait_engine,node_controller_input toneBlue
class node_gaits,node_gait_definition,node_stepper,node_ik_solver,node_fk_solver,node_data_structures toneAmber
class node_gamepad,node_input_layer,node_output_layer,node_dummy_output toneMint
class node_interpolation_base,node_catmull_rom,node_lagrange,node_visualisation_main,node_gait_visualisation,node_curve_visualisation,node_angle_visualisation toneRose
class node_operator toneIndigo
```

## Components

### Control runtime

- [Controller entry](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/main.py): `py_src/kinematic_controller/main.py`
- [Gait engine](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gait_engine.py): `py_src/kinematic_controller/gait_engine.py`
- [Controller data](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/data_structures/controller_input.py): `py_src/data_structures/controller_input.py`

### Motion and kinematics

- [Gait presets](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gaits.py): `py_src/kinematic_controller/gaits.py`
- [Gait definition](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/gait_definition.py): `py_src/kinematic_controller/gait_definition.py`
- [Foot stepping](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/stepper.py): `py_src/kinematic_controller/stepper.py`
- [Inverse kinematics](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/ik_solver.py): `py_src/kinematic_controller/ik_solver.py`
- [Forward kinematics](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/kinematic_controller/fk_solver.py): `py_src/kinematic_controller/fk_solver.py`
- [Geometry types](https://github.com/caleb-pace/stability-aware-robotic-dog/tree/main/py_src/data_structures): `py_src/data_structures`

### Hardware interface

- [Gamepad polling](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/gamepad_controller.py): `py_src/hardware_abstraction_layer/gamepad_controller.py`
- [Input interface](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/input_layer.py): `py_src/hardware_abstraction_layer/input_layer.py`
- [Output interface](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/output_layer.py): `py_src/hardware_abstraction_layer/output_layer.py`
- [Dummy output](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/hardware_abstraction_layer/dummy_out.py): `py_src/hardware_abstraction_layer/dummy_out.py`

### Interpolation and visualisation

- [Interpolator API](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/base.py): `py_src/interpolation/base.py`
- [Catmull-Rom](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/catmull_rom_spline.py): `py_src/interpolation/catmull_rom_spline.py`
- [Lagrange interpolation](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/interpolation/lagrange.py): `py_src/interpolation/lagrange.py`
- [Visualisation entry](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/main.py): `py_src/visualisation/main.py`
- [Gait plots](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_3d_kinematics.py): `py_src/visualisation/graph_3d_kinematics.py`
- [Curve plots](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_3d_interpolated_curves.py): `py_src/visualisation/graph_3d_interpolated_curves.py`
- [Joint-angle plots](https://github.com/caleb-pace/stability-aware-robotic-dog/blob/main/py_src/visualisation/graph_angle.py): `py_src/visualisation/graph_angle.py`

### Other components

- **Operator**

## Connections

- Operator → Gamepad polling: moves sticks
- Controller entry → Gamepad polling: polls input
- Gamepad polling → Controller data: builds data
- Controller entry → Gait engine: passes input
- Controller entry → Gait presets: selects preset
- Gait engine → Foot stepping: requests foot positions
- Gait engine → Inverse kinematics: solves positions
- Gait engine → Output interface: sends commands
- Controller entry → Dummy output: constructs output
- Dummy output → Output interface: implements
- Catmull-Rom → Interpolator API: implements
- Visualisation entry → Gait plots: plots gait
- Visualisation entry → Gait presets: supplies TROT