update README and kraken_nav/README (#272)

* update README and kraken_nav/README
* update preview.png image
* remove outdated URDF import guide
* code review: fix backtick

---------

Signed-off-by: Jan Hanca <[email protected]>
Co-authored-by: Artur Kamieniecki <[email protected]>

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
 

Project/preview.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:13e825d395c997ca41a7db98191b14d7d4b900329bf15a6ba91579abac4df61f
-size 6058
+oid sha256:6cbc85952e1ea83de0d51fbcd6a0c86b05913a4613538c13d4d7122af8eeb4c5
+size 148773

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,12 +249,6 @@ 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
@@ -256,16 +256,14 @@ This can be very informative for a similar process with another robot.
 - 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.
 

docs/ImportingURDF/URDF_import_guide.md

@@ -1,218 +0,0 @@
-# Importing your robot from URDF - a tutorial
- 
-[Unified Robot Definition Format](http://wiki.ros.org/urdf/XML) (URDF) is a standard for description of robots used widely in the ROS ecosystem.
-O3DE supports URDF through its ROS 2 Gem. The feature of URDF import is still in development.
-This document will guide you through the process of importing a robot and covers the steps necessary to make it mobile.
-
-## 1. Before you start
-
-- Follow the instructions in the [project README](https://github.com/o3de/ROSConDemo) to build and test the orchard demo project.
-- Examples in the demo use the .xacro extension, which is helpful for parametrization of robot definition. 
-To follow the guide, you need this package installed:
-```bash
-sudo apt install ros-$ROS_DISTRO-xacro
-```
-
-## 2. Prepare the URDF file
-
-First, we need to produce our URF file out of the .xacro file. This is typically done through running a command and specifying robot parameters.
-For this example, we will use default values.
-
-In `ROSConDemo` folder run:
-
-```bash
-cd Project/Assets/applekraken_urdf
-xacro apple_kraken.xacro > apple_kraken_new.urdf
-```
-
-## 3. Import URDF into O3DE
-
-Run the ROSConDemo O3DE project, load `Main` level and import `apple_kraken_new.urdf` file using `RobotImporter` button. 
-The `apple_kraken_new` prefab should appear in the `Entity Outliner`.
-
-The robot imported in this way should look correct and have all the parts included. 
-However, URDF format itself does not include specification of simulation behavior. To enable robot mobility, we need to set up the vehicle control.
-
-## 4. Set up the vehicle control
-
-In the `apple_kraken_new` prefab:
-
-1. Add a `Wheel controller` component to entities: `wheel_rear_right_link` and `wheel_rear_left_link`. Leave all settings default.
-2. Add a `Wheel controller` component to entities: `wheel_front_right_link` and `wheel_front_left_link`. Set the `Steering entity` to `steering_front_right_link` and `steering_front_left_link` respectively (by dragging these entities from the `Entity Outliner`). Leave other properties default.
-
-
-![](static/images/URDF_tutorial_Wheel_controller.png)
-
-
-3. In the `base_link` entity add a `Vehicle Model` component. In this component:
-    - Add 2 new axles by clicking `+` next to `Axles`. 
-    - In the first of these axles:
-      - Set `Axle tag` to `Front`
-      - Add 2 wheels by clicking `+` next to `Axle wheels`
-      - Set the first of these wheels to `wheel_front_left_link` and the second to `wheel_front_right_link` (by dragging these entities from the `Entity Outliner`). 
-      - Turn on `Is it a steering axle` switch.
-    - In the second of these axles:
-      - Set `Axle tag` to `Rear`
-      - Add 2 wheels by clicking `+` next to `Axle wheels`
-      - Set the first of these wheels to `wheel_rear_left_link` and the second to `wheel_rear_right_link` (by dragging these entities from the `Entity Outliner`). 
-      - Turn on the `Is it a drive axle` switch.
-    - In the `Drive model`/`Steering PID` set:
-      - `P`: `1000.0`
-      - `OutputLimit`: `200.0`
-    - In the `Drive model`/`Speed PID` set:
-      - `P`: `250.0`
-      - `I`: `150.0`
-      - `Imax`: `500.0`
-      - `OutputLimit`: `500.0`
-      - Turn on the `AntiWindUp` switch
-    - In the `Vehicle limits` set `Speed limit` to `3.0`
-    - Leave all the other settings default. The component should look like this:
-
-![](static/images/URDF_tutorial_Vehicle_Model.png)
-
-4. In the `base_link` entity select `ROS2 Robot control` component and change `Topic` to `ackermann_vel`, `Type` to `ackermann_msgs::msg::AckermannDrive` and `Steering` to `Ackermann`.
-
-![](static/images/URDF_tutorial_ROS2_Robot_Control.png)
-
-5. In the `base_link` entity add a `Ackermann Control` component. 
-6. In the `base_link` entity add a `Tag` component. Add 1 tag by clicking `+` next to `Tags` and set the name to `Robot`.
-7. In the `base_link` entity add an `Input` component and in the `Input to event bindings` field select `mobile_robot_control_keyboard.inputbindings`.
-
-![](static/images/URDF_tutorial_Tag_Input.png)
-
-In the following step, we will set properties for the manipulator so that it behaves better. Note that desired behavior can be achieved in other
-ways, but for the purpose of this demo we are going for a simple solution.
-
-## 5. Set collision layers and Rigid Body parameters
-
-- Browse each entity in the `apple_kraken_new` prefab and find all `PhysX Collider` components. Change `Collision Layer` to `Robot` in each.
-- Select the `PhysX Rigid Body` component and turn off `Gravity enabled` checkbox in following entities:
-    - `kraken_manipulator_link_1`
-    - `kraken_manipulator_link_2`
-    - `kraken_manipulator_link_3`
-    - `kraken_manipulator_link_4`
-    - `Effector`
-
-## 6. Test robot mobility
-
-Now it is a good time to test the robot. Check that the robot is located over the ground (but not too high) and set a camera to see the robot. 
-Click the Play button in the right-top corner of the O3DE window, or press `Ctrl G`.
-You should be able to control robot movement using arrow keys.
-
-URDF format by itself does not specify sensor behavior (unless through Gazebo extensions). Now, we will now add a LIDAR to our robot.
-
-## 7. Add LIDAR
-
-Select the `lidar_mount` entity in the `apple_kraken_new` prefab, open the right-click menu and select `Instantiate Prefab`.
-Select `ROSConDemo/Project/Prefabs/LidarKraken.prefab` and click `OK`. Enter the `LidarKraken` prefab, select `Sensor` entity and change:
-1. Set `Ignore layer` to `True`
-2. Set `Ignored layer index` to `1`
-
-![](static/images/URDF_tutorial_Lidar_Kraken.png)
-
-## 8. Test robot navigation
-
-Select `base_link` entity and change its name to `apple_kraken_rusty_1`.
-This step ensures that our namespace is the same as if the robot was spawned and as such compatible with the demo instructions.
-
-![](static/images/URDF_tutorial_base_link_name.png)
-
-Follow instructions in the [o3de_kraken_nav](https://github.com/o3de/ROSConDemo/blob/development/kraken_nav/README.md) to install the navigation stack.
-After the `Installation` part run the O3DE simulation (`ctrl-g`), switch to terminal and run the following commands:
-
-```bash
-source /opt/ros/$ROS_DISTRO/setup.bash
-cd ~/o3de_kraken_ws
-source ./install/setup.bash
-export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
-ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_1 rviz:=True
-```
-
-You should see something like this:
-
-![](static/images/URDF_tutorial_RViz_test.png)
-
-The following steps are dedicated to setting up the manipulator and fine-tuned parameters for its controllers:
-
-## 9. Set up the manipulator
-
-In the `apple_kraken_new` prefab:
-
-1. Open the `kraken_manipulator_link_1` entity and add a `MotorizedJoint` component:
-   - Set `ControllerLimits` to `0.6` and `2.2`
-   - Turn off the `Animation mode` switch
-   - Set `Zero off.` to `1.65`
-   - In `PidPosition` set:
-     - `P` to `1200.0`
-     - `D` to `600.0`
-     - `OutputLimit` to `500.0`
-   - Turn off the `SinusoidalTest` switch
-
-![](static/images/URDF_tutorial_manipulator_link1.png)
-
-2. Open the `kraken_manipulator_link_2` entity and add a `MotorizedJoint` component:
-   - Set `Joint Dir.` to `1.0, 0.0, 0.0`
-   - Set `ControllerLimits` to `-0.5` and `1.5`
-   - Turn off the `Animation mode` switch
-   - In `PidPosition` set:
-     - `P` to `1500.0`
-     - `D` to `600.0`
-     - `OutputLimit` to `500.0`
-   - Turn off the `SinusoidalTest` switch
-
-![](static/images/URDF_tutorial_manipulator_link2.png)
-
-3. Open the `kraken_manipulator_link_4` entity and add a `MotorizedJoint` component:
-   - Set `Joint Dir.` to `0.0, -1.0, 0.0`
-   - Set `ControllerLimits` to `0.35` and `0.95`
-   - Set `Zero off.` to `0.36`
-   - Turn off the `Animation mode` switch
-   - In `PidPosition` set:
-     - `P` to `250.0`
-     - `D` to `50.0`
-     - `OutputLimit` to `250.0`
-   - Turn off the `SinusoidalTest` switch
-   - Set `Step Parent` to `kraken_manipulator_link_2` (by dragging entity from the Entity Outliner)
-
-![](static/images/URDF_tutorial_manipulator_link4.png)
-
-4. Open the `apple_kraken_rusty_1` entity and add a `ManipulatorController` component:
-   - Set `m_entityX` to `kraken_manipulator_link_2` (by dragging entity from the Entity Outliner)
-   - Set `m_entityY` to `kraken_manipulator_link_4`
-   - Set `m_entityZ1` to `kraken_manipulator_link_1`
-   - Set `vz` to `0.0, 0.0, -1.0` 
-   - Set `Rest entity` to `Rest`
-   - Set `Effector` to `Effector`
-
-![](static/images/URDF_tutorial_Manipulator_Controller.png)
-
-5. In `apple_kraken_rusty_1`, add a `Apple picking component` component:
-   - Set `Effector` to `base_link` or `apple_kraken_rusty_1`
-   - Set `Fruit Storage` to `base_link` or `apple_kraken_rusty_1`
-   - Set `Retrieval point` to `RetrievalChute`
-
-![](static/images/URDF_tutorial_apple_picking_component.png)
-
-6. In `apple_kraken_rusty_1`, add a `Kraken Effector` component:
-   - Set `Kraken Reach entity` to `Reach_visual`
-   - Set `Entity with manipulator` to `base_link` or `apple_kraken_rusty_1`
-   - Set `BaseLinkToKinematic` to `base_link` or `apple_kraken_rusty_1`
-
-![](static/images/URDF_tutorial_kraken_effector.png)
-
-
-## 10. Test the manipulator
-
-Drive or place the Apple Kraken next to one of apple trees:
-
-![](static/images/URDF_tutorial_manipulator_and_tree.png)
-
-You can now start the process of automated apple gathering.
-When the simulation is running, run these commands in a bash console:
-
-```bash
-source /opt/ros/$ROS_DISTRO/setup.bash
-ros2 service call /apple_kraken_rusty_1/trigger_apple_gathering std_srvs/srv/Trigger
-````
-
-You should see the manipulator picking apples.

kraken_nav/README.md

@@ -1,4 +1,4 @@
-# Apple kraken stack #
+# Apple Kraken stack #
 
 This repository contains two ROS2 packages:
  - o3de_kraken_nav
@@ -16,43 +16,23 @@ Allows the Apple Kraken vehicle to operate autonomously.
 
 ## ROS2 prerequisites
 
-### Middleware
-
-- CycloneDDS
-
-```
-sudo apt install ros-${ROS_DISTRO}-cyclonedds ros-${ROS_DISTRO}-rmw-cyclonedds-cpp
-```
-
-It is required that `CycloneDDS` implementation is chosen in every working terminal:
-
-```
-export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
-```
+Please make sure to carefully follow the [installation guide](../README.md) before starting the Apple Kraken stack. The environmental variables need to be set correctly in every console, including:
+- sourcing ROS 2
+- installing and setting CycloneDDS as a default RMW implementation
 
 ### Packages
 
-On top of dependencies for the [agricultural demo project](https://github.com/o3de/ROSConDemo), you will also need some additional ROS2 packages.
+On top of dependencies for the [agricultural demo project](https://github.com/o3de/ROSConDemo), you will also need additional ROS2 packages.
 
-1.  Make sure to source the Iron distribution's setup script
-    ```
-    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`
-
-
-2.  Run the following command to install the remaining required packages
-    ```
+1.  Run the following command to install the required ROS 2 packages
+    ```bash
     sudo apt install ros-${ROS_DISTRO}-slam-toolbox ros-${ROS_DISTRO}-navigation2 ros-${ROS_DISTRO}-nav2-bringup ros-${ROS_DISTRO}-pointcloud-to-laserscan ros-${ROS_DISTRO}-teleop-twist-keyboard ros-${ROS_DISTRO}-ackermann-msgs ros-${ROS_DISTRO}-topic-tools
     ```
 
-3.  You will also need [colcon](https://colcon.readthedocs.io/en/released/user/installation.html) installed in order to build the workspace. Run the following command to install.
-
-    ```
+3.  Run the following command to install [colcon](https://colcon.readthedocs.io/en/released/user/installation.html) for building the workspace. 
+    ```bash
     sudo sh -c 'echo "deb [arch=amd64,arm64] http://repo.ros2.org/ubuntu/main `lsb_release -cs` main" > /etc/apt/sources.list.d/ros2-latest.list'
-
     curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
-
     sudo apt update
     sudo apt install python3-colcon-common-extensions
     ```
@@ -69,47 +49,29 @@ pip install python-statemachine
 
 ## Installation ##
 
-- Use the [development](https://github.com/o3de/o3de/tree/development) branch of the `O3DE`.
-- Use the the [development](https://github.com/o3de/o3de-extras/tree/development) branch of the `o3de-extras`.
-- Use the [development](https://github.com/o3de/ROSConDemo) branch of the `ROSConDemo`.
+Build the workspace (assuming `${WORKDIR}` is your working directory in which `ROSConDemo` is cloned):
 
-1. Source ROS 2 Iron
 ```bash
-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`
-
-2. Build the workspace
-
-```bash
-cd ./kraken_nav
+cd ${WORKDIR}/ROSConDemo/kraken_nav
 colcon build --symlink-install
 ```
 
-## Running simulation
+## Running the simulation
 
-1. [Build](https://github.com/o3de/ROSConDemo#download-and-install) and run the `ROSConDemo`
-2. Load level `Main`
-3. Start a simulation by hitting `CTRL+G`
+1. Build and run the `ROSConDemo` as detailed in the [README file](../README.md).
+2. Load `Main` level.
+3. Start the simulation by hitting `CTRL+G`.
 
 ## Usage scenario
 
 ## Base step (for every scenario)
-Please make sure that the enviroment is correct.
-Note that you need to set it up for every console.
-You can consider adding it to your `~/.bashrc`.
-
-1. Make sure that you have ROS 2 workspace sourced
+Make sure that you have Apple Kraken ROS 2 workspace sourced:
 
 ```bash
+cd ${WORKDIR}/ROSConDemo/
 source ./kraken_nav/install/setup.bash
 ```
 
-2. Make sure that you have `CycleDDS` as middleware 
-```bash
-export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
-```
-
 ### Single robot teleoperation with joystick
 
 1. Start teleoperation launch, make sure that you have your joystick plugged in
@@ -118,7 +80,7 @@ ros2 launch o3de_kraken_nav teleop.launch.py namespace:=apple_kraken_rusty_1
 ```
 
 2. Spawn a single robot
-```
+```bash
 ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_rusty', xml: 'line1'}'
 ```
 
@@ -130,7 +92,6 @@ ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_krake
 
 
 1. Run the navigation stack
-
 ```bash
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_1 rviz:=True
 ```
@@ -140,22 +101,19 @@ ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_r
 ros2 service call /spawn_entity gazebo_msgs/srv/SpawnEntity '{name: 'apple_kraken_rusty', xml: 'line1'}'
 ```
 
-3. You should be able to send goal to the robot. 
-Make sure that that you use only the first `2D Goal Pose`
-
+3. You should be able to send a goal to the robot. 
+Make sure that you use only the first `2D Goal Pose`
 
 ### Multiple robots navigation
 
 > Note: Slam is turned off by default since we have ground truth information about the robot's position from the simulator. However, it is possible to enable `slam_toolbox` forcefully. You can allow slam by adding `use_slam:=True` to the navigation launch command.
 
 1. Run the first navigation stack with `Rviz` param set to `True`:
-
 ```bash
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_1 rviz:=True
 ```
 
-2. Run the navigation stack for rest of the robots (in separate terminals):
-
+2. Run the navigation stack for the remaining robots (in separate terminals):
 ```bash
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_shiny_2 rviz:=False
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_3 rviz:=False
@@ -178,13 +136,11 @@ In this scenario on top of four navigation stacks, the orchestrator nodes are ex
 Those are providing navigation stacks with goals and trigger apple gathering.
 
 1. Run the first navigation stack with `Rviz` param set to `True`:
-
 ```bash
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_1 rviz:=True
 ```
 
 2. Run the navigation stack for the rest of the robots (in separate terminals):
-
 ```bash
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_shiny_2 rviz:=False
 ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_rusty_3 rviz:=False
@@ -192,7 +148,6 @@ ros2 launch o3de_kraken_nav navigation_multi.launch.py namespace:=apple_kraken_s
 ```
 
 3. Run the orchestration nodes for all the robots (in separate terminals):
-
 ```bash
 ros2 run o3de_kraken_orchestration kraken_orchestration_node --ros-args -p robot_name:=apple_kraken_rusty_1 -p spawn_line:=line1
 ros2 run o3de_kraken_orchestration kraken_orchestration_node --ros-args -p robot_name:=apple_kraken_shiny_2 -p spawn_line:=line2