/ros-d2

Exports ROS2 nodes (publishers, subscribers and services) into a D2 file so they can be visualised.

Primary LanguagePythonMIT LicenseMIT

ros_d2

Banner

Exports ROS2 nodes (publishers, subcribers and services) into a D2 file so they can be visualised and serialised for later use.

Features

  • Export runtime ROS2 system architecture (nodes, services, topics, clients) to .d2 (using ros2cli)
  • Powerful visualisation and theming provided by D2
  • Simple serialisable diagram format
  • Ros node descriptions pulled from the package.xml
  • Topic QOS descriptions
  • Action servers / clients?
  • Topic Types (--verbose flag)
  • Advanced theming
  • Pytest helpers that ensure your ROS2 System architecture matches that of your .d2 diagram
  • Better testing on this repo!
  • ros_d2 export-launch-files command that will export a .d2 file for each of your launch files
  • ros_d2 render command that will render all .d2 files in the current directory

Examples

Simple

Simple example

More complex applications

Example

Installation

pip install ros-d2
ros_d2 export --help # prints help
# If you get an error about "No module named 'ros2cli'" - ros has not been sourced!

Requirements

  • ROS2 + Colcon
  • D2

Usage

Exporting a diagram

  1. Launch your ROS2 system
  2. Source ROS
  3. Use ros_d2 to export your runtime ros system to a .d2 file
ros_d2 export ros-diagram.d2
  1. Render your diagram using d2.
ros_d2 render # to render ALL .d2 files in the current directory
# or...
d2 --layout dagre ros-diagram.d2 # to use d2 directly

Exporting diagrams for all launch files

If you want to create a .d2 and .svg alongside each of your ros2 .launch.py files. You can use the following script:

# Source ros: eg) `source /opt/ros/humble/setup.bash`
# Build your ros2 workspace: eg) `colcon build`
# Source your ros2 workspace: eg) `source install/setup.bash`
ros_d2 export-launch-files
ros_d2 render

Development

Prerequisite

Installation

following the steps below to setup the project:

```bash
# Clone the repository
git clone git@github.com:Greenroom-Robotics/ros-d2.git && cd ros-d2

# Install all dependencies
pip install -e ./src/ros_d2

Example usage

From the root of this repo:

  1. Build this project using colcon
source /opt/ros/galactic/setup.bash
colcon build

ros_d2 --help # prints help
  1. Let's bring up the example nodes:
source install/setup.sh
ros2 launch ./src/ros_example_adder_node/launch/example_adder_node.launch.py
  1. Now that ROS is running, lets use ros_d2 to generate a diagram of all the nodes in the system:
ros_d2 export example_output/ros-diagram.d2
  1. We will now have the example_output/ros-diagram.d2 file. We can render this using d2:
d2 --layout dagre example_output/ros-diagram.d2 example_output/ros-diagram-dagre.svg
# or
d2 --layout elk example_output/ros-diagram.d2 example_output/ros-diagram-dagre.svg
# Note - d2 provides other layouts and themes. See `d2 --help` for more info

This will produce the following diagram:

Dagre: dagre

Elk: elk

  1. We can also export with more info using ros_d2 export example_output/ros-diagram.d2

dagre