Treat autoware_system_designer files as lock files

[mojomex]

As outlined in this comment in

• feat: implement autoware system designer tier4/nebula#403

I think that most info in the YAML files could be auto-generated and CI-checked:

1. Launch the node (either with the legacy launch system or with autoware_system_designer)
2. Extract the node's subscriptions and publishers
3. Extract the node's parameters
4. Generate or verify the YAML based on these

My main motivations are twofold:

• It's essential to keep the code and the YAMLs in sync, otherwise we might be analyzing something that doesn't match the running system
• Treating the YAMLs as (largely) auto-generated files reduces maintenance overhead and manually written duplicate code

Please let me know your thoughts!

[maxime-clem]

I previously looked into making a tool for automatically generating YAML files and I ran into these issues:

• Topic names can be absolute (/topic) or relative to the node namespace (~/topic), but at runtime it is unclear which is the one used in the code.
  • possible solution: run the node twice with different namespace to clarify the format of each topic.
• Some topics may only be created under some conditions (e.g., specific plugin is loaded).
  • Similarly, some parameters may only be declared by some plugins.
  • possible solution: also require some YAML definitions for plugins (*.plugin.yaml) that would assumed to be handwritten.

I also considered writing a script to parse the code of the nodes, but it quickly becomes overly

Therefore, I ended up asking an LLM to generate the .node.yaml file for some given packages and the results were good but still required some correcting.

I do think an automatic validator can be implement and would be very useful to automatically detect obvious mismatches.

[mojomex]

Thank you for the insight! I agree, it's definitely not an easy problem to solve.

I also agree that automatic validation will be useful, and would even say that to prevent issues and confusion down the line, is essential.

run the node twice with different namespace to clarify the format of each topic.

Sounds good! It's automatable and fool-proof.

There are also some nodes that take (an arbitrary number of) topic names as parameters (e.g. pointcloud concat is handed a list of topics to concatenate).
This might be hard to express in the current Autoware System Designer and might need a hand-crafted config for each different sensing architecture (which is fine I think).

YAML definitions for plugins (*.plugin.yaml) that would assumed to be handwritten

This one is indeed tricky. For clarification, for a node that has N optional plugins, what would be the resulting node yaml?

• one yaml with the superset of all the possible params
• 2^N yaml files that match their runtime exactly?

The first option is more realistic I think, even if it sadly means that we can't map 1:1 between architecture and runtime.

As for the handwritten part, that would bring us back to the maintenance&out-of-sync problems I mentioned above..

parse the code of the nodes

I did something like that in my Master's Thesis: find data flows (e.g. subscriptions, callbacks, publishers) by traversing the abstract syntax tree with Clang Matchers. It is in general impossible to find all relevant info for arbitrary code.

Having read and thought about your points, I think auto-generation can be done up to a point. If the developer provides a list of launch configs (basically unit tests for launching), then the validator could execute all launches, collect the superset of topics and params, and validate or edit the architecture file.

What are your thoughts @maxime-clem?

[technolojin]

First of all, I am glad to hear the real voice of active users.
Discussions like this shall be done.

There are also some nodes that take (an arbitrary number of) topic names as parameters (e.g. pointcloud concat is handed a list of topics to concatenate).
This might be hard to express in the current Autoware System Designer and might need a hand-crafted config for each different sensing architecture (which is fine I think).

https://github.com/tier4/autoware_universe/blob/2e05a3593c7741b7f24e46ba205a49ad488adf05/common/autoware_universe_designs/design/sensing/autoware_pointcloud_preprocessor/ConcatenateAndTimeSync.node.yaml#L47-L49

I solved this issue by treat special variables.

• Auto generation (Initial)
  This is one of the biggest pain point of the implementation work. I did it manually at the end.

• Maintenance

1. the developer of node package need to ensure the alignment, which cause maintenance cost.
2. a part of README file can be altered by this node files (similar to parameter schema)
3. later, the cpp ros2 node shall be auto-generated. we had internal discussion about splitting the business logic from ros2 node impl.

[mojomex]

@technolojin The special variables are super nice, this makes a lot of sense!

later, the cpp ros2 node shall be auto-generated. we had internal discussion about splitting the business logic from ros2 node impl.

This would be awesome, really looking forward to this!

[technolojin]

As first step, I am working on CI check. #3

[technolojin]

@mojomex

• linter has been developed and implemented
  for nebula ci ci: add GitHub Actions workflow for linting Autoware system design format tier4/nebula#416

• auto-generation
  unfortunately, it turns out auto-generation is too complex and difficult.