# sidharthsharma96/tabletennis architecture

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

- Interactive diagram: https://gitdiagram.com/sidharthsharma96/tabletennis
- Repository: https://github.com/sidharthsharma96/tabletennis

## Overview

Tabletennis is a ROS/Gazebo simulation of a KUKA iiwa playing table tennis, with ROS interfaces and control components supplied by the adjacent iiwa_stack. The documented workflow starts a simulated world, then accepts demo, pose, incremental-motion, or RViz planning requests; the world plugin tracks ball motion and exposes simulation services. The plugin excerpt confirms a ROS agent-command dispatch, but the agent implementation and several launch/configuration details were not sampled, so those connections are kept limited. Paths for unsampled subsystems use their exact enclosing directories.

Main entry points: [`src/table_tennis/plugins/training_return_plugin.cc`](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/plugins/training_return_plugin.cc) (Training world plugin), [`src/table_tennis`](https://github.com/sidharthsharma96/tabletennis/tree/master/src/table_tennis) (Pose and step services), [`src/iiwa_stack/iiwa_hw/include/iiwa_hw.hpp`](https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_hw/include/iiwa_hw.hpp) (Robot hardware interface), [`src/table_tennis/scripts/table_tennis_agent.py`](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/table_tennis_agent.py) (Table-tennis agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Table-tennis simulation"]
  node_demo_api["Demo and world services"]
  node_world_plugin["Training world plugin"]
  node_ball_plugin["Ball physics plugin<br/>[ball_plugin.cc]"]
  node_ball_state["Ball state topic"]
  node_simulation_description["Simulation packages"]
end

subgraph group_learning["Agent and learning"]
  node_agent["Table-tennis agent"]
  node_dqn_script["DQN runner<br/>[dqn.py]"]
  node_dqn_model["DQN model<br/>[dqn.py]"]
end

subgraph group_robot["iiwa control stack"]
  node_sunrise["Cartesian-to-joint control<br/>[iiwa_sunrise.py]"]
  node_trajectory["Joint trajectory controller"]
  node_hw_loop["Hardware control loop<br/>[main.cpp]"]
  node_hw_interface["Robot hardware interface<br/>[iiwa_hw.hpp]"]
  node_ros_commands["ROS commands and services"]
  node_ros_states["ROS robot state"]
  node_sunrise_robot["KUKA Sunrise application"]
  node_robot_description["Robot description"]
end

subgraph group_planning["Motion and planning"]
  node_ik_solver["IK solver<br/>[ik_solver.cpp]"]
  node_pose_api["Pose and step services"]
  node_moveit["MoveIt and RViz planning"]
end

node_operator(("ROS user"))
node_gazebo["Gazebo world"]

node_operator -->|"requests demo"| node_demo_api
node_operator -->|"requests motion"| node_pose_api
node_operator -->|"plans paths"| node_moveit
node_gazebo -->|"loads plugin"| node_world_plugin
node_gazebo -->|"loads plugin"| node_ball_plugin
node_world_plugin -->|"publishes state"| node_ball_state
node_ball_plugin -->|"simulates ball"| node_gazebo
node_demo_api -->|"serves demo"| node_world_plugin
node_world_plugin -->|"dispatches command"| node_agent
node_agent -.->|"runs policy"| node_dqn_script
node_dqn_script -->|"uses model"| node_dqn_model
node_agent -.->|"requests robot action"| node_pose_api
node_pose_api -.->|"solves pose"| node_ik_solver
node_pose_api -.->|"submits pose command"| node_sunrise
node_sunrise -->|"publishes trajectory"| node_trajectory
node_trajectory -.->|"commands joints"| node_hw_interface
node_hw_loop -->|"reads and writes"| node_hw_interface
node_hw_loop -->|"updates control"| node_hw_interface
node_ros_commands -.->|"bridges commands"| node_sunrise_robot
node_sunrise_robot -.->|"publishes state"| node_ros_states
node_hw_interface -->|"exposes state"| node_ros_states
node_moveit -->|"uses model"| node_robot_description
node_simulation_description -.->|"configures simulation"| node_gazebo

click node_demo_api "https://github.com/sidharthsharma96/tabletennis/tree/master/src/table_tennis"
click node_world_plugin "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/plugins/training_return_plugin.cc"
click node_ball_plugin "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/plugins/ball_plugin.cc"
click node_agent "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/table_tennis_agent.py"
click node_dqn_script "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/dqn.py"
click node_dqn_model "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/nn/dqn.py"
click node_ik_solver "https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/ik_solver.cpp"
click node_pose_api "https://github.com/sidharthsharma96/tabletennis/tree/master/src/table_tennis"
click node_sunrise "https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_control/src/iiwa_sunrise.py"
click node_hw_loop "https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_hw/src/main.cpp"
click node_hw_interface "https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_hw/include/iiwa_hw.hpp"
click node_ros_commands "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros/include/iiwa_ros"
click node_ros_states "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros/include/iiwa_ros/state"
click node_sunrise_robot "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros_java/src/de/tum/in/camp/kuka/ros"
click node_moveit "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_moveit"
click node_robot_description "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_description"
click node_simulation_description "https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_gazebo"

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_demo_api,node_world_plugin,node_ball_plugin,node_ball_state,node_simulation_description,node_operator toneBlue
class node_agent,node_dqn_script,node_dqn_model toneAmber
class node_sunrise,node_trajectory,node_hw_loop,node_hw_interface,node_ros_commands,node_ros_states,node_sunrise_robot,node_robot_description toneMint
class node_ik_solver,node_pose_api,node_moveit toneRose
class node_gazebo toneIndigo
```

## Components

### Table-tennis simulation

- [Demo and world services](https://github.com/sidharthsharma96/tabletennis/tree/master/src/table_tennis): `src/table_tennis`
- [Training world plugin](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/plugins/training_return_plugin.cc): `src/table_tennis/plugins/training_return_plugin.cc`
- [Ball physics plugin](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/plugins/ball_plugin.cc): `src/table_tennis/plugins/ball_plugin.cc`
- **Ball state topic**
- [Simulation packages](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_gazebo): `src/iiwa_stack/iiwa_gazebo`

### Agent and learning

- [Table-tennis agent](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/table_tennis_agent.py): `src/table_tennis/scripts/table_tennis_agent.py`
- [DQN runner](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/dqn.py): `src/table_tennis/scripts/dqn.py`
- [DQN model](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/nn/dqn.py): `src/table_tennis/nn/dqn.py`

### iiwa control stack

- [Cartesian-to-joint control](https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_control/src/iiwa_sunrise.py): `src/iiwa_stack/iiwa_control/src/iiwa_sunrise.py`
- **Joint trajectory controller**
- [Hardware control loop](https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_hw/src/main.cpp): `src/iiwa_stack/iiwa_hw/src/main.cpp`
- [Robot hardware interface](https://github.com/sidharthsharma96/tabletennis/blob/master/src/iiwa_stack/iiwa_hw/include/iiwa_hw.hpp): `src/iiwa_stack/iiwa_hw/include/iiwa_hw.hpp`
- [ROS commands and services](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros/include/iiwa_ros): `src/iiwa_stack/iiwa_ros/include/iiwa_ros`
- [ROS robot state](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros/include/iiwa_ros/state): `src/iiwa_stack/iiwa_ros/include/iiwa_ros/state`
- [KUKA Sunrise application](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_ros_java/src/de/tum/in/camp/kuka/ros): `src/iiwa_stack/iiwa_ros_java/src/de/tum/in/camp/kuka/ros`
- [Robot description](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_description): `src/iiwa_stack/iiwa_description`

### Motion and planning

- [IK solver](https://github.com/sidharthsharma96/tabletennis/blob/master/src/table_tennis/scripts/ik_solver.cpp): `src/table_tennis/scripts/ik_solver.cpp`
- [Pose and step services](https://github.com/sidharthsharma96/tabletennis/tree/master/src/table_tennis): `src/table_tennis`
- [MoveIt and RViz planning](https://github.com/sidharthsharma96/tabletennis/tree/master/src/iiwa_stack/iiwa_moveit): `src/iiwa_stack/iiwa_moveit`

### Other components

- **ROS user**
- **Gazebo world**

## Connections

- ROS user → Demo and world services: requests demo
- ROS user → Pose and step services: requests motion
- ROS user → MoveIt and RViz planning: plans paths
- Gazebo world → Training world plugin: loads plugin
- Gazebo world → Ball physics plugin: loads plugin
- Training world plugin → Ball state topic: publishes state
- Ball physics plugin → Gazebo world: simulates ball
- Demo and world services → Training world plugin: serves demo
- Training world plugin → Table-tennis agent: dispatches command
- Table-tennis agent → DQN runner: runs policy
- DQN runner → DQN model: uses model
- Table-tennis agent → Pose and step services: requests robot action
- Pose and step services → IK solver: solves pose
- Pose and step services → Cartesian-to-joint control: submits pose command
- Cartesian-to-joint control → Joint trajectory controller: publishes trajectory
- Joint trajectory controller → Robot hardware interface: commands joints
- Hardware control loop → Robot hardware interface: reads and writes
- Hardware control loop → Robot hardware interface: updates control
- ROS commands and services → KUKA Sunrise application: bridges commands
- KUKA Sunrise application → ROS robot state: publishes state
- Robot hardware interface → ROS robot state: exposes state
- MoveIt and RViz planning → Robot description: uses model
- Simulation packages → Gazebo world: configures simulation