diff --git a/source/Demos.rst b/source/Demos.rst index cecf226..a2cdf9d 100644 --- a/source/Demos.rst +++ b/source/Demos.rst @@ -2,7 +2,7 @@ Demos ===== There are currently two Space ROS demonstration applications. -The first demo uses `MoveIt2 `_ and a model of the `Canadarm manipulator `_ along with the Space ROS base image. +Both demos uses the `MoveIt2 `_ docker image. The Canadarm demo uses a model of the `Canadarm manipulator `_ along with the Space ROS base image. In this demo, MoveIt2 is used to plan the motion for the Canadarm, which is running in simulation. The second demo shows the `Mars Curiosity rover `_ in simulation, presenting multiple ROS 2 services to allow the user to directly control the rover. The following pages go into detail to show you how to run these demo applications. @@ -11,5 +11,6 @@ The following pages go into detail to show you how to run these demo application :titlesonly: :maxdepth: 2 + Demos/MoveIt2 Demos/Canadarm Demos/Mars-Rover diff --git a/source/Demos/Canadarm.rst b/source/Demos/Canadarm.rst index 93e1ff2..c3c5fc9 100644 --- a/source/Demos/Canadarm.rst +++ b/source/Demos/Canadarm.rst @@ -1,7 +1,45 @@ Canadarm Demo ============= -TODO: +Build the Space ROS & MoveIt2 Docker Images +------------------------------------------- + +If you haven't already, follow `the MoveIt2 instructions `_, and `the Space ROS image instructions `_. These are the base images for the Canadarm and Curiosity Mars rover demos. The Dockerfile installs all of the prerequisite system dependencies along with the demos source code, then builds the Space ROS Space Robots Demo. + +Space ROS Space Robots Demo Docker Image +---------------------------------------- + +Build the ``space_robots`` image: + +.. code-block:: console + + cd ../space_robots + ./build.sh + +Running the Demo Docker +----------------------- + +Run the following to allow GUI passthrough: + +.. code-block:: console + + xhost +local:docker + +Then run: + +.. code-block:: console + + ./run.sh + +Depending on the host computer, you might need to remove the ``--gpus all`` flag in ``run.sh``, which uses your GPUs. + +Running the Canadarm Demo +------------------------- + +Run the following command: + +.. code-block:: console + + ros2 launch canadarm canadarm.launch.py + -Describe how to run the Canadarm demo. -This may be simply a link to the demo repo that provides the instructions. diff --git a/source/Demos/Mars-Rover.rst b/source/Demos/Mars-Rover.rst index bcdc603..a4faaef 100644 --- a/source/Demos/Mars-Rover.rst +++ b/source/Demos/Mars-Rover.rst @@ -1,7 +1,121 @@ Mars Rover Demo =============== -TODO: +Build the Space ROS & MoveIt2 Docker Images +------------------------------------------- + +If you haven't already, follow `these instructions `_ for building the MoveIt2 docker image, `and these instructions `_ for the spaceros image. These are the base images for the Canadarm and Curiosity Mars rover demos. The Dockerfile installs all of the prerequisite system dependencies along with the demos source code, then builds the Space ROS Space Robots Demo. + +Space ROS Space Robots Demo Docker Image +---------------------------------------- + +Build the ``space_robots`` image: + +.. code-block:: console + + cd ../space_robots + ./build.sh + +Running the Demo Docker +----------------------- + +Run the following to allow GUI passthrough: + +.. code-block:: console + + xhost +local:docker + +Then run: + +.. code-block:: console + + ./run.sh + +Depending on the host computer, you might need to remove the ``--gpus all`` flag in ``run.sh``, which uses your GPUs. + +Running the Mars Rover Demo +--------------------------- + +Launch the demo: + +.. code-block:: console + + ros2 launch mars_rover mars_rover.launch.py + +On the top left corner, click on the refresh button to show camera feed. + +Perform Tasks +^^^^^^^^^^^^^ + +Setup +~~~~~ + +Open a new terminal and attach it to the currently running container: + +.. code-block:: console + + docker exec -it bash + +Make sure packages are sourced: + +.. code-block:: console + + source ~/spaceros/install/setup.bash + +.. code-block:: console + + source ~/demos_ws/install/setup.bash + +Available Commands +~~~~~~~~~~~~~~~~~~ + +Drive the rover forward: + +.. code-block:: console + + ros2 service call /move_forward std_srvs/srv/Empty + +Stop the rover: + +.. code-block:: console + + ros2 service call /move_stop std_srvs/srv/Empty + +Turn left: + +.. code-block:: console + + ros2 service call /turn_left std_srvs/srv/Empty + +Turn right: + +.. code-block:: console + + ros2 service call /turn_right std_srvs/srv/Empty + +Open the tool arm: + +.. code-block:: console + + ros2 service call /open_arm std_srvs/srv/Empty + +Cloes the tool arm: + +.. code-block:: console + + ros2 service call /close_arm std_srvs/srv/Empty + +Open the mast (camera arm): + +.. code-block:: console + + ros2 service call /mast_open std_srvs/srv/Empty + +Close the mast (camera arm): + +.. code-block:: console + + ros2 service call /mast_close std_srvs/srv/Empty + + -Describe how to run the Mars rover demo. -This may be simply a link to the demo repo that provides the instructions diff --git a/source/Demos/MoveIt2.rst b/source/Demos/MoveIt2.rst new file mode 100644 index 0000000..acbd0ec --- /dev/null +++ b/source/Demos/MoveIt2.rst @@ -0,0 +1,96 @@ +Moveit2 Image +============= + +The MoveIt2 Docker image uses the Space ROS docker image (openrobotics/spaceros:latest) as its base image, which you can build, following `this `_ tutorial. The MoveIt2 Dockerfile installs all of the prerequisite system dependencies to build MoveIt2 (and Moveit2 tutorials) and then pulls and builds the latest MoveIt2 and Moveit2 tutorials source code. + +Cloning the repository +---------------------- + +Move into your Space ROS workspace: + +.. code-block:: console + + cd spaceros_ws + +Clone the docker repository: + +.. code-block:: console + + git clone https://github.com/space-ros/docker + +Building the MoveIt2 Image +-------------------------- + +To build the docker image, run: + +.. code-block:: console + + cd docker/moveit2 + ./build.sh + +The build process will take about 30 minutes, depending on the host computer. + +Running the MoveIt2 Docker Image in a Container +----------------------------------------------- + +After building the image, you can see the newly-built image by running: + +.. code-block:: console + + docker image list + +The output will look something like this: + +.. code-block:: console + + REPOSITORY TAG IMAGE ID CREATED SIZE + openrobotics/moveit2 latest 6edb2edc9643 10 hours ago 15.5GB + openrobotics/spaceros latest 629b13cf7b74 12 hours ago 7.8GB + nvidia/cudagl 11.4.1-devel-ubuntu20.04 336416dfcbba 1 week ago 5.35GB + +The new image is named openrobotics/moveit2:latest. + +There is a run.sh script provided for convenience that will run the spaceros image in a container. + +.. code-block:: console + + ./run.sh + +Upon startup, the container automatically runs the entrypoint.sh script, which sources the MoveIt2 and Space ROS environment files. You'll now be running inside the container and should see a prompt similar to this: + +.. code-block:: console + + spaceros-user@8e73b41a4e16:~/moveit2# + +Running MoveIt2 Tutorials +------------------------- + +Run the following command to launch the MoveIt2 tutorials demo launch file: + +.. code-block:: console + + ros2 launch moveit2_tutorials demo.launch.py rviz_tutorial:=true + +You should see lots of console output and the rviz2 window appear: + +.. image:: ../images/rviz2-window.png + +You can now follow the `MoveIt2 Tutorial documentation `_ + +Running the MoveIt2 Move Group C++ Interface Demo +------------------------------------------------- + +To run the Move Group C++ Interface Demo, execute the following command: + +.. code-block:: console + + ros2 launch moveit2_tutorials move_group.launch.py + +.. image:: ../images/move-group-demo.png + +Then, you can follow the `Move Group C++ Interface Demo documentation `_ + +Running the Space ROS Space Robots Demos +---------------------------------------- + +Once you have tested that MoveIt2 works, you are ready to run some of the other `Space ROS space robot demos `_ diff --git a/source/Getting-Started/.Building-From-Source.rst.swp b/source/Getting-Started/.Building-From-Source.rst.swp new file mode 100644 index 0000000..a89e88d Binary files /dev/null and b/source/Getting-Started/.Building-From-Source.rst.swp differ diff --git a/source/Getting-Started/Building-From-Source.rst b/source/Getting-Started/Building-From-Source.rst index 6c17b58..0c83fb3 100644 --- a/source/Getting-Started/Building-From-Source.rst +++ b/source/Getting-Started/Building-From-Source.rst @@ -1,3 +1,5 @@ +Building Space ROS from Source + Building Space ROS from Source ============================== diff --git a/source/Tutorials/First-Time-Building.rst b/source/Tutorials/First-Time-Building.rst index d49dd28..50c7a0a 100644 --- a/source/Tutorials/First-Time-Building.rst +++ b/source/Tutorials/First-Time-Building.rst @@ -3,10 +3,6 @@ First Time Building Space ROS ============================= -.. contents:: Table of Contents - :depth: 1 - :local: - **Goal:** Create a workspace using Earthly for development and testing. **Tutorial level:** Beginner @@ -40,10 +36,7 @@ The configured ``+build-testing`` target is comprehensive and always builds and Even on a powerful workstation this process can take a long time. This tutorial does not cover iterating on an individual package or set of packages at this time. -Tasks ------ - -1 Create a local workspace directory +Create a local workspace directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: console @@ -51,52 +44,277 @@ Tasks mkdir spaceros_ws cd spaceros_ws -2 Bootstrap the Earthly configuration file. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Clone the repository +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + git clone https://github.com/space-ros/space-ros + +The Earthfile configuration in this directory facilitates builds of Space ROS from source code. The generated container image is based on Ubuntu 22.04 (Jammy) + +Building the Docker Image +------------------------- + +To build the image, run: + +.. code-block:: console + + cd space-ros + ./build.sh + +The build process will take about 20 or 30 minutes, depending on the host computer. + +The build will use the local `ros2.repos `_ file, and will pick up any local modifications. The ros2 repos file can be regenerated or updated using the build target, + +.. code-block:: console + + earthly build +repos-file + +Running the Space ROS Docker Image in a Container +------------------------------------------------- + +After building the image, you can see the newly-built image by running: + +.. code-block:: console + + docker image list + +The output will look something like this: + +.. code-block:: console + + $ docker image list + REPOSITORY TAG IMAGE ID CREATED SIZE + osrf/space-ros latest 109ad8fb7460 4 days ago 2.45GB + ubuntu jammy a8780b506fa4 5 days ago 77.8MB + +The new image is named osrf/space-ros:latest. -Configuration for Earthly is stored in an ``Earthfile`` at the top level directory. -If you inspect the contents, you'll find a file which looks like a hybrid of a ``Dockerfile``/``Containerfile`` and a ``Makefile``. -It is not necessary to understand the contents of this file in order to complete this tutorial or use Earthly for Space ROS development but you can read the `Earthfile reference `__ if interested. +There is a run.sh script provided for convenience that will run the spaceros image in a container. .. code-block:: console - earthly --artifact github.com/space-ros/docker/spaceros:nuclearsandwich/earthly-prototyping+earthfile/Earthfile + ./run.sh -3 Clone Space ROS sources -^^^^^^^^^^^^^^^^^^^^^^^^^ +Upon startup, the container automatically runs the entrypoint.sh script, which sources the Space ROS environment file (setup.bash). -In a typical ROS 2 or Space ROS development setup, you would need to configure the ROS repositories on your host system and install the ``vcs`` utility. -With Earthly this utility and the others required for ROS development are installed and used within containers, avoiding this requirement. -The ``+sources`` target will use ``vcs`` to clone repositories from the Space ROS repos file and save the results to the ``src`` subdirectory of your host workspace. +You'll now be running inside the container and should see a prompt similar to this: .. code-block:: console - earthly +sources + spaceros-user@d10d85c68f0e:~/$ -4 Optionally update Space ROS sources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Space ROS is installed to the ``${SPACEROS_DIR}`` in ``/opt/spaceors``, if required, the ROS environment file can be manually sourced with: -If you want to check that Space ROS builds in its default configuration, you can jump to step 5 below and return after to verify that Space ROS's default configuration is currently building. +.. code-block:: console + + source "${SPACEROS_DIR}"/install/setup.bash + +At this point, you can run the ``ros2`` command line utility to make sure everything is working OK: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:~/$ ros2 + usage: ros2 [-h] [--use-python-default-buffering] Call `ros2 -h` for more detailed usage. ... + + ros2 is an extensible command-line tool for ROS 2. + + optional arguments: + -h, --help show this help message and exit + --use-python-default-buffering + Do not force line buffering in stdout and instead use the python default buffering, which might be affected by PYTHONUNBUFFERED/-u and depends on whatever stdout is interactive or not + + Commands: + action Various action related sub-commands + component Various component related sub-commands + daemon Various daemon related sub-commands + doctor Check ROS setup and other potential issues + interface Show information about ROS interfaces + launch Run a launch file + lifecycle Various lifecycle related sub-commands + multicast Various multicast related sub-commands + node Various node related sub-commands + param Various param related sub-commands + pkg Various package related sub-commands + run Run a package specific executable + service Various service related sub-commands + topic Various topic related sub-commands + trace Trace ROS nodes to get information on their execution + + wtf Use `wtf` as alias to `doctor` + Call `ros2 -h` for more detailed usage. + + +Rebuilding Space ROS and running unit tests +------------------------------------------- + +Space ROS sources and intermediate build artifacts are not included in the docker image. + +A manifest of the exact sources used to produce the current image is saved as ``exact.repos`` in the ``/opt/spaceros directory``. To clone all sources from this manifest you can use the command sequence + +.. code-block:: console + + spaceros-user@d10d85c68f0e:~/$ cd /opt/spaceros + spaceros-user@d10d85c68f0e:/opt/spaceros$ mkdir src + spaceros-user@d10d85c68f0e:/opt/spaceros$ vcs import src < exact.repos + +From there you can run a new build and any additional tests. + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON --no-warn-unused-cli + spaceros-user@d10d85c68f0e:/opt/spaceros$ colcon test --ctest-args -LE "(ikos|xfail)" --pytest-args -m "not xfail" + +The tests include running the static analysis tools clang_tidy and cppcheck (which has the MISRA 2012 add-on enabled). + +You can use colcon's ``--packages-select`` option to run a subset of packages. For example, to run tests only for the rcpputils package and display the output directly to the console (as well as saving it to a log file), you can run: + +.. code-block:: console -At this point you can make any modifications or additions to the repositories in src before continuing with the build. -Editing the sources now will allow you to test Space ROS builds with additional packages or with modifications to an existing package which could be used to test in progress development branches before they are merged. -None of the later steps of this tutorial will modify the contents of ``src``. + spaceros-user@d10d85c68f0e:/opt/spaceros$ colcon test --event-handlers console_direct+ --packages-select rcpputils +Viewing Test Output +------------------- -5 Building and testing Space ROS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The output from the tests are stored in XUnit XML files, named ``.xunit.xml``. After running the unit tests, you can scan the build directory for the various ``*.xunit.xml`` files. -The ``+build-testing`` target will build all packages in ``src`` and place the resulting ``install`` directory as well as a build results archive in ``log/build_results_archives``. -Any changes you make to the repositories in ``src`` will be reflected in each build. -It isn't currently possible to change the build arguments or limit which packages are built and tested without modifying the target directly. +For example, a clang_tidy.xunit.xml file looks like this: .. code-block:: console - earthly +build-testing + + + + + + + + + + + + + + + ... + +Connecting Another Terminal to a Running Docker Container +--------------------------------------------------------- + +Sometimes it may be convenient to attach additional terminals to a running Docker container. + +With the Space ROS Docker container running, open a second host terminal and then run the following command to determine the container ID: + +.. code-block:: console + + docker container list + +The output will look something like this: + +.. code-block:: console + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + d10d85c68f0e openrobotics/spaceros "/entrypoint.sh …" 28 minutes ago Up 28 minutes inspiring_moser + +The container ID in this case, is d10d85c68f0e. So, run the following command in the host terminal: + +.. code-block:: console + + docker exec -it d10d85c68f0e /bin/bash --init-file "install/setup.bash" + +You will then be at a prompt in the same running container. + +In place of the container ID, you can also use the automatically-generated container name ("inspiring_moser" in this case). + +Running an IKOS Scan +-------------------- + +IKOS uses special compiler and linker settings in order to instrument and analyze binaries. To run an IKOS scan on all of the Space ROS test binaries (which will take a very long time), run the following command at the root of the Space ROS workspace: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ CC="ikos-scan-cc" CXX="ikos-scan-c++" LD="ikos-scan-cc" colcon build --build-base build_ikos --install-base install_ikos --cmake-args -DSECURITY=ON -DINSTALL_EXAMPLES=OFF -DCMAKE_EXPORT_COMPILE_COMMANDS=ON --no-warn-unused-cli + +The previous command generates the instrumented binaries and the associated output in a separate directory from the normal Space ROS build; the command uses --build-base option to specify build_ikos as the build output directory instead of the default build directory. + +To run an IKOS scan on a specific package, such as rcpputils in this case, use the --packages-select option, as follows: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ CC="ikos-scan-cc" CXX="ikos-scan-c++" LD="ikos-scan-cc" colcon build --build-base build_ikos --install-base install_ikos --packages-select rcpputils --cmake-args -DSECURITY=ON -DINSTALL_EXAMPLES=OFF -DCMAKE_EXPORT_COMPILE_COMMANDS=ON --no-warn-unused-cli + +Generating IKOS Results +----------------------- + +To generate JUnit XML/SARIF files for all of the binaries resulting from the build command in the previous step, you can use colcon test, as follows: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ colcon test --build-base build_ikos --install-base install_ikos --ctest-args -L "ikos" + +To generate a JUnit XML file for a specific package only, you can add the --packages-select option, as follows: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ colcon test --build-base build_ikos --install-base install_ikos --ctest-args -L "ikos" --packages-select rcpputils + +The ``colcon test`` command with the ``-L "ikos"`` flag runs IKOS report generation, which reads the IKOS database generated in the previous analysis step and generates a JUnit XML report file. After running ``colcon test``, you can view the JUnit XML files. For example, to view the JUnit XML file for IKOS scan of the rcpputils binaries you can use the following command: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ more build_ikos/rcpputils/test_results/rcpputils/ikos.xunit.xml + +SARIF files are also available in the same path: + +.. code-block:: console + + spaceros-user@d10d85c68f0e:/opt/spaceros$ more build_ikos/rcpputils/test_results/rcpputils/ikos.sarif + +Saving build artifacts locally +------------------------------ + +``./build.sh`` script executes the Earthly ``build`` task defined in ``Earthfile``, which copies specified artifacts from the container to the host. Additional tasks defined in the Earthfile enable the preservation of intermediate artifacts generated during the build process. + +For instance, the ``vcs-exact`` task can be utilized to copy the exact version of ROS packages pulled during the spaceros build. + +To invoke a task, use the following syntax: + +.. code-block:: console + + earthly +TASK_NAME + +Example: + +.. code-block:: console + earthly +vcs-exact -Summary and conclusion ----------------------- +Refer to the `Earthfile `_ for tasks that save artifacts locally on the host. Such tasks end with the ``SAVE ARTIFACT .. AS LOCAL`` syntax. -* Earthly can help you get started by quickly setting up a container environment for building Space ROS yourself and replicating the periodic builds running on Space ROS infrastructure. -* Earthly does not help set up your host computer to develop or run Space ROS directly. diff --git a/source/images/move-group-demo.png b/source/images/move-group-demo.png new file mode 100644 index 0000000..9207ece Binary files /dev/null and b/source/images/move-group-demo.png differ diff --git a/source/images/rviz2-window.png b/source/images/rviz2-window.png new file mode 100644 index 0000000..1472f46 Binary files /dev/null and b/source/images/rviz2-window.png differ