rosdiscover

Description

rosdiscover is a system for extracting the run-time software architecture from ROS system code. Current ROS tools like rosgraph or rosdoctor require the system to be running and the node interconnections to be observed from the system. In contrast, rosdiscover analyzes the launch files and source code of ROS systems to derive the anticipated run-time architecture (the nodes that will be started, the topic, service, and action connections between them, as well as parameters that are read and written). This architecture information can be used by downstream tools to support various kinds of architectural analysis, such as configuration error checking.

This project is a research project within the Institute for Software Research at Carnegie Mellon University.

The currently supported output formats are a simple YML file listing the nodes in a similar way to what might be reported by running rosnode list and rosnode info but without the need to run the system, and an architecture description language called Acme, used within our research group.

The system assumes that the ROS system is contained inside a Docker container, and uses roswire to interact with the container.

We are developing support for ROS 1 and ROS 2, and both static and dynamic extraction.

Installation

See below for two different methods of installing rosdiscover. In general, the native installation should be preferred, but for some cases (e.g., machines that run Mac OS or Windows), the Docker-based method is ideal.

Both methods require that Docker is installed on your machine and that your user belongs to the docker group (i.e., sudo isn't required to run docker commands). For instructions on installing Docker, refer to: https://docs.docker.com/install/

Native Installation

The ideal way to install rosdiscover is to install to a virtual environment running on your host machine. This method requires that your host machine is running Python 3.6 or greater. If that isn't the case, the safest way to install a newer version of Python on your machine is via pyenv, which allows you to manage multiple installations of Python.

We strongly recommend that you install rosdiscover inside a Python virtual environment (via virtualenv or pipenv) to avoid interfering with the rest of your system (i.e., to avoid Python’s equivalent of DLL hell). To install roswire from source within a virtual environment using pipenv:

$ git clone git@github.com:https:cmu-rss-lab/rosdiscover rosdiscover
$ cd rosdiscover
$ pipenv shell

(rosdiscover) $ pip install -e .

(Alternative) Docker Installation

(WARNING: This approach is more complex than the native installation: Where possible, you should try to stick to the native installation.)

In some cases, it may not be possible to install rosdiscover natively on your machine (e.g., Mac OS or Windows machines). rosdiscover can be installed on such systems by building (or downloading) and using a Docker image for rosdiscover.

To build the Docker image for rosdiscover:

$ docker build -t rosdiscover .

To run rosdiscover commands via Docker, replace in all commands shown below rosdiscover with the following prefix:

$ docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -it rosdiscover

where -v /var/run/docker.sock:/var/run/docker.sock is used to mount the host's Docker socket inside the rosdiscover container. Optionally, you may also want to use volume mounting to persist (and reuse) the cache:

TODO: requires careful handling of users/permissions.

Getting Started

ROSDiscover offers a number of commands for interacting with Docker images, all of which accept the path to a YAML configuration file as one of their parameters. Several example YAML configuration files can be found under the example directory at the root of this repository. Below is an example of one of those configuration files, example/fetch.yml, a configuration file for the Fetch mobile robot.

image: fetch
sources:
- /opt/ros/melodic/setup.bash
- /ros_ws/devel/setup.bash
launches:
- /ros_ws/src/fetch_gazebo/fetch_gazebo/launch/pickplace_playground.launch

The image property specifies the name of the Docker image that is used to provide the robot. sources gives an ordered list of the scripts that must be sourced to setup the correct working environment for the robot; in most cases, sources will look as it does above, except the term melodic may be replaced with the name of another ROS distribution (e.g., indigo or kinetic). launches gives an ordered list of the XML launch files that should be used to launch the software for the robot. For now, each element in this list is an absolute path to a launch file inside the container. In the near future, support for relative paths (e.g., name of package + name of launch file) and passing command-line arguments will be added. There is also an additional environment property, exemplified below, which accepts a mapping from names of environment variables to their respective values. This is useful in a small number of cases (e.g., specifying TURTLEBOT3_MODEL for TurtleBot3).

image: turtlebot3
sources:
- /opt/ros/kinetic/setup.bash
- /ros_ws/devel/setup.bash
environment:
  TURTLEBOT3_MODEL: burger
launches:
- filename: /ros_ws/src/turtlebot3_simulations/turtlebot3_gazebo/launch/turtlebot3_house.launch
  arg1: value
  arg2: value
  arg3: value

Commands

To see a complete list of commands that are supported by ROSDiscover, run the following:

$ rosdiscover --help
usage: rosdiscover [-h] {launch,rostopic,rosservice,acme} ...

discovery of ROS architectures

positional arguments:
  {launch,rostopic,rosservice,acme}
    launch              simulates the effects of a roslaunch.
    rostopic            simulates the output of rostopic for a given
                        configuration.
    rosservice          simulates the output of rosservice for a given
                        configuration.
    acme                generates Acme from a source file

optional arguments:
  -h, --help            show this help message and exit

The launch command is used to simulate the effects of a sequence of roslaunch calls for a robot application:

$ pipenv run rosdiscover launch example/fetch.yml

Docker Development Setup (for Windows 10)

If you are planning to develop on Windows 10, then you will need to mount rosdiscover source directories into a Docker container. You can use your favorite Python IDE in Windows, but run and test rosdiscover inside the container.

We provide a Docker build file for setting up this development environment. To run inside the image you need to mount (i) the source directory that is the top of this repository as /code in the container, (ii) the socket/port that the host docker daemon connects to (so that rosdiscover can find other, (iii) (recommended) a host folder that can be used to cache some of the rosdiscover builds, so that there is no need to start from scratch with rosdiscover each time.

To run rosdiscover on Windows 10, where the source code is mounted on D:/rosdiscover, and you want to store the cache on D:/cache:

1. Ensure that the folders to mount are shared. This needs to be done through the Docker settings on your host. (This is done through the Dashboard or through settings on Windows Docker)

2. Build the development docker image:

   $ docker build -t build/rosdiscover-dev -f .\Dockerfile-dev .
   

3. Run the docker image:

   $ docker run --rm -v d:/rosdiscover:/code -v d:/cache:/root/.roswire -v //var/run/docker.sock:/var/run/docker.sock -it build/rosdiscover-dev
   

4. Once the shell has started and you are inside the container, you will need to install rosdiscover locally:

   bash-4.4# pip install -e .
   

You will then be able to run rosdiscover from the command line.