Modeling and Recovering Hierarchical Structural Architectures of ROS 2 Systems from Code and Launch Configurations using LLM-based Agents
This paper proposes a UML-based modeling concept and an LLM-agent-driven pipeline to automatically reconstruct hierarchical structural architectures of ROS 2 systems from code and launch configurations, achieving high precision in abstraction-level recovery while highlighting challenges in capturing complex subsystem-level semantics.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
The Big Picture: The "Lost Blueprint" Problem
Imagine you walk into a massive, high-tech factory (a ROS 2 system). Inside, there are hundreds of robots (called Nodes) working together. Some robots talk to each other by shouting messages across the room (Topics), while others have direct phone lines (Services).
The problem? The factory manager (the Architect) never drew a map of how these robots are organized. Instead, the instructions on how to connect them are scattered everywhere:
- Some instructions are written in the code of the robots themselves.
- Some are in a "Launch File" (a master schedule that tells the factory which robots to turn on and how to group them).
- Some are hidden in configuration files.
If you want to understand the factory, you have to read thousands of pages of code and schedules to guess the structure. If the factory changes, those guesses become wrong immediately. This is the problem the paper solves: How do we automatically draw a clear, organized map of a robot factory just by reading its messy instructions?
The Solution: A Smart Detective with a Rulebook
The authors built a system that acts like a super-smart detective to rebuild the factory map. But they didn't just let the detective guess; they gave them a strict Rulebook (the "Blueprint").
Here is how their system works, step-by-step:
1. The Rulebook (The UML Model)
Before the detective starts, the authors created a specific language (based on UML, a standard way of drawing software diagrams) to describe the factory.
- Atomic Nodes: These are the individual robots.
- Composed Nodes: These are teams of robots working together (like a "Painting Crew" or "Inspection Team").
- Namespaces: Think of these as different rooms in the factory. A robot named "Camera" in the "Kitchen" is different from a "Camera" in the "Garage."
2. The Hybrid Detective Team (LLM + Rules)
The system uses two types of detectives working together:
- Detective A (The Robot): This part is purely logical and deterministic. It scans the source code to find the basic robots. It looks for specific patterns (like "This class inherits from
rclcpp::Node"). It's like a barcode scanner; it's fast, perfect, and never makes mistakes on simple things. - Detective B (The AI Agent): This is a Large Language Model (an AI). Its job is to look at the messy "Launch Files" and figure out how the robots are grouped into teams.
- The Catch: If you just ask an AI to "draw a map," it might hallucinate (make things up) or get confused.
- The Fix: The authors gave the AI the Rulebook. The AI isn't allowed to invent new types of robots or connections that don't exist in the ROS 2 world. It must fit its answers into the pre-defined boxes of the Rulebook. This makes the AI much more reliable.
3. The Output
The system spits out a clean, hierarchical diagram (like a family tree for the robots). It shows:
- Who the individual robots are.
- Which robots are grouped into teams.
- Which room (namespace) they are in.
- How they talk to each other.
The Experiment: Testing the Detective
The team tested their system on three different "factories":
The Toy Factory (Simple): A small, clean codebase with no complex launch files.
- Result: Perfect Score (100%). The system found every robot and connection. Since the instructions were clear, the AI didn't have to guess much.
The Organized Workshop (Medium): A slightly more complex setup with launch files that group robots into teams.
- Result: High Accuracy. The system was great at finding the individual robots. It was also very good at grouping them, though it missed a few subtle connections in the "Launch" instructions.
The Giant Industrial Plant (Hard): A massive, real-world industrial codebase (from Autoware, used for self-driving cars).
- Result: Mixed Bag.
- Precision (Quality): When the system did draw a connection, it was almost always correct. It didn't make up fake connections.
- Recall (Completeness): It missed about 65% of the complex team structures.
- Why? In huge industrial systems, the instructions are often hidden deep inside layers of code or written in very clever, implicit ways. The AI, even with the Rulebook, couldn't find every single hidden instruction.
- Result: Mixed Bag.
The Takeaway: What Did We Learn?
The paper concludes with a very important lesson:
- We are great at finding the "Bricks": The system is excellent at identifying the individual components (the code classes) because that is easy to read.
- We are still struggling with the "Mortar": The system struggles to figure out how those bricks are glued together into complex structures when the instructions are hidden or implicit.
The Metaphor:
Imagine trying to rebuild a castle from a pile of stones and a few scattered notes.
- The system is perfect at identifying that "This is a stone" and "This is a window."
- However, when the notes say "Put the tower here," but the note is written in a riddle inside a different book, the system sometimes misses the tower.
Why Does This Matter?
For companies building self-driving cars or robots, having a clear map of their software is crucial for safety and maintenance. This paper provides a tool that can automatically generate that map, saving engineers hours of manual work and helping them understand their complex systems better—even if it's not perfect yet for the most chaotic, industrial-scale projects.
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.