Creation of O3DE tutorials

source/Tutorials/Advanced/Simulators/O3DE/Installation-Ubuntu.rst

@@ -0,0 +1,226 @@
+Installation (Ubuntu)
+======================================
+
+**Goal:** Install Open 3D Engine (O3DE) from the .deb package and run a simulation using the O3DE-extras template.
+
+**Tutorial level:** Advanced
+
+**Time:** 20-30 minutes
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+
+Background
+-------------
+
+This tutorial will guide you through the steps to install Open 3D Engine (O3DE) from a .deb package and set up the O3DE-extras package for simulation on Ubuntu. The guide minimizes terminal use and focuses on GUI-based steps where possible.
+
+Prerequisites
+-------------
+
+It is recommended to understand basic ROS principles covered in the beginner :doc:`../../../../Tutorials`.
+In particular, :doc:`../../../Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace` and :doc:`../../../Beginner-Client-Libraries/Creating-Your-First-ROS2-Package` are useful prerequisites.
+
+Before you begin, ensure you have the following:
+
+- **ROS 2 installed**: The o3de-extras package assumes that ROS 2 is already installed on your system.
+
+Setting up O3DE from GitHub on Linux
+------------------------------------
+
+Step 1: Install Required Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First, install the necessary dependencies by running the following commands in your terminal:
+
+.. code-block:: bash
+
+   sudo apt-get update
+   sudo apt-get install -y build-essential ninja-build python3 python3-pip python3-venv \
+                           libglu1-mesa-dev libxcb-xinerama0 libxcb-xinput0 libxcb-xinput-dev \
+                           libfontconfig1 libssl-dev uuid-dev clang lld
+
+Step 2: Clone the O3DE Repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Next, clone the O3DE repository from GitHub:
+
+.. code-block:: bash
+
+   git clone https://github.com/o3de/o3de.git
+   cd o3de
+
+This command downloads the O3DE source code into a directory named ``o3de`` and changes the current working directory to it.
+
+Step 3: Configure the O3DE Project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. @TODO: Restricted in manifest file
+
+Run the ``cmake`` command to configure the project. This will generate the necessary build files in the ``build`` directory.
+
+.. code-block:: bash
+
+   cmake -B build/ -S . -G "Ninja Multi-Config"
+
+Here’s what each argument does:
+
+- ``-B build/``: Specifies the output directory for the build files.
+- ``-S .``: Specifies the source directory (current directory).
+- ``-G "Ninja Multi-Config"``: Specifies Ninja as the build system with multi-config support.
+
+If you experience any issues regarding the ``restricted.json`` file, try opening the ``o3de_manifest.json``:
+
+.. code-block:: bash
+
+   nano ~/.o3de/o3de_manifest.json
+
+then, remove the ``restricted`` list located in the file.
+
+Step 4: Set Up the Project Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before building the O3DE, you need to set up the project environment. Run the following script to do so:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh register --this-engine
+
+This command registers the engine, allowing you to create and manage projects with O3DE.
+
+Step 5: Build O3DE
+^^^^^^^^^^^^^^^^^^
+
+Now, build O3DE using the ``cmake`` command:
+
+.. code-block:: bash
+
+   cmake --build build/ --config profile
+
+This command builds O3DE in ``profile`` mode, which is recommended for development. You can replace ``profile`` with ``debug`` or ``release`` depending on your needs.
+
+
+Download and Install o3de-extras 
+----------------------------------
+
+Downloading a .zip package 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+   1. Navigate to the `o3de-extras GitHub repository <https://github.com/o3de/o3de-extras>`_.
+   2. Download the necessary files as a ZIP package. To do this, click the **Code** button on the repository's main page and select **Download ZIP**.
+   3. Once the ZIP file is downloaded, extract its contents to a folder of your choice.
+
+
+Setting up o3de-extras
+^^^^^^^^^^^^^^^^^^^^^^
+
+Now, you need to inform O3DE about the location of the extra assets in this repository by registering them. From the O3DE repository folder, you can register some or all of the extra assets using the ``o3de register`` command. Since these are optional assets, you may choose to register only those that you need. For example, to register a specific gem, use the following command:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh register --gem-path <o3de-extras>/Gems/<gem name>
+
+If you want to register all the gems, you can do so since the repository follows the standard O3DE compound repository structure, with all gems located in the ``<o3de-extras>/Gems`` directory. To register all gems at once, use:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh register --all-gems-path <o3de-extras>/Gems
+
+This process can be repeated for any other object types, if they exist:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh register --all-engines-path <o3de-extras>/Engines
+   ./scripts/o3de.sh register --all-projects-path <o3de-extras>/Projects
+   ./scripts/o3de.sh register --all-gems-path <o3de-extras>/Gems
+   ./scripts/o3de.sh register --all-templates-path <o3de-extras>/Templates
+   ./scripts/o3de.sh register --all-restricted-path <o3de-extras>/Restricted
+
+If you've registered a gem, which functions like a plugin or component within a project, and you wish to use it in your project, you need to enable it by using the ``o3de enable-gem`` command:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh enable-gem --gem-name <gem name> --project-name <project name>
+
+
+Setting Up and Running a Simulation
+------------------------------------
+
+Creating a New ROS 2 Project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Register the ROS 2 Project Template**:
+
+   Navigate to your O3DE directory and register the ROS 2 Project Template from the ``o3de-extras`` repository:
+
+   .. code-block:: bash
+
+      ./scripts/o3de.sh register --all-templates-path <path-to-o3de-extras>/Templates
+
+   This command registers all templates within the ``o3de-extras`` repository, including the ROS 2 Project Template.
+
+2. **Create a New Project**:
+
+   Create a new project using the ROS 2 Project Template:
+
+   .. code-block:: bash
+
+      ./scripts/o3de.sh create-project --project-name <project_name> --template-name Ros2ProjectTemplate --project-path <path-to-project-directory>
+
+   Replace ``<project_name>`` with your desired project name and ``<path-to-project-directory>`` with the directory where you want the project to be created.
+
+3. **Configure and build the Project**:
+
+   After creating the project, you need to cofigure and build it:
+
+   Navigate to your project directory:
+
+   .. code-block:: bash
+
+      cd <project_path>
+
+   .. code-block:: bash
+
+      cmake -B build/ -S . -G "Ninja Multi-Config"
+
+   .. code-block:: bash
+
+      cmake --build <path-to-build-directory> --target <project_name> Editor
+
+   Ensure the build completes without errors.
+
+Setting Up the SLAM Navigation Example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ROS 2 Project Template includes several example projects. In this tutorial, you will use the SLAM navigation example to simulate a robot performing SLAM and navigation tasks.
+
+1. **Navigate to the Example Directory**:
+
+   The SLAM navigation example is located in the following directory:
+
+   .. code-block:: bash
+
+      <project-directory>/Examples/slam_navigation
+
+2. **Run the Example**:
+
+   Launch the example by opening the O3DE Editor:
+
+   .. code-block:: bash
+
+      <path-to-o3de-directory>/build/bin/profile/Editor
+
+   Once in the Editor, open the SLAM navigation level by navigating to the ``Levels`` tab and selecting the SLAM navigation level.
+
+   Press ``Ctrl+G`` to start the simulation.
+
+3. **Launching ROS 2 Nodes**:
+
+   In a new terminal, source your ROS 2 environment and launch the ROS 2 nodes required for SLAM and navigation:
+
+   .. code-block:: bash
+
+      source /opt/ros/foxy/setup.bash
+      ros2 launch slam_navigation slam_navigation_launch.py
+
+   This command starts the ROS 2 nodes, enabling the robot in the simulation to perform SLAM and navigation.

