Generate various aspects of Robot Operating System workspace in form of diagrams, graphs and interactive views. To produce results package uses Grpahviz and PlantUML diagram tools.
Package can produce following diagrams:
- source code distribution chart
- source packages dependency tree
catkinpackages build schedule- ROS nodes, topics and messages graphs
- ROS launch files tree
- rosbag sequence graph
In addition there is rosverifier tool detecting packages overlay in catkin workspace.
Output can be generated in HTML and Markdown format.
Main motivation for the project was to present variuos aspects of ROS workspace in easy to understand form.
- How to use?
- Requirements
- Installation
- Examples
- The Tools
- Comparison with ROS tools
- Dumping information
- References
- License
- run dump tools to collect data
- run one of diagram tools:
./src/rosdiagramtools.py {tool} {args}
Depending on desired tool, user can run subset of dump scripts.
Examples of provided diagrams can be seen in /examples/ repo directory.
First example (sample) contains synthetic data. Example turtlesim presents
structure of turtlesim tool.
Whole commands list with description can be found here or by calling rosdiagramtools.py --help.
Required dependency packages are needed to be installed before first run of main application. To do it execute one of commands:
src/install-deps.shpip3 install -r ./src/requirements.txt
Moreover there are additional required packages: python3-catkin-tools (for catkin), python3-rosdep, cloc,
imagemagick, plantuml.
Installation:
sudo apt install python3-catkin-tools python3-rosdep cloc imagemagick plantuml.
Installation of package can be done by:
install-package.shto install package in standard way throughpipinstall-devel.shto install package in developer mode- to install package from downloaded ZIP file execute:
pip3 install --user file:ros-diagram-tools-master.zip#subdirectory=src
In /examples there are few examples of generated diagrams:
- artificial sample
- turtlesim: build schedule, ros connections, rosbag sequence
- turtlebot3: code distribution, packages tree, build schedule, ros verify
- mecanum_simulator: code distribution, packages tree, build schedule, nodes classification, ros verify, ros connections
Tools are divided into following categories:
- working on source code:
codedistribution, - working on ROS workspace:
packagetree,buildtime,rosverify,classifynodes, - working on running ROS master:
rosparamlist,rosmsglist,rosnodegraph,rostopicgraph,rosbagflow.
From other perspective tools can be split into:
- ones working with dumped data:
codedistribution,packagetree,buildtime,classifynodes,rosparamlist,rosmsglist,rosnodegraph,rostopicgraph,rosbagflow, - ones requiring direct access:
rosverify
List of tools:
Tool presents distribution of code in source subdirectories.
Help: ./src/rosdiagramtools.py codedistribution --help
Help output.
Show workspace packages in form of dependency tree. Graph presents package build dependencies defined in package.xml.
Help: ./src/rosdiagramtools.py packagetree --help
Help output.
Tool tries to match ROS nodes (given by rosnode command) to source packages where nodes are implemented. Result is presented in form
of text file.
Help: ./src/rosdiagramtools.py classifynodes --help
Help output.
Output example: mecanum_simulator
Presents build time and order of packages in workspace.
Help: ./src/rosdiagramtools.py buildtime --help
Help output.
To generate graph execute following steps:
- build workspace with command
catkin build | tee build_log.txt - execute tool:
rosdiagramtools.py buildtime -la \
--buildlogfile build_log.txt \
-st 1 -sp 150 \
--outhtml --outdir output_dir
Then graph will be available through file: output_dir/full_graph.html.
More real-life example with full view is presented on folowing image:
Calculate compilation time of objects under make. Calculation is done by analyzing log file. The log have to be obtained
running following command:
make -j1 <optional_targets> | ts '[%H:%M:%.S]' | tee compile_log.txt
Tool output is presented in form of sorted list cntaining object name and it's compilation time.
Help: ./src/rosdiagramtools.py maketime --help
Help output.
Script detects packages overlay in given workspace and extended workspaces.
Help: ./src/rosdiagramtools.py rosverify --help
Help output.
Example output on turtlesim generated by command rosdiagramtools.py rosverify:
INFO:rosdiagram.tool.rosverify:found workspaces: ['/path/to/catkin_ws', '/opt/ros/noetic']
INFO:rosdiagram.tool.rosverify:all overlay packages: []
INFO:rosdiagram.tool.rosverify:workspace overlay packages: []
Presents list of ROS parameters with values.
Help: ./src/rosdiagramtools.py rosparamlist --help
Help output.
Presents list of ROS messages and services with definitions.
Help: ./src/rosdiagramtools.py rosmsglist --help
Help output.
Presents dependecy of ROS nodes, topics and services in form of data flow graph.
Help: ./src/rosdiagramtools.py rosnodegraph --help
Help output.
In addition, for given graph interactive web page can be generated, example here.
Following animation shows navigation thorough nodes of graph:
Example of topic graph view:
Example of service graph view:
Present dependecy of ROS nodes and topics in form of dependency graph.
Help: ./src/rosdiagramtools.py rostopicgraph --help
Help output.
Note: tool is considered deprecated, so please use rosnodegraph tool.
Present include tree of ROS launch files with nodes, parameters and topic mappings among other things.
Help: ./src/rosdiagramtools.py roslaunchgraph --help
Help output.
Generates simple index page containing links to any content.
Help: ./src/rosdiagramtools.py rosindex --help
Help output.
Generates diagrams from data generated by dumpros tool.
Those diagrams are:
- code distribution through packages (
codedistribution) - packages tree (
packagetree) - parameters list (
rosparamlist) - messages list (
rosmsglist) - nodes graph (
rosnodegraph)
Help: ./src/rosdiagramtools.py rosgeneral --help
Help output.
Presents visualisation of ROS bag in form of sequence graph.
Help: ./src/rosdiagramtools.py rosbagflow --help
Help output.
Tool generates sequence diagram and interactive web page with following functionalities:
- viewing full graph,
- viewing messages of node and topic,
- viewing message data and message type definition,
- annotating messages with additional information (for example validation messages)
The web page output is stored here.
Example of node and message view preview can be found here: turtlesim
codedistributiondoes not have equivalent,packagetreepresents similar results torqt_dep, but limited only to workspace packages and it's build dependencies.rqt_deppresents packages full tree of runtime dependencies,classifynodesdoes not have equivalent,buildtimedoes not have equivalent,rosnodegraphpresents similar results torqt_graph. Focuses more on connections between nodes and messages,rostopicgraphpresents similar results torqt_graph. Presents connection graph of nodes,rosbagflowpresents similar results torqt_bag. Emphasises communication between nodes and time relation between messages. Usingrqt_bagit is hardly possible to read senders and receivers of messages,rosverifyandrosbagflowcan be used to verify certain aspects of system. ROS also have tool dedicated for looking for potential issues - it isroswtf.
Moreover with diagram tools it is possible to generate and store diagram images in automated way serving for example for documentation purposes.
From the other hand, diagram tools are not capable of presenting state changes of running system like in rqt_bag. The
tools just makes snapshot of the system in certain moment.
Dumping data is done through rosdiagramdump.py script. Description of arguments can be found here or
by calling rosdiagramdump.py --help.
Dump tools:
dumpclocdir- dump result ofcloccommand on given directorydumpcatkindeps- dump catkin dependencies of packages in workspace (from package.xml)dumprospack- dump data fromrospackdumprosmsg- dump messages infodumprossrv- dump services definitionsdumprosnode- dump nodes infodumprostopic- dump topics infodumprosservice- dump services infodumproslaunch- dump launch file infodumpros- dump majority of data (uses above mentioned dump tools)extractscripts- extract embedded scripts to files
Tools can be divided into following categories:
- working on source code:
dumpclocdir, - working on ROS workspace:
dumpcatkindeps,dumprospack,dumprosmsg,dumprossrv,dumproslaunch, - working on running ROS master:
dumprosnode,dumprostopic,dumprosservice,dumpros.
Dependency graph between tools, dump scripts and external executables is presented on following graph:
BSD 3-Clause License
Copyright (c) 2022, Arkadiusz Netczuk dev.arnet@gmail.com
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.