update README and kraken_nav/README

CONTRIBUTING.md

@@ -13,7 +13,7 @@ When creating a pull request to this repository, make sure that:
   - If you commit parts of code which are not yours, make sure you are allowed to do so (in terms of license) and respect all the requirements of the license, such as Attribution.
   - If you are not the author of the commit, indicate authorship with `--author` flag of `git commit` command.
   - Try to divide your work into commits done by a single author. If you decide to use a single commit for a multi-author work, use the [Co-authored-by syntax](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) in the commit message.
-- Your commits are signed, indicating complience with the DCO: use `git commit -s` to ensure that.
+- Your commits are signed, indicating compliance with the DCO: use `git commit -s` to ensure that.
 
 ### Additional information
 

README.md

@@ -30,62 +30,64 @@ The integration is realized through [ROS 2 Gem](https://github.com/o3de/o3de-ext
 
 ### Main Level
 
-The main scene of the demo is set in an apple orchard surrounded by a countryside. The orchard is managed by the Apple
-Kraken.
+The main scene of the demo is set in an apple orchard surrounded by countryside. The orchard is managed by the Apple Kraken.
 
-The main level is rather performance intensive.
+The main level is rather performance-intensive.
 
-The Apple Kraken is a four-wheeled robot assigned the task of navigating around the orchard, collecting apples and
-storing them in its basket.
+The Apple Kraken is a four-wheeled robot assigned the task of navigating around the orchard, collecting apples and storing them in its basket.
 
 ### Playground Level
 
-The playground scene is much lighter and can be used to quickly prototype with Kraken. There is only a couple
-of apple trees and the robot itself.
+The playground scene is much lighter and can be used to quickly prototype with Kraken. There are only a couple of apple trees and the robot itself.
 
 # Requirements
 
 ## Platforms
 
-The project runs on Ubuntu 22.04 with ROS 2 Humble or ROS 2 Iron.
+The project runs on Ubuntu 22.04 with ROS 2 Humble or ROS 2 Iron. If you wish to run this demo in _Docker environment_, please use the [instructions](docker/README.md) in the `Docker` folder.
 
-💡 ***Note:*** This demo is **not supported on Windows!** 
+💡 ***Note:*** This demo is **not supported on Windows!**
 
 ## O3DE
 
-1. Refer to the [O3DE System Requirements](https://www.o3de.org/docs/welcome-guide/requirements/) documentation to make
-   sure that the system/hardware requirements are met.
-2. Please follow the instructions
-   to [set up O3DE from GitHub](https://o3de.org/docs/welcome-guide/setup/setup-from-github/).
-3. **Use the `main` branch**.
-
-The following commands should prepare O3DE:
-
-```
-~$ git clone --branch main --single-branch https://github.com/o3de/o3de.git
-~$ cd o3de
-~/o3de$ git lfs install
-~/o3de$ git lfs pull
-~/o3de$ python/get_python.sh
-~/o3de$ scripts/o3de.sh register --this-engine
+Refer to the [O3DE System Requirements](https://www.o3de.org/docs/welcome-guide/requirements/) documentation to make sure that the system/hardware requirements are met.
+
+The following commands should prepare O3DE (assuming `${WORKDIR}` is your working directory):
+```bash
+cd ${WORKDIR}
+git clone --branch main --single-branch https://github.com/o3de/o3de.git
+cd o3de
+git lfs install
+git lfs pull
+python/get_python.sh
+scripts/o3de.sh register --this-engine
 ```
 
+In case of any problems, please refer to the instructions to [set up O3DE from GitHub](https://o3de.org/docs/welcome-guide/setup/setup-from-github/).
+
 ## ROS 2 Gem
 
-This project uses the [ROS 2 Gem](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2).
-Please make sure to follow the installation guide
-in [ROS 2 Project Configuration](https://www.o3de.org/docs/user-guide/interactivity/robotics/project-configuration/).
-To learn more about how the Gem works check out
-the [Robotics in O3DE](https://www.o3de.org/docs/user-guide/interactivity/robotics/).
+This project uses the [ROS 2 Gem](https://github.com/o3de/o3de-extras/blob/development/Gems/ROS2), which is included in the [O3DE extras bundle](https://github.com/o3de/o3de-extras). Please [install ROS 2](https://docs.ros.org/en/dashing/Installation/Ubuntu-Install-Binary.html) first. 
 
-Note that the Gem instructions include installation of ROS 2 with some additional packages.
+The following commands should prepare `o3de-extras` into your `${WORKDIR}`:
+```bash
+cd ${WORKDIR}
+git clone --branch main --single-branch https://github.com/o3de/o3de-extras
+cd o3de-extras
+git lfs install
+git lfs pull
+```
+And register required Gem:
+```bash
+cd ${WORKDIR}
+./o3de/scripts/o3de.sh register --gem-path o3de-extras/Gems/ROS2
+```
 
-The Gem is open to your contributions!
+Please make sure to use the same version of `o3de` and `o3de-extras`. This demo was successfully tested with the `2310.1` release.
 
-### Registering the Gem
+More information about installing ROS 2 Gem can be found in the installation guide in [ROS 2 Project Configuration](https://www.o3de.org/docs/user-guide/interactivity/robotics/project-configuration/). Note that the Gem instructions include the installation of ROS 2 with some additional packages.
 
-During the step above, make sure to register the Gem in the engine:
-`scripts/o3de.sh register --gem-path <PATH_TO_CLONED_ROS2_GEM>`
+To learn more about how the Gem works check out the [Robotics in O3DE](https://www.o3de.org/docs/user-guide/interactivity/robotics/). The Gem is open to your contributions!
 
 ### Additional ROS 2 packages
 
@@ -99,16 +101,16 @@ sudo apt install ros-${ROS_DISTRO}-vision-msgs ros-${ROS_DISTRO}-nav-msgs ros-${
 
 ### Required environment settings
 
-Some commands and environmental variables are necessary for ROS 2 systems, including this demo, to function properly. It is best to add these commands and settings to either `~/.bashrc` or `~/.profile`.
+Some commands and environmental variables are necessary for ROS 2 systems, including this demo, to function properly. It is best to add these commands and settings to either `~/.bashrc` or equivalent file. 
 
-ROS 2 distribution and should always be sourced when building and running the demo and its command line interfaces. For a typical ROS 2 Iron installation, this would mean running the following for each console:
+ROS 2 distribution should always be sourced when building and running the demo and its command line interfaces. For a typical ROS 2 Iron installation, this would mean running the following for each console:
 
 ```
 source /opt/ros/iron/setup.bash
 ```
 💡 ***Note:*** ROS 2 Humble is also supported. In that case, the provided command would be `source /opt/ros/humble/setup.bash`
 
-Currently we are observing issues when running navigation with FastDDS (the default middleware for ROS 2 Humble and ROS 2 Iron). While the exact cause is yet to be investigated, there are no such issues when running with CycloneDDS. Thus, please set the following:
+Currently, we are observing issues when running navigation with FastDDS (the default middleware for ROS 2 Humble and ROS 2 Iron). While the exact cause is yet to be investigated, there are no such issues when running with CycloneDDS. Thus, please set the following:
 
 ```
 export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
@@ -120,61 +122,65 @@ export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
 
 1. Clone this project:
 
-```
+```bash
+cd ${WORKDIR}
 git clone https://github.com/o3de/ROSConDemo.git
 ```
 
-2. Register this project in O3DE engine. In O3DE directory:
-```
-scripts/o3de.sh register -pp <PATH_TO_THIS_PROJECT>
+2. Register this project in the O3DE engine. In O3DE directory:
+```bash
+cd ${WORKDIR}/o3de
+scripts/o3de.sh register -pp ${WORKDIR}/ROSConDemo/Project
 ```
 
 3. Ensure your [ROS 2 is sourced](https://docs.ros.org/en/rolling/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html):
 
-```
+```bash
 echo $ROS_DISTRO
 > iron
 ```
-💡 ***Note:*** ROS 2 Humble is also supported. In the case that ROS 2 Humble was sourced this command output will be `humble`
+💡 ***Note:*** In the case ROS 2 Humble is sourced, the output is `humble`.
 
 4. Configure build:
 
-```
+```bash
+cd ${WORKDIR}/ROSConDemo/Project
 cmake -B build/linux -G"Ninja Multi-Config" -DLY_DISABLE_TEST_MODULES=ON
 ```
 
 5. Execute build (this will take a while the first time):
 
-```
+```bash
+cd ${WORKDIR}/ROSConDemo/Project
 cmake --build build/linux --config profile --target ROSConDemo Editor AssetProcessor ROSConDemo.Assets
 ```
 
-## Launching the Editor
+## Building the Navigation package
+
+To build the ROS 2 navigation stack configured for this Project, please follow this [detailed document](kraken_nav/README.md). Do not run it yet if you wish to follow the demo scenario.
 
+## Launching the Editor
 
-Launch the O3DE Editor (in the Project directory):
+Launch the O3DE Editor:
 
-```
+```bash
+cd ${WORKDIR}/ROSConDemo/Project
 build/linux/bin/profile/Editor
 ```
 
-## Building the Navigation package
-
-To build the ROS 2 navigation stack configured for this Project, please follow this [detailed document](kraken_nav/README.md). Do not run it yet if you wish to follow the demo scenario.
-
 # Running the demo scenario
 
 You can try out the demo scenario as presented during ROSCon 2022. Take the following steps:
 
 1. Launch the Editor and select the Main level. Allow it to load.
-2. Run the simulation with `Ctrl-G` or by pressing the Play button in the Editor. 
+2. Start the simulation with `Ctrl-G` or by pressing the Play button in the Editor. 
 3. When it loads, spawn your first Apple Kraken using the following command: `ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_rusty', xml: 'line1'}'`.
    1. You can learn more about spawning in [this section](#spawning-krakens)
 3. Once the simulation is running, start the [navigation stack](kraken_nav/README.md). If you followed all the instructions for setting it up, do the following:
    1. launch the stack for the first robot with `ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_1 rviz:=True`. 
    1. You should see a new Rviz2 window.
    1. Note that the number index `_1` has been added to the namespace when it was automatically generated by the Spawner.
-4. Using RViz2, set the navigation goal using a widget in the toolbar (`2D Goal Pose`). You need to click and drag to indicate direction the robot will be facing. Make sure to set the goal next to an apple tree, to have the tree on the right side. Not too close, not too far. You can set subsequent goals for the robot to move around.
+4. Using RViz2, set the navigation goal using a widget in the toolbar (`2D Goal Pose`). You need to click and drag to indicate the direction the robot will be facing. Make sure to set the goal next to an apple tree, to have the tree on the right side. Not too close, not too far. You can set subsequent goals for the robot to move around.
    1. As configured in our package, RViz2 has additional `2D Goal Pose` buttons which are hard-set to work with specific robot namespaces.
    1. Use the button first to the left.
 5. Once the robot arrives and stops next to the tree, you can [trigger apple gathering](#triggering-apple-gathering).
@@ -184,9 +190,9 @@ You can try out the demo scenario as presented during ROSCon 2022. Take the foll
    1. `ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_shiny', xml: 'line2'}' &&
 ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_rusty', xml: 'line3'}' &&
 ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_shiny', xml: 'line4'}'`
-   1. You can also navigate with them using remaining `2D Goal Pose` buttons and trigger gathering events. Follow the instructions in [this section](kraken_nav/README.md#running-nav-stack-for-multiple-vehicles) to launch navigation stack for each Kraken.
+   1. You can also navigate with them using the remaining `2D Goal Pose` buttons and trigger gathering events. Follow the instructions in [this section](kraken_nav/README.md#running-nav-stack-for-multiple-vehicles) to launch the navigation stack for each Kraken.
 
-💡 ***Note:*** If you would like to start the scenario over, **remember to close all the navigation stacks as well**. You can do this by pressing Ctrl-C in each console where you ran the `ros2 launch o3de_kraken_nav (..)` command.
+💡 ***Note:*** If you would like to start the scenario over, **remember to close all navigation stacks**. You can do this by pressing Ctrl-C in each console you started the `ros2 launch o3de_kraken_nav (..)` command.
 
 ## Controlling the Apple Kraken
 
@@ -216,14 +222,14 @@ You can also cancel a gathering operation in progress by calling another service
 
 Please read the following section on [Robot Spawner](https://github.com/RobotecAI/o3de-ros2-gem/blob/development/docs/guides/ros2-gem.md#spawner).
 
-To spawn a new Apple Kraken, you can used named points (provided by a Spawner Component) or custom poses. 
+To spawn a new Apple Kraken, you can use named points (provided by a Spawner Component) or custom poses. 
 
 #### Available spawn aliases
 
-You can use the spawn service with following robot names:
+You can use the spawn service with the following robot names:
 - apple_kraken_rusty
 - apple_kraken_shiny
-- apple_kraken (defualts to shiny).
+- apple_kraken (defaults to shiny).
 These two robots are functionally the same.
 
 #### Available named spawn poses
@@ -243,29 +249,21 @@ Free pose:
 ```
 ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken', initial_pose: {position:{ x: 4, y: 4, z: 0.2}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}}'
 ```
-
-## How to use my robot in O3DE?
-
-You can follow up this [guide for re-creating the Apple Kraken prefab](docs/ImportingURDF/URDF_import_guide.md), starting with an URDF file.
-This can be very informative for a similar process with another robot.
-
 # Troubleshooting
 
 ## Check-list
 
 - Is O3DE running ok with an empty or default project?
 - Is ROS 2 installation ok? (check with `ros2 topic pub` etc.)
 - Is ROS 2 workspace sourced? (check `ROS_DISTRO`, `AMENT_PREFIX_PATH`)
-  - Note this needs to be true before cmake is ran. Re-run configuration and build when in doubt. 
-- Do you have compatible settings for crucial ENV variables when running the navigation / orchestration stack in the
-  console and when running the simulator?
+  - Note this needs to be true before `cmake` is run. Re-run configuration and build when in doubt. 
+- Do you have compatible settings for crucial ENV variables when running the navigation / orchestration stack in the console and when running the simulator?
     - check `RMW_IMPLEMENTATION`, `ROS_DOMAIN_ID` etc.
-- Check console for errors as well as logs. From the Project folder, check `user/log/Editor.log`.
+- Check the console for errors as well as logs. From the Project folder, check `user/log/Editor.log`.
 - Are simulation topics up when you play the simulation?
     - `ros2 node list` should include `/o3de_ros2_node`
     - `ros2 topic list` should include `/clock`, `/tf` and `/tf_static` regardless of robot presence.
-    - topic list should also include `/pc`, `/ackermann_vel` and `/ground_truth_3D_detection` if there is a robot in the
-      scene and simulation is running.
+    - topic list should also include `/pc`, `/ackermann_vel` and `/ground_truth_3D_detection` if there is a robot in the scene and the simulation is running.
         - note that these topics will be namespaced.
     - `ros2 service list` should also show several simulation and robot services such as spawning and apple gathering.