# noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof architecture
> Architecture diagram of the GitHub repository noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof
- Repository: https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof
## Overview
1. **Overall shape**
- This repository is a ROS 2 workspace for teaching and prototyping robotic arm systems.
- It is split into two main packages: one for robot descriptions and one for control/kinematics behavior.
- The code targets **ROS 2 Humble** on **Ubuntu 22.04**, and is built with **colcon**.
2. **`franka_description`: robot model/package boundary**
- This package is a pure description layer for Franka-style arms and hand variants.
- It contains URDF/Xacro robot models, inertial and joint-limit data, meshes, and RViz/launch assets.
- Its job is to define the robot’s structure and appearance, not to execute control logic.
3. **Robot model composition**
- The model files are organized by reuse:
- `robots/common/` holds shared Xacro components for arm, hand, and utility macros.
- `robots/panda/`, `robots/fr3/`, and `robots/dual_panda/` provide robot-specific variants.
- The package also includes prebuilt URDFs such as `panda_ros2.urdf` and `panda_arm.urdf.xacro`, suggesting multiple model entry points for different exercises.
4. **Geometry and visualization assets**
- `meshes/visual` and `meshes/collision` separate rendering geometry from collision geometry.
- This is important architecturally because the same logical robot model feeds both visualization and simulation/collision-aware use cases.
- RViz configuration and launch support live alongside the description package, reinforcing that this package is the source of truth for robot state representation.
5. **`robotic_arms_control`: runtime/control package boundary**
- This package contains executable ROS 2 nodes and launch files for control, trajectory handling, and transform publishing.
- It is the behavior layer of the repository: it consumes URDF/robot descriptions and produces motion or TF outputs.
- The package includes its own `urdf/` copies for `bazu` and `panda_arm`, indicating it can run with both a custom arm and the Franka arm.
6. **Controller configuration subsystem**
- The `config/` directory stores controller YAML files for:
- `bazu_pos_controller.yaml`
- `bazu_jtc_controller.yaml`
- `panda_jtc_controller.yaml`
- These configs likely define ROS control interfaces and trajectory/position controller parameters, making this the bridge between the robot model and runtime control.
7. **Launch orchestration and execution paths**
- `launch/controller_spawner.launch.py` appears to start controllers for the configured robot.
- `launch/gazebo_bringup.launch.py` likely connects the robot model to a simulated environment.
- `launch/rviz_bringup.launch.py` provides visualization startup.
- Together, these launch files define the main runtime topologies: simulation, controller startup, and visualization.
8. **Python node layer**
- The Python modules under `robotic_arms_control/robotic_arms_control/` are the main executable logic:
- `joint_controller_test.py`
- `jtc_multi_goals.py`
- `transform_publisher.py`
- `kinematic_solver.py`
- `rtb_ikine_fkine.py`
- Conceptually, these split into three behaviors:
- controller interaction/tests,
- trajectory goal generation,
- kinematics and transform computation/publishing.
9. **Kinematics and teaching workflow**
- The README describes a progression from custom arm modeling to controller integration, then to forward/inverse kinematics.
- The presence of `Robotics_kinematics_solver.ipynb` and the `rtb_ikine_fkine.py` module suggests offline/interactive kinematics exploration using Peter Corke’s Robotics Toolbox alongside ROS 2 runtime nodes.
- This means the repo is not just deployment code; it also supports analysis and derivation of robot motion models.
10. **Simulation/visualization data flow**
- The typical data path is:
- URDF/Xacro + meshes from `franka_description`
- controller configs and robot URDFs in `robotic_arms_control`
- launch files start controllers and optionally Gazebo/RViz
- Python nodes issue joint goals or publish transforms
- RViz/Gazebo consume the resulting robot state for visualization or simulation.
- The key boundary is between static robot definition and runtime actuation/state propagation.
11. **Custom robot vs. Franka Panda split**
- The repo supports two parallel robot tracks:
- **BAZU**, a custom educational arm used to introduce URDFs and control concepts.
- **Franka Panda / FR3**, a known 7-DOF platform used for more advanced trajectory and kinematics exercises.
- Diagrammatically, these are two robot model branches feeding the same control/visualization concepts.
12. **Testing and package quality**
- Both packages include ROS-style tests:
- URDF validation in `franka_description/test/urdf_tests.py`
- linting/style tests in `robotic_arms_control/test/`
- These are supporting boundaries rather than runtime components, but they indicate the repo expects correct model generation and ROS package hygiene.
13. **Supporting documentation and course assets**
- The root `Notes/` PDF and the `Images/` folder are course material rather than runtime dependencies.
- They reinforce that this repository is a learning-oriented monorepo: code, robot models, launch files, and lecture notes are packaged together.
14. **Architectural summary**
- If you draw the system, the center should be a ROS 2 workspace with two packages:
- a **description package** producing robot models/assets,
- a **control package** consuming those models to run simulation, trajectory control, and kinematics workflows.
- External execution contexts are **RViz**, **Gazebo**, and ROS 2 control tooling, with kinematics analysis also happening in Python notebooks/scripts.
Main entry points: [`franka_description`](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description) (Description), [`robotic_arms_control`](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control) (Control), [`robotic_arms_control/robotic_arms_control`](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/robotic_arms_control) (Python nodes), [`robotic_arms_control/launch`](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/launch) (Bringup launch)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_workspace["ROS 2 Workspace"]
node_root["Workspace
ROS 2 repo"]
end
subgraph group_description_pkg["franka_description"]
node_franka_desc["Description"]
node_common_models["Common Xacro
model macros"]
node_panda_models["Panda models
robot variant"]
node_fr3_models["FR3 models
robot variant"]
node_dual_models["Dual Panda
robot variant"]
node_meshes_visual[("Visual meshes
geometry assets")]
node_meshes_collision[("Collision meshes
geometry assets")]
node_desc_launch["Visualize launch
launch file"]
node_rviz_config["RViz config"]
end
subgraph group_control_pkg["robotic_arms_control"]
node_control_pkg["Control"]
node_controller_cfg["Controller YAMLs
control config"]
node_bringup_launch["Bringup launch
launch files"]
node_python_nodes["Python nodes
runtime scripts"]
node_bazu_urdf["BAZU URDF
robot model
[bazu.urdf]"]
node_panda_ctrl_urdf["Panda URDF
robot model
[panda_arm.urdf]"]
end
subgraph group_runtime["External Runtime"]
node_gazebo(("Gazebo
simulator"))
node_rviz(("RViz
visualizer"))
node_ros2_control(("ROS 2 control
control runtime"))
end
subgraph group_learning["Course Assets"]
node_notebook["Kinematics notebook
analysis notebook"]
node_notes["Course notes
teaching asset
[Complete_notes.pdf]"]
end
node_root -->|"contains"| node_franka_desc
node_root -->|"contains"| node_control_pkg
node_franka_desc -->|"reuses"| node_common_models
node_franka_desc -->|"defines"| node_panda_models
node_franka_desc -->|"defines"| node_fr3_models
node_franka_desc -->|"defines"| node_dual_models
node_franka_desc -->|"packages"| node_meshes_visual
node_franka_desc -->|"packages"| node_meshes_collision
node_franka_desc -->|"launches"| node_desc_launch
node_desc_launch -->|"uses"| node_rviz_config
node_control_pkg -->|"configures"| node_controller_cfg
node_control_pkg -->|"orchestrates"| node_bringup_launch
node_control_pkg -->|"executes"| node_python_nodes
node_control_pkg -->|"uses"| node_bazu_urdf
node_control_pkg -->|"uses"| node_panda_ctrl_urdf
node_bringup_launch -->|"spawns"| node_ros2_control
node_bringup_launch -->|"brings up"| node_gazebo
node_bringup_launch -->|"brings up"| node_rviz
node_controller_cfg -->|"feeds"| node_ros2_control
node_python_nodes -->|"drives"| node_ros2_control
node_python_nodes -->|"publishes"| node_rviz
node_python_nodes -->|"drives"| node_gazebo
node_franka_desc -->|"feeds"| node_control_pkg
node_notebook -.->|"inspires"| node_python_nodes
node_notes -.->|"documents"| node_root
click node_franka_desc "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description"
click node_control_pkg "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control"
click node_common_models "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/common"
click node_panda_models "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/panda"
click node_fr3_models "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/fr3"
click node_dual_models "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/dual_panda"
click node_meshes_visual "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/meshes/visual"
click node_meshes_collision "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/meshes/collision"
click node_desc_launch "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/franka_description/launch/visualize_franka.launch.py"
click node_rviz_config "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/franka_description/rviz/visualize_franka.rviz"
click node_controller_cfg "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/config"
click node_bringup_launch "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/launch"
click node_python_nodes "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/robotic_arms_control"
click node_bazu_urdf "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/robotic_arms_control/urdf/bazu.urdf"
click node_panda_ctrl_urdf "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/robotic_arms_control/urdf/panda_arm.urdf"
click node_notebook "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/Robotics_kinematics_solver.ipynb"
click node_notes "https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/Notes/Complete_notes.pdf"
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_root toneBlue
class node_franka_desc,node_common_models,node_panda_models,node_fr3_models,node_dual_models,node_meshes_visual,node_meshes_collision,node_desc_launch,node_rviz_config toneAmber
class node_control_pkg,node_controller_cfg,node_bringup_launch,node_python_nodes,node_bazu_urdf,node_panda_ctrl_urdf toneMint
class node_gazebo,node_rviz,node_ros2_control toneRose
class node_notebook,node_notes toneIndigo
```
## Components
### ROS 2 Workspace
Top-level learning and prototyping workspace for robotic arm models and control workflows.
- **Workspace**: ROS 2 repo · Workspace that combines robot descriptions, control runtime, and kinematics teaching assets.
### franka_description
Robot description package providing URDF/Xacro models, meshes, and visualization assets.
- [Description](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description): package · Source of truth for Franka-style robot models and assets. · `franka_description`
- [Common Xacro](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/common): model macros · Reusable arm, hand, and utility Xacro components shared across robot variants. · `franka_description/robots/common`
- [Panda models](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/panda): robot variant · Panda-specific URDF/Xacro variants and joint-limit data. · `franka_description/robots/panda`
- [FR3 models](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/fr3): robot variant · FR3-specific robot model entry points and limits. · `franka_description/robots/fr3`
- [Dual Panda](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/robots/dual_panda): robot variant · Dual-arm Panda example model for composition exercises. · `franka_description/robots/dual_panda`
- [Visual meshes](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/meshes/visual): geometry assets · Rendering geometry used by RViz and other visual consumers. · `franka_description/meshes/visual`
- [Collision meshes](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/franka_description/meshes/collision): geometry assets · Collision geometry used for simulation and planning-aware representations. · `franka_description/meshes/collision`
- [Visualize launch](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/franka_description/launch/visualize_franka.launch.py): launch file · Launch entry point for displaying the Franka description in RViz. · `franka_description/launch/visualize_franka.launch.py`
- [RViz config](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/franka_description/rviz/visualize_franka.rviz): viz config · RViz layout and display configuration for the robot description. · `franka_description/rviz/visualize_franka.rviz`
### robotic_arms_control
Runtime control package providing launch files, controller configs, and Python nodes.
- [Control](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control): package · Runtime package for controller startup, simulation bringup, and kinematic utilities. · `robotic_arms_control`
- [Controller YAMLs](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/config): control config · Controller parameter sets for BAZU and Panda trajectory/position control. · `robotic_arms_control/config`
- [Bringup launch](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/launch): launch files · Launch orchestration for controller spawning, Gazebo simulation, and RViz startup. · `robotic_arms_control/launch`
- [Python nodes](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/tree/master/robotic_arms_control/robotic_arms_control): runtime scripts · Main executable logic for controller tests, goal generation, transforms, and kinematics. · `robotic_arms_control/robotic_arms_control`
- [BAZU URDF](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/robotic_arms_control/urdf/bazu.urdf): robot model · Custom educational arm model used by the control package. · `robotic_arms_control/urdf/bazu.urdf`
- [Panda URDF](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/robotic_arms_control/urdf/panda_arm.urdf): robot model · Panda arm model copy used for runtime control workflows. · `robotic_arms_control/urdf/panda_arm.urdf`
### External Runtime
ROS 2 execution contexts used by the repository.
- **Gazebo**: simulator · Simulation runtime for robot bringup and controller interaction.
- **RViz**: visualizer · Visualization runtime for inspecting the robot model and state.
- **ROS 2 control**: control runtime · Controller manager and hardware abstraction used by the bringup flow.
### Course Assets
Documentation and notebook assets used for teaching and exploration.
- [Kinematics notebook](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/Robotics_kinematics_solver.ipynb): analysis notebook · Interactive offline exploration of forward and inverse kinematics. · `Robotics_kinematics_solver.ipynb`
- [Course notes](https://github.com/noshluk2/ros2-ultimate-guide-for-custom-robotic-arms-and-panda-7-dof/blob/master/Notes/Complete_notes.pdf): teaching asset · PDF notes and images supporting the learning workflow. · `Notes/Complete_notes.pdf`
## Connections
- Workspace → Description: contains · Workspace includes the robot description package.
- Workspace → Control: contains · Workspace includes the runtime/control package.
- Description → Common Xacro: reuses · Shared Xacro macros are the base for multiple robot variants.
- Description → Panda models: defines · Panda-specific robot model branch.
- Description → FR3 models: defines · FR3-specific robot model branch.
- Description → Dual Panda: defines · Dual Panda example branch.
- Description → Visual meshes: packages · Description package provides visual geometry.
- Description → Collision meshes: packages · Description package provides collision geometry.
- Description → Visualize launch: launches · Visualization launch starts the model in RViz.
- Visualize launch → RViz config: uses · RViz launch consumes the bundled visualization config.
- Control → Controller YAMLs: configures · Control package stores controller YAMLs.
- Control → Bringup launch: orchestrates · Launch files coordinate control, simulation, and visualization.
- Control → Python nodes: executes · Python modules provide runtime behavior.
- Control → BAZU URDF: uses · Custom arm URDF supports control workflows.
- Control → Panda URDF: uses · Panda URDF supports control workflows.
- Bringup launch → ROS 2 control: spawns · Controller spawner launch activates ROS 2 control.
- Bringup launch → Gazebo: brings up · Gazebo launch connects the model to simulation.
- Bringup launch → RViz: brings up · RViz launch starts visualization.
- Controller YAMLs → ROS 2 control: feeds · Controller parameters are consumed by ROS 2 control.
- Python nodes → ROS 2 control: drives · Controller tests and goal generators interact with control interfaces.
- Python nodes → RViz: publishes · Transform publishing and kinematic outputs support visualization.
- Python nodes → Gazebo: drives · Runtime nodes can generate motion for simulated robots.
- Description → Control: feeds · Control workflows consume the robot descriptions and models.
- Kinematics notebook → Python nodes: inspires · Interactive kinematics exploration parallels runtime kinematics scripts.
- Course notes → Workspace: documents · Course materials explain the workspace and workflows.