# ros_d2
Exports ROS2 nodes (publishers, subcribers and services) into a [D2](https://d2lang.com/tour/intro/) file so they can be visualised and serialised for later use.
## Features
- [x] Export runtime ROS2 system architecture (nodes, services, topics, clients) to .d2 (using `ros2cli`)
- [x] Powerful visualisation and theming provided by [D2](https://d2lang.com/tour/intro/)
- [x] Simple serialisable diagram format
- [ ] Ros node descriptions pulled from the package.xml
- [ ] Topic QOS descriptions
- [ ] Action servers / clients?
- [x] 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!
- [x] `ros_d2 export-launch-files` command that will export a .d2 file for each of your launch files
- [x] `ros_d2 render` command that will render all .d2 files in the current directory
## Examples
### Simple
### More complex applications
## Installation
```bash
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](https://github.com/terrastruct/d2#install)
## 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
```bash
ros_d2 export ros-diagram.d2
```
4. Render your diagram using `d2`.
```bash
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:
```bash
# 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
- [Python 3.7+](https://www.python.org/)
- [pre-commit](https://pre-commit.com/)
### Installation
following the steps below to setup the project:
```bash
```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
```bash
source /opt/ros/galactic/setup.bash
colcon build
ros_d2 --help # prints help
```
2. Let's bring up the example nodes:
```bash
source install/setup.sh
ros2 launch ./src/ros_example_adder_node/launch/example_adder_node.launch.py
```
3. Now that ROS is running, lets use `ros_d2` to generate a diagram of all the nodes in the system:
```bash
ros_d2 export example_output/ros-diagram.d2
```
4. We will now have the [example_output/ros-diagram.d2](example_output/ros-diagram.d2) file. We can render this using `d2`:
```bash
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:
Elk:
5. We can also export with more info using `ros_d2 export example_output/ros-diagram.d2`
Raw data
{
"_id": null,
"home_page": "https://github.com/Greenroom-Robotics/ros-d2",
"name": "ros-d2",
"maintainer": "David Revay",
"docs_url": null,
"requires_python": "",
"maintainer_email": "david.revay@greenroomrobotics.com",
"keywords": "colcon",
"author": "Greenroom Robotics",
"author_email": "team@greenroomrobotics.com",
"download_url": "https://files.pythonhosted.org/packages/07/52/d53b6c8eb1448b0b23682f971cc2ef771312c4e59568afd9f466de23f1e0/ros-d2-1.0.5.tar.gz",
"platform": null,
"description": "# ros_d2\n\n\n\nExports ROS2 nodes (publishers, subcribers and services) into a [D2](https://d2lang.com/tour/intro/) file so they can be visualised and serialised for later use.\n\n## Features\n\n- [x] Export runtime ROS2 system architecture (nodes, services, topics, clients) to .d2 (using `ros2cli`)\n- [x] Powerful visualisation and theming provided by [D2](https://d2lang.com/tour/intro/)\n- [x] Simple serialisable diagram format\n- [ ] Ros node descriptions pulled from the package.xml\n- [ ] Topic QOS descriptions\n- [ ] Action servers / clients?\n- [x] Topic Types (`--verbose` flag)\n- [ ] Advanced theming\n- [ ] Pytest helpers that ensure your ROS2 System architecture matches that of your .d2 diagram\n- [ ] Better testing on this repo!\n- [x] `ros_d2 export-launch-files` command that will export a .d2 file for each of your launch files\n- [x] `ros_d2 render` command that will render all .d2 files in the current directory\n\n\n## Examples\n\n### Simple\n\n\n\n\n### More complex applications\n\n\n## Installation\n\n```bash\npip install ros-d2\nros_d2 export --help # prints help\n# If you get an error about \"No module named 'ros2cli'\" - ros has not been sourced!\n```\n\n## Requirements\n\n- ROS2 + Colcon\n- [D2](https://github.com/terrastruct/d2#install)\n\n## Usage\n\n### Exporting a diagram\n1. Launch your ROS2 system\n2. Source ROS\n3. Use `ros_d2` to export your runtime ros system to a .d2 file\n\n ```bash\n ros_d2 export ros-diagram.d2\n ```\n\n4. Render your diagram using `d2`.\n\n ```bash\n ros_d2 render # to render ALL .d2 files in the current directory\n # or...\n d2 --layout dagre ros-diagram.d2 # to use d2 directly\n ```\n\n### Exporting diagrams for all launch files\nIf you want to create a `.d2` and `.svg` alongside each of your ros2 `.launch.py` files. You can use the following script:\n\n ```bash\n # Source ros: eg) `source /opt/ros/humble/setup.bash`\n # Build your ros2 workspace: eg) `colcon build`\n # Source your ros2 workspace: eg) `source install/setup.bash`\n ros_d2 export-launch-files\n ros_d2 render\n ```\n\n\n## Development\n### Prerequisite\n\n- [Python 3.7+](https://www.python.org/)\n- [pre-commit](https://pre-commit.com/)\n\n### Installation\n\nfollowing the steps below to setup the project:\n\n```bash\n\n```bash\n# Clone the repository\ngit clone git@github.com:Greenroom-Robotics/ros-d2.git && cd ros-d2\n\n# Install all dependencies\npip install -e ./src/ros_d2\n```\n\n### Example usage\n\nFrom the root of this repo:\n\n1. Build this project using colcon\n ```bash\n source /opt/ros/galactic/setup.bash\n colcon build\n\n ros_d2 --help # prints help\n ```\n\n2. Let's bring up the example nodes:\n\n ```bash\n source install/setup.sh\n ros2 launch ./src/ros_example_adder_node/launch/example_adder_node.launch.py\n ```\n\n3. Now that ROS is running, lets use `ros_d2` to generate a diagram of all the nodes in the system:\n\n ```bash\n ros_d2 export example_output/ros-diagram.d2\n ```\n\n4. We will now have the [example_output/ros-diagram.d2](example_output/ros-diagram.d2) file. We can render this using `d2`:\n\n ```bash\n d2 --layout dagre example_output/ros-diagram.d2 example_output/ros-diagram-dagre.svg\n # or\n d2 --layout elk example_output/ros-diagram.d2 example_output/ros-diagram-dagre.svg\n # Note - d2 provides other layouts and themes. See `d2 --help` for more info\n ```\n\n This will produce the following diagram:\n\n Dagre:\n \n\n Elk:\n \n\n5. We can also export with more info using `ros_d2 export example_output/ros-diagram.d2`\n\n\n",
"bugtrack_url": null,
"license": "Copyright (C) 2022, Greenroom Robotics",
"summary": "Exports ROS2 nodes into the .d2 diagram format",
"version": "1.0.5",
"project_urls": {
"Homepage": "https://github.com/Greenroom-Robotics/ros-d2"
},
"split_keywords": [
"colcon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f6f3d654ca6c2da106591eb8cc48be9728f94ecd626430694dee50aa7e52c7c3",
"md5": "f29b4b8e155c59456e451d2b187392ad",
"sha256": "cf6e8b42f8c4cd16fafe5e4ffdf2c6d2fc41cd19996b03e8a6dcb5b041fa0e5b"
},
"downloads": -1,
"filename": "ros_d2-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f29b4b8e155c59456e451d2b187392ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7500,
"upload_time": "2023-05-27T10:59:08",
"upload_time_iso_8601": "2023-05-27T10:59:08.624379Z",
"url": "https://files.pythonhosted.org/packages/f6/f3/d654ca6c2da106591eb8cc48be9728f94ecd626430694dee50aa7e52c7c3/ros_d2-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0752d53b6c8eb1448b0b23682f971cc2ef771312c4e59568afd9f466de23f1e0",
"md5": "3e4bf6f386fbf4f7059419a72679e718",
"sha256": "3f6348a74ff2909579ec30d36732ef52ce47b0257f5e2cf91949678297c6bbdf"
},
"downloads": -1,
"filename": "ros-d2-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "3e4bf6f386fbf4f7059419a72679e718",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6580,
"upload_time": "2023-05-27T10:59:10",
"upload_time_iso_8601": "2023-05-27T10:59:10.326022Z",
"url": "https://files.pythonhosted.org/packages/07/52/d53b6c8eb1448b0b23682f971cc2ef771312c4e59568afd9f466de23f1e0/ros-d2-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-27 10:59:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Greenroom-Robotics",
"github_project": "ros-d2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ros-d2"
}
JSON
