Skip to content

Commit d17ac70

Browse files
technolojinpre-commit-ci[bot]
technolojin
and
pre-commit-ci[bot]
authored
chore(autoware_sample_designs): add comprehensive README for autoware_sample_designs package (#1820)
* feat(autoware_sample_designs): add comprehensive README for autoware_sample_designs package Signed-off-by: Taekjin LEE <taekjin.lee@tier4.jp> * style(pre-commit): autofix Signed-off-by: Taekjin LEE <taekjin.lee@tier4.jp> * fix(README): update formatting for code blocks and enhance section headings for clarity Signed-off-by: Taekjin LEE <taekjin.lee@tier4.jp> --------- Signed-off-by: Taekjin LEE <taekjin.lee@tier4.jp> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 66ae001 commit d17ac70

1 file changed

Lines changed: 178 additions & 0 deletions

File tree

‎autoware_sample_designs/README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# autoware_sample_designs
2+
3+
`autoware_sample_designs` is a complete, working example of defining and launching a full Autoware system using [Autoware System Designer](https://github.com/autowarefoundation/autoware_system_designer/blob/main/README.md).
4+
5+
It serves as the reference implementation for how to describe, configure, and deploy an Autoware autonomous driving stack using YAML-based system design — without writing ROS 2 launch files by hand.
6+
7+
## What is Autoware System Designer?
8+
9+
Autoware System Designer is a toolset that lets you describe your entire software system in structured YAML files and automatically generates correct-by-construction ROS 2 launch files, parameter templates, and system visualization diagrams from them.
10+
11+
![Configuration Structure](https://raw.githubusercontent.com/autowarefoundation/autoware_system_designer/main/autoware_system_designer/doc/images/configuration_structure.png)
12+
13+
A system is composed of four entity types:
14+
15+
| Entity | File | Description |
16+
| ----------------- | ---------------------- | ------------------------------------------------------------------ |
17+
| **Node** | `*.node.yaml` | A single ROS 2 node — its topics, parameters, and execution config |
18+
| **Module** | `*.module.yaml` | A reusable group of nodes/sub-modules with wired connections |
19+
| **System** | `*.system.yaml` | The top-level description: components, connections, modes |
20+
| **Parameter Set** | `*.parameter_set.yaml` | Parameter overrides applied to nodes at deployment time |
21+
22+
The build step collects node definitions from across the workspace (resolved via `workspace.yaml`), combines them with the system design files in this package, and generates launch files and a system visualization:
23+
24+
```text
25+
each ROS 2 package (core, universe, …) ┐
26+
└── design/node/ *.node.yaml │
27+
├── autoware_system_designer
28+
this package │
29+
├── design/node/ *.node.yaml (optional) │
30+
├── design/module/ *.module.yaml │
31+
├── design/system/ *.system.yaml │
32+
└── design/parameter_set/ *.parameter_set.yaml ┘
33+
│
34+
▼
35+
install/
36+
├── systems.html
37+
├── AutowareSample/
38+
│ ├── Runtime.launch.xml
39+
│ ├── LoggingSimulation.launch.xml
40+
│ └── PlanningSimulation.launch.xml
41+
└── ...node launchers...
42+
```
43+
44+
The generated node diagram shows the full system topology including all modules, nodes, and topic connections:
45+
46+
![Node Diagram](https://raw.githubusercontent.com/autowarefoundation/autoware_system_designer/main/autoware_system_designer/doc/images/node_diagram.png)
47+
48+
## Visualizing the System
49+
50+
After building, open the generated HTML page in your browser to interactively explore the full system graph:
51+
52+
```sh
53+
# From your colcon workspace root
54+
firefox install/systems.html
55+
# or
56+
google-chrome install/systems.html
57+
```
58+
59+
The visualization page shows every node, module, topic connection, and operating mode defined in the system.
60+
61+
## Package Structure
62+
63+
```text
64+
autoware_sample_designs/
65+
├── design/
66+
│ ├── node/ # System-specific node definitions (wrapper/optional nodes only)
67+
│ ├── module/ # Reusable subsystem modules (sensing, perception, …)
68+
│ ├── system/
69+
│ │ └── AutowareSample.system.yaml # Top-level system definition
70+
│ └── parameter_set/ # Parameter overrides per node, per mode
71+
├── config/ # Shared parameter YAML files (owned by this package)
72+
├── launch/ # Hand-written wrapper launch files for legacy integration
73+
├── urdf/ # Vehicle URDF
74+
├── workspace.yaml # Provider resolution rules for the system designer
75+
└── CMakeLists.txt
76+
```
77+
78+
The `AutowareSample.system.yaml` defines four operating modes — `Runtime`, `LoggingSimulation`, `PlanningSimulation`, and `E2ESimulation` — each with mode-specific component overrides and connections.
79+
80+
## Relationship with `autoware_launch`
81+
82+
`autoware_sample_designs` is **independent** of `autoware_launch` as a system builder.
83+
The system designer generates its own launch files and manages its own system topology.
84+
`autoware_launch` does **not** control how this system is structured or launched.
85+
86+
The only connection is that some **parameter set files** reference shared parameter YAML files from `autoware_launch` (e.g., tracker, fusion, and filter configs that are common across vehicle variants):
87+
88+
```yaml
89+
# design/parameter_set/sample_system_perception.parameter_set.yaml
90+
parameters:
91+
- node: /perception/object_recognition/detection/clustering/...
92+
param_files:
93+
# shared param file from autoware_launch — values only, no launch dependency
94+
- param_path: $(find-pkg-share autoware_launch)/config/perception/...
95+
```
96+
97+
This is a runtime parameter file lookup — `autoware_launch` is not involved in building or launching the system. Node-specific parameters that belong to this vehicle configuration live in `config/` inside this package itself.
98+
99+
## Building
100+
101+
In your colcon workspace:
102+
103+
```sh
104+
source /opt/ros/$ROS_DISTRO/setup.bash
105+
colcon build --symlink-install \
106+
--packages-select autoware_sample_designs \
107+
--cmake-args -DCMAKE_BUILD_TYPE=Release
108+
```
109+
110+
This invokes `autoware_system_designer_build_deploy()` from `CMakeLists.txt`, which processes `AutowareSample.system.yaml` and generates all launch files under `install/`.
111+
112+
## Launching the System
113+
114+
The exact launch command for each mode is shown in the **Launcher** section of the visualization page (`install/systems.html`).
115+
Use that as the authoritative source — launch file names like `Runtime.launch.xml` are not unique and the same name may be generated by other system design packages in your workspace, so copying a bare `ros2 launch <package> <mode>.launch.xml` from documentation can silently run the wrong system.
116+
117+
In the visualization page, navigate to the deploy system (`AutowareSample`), open the **Launch** section, and copy the command for the desired mode:
118+
119+
```sh
120+
# From your colcon workspace root
121+
firefox install/systems.html
122+
```
123+
124+
## Introducing System Designer to Your Own System
125+
126+
Use `autoware_sample_designs` as the template. The steps to create a new system design package are:
127+
128+
### 1. Create a ROS 2 package with the standard layout
129+
130+
```text
131+
my_vehicle_designs/
132+
├── design/
133+
│ ├── node/
134+
│ ├── module/
135+
│ ├── system/
136+
│ │ └── MyVehicle.system.yaml
137+
│ └── parameter_set/
138+
├── config/
139+
├── workspace.yaml
140+
├── CMakeLists.txt
141+
└── package.xml
142+
```
143+
144+
### 2. Declare the dependency in `package.xml`
145+
146+
```xml
147+
<depend>autoware_system_designer</depend>
148+
```
149+
150+
### 3. Wire up the build in `CMakeLists.txt`
151+
152+
```cmake
153+
find_package(autoware_system_designer REQUIRED)
154+
155+
# Generate launch files from MyVehicle.system.yaml
156+
autoware_system_designer_build_deploy(
157+
${PROJECT_NAME}
158+
MyVehicle.system
159+
PRINT_LEVEL=WARNING
160+
STRICT=AUTO
161+
)
162+
```
163+
164+
### 4. Define your system
165+
166+
Node definitions (`*.node.yaml`) live in each individual ROS 2 package (under `core/`, `universe/`, etc.) and are resolved automatically via `workspace.yaml` — you do not need to copy them.
167+
Only add files to `design/node/` for nodes that are unique to your system package (e.g., wrapper nodes or optional system-level nodes not defined elsewhere).
168+
169+
Compose these nodes into modules and a top-level system in your `*.system.yaml`. Add `*.parameter_set.yaml` files to override parameters for your specific hardware.
170+
171+
### 5. Build and visualize
172+
173+
```sh
174+
colcon build --packages-select my_vehicle_designs
175+
firefox install/systems.html
176+
```
177+
178+
The generated `install/systems.html` gives you a full interactive diagram of your system before running a single node. Use it to verify connections, inspect parameters, and review mode differences.

0 commit comments

Comments
 (0)