diff --git a/source/Demos/Canadarm.rst b/source/Demos/Canadarm.rst index 93e1ff2..a72c01c 100644 --- a/source/Demos/Canadarm.rst +++ b/source/Demos/Canadarm.rst @@ -1,7 +1,10 @@ Canadarm Demo ============= -TODO: +`Prequiste`: Ensure `space_robots `_ has been cloned. -Describe how to run the Canadarm demo. -This may be simply a link to the demo repo that provides the instructions. +The Canadarm demo is located in the `demos repository `_ of Space ROS. Simply clone the repository, then: + +``` +ros2 launch canadarm canadarm.launch.py +``` diff --git a/source/Demos/Mars-Rover.rst b/source/Demos/Mars-Rover.rst index bcdc603..2dace2a 100644 --- a/source/Demos/Mars-Rover.rst +++ b/source/Demos/Mars-Rover.rst @@ -1,7 +1,10 @@ Mars Rover Demo =============== -TODO: +`Prequiste`: Ensure [space_robots](https://github.com/space-ros/docker/tree/main/space_robots) has been cloned. -Describe how to run the Mars rover demo. -This may be simply a link to the demo repo that provides the instructions +The Mars Rover demo is located in the [demos repository](https://github.com/space-ros/demos/tree/main/mars_rover) of Space ROS. Simply clone the repository, then: + +``` +ros2 launch mars_rover mars_rover.launch.py +``` diff --git a/source/Getting-Started/Building-From-Source.rst b/source/Getting-Started/Building-From-Source.rst index 6c17b58..d802cc8 100644 --- a/source/Getting-Started/Building-From-Source.rst +++ b/source/Getting-Started/Building-From-Source.rst @@ -1,6 +1,27 @@ Building Space ROS from Source ============================== -TODO: +There are multiple ways to acquire docker images within the Space ROS ecosystem. -Describe how to build Space ROS from source code (presumably using Earthly). +As a prerequisite ensure that docker is `installed `_. + +1. Local Dockerfiles +--------------------- + +Within the Space ROS organization there is repository full of `docker images `_. There is also a repository containing the install of `Space ROS `_. To install either locally, clone the wanted repository. + +For Example: + +``` +git clone https://github.com/space-ros/docker.git +``` +or +``` +git clone https://github.com/space-ros/space-ros.git +``` + +From there navigate to the wanted package, build, and run. + +``` +./build.sh && ./run.sh +``` diff --git a/source/Getting-Started/Docker-Images.rst b/source/Getting-Started/Docker-Images.rst index e1822e1..9f63b3f 100644 --- a/source/Getting-Started/Docker-Images.rst +++ b/source/Getting-Started/Docker-Images.rst @@ -1,9 +1,27 @@ The Space ROS Docker Images =========================== -TODO: +There are multiple ways to acquire docker images within the Space ROS ecosystem. -Describe how to use the Space ROS docker image from Docker Hub, and any other images published to Docker Hub. +As a prerequisite ensure that docker is `installed `_. + +1. Docker Hub +------------- + +Docker Hub is a collection of various groups and images within the Docker ecosystem. +Space ROS has it's own `collection of images `_ +To install a version of Space ROS simply: + +``` +docker pull osrf/space-ros:{tag} +``` + +Then run the image with: + +``` +docker run --rm -it --name osrf_space-ros --network host \ + -e DISPLAY -e TERM -e QT_X11_NO_MITSHM=1 osrf/space-ros:{tag}` +``` + +You can install other packages like `moveit2 `_ and `navigation2 `_ with their packages on Docker Hub, using the same commands, just replacing them with the correct organization and image names. -* Docker Hub -* Base image, MoveIt2, demos, etc. diff --git a/source/How-To-Guides/Use-Custom-Allocator.rst b/source/How-To-Guides/Use-Custom-Allocator.rst index d0fd888..97a0df7 100644 --- a/source/How-To-Guides/Use-Custom-Allocator.rst +++ b/source/How-To-Guides/Use-Custom-Allocator.rst @@ -1,8 +1,41 @@ Using a Custom Memory Allocator with Space ROS ============================================== +This guide breaks down a demo using a custom C++ memory allocator within the Space ROS system. + +.. contents:: Table of Contents + :depth: 1 + :local: + +Introduction +------------ +Within the Demos section of the Space ROS ecosystem there is an `example `__ of using C++17 style allocators with Space ROS. +During the release of C++17, developers of the C++ STL felt it would be important to increase one's ability to allocate memory dynamically opposed to strictly staticly. Thus they created the `polymorphic_allocator `__which had different allocation behavior. We are able to use various customizable allocation methods within a common type. + +Running the Demo +---------------- +The best way to visualize the memory allocator in action is to run the demo associated with it. +First clone the demos repository to gain access to the Space ROS package that is the memory_allocator. + +..code-block:: console + + git clone https://github.com/space-ros/demos.git + +Then navigate to the `spaec_ros_memory_allocation_demo` section of the repository to launch the ROS nodes. Remove the `COLCON_IGNORE` and build. + +..code-block:: console + + rm -rf COLCON_IGNORE + colcon build + source install/setup.zsh + +We can then build out the talker/listener node pair to showcase the memory allocator, run: + +..code-block:: console + + ros2 run space_ros_memory_allocation_demo talker_listener.launch.xml + TODO: -* How to use a custom memory allocator with Space ROS. * How to use the memory_tools package to confirm that no additional memory is allocated via other means beyond the supplied allocator. diff --git a/source/How-To-Guides/Use-Simulation-Assets.rst b/source/How-To-Guides/Use-Simulation-Assets.rst index d9a207f..547a215 100644 --- a/source/How-To-Guides/Use-Simulation-Assets.rst +++ b/source/How-To-Guides/Use-Simulation-Assets.rst @@ -1,7 +1,61 @@ Using Space-Related Simulation Assets ===================================== -TODO: +This guide explains how to import assests from the Space ROS ecosystem into your simulations. -How to use the provided simulation assets in a new project. +.. contents:: Table of Contents + :depth: 1 + :local: +Introduction +------------- +Most isolated assets within Space-ROS are contained in the `simulation `__ repository. These assets are models which many space projects utilize like the `canadarm `__, which has a `demo `__ dedicated just for it. + +Importing a model +----------------- +Importing a model can be done similarly in almost any project by using a standard ROS 2 launch file. Simply clone the ``simulation`` repository, create a new launch file, find the simulation repository, get the model path, then load with ``xacro``. + +Ensure you have a valid workspace with a launch folder + +.. code-block:: console + + mkdir ~p ./asset_ws/launch + cd ./asset_ws/launch + touch asset.launch.py + +A basic launch file should look similar to the `canadarm demo `__: + +A set of basic imports: + +.. code-block:: python + + from http.server import executable + from launch import LaunchDescription + from launch.actions import DeclareLaunchArgument, ExecuteProcess, RegisterEventHandler + from launch.substitutions import TextSubstitution, PathJoinSubstitution, LaunchConfiguration, Command + from launch_ros.actions import Node + from launch_ros.substitutions import FindPackageShare + from launch.event_handlers import OnProcessExit, OnExecutionComplete + import os + from os import environ + + from ament_index_python.packages import get_package_share_directory + + import xacro + +Finding the now cloned simulation repository: + +.. code-block:: python + + def generate_launch_description(): + simulation_models_path = get_package_share_directory('simulation') + +Locating and loading the path of the asset we want to import: + +.. code-block:: python + + urdf_model_path = os.path.join(simulation_models_path, 'models', 'canadarm', 'urdf', 'SSRMS_Canadarm2.urdf.xacro') + doc = xacro.process_file(urdf_model_path, mappings={'xyz' : '1.0 0.0 1.5', 'rpy': '3.1416 0.0 0.0'}) + robot_description = {'robot_description': doc.toxml()} + +From here your asset can be utilized in a world within gazebo to do thorough testing.. diff --git a/source/Introduction/Dev-And-Release-Model.rst b/source/Introduction/Dev-And-Release-Model.rst index a285e43..79d7196 100644 --- a/source/Introduction/Dev-And-Release-Model.rst +++ b/source/Introduction/Dev-And-Release-Model.rst @@ -1,11 +1,17 @@ The Space ROS Development and Release Model =========================================== -TODO: +Background Information +---------------------- +Space ROS is meant to be a stable distribution of ROS 2 and similar robotics tools to interact with safety critical space systems. Thus, the Space ROS organization does main stable releases in the form of snapshots every 3 months. These releases contained updated repositories for the docker, demos, simulation, docs, and process_sarif on top of valid docker images on `docker hub `__, they can be seen in the three month differences in ``TAG`` numbers. -Describe the development and release model for Space ROS. For example, +Release Process +--------------- +Space ROS is entirely open source, meaning contributions are always welcome and always tracked. Within the `Space ROS organization `__ there is a project board and main issue which tracks each release. +For instance the October 2024 release has a `project board `__ and a matching `space-ros issue `__. These tools track steps for before, during, at the end, and after the release all in a neat location, allowing contributors to pick problems in an organized way. -* How we target Humble’s release track -* How contributions are made to Space ROS -* When to target upstream -* Handling changes unique to Space ROS +Unique Changes +-------------- +The beneficial part of open source code is being able to change a repository to fit your own needs. If there are changes which would be applied best to Space ROS on its own, you can push the changes to a seperate branch, then utilize that branch in the ``repos`` list. For example ``ament_lint`` has a seperate branch just for space-ros: + +https://github.com/space-ros/space-ros/blob/main/ros2.repos#L23-#L26 diff --git a/source/The-Space-ROS-Project/Contributing.rst b/source/The-Space-ROS-Project/Contributing.rst index 0911c4e..168c543 100644 --- a/source/The-Space-ROS-Project/Contributing.rst +++ b/source/The-Space-ROS-Project/Contributing.rst @@ -7,4 +7,8 @@ Contributing :depth: 1 :local: -To contribute to the Space ROS and ROS 2 projects please refer to the `ROS 2 contributing guidelines `__. +To contribute to the Space ROS and ROS 2 projects please refer to the `ROS 2 contributing guidelines `_. + +Space ROS has a slew of issues to be addressed, most issues are addressed the `Space ROS Project Development `_. + +New Contributors may find a list of good issues `here `_. diff --git a/source/Tutorials/Eventing-And-Telemetry.rst b/source/Tutorials/Eventing-And-Telemetry.rst index 0a9e44f..6080207 100644 --- a/source/Tutorials/Eventing-And-Telemetry.rst +++ b/source/Tutorials/Eventing-And-Telemetry.rst @@ -3,4 +3,6 @@ The Eventing and Telemetry Subsystem TODO: -Describe the Space ROS Eventing and Telemetry Subsystem. +- Create the Eventing and `Telemetry Subsystem `__ +- Describe the Space ROS Eventing and Telemetry Subsystem. +- Define the relationship between the detailed FRETish language and code generation tools like ``ogma`` diff --git a/source/Tutorials/Requirements-Tools-And-Processes.rst b/source/Tutorials/Requirements-Tools-And-Processes.rst index b9de8cf..808f052 100644 --- a/source/Tutorials/Requirements-Tools-And-Processes.rst +++ b/source/Tutorials/Requirements-Tools-And-Processes.rst @@ -1,8 +1,135 @@ +.. _Requirements-Tools-And-Processes: + Requirements Tools and Processes ================================ -TODO: +.. contents:: Table of Contents + :depth: 1 + :local: + +**Goal:** Utilize Doorstop and FRET to create, analyze, and stabilize requirements for a project. +**Tutorial level:** Beginner + +**Time:** 10 minutes (not including build time) + +Prerequisites +------------- + +* `Install Doorstop `__ +* `Install FRET `__ +* `Clone Requirements Repository `__ + +Introduction +------------ + +Writing requirements is essential to the development of safety-critical systems, leading to a clear definition of how the system needs to function. Acting as guidelines to that system, it's imperative that requirements aren't ambigious, which can be difficult as they are usually written in formal language. +The system Space ROS uses is meant to be a sync, in which the user writes natural languagerequirements in either yaml or markdown, which is processed and version controlled by :doc:`Doorstop <../Related-Projects/Doorstop.rst>`, then converted to viable code through the :doc:`FRET <../Related-Projects/FRET.rst>` pipeline. +"The creation and integration of these monitors is intended +to be as seamless as possible; the properties to be monitored are written in FRETish, and +little to no code is required to be written by hand." + +Tasks +----- +1. Create a Parent Document +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``Doorstop`` begins each of its projects with a main yaml control file to make unity easy. +First, head to the top of your working directory, using the requirements repository you should end up with this tree. + +.. code-block:: console + + ets/ + └── docs/ + ├── system_requirements/ + └── .doorstop.yml + ├── SYSTEM001.md + ├── SYSTEM002.md + ├── ... + ├── SYSTEM073.md + +This mimics the essential command each ``Doorstop`` project starts with, which is creating that top level document. This set of requirements can be then be added to any version control system through ``git`` which allows us to trace, blame, and see the development of our requirements. + +.. code-block:: console + + doorstop create SYSTEM ./system_requirements + +1.1 Analyze .doorstop.yml +^^^^^^^^^^^^^^^^^^^^^^^^^ +A look into the ``.doorstop.yml`` file should reveal the following: + +.. code-block:: yaml + + settings: + digits: 3 + itemformat: markdown + prefix: SYSTEM + sep: '' + +These 4 settings will affect the rest of the document for the duration of the project. + +* **digits** -- The number of digits in an Item UID, seen in the 3 numbers after SYSTEM in each markdown file. +* **itemformat** -- The supported file type that can be converted into FRETish language, either ``yaml`` or ``markdown``. +* **prefix** -- The parent document's prefix, a read-only setting, in our case it is ``SYSTEM``. +* **sep** -- The separator between each document prefix and the number, in our case there is no separator between SYSTEM and the 3 digits. + +1.2 Analyze Requirements Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A look into any of the requirements files like ``SYSTEM001.md``, should showcase the shown format: + +.. code-block:: markdown + + --- + active: true + derived: false + level: 1 + links: [] + normative: true + ref: '' + reviewed: none + --- + + The ETS shall store events that occur in the spacecraft. + +* **active** -- Determines if the item should be published during export, a boolean. +* **derived** -- Determines if the item was derived, a boolean. +* **level** -- Determines the presentation order within the document as a whole, a float. +* **links** -- A list of links to parent item(s), along with the relationship of those items. +* **normative** -- Determines if the item is part of the standard, a boolean. +* **ref** -- A reference to an external file which needs to be established. +* **reviewed** -- Determines if the item has been reviewed, along with the fingerprinted hash alorgithm, a Base64 encoding. + +2. Export the Information to FRETish Language +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Now that we have a slew of requirements, our system guidelines must be exported to a format which FRET can read. + +.. code-block:: console + + doorstop export SYSTEM ./system.csv + +3. Import Requirements to FRET +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the ``Fret`` GUI we can take advantage of our requirements in ``.csv`` form in order to analyze them. Enter the ``Fret`` repository after it was installed earlier, then open the GUI. + +.. code-block:: console + + cd fret-electron + npm start + +The FRET GUI will begin with just a basic untitled project, so we must create a project, we can create a new one when we import our list of requirements. On the left side bar, select the import option (the downward facing arrow), then import the ``system.csv`` file. Complete the following settings by default: + +* **Requirement ID** -- ``uid`` +* **Requirement Description** -- ``text`` +* **Project ID** -- Create new Project +* **Project ID Name** -- Create a custom a name + +Your FRET page should look similar to the following, from here we can begin to analyze our requirements. + +.. image:: ../images/fret-gui.png + + +* Red bubbles indicate requirements that aren't expressed in correct FRETish and therefore aren't formalized. +* Green bubbles have been correctly parsed in FRETish and formalized. +* White bubbles indicate requirements that are empty or that have been entered within quotes, indicating that parsing in FRETish has not been attempted. + +After importing a requirements list like the original ETS system, most of the bubbles will be white, that is because FRETish requirements are more detailed than basic requirements. Requirements through Doorstop are meant to be either functional or nonfunctional, in which functional documents can be synched to FRET and be imporved in detail. This can be seen in OSRF's management of requirements flow chart. -* Describe the overall vision -* Walk through how to use Doorstop and FRET -* Describe our existing examples of using Doorstop (and FRET) +.. image:: ../images/osrf-flow.png diff --git a/source/Tutorials/Run-On-RTEMS.rst b/source/Tutorials/Run-On-RTEMS.rst index 6ef782e..8da5232 100644 --- a/source/Tutorials/Run-On-RTEMS.rst +++ b/source/Tutorials/Run-On-RTEMS.rst @@ -1,8 +1,131 @@ Running Space ROS on RTEMS ========================== -TODO: +.. contents:: Table of Contents + :depth: 1 + :local: -* Provide some background on RTEMS -* Describe how to run Space ROS on RTEMS +**Goal:** Create a real-time embedded application using the pairing of RTEMS and the Zynq FPGA +**Tutorial level:** Intermediate +**Time:** 10 minutes (not including build time) + +Background +---------- + +This demonstration will be on `QEMU `_, the open-source CPU and system emulator. This is for a couple reasons: + * Using an Emulator reduces costs of using hardware and can be checked with any system. + * Cycles with QEMU are faster than their hardware counterparts. + +`RTEMS `_ was selected because of its open-source nature and the constant use in `space applications `_. +RTEMS is a an operating system, hense RTOS (Real Time Operating System), supporting various standard APIs. + +Ensure Docker is installed on your system. + +Build +----- + +To simplify collecting and compiling dependencies on a wide range of systems, we have created a Docker container that contains everything. + +.. code-block:: console + cd /path/to/zynq_rtems + ./build_dependencies.sh + +This will build the `zynq_rtems Dockerfile `_, which builds QEMU, a cross-compile toolchain for the ARMv8 processor inside the Zynq SoC, and RTEMS from source in the container. +This will typically take at least 10 minutes, and can take much longer if either your network connection or compute resources is limited. + +Next, we will use this "container full of dependencies" to compile a sample application. + +.. code-block:: console + cd /path/to/zynq_rtems + ./compile_demos.sh + +The demo application and its cross-compiled RTEMS kernel will be accessible both "inside" and "outside" the container for ease of source control, editing cycles, and debugging. +The build products will land in `zynq_rtems/hello_zenoh/build`. + +Run +------------- + +The emulated system that will run inside QEMU needs to have a way to talk to a virtual network segment on the host machine. +We'll create a TAP device for this. +The following script will set this up, creating a virtual `10.0.42.x` subnet for a device named `tap0`: +.. code-block:: console + ./start_network_tap.sh +We will need three terminals for this demo: + * Zenoh router + * Zenoh subscriber + * Zenoh-Pico publisher (in RTEMS in QEMU) + +First, we will start a Zenoh router: +.. code-block:: console + cd /path/to/zynq_rtems + cd hello_zenoh + ./run_zenoh_router +This will print a bunch of startup information and then continue running silently, waiting for inbound Zenoh traffic. Leave this terminal running. + +In the second terminal, we'll run the Zenoh subscriber example: +.. code-block:: console + cd /path/to/zynq_rtems + cd hello_zenoh + ./run_zenoh_subscriber +In the third terminal, we will run the RTEMS-based application, which will communicate with the Zenoh router and thence to the Zenoh subscriber. +The following script will run QEMU inside the container, with a volume-mount of the `hello_zenoh` demo application so that the build products from the previous step are made available to the QEMU that was built inside the container. +.. code-block:: console + cd /path/to/zynq_rtems + cd hello_zenoh + ./run_rtems.sh +The terminal should print a bunch of information about the various emulated Zynq network interfaces and their routing information. +After that, it should contact the `zenohd` instance running in the other terminal. It should print something like this: + +.. code-block:: console + Opening zenoh session... + Zenoh session opened. + Own ID: 0000000000000000F45E7E462568C23B + Routers IDs: + B2FE444C3B454E27BCB11DF83120D927 + Peers IDs: + Stopping read and lease tasks... + sending a few messages... + publishing: Hello, world! 0 + publishing: Hello, world! 1 + publishing: Hello, world! 2 + publishing: Hello, world! 3 + publishing: Hello, world! 4 + publishing: Hello, world! 5 + publishing: Hello, world! 6 + publishing: Hello, world! 7 + publishing: Hello, world! 8 + publishing: Hello, world! 9 + Closing zenoh session... + Done. Goodbye. +The second terminal, running a Zenoh example subscriber, should print something like this: + +.. code-block:: console + Declaring Subscriber on 'example'... + [2022-12-06T21:41:11Z DEBUG zenoh::net::routing::resource] Register resource example + [2022-12-06T21:41:11Z DEBUG zenoh::net::routing::pubsub] Register client subscription + [2022-12-06T21:41:11Z DEBUG zenoh::net::routing::pubsub] Register client subscription example + [2022-12-06T21:41:11Z DEBUG zenoh::net::routing::pubsub] Register subscription example for Face{0, 5F6D54C4366D42EDB367F17A5A2CACCD} + Enter 'q' to quit... + >> [Subscriber] Received PUT ('example': 'Hello, world! 0') + >> [Subscriber] Received PUT ('example': 'Hello, world! 1') + >> [Subscriber] Received PUT ('example': 'Hello, world! 2') + >> [Subscriber] Received PUT ('example': 'Hello, world! 3') + >> [Subscriber] Received PUT ('example': 'Hello, world! 4') + >> [Subscriber] Received PUT ('example': 'Hello, world! 5') + >> [Subscriber] Received PUT ('example': 'Hello, world! 6') + >> [Subscriber] Received PUT ('example': 'Hello, world! 7') + >> [Subscriber] Received PUT ('example': 'Hello, world! 8') + >> [Subscriber] Received PUT ('example': 'Hello, world! 9') +After that output, the RTEMS shutdown will display the various RTEMS threads running and their memory usage. + +This showed that the Zenoh Pico client running in RTEMS successfully reached the Zenoh router running natively on the host. +Success! +This is a good thing. + +Clean up +------------- + +If you would like, you can now remove the network tap device that we created in the previous step: +.. code-block:: console + zynq_rtems/stop_network_tap.sh diff --git a/source/images/fret-gui.png b/source/images/fret-gui.png new file mode 100644 index 0000000..7ec9076 Binary files /dev/null and b/source/images/fret-gui.png differ diff --git a/source/images/osrf-flow.png b/source/images/osrf-flow.png new file mode 100644 index 0000000..5b1b419 Binary files /dev/null and b/source/images/osrf-flow.png differ