source/Tutorials/Advanced/Simulators/O3DE/Setting-Up-Simulation-O3DE-Advanced.rst

@@ -0,0 +1,132 @@
+Setting up a robot simulation (Advanced)
+========================================
+
+**Goal:** Setup a robot simulation and control it from ROS 2.
+
+**Tutorial level:** Advanced
+
+**Time:** 30 minutes
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+
+Background
+----------
+
+In this tutorial, you will use the Open 3D Engine (O3DE) to set up and execute a ROS 2 robotic manipulation simulation.
+
+The ``o3de-extras`` repository offers additional tools and templates to enhance O3DE projects with ROS 2 functionality. In this tutorial, you will use the ``Ros2RoboticManipulationTemplate`` from the ``o3de-extras`` repository. This template provides a foundation for integrating ROS 2 with O3DE to simulate robotic manipulation tasks in a virtual environment. It includes predefined configurations and examples to demonstrate how to control and interact with robotic manipulators within O3DE.
+
+For detailed instructions and further examples on using the ROS 2 Robotic Manipulation Template, you can refer to the `O3DE ROS 2 Robotic Manipulation Template <https://github.com/o3de/o3de-extras/tree/development/Templates/Ros2RoboticManipulationTemplate>`_ page.
+
+
+Prerequisites
+-------------
+Ensure you have the following before starting:
+
+- O3DE set up on your machine. For instructions, follow the `O3DE installation for Ubuntu <Installation-Ubuntu>` guide.
+- ROS 2 (Foxy or later) installed on your system.
+- The ``o3de-extras`` repository cloned locally (on the ``stabilization`` branch).
+- **MoveIt**, which is used for motion planning in ROS 2. Follow the MoveIt 2 documentation for installation instructions.
+
+
+Creating a New ROS 2 Project
+----------------------------
+
+1. **Register the Template**:
+
+Register the template with O3DE so that it can be used to create a new project.
+
+From the root directory of your O3DE installation, run:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh register --all-templates-path <path_to_o3de_extras>/Templates
+
+This command registers all templates in the ``o3de-extras`` repository, including the Robotic Manipulation Template.
+
+2. **Create a New Project**:
+
+Create a new project using the ROS 2 Robotic Manipulation Template:
+
+.. code-block:: bash
+
+   ./scripts/o3de.sh create-project --project-name <project_name> --template-name Ros2RoboticManipulationTemplate --project-path <path-to-project-directory>
+
+This will generate a new project directory with the necessary files and configurations.
+
+3. **Install Dependencies**:
+
+Navigate to your project directory:
+
+.. code-block:: bash
+
+   cd <project_path>
+
+Install the required Python packages and dependencies for the project. Typically, you will need to install ROS 2 and MoveIt dependencies. This can often be done with:
+
+.. code-block:: bash
+
+   sudo apt install ros-${ROS_DISTRO}-moveit ros-${ROS_DISTRO}-moveit-resources ros-${ROS_DISTRO}-depth-image-proc
+
+Ensure that you also have any additional dependencies specified in the project's ``requirements.txt`` or equivalent configuration files.
+
+4. **Configure and build the Project**:
+
+After installing dependencies, cofigure and build the project using the following commands:
+
+.. code-block:: bash
+
+   cmake -B build/ -S . -G "Ninja Multi-Config"
+
+.. code-block:: bash
+
+   cmake --build <path-to-build-directory> --target <project_name> Editor
+
+Ensure the build completes without errors.   
+
+
+Configurations and launch of the project
+----------------------------------------
+
+1. **Configure ROS 2 and MoveIt**:
+
+The template may include configuration files for ROS 2 and MoveIt. Ensure these are properly configured to match your simulation setup. Key files include:
+
+- **ROS 2 Launch Files**: Typically found in the ``launch`` directory, configure these files to start the ROS 2 nodes required for your simulation.
+- **MoveIt Configuration**: Check the ``moveit_config`` directory for MoveIt configuration files. Ensure these files are correctly set up for your robot and planning requirements.
+
+2. **Launch the Simulation**:
+
+Start the O3DE Editor:
+
+.. code-block:: bash
+
+   <path-to-o3de-directory>/build/bin/profile/Editor
+
+In the O3DE Editor:
+
+1. Open the example level provided by the template. Navigate to the ``File`` menu, select ``Open Level``, and choose the example level from the ``Levels`` directory.
+2. Launch the ROS 2 nodes and MoveIt components required for the simulation. For manipulation, this can be done with:
+
+.. code-block:: bash
+
+   ros2 launch Examples/panda_moveit_config_demo.launch.py
+
+And for the palletization try:
+
+.. code-block:: bash
+
+   source install/setup.bash
+   ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur10 use_sim_time:=true use_fake_hardware:=true
+
+
+3. **Simulate Robotic Manipulation**:
+
+With the simulation running, you can interact with the robotic manipulator in the O3DE Editor. Test different manipulation tasks and adjust configurations as needed. Use the MoveIt interface to plan and execute robotic movements.
+
+For further details on configuring ROS 2 and MoveIt for your specific needs, refer to the `MoveIt 2 Documentation`_ and the `O3DE Robotics Project Configuration`_ guide.
+
+.. _MoveIt 2 Documentation: https://moveit.ros.org/documentation/
+.. _O3DE Robotics Project Configuration: https://development--o3deorg.netlify.app/docs/user-guide/interactivity/robotics/project-configuration/