Procházet zdrojové kódy

Clarified instructions and linked them through README

Signed-off-by: Adam Dabrowski <[email protected]>
Adam Dabrowski před 2 roky
rodič
revize
82d2723eaf
31 změnil soubory, kde provedl 129 přidání a 61 odebrání
  1. 1 1
      .gitattributes
  2. 5 0
      README.md
  3. 81 60
      docs/ImportingURDF/URDF_import_guide.md
  4. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_Lidar_Kraken.png
  5. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_Manipulator_Controller.png
  6. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_ROS2_Robot_Control.png
  7. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_RViz_test.png
  8. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_Tag_Input.png
  9. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_Vehicle_Model.png
  10. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_Wheel_controller.png
  11. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_apple_picking_component.png
  12. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_base_link_name.png
  13. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_kraken_effector.png
  14. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_manipulator_and_tree.png
  15. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link1.png
  16. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link2.png
  17. 3 0
      docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link4.png
  18. binární
      docs/URDF_import/static/images/URDF_tutorial_Lidar_Kraken.png
  19. binární
      docs/URDF_import/static/images/URDF_tutorial_Manipulator_Controller.png
  20. binární
      docs/URDF_import/static/images/URDF_tutorial_ROS2_Robot_Control.png
  21. binární
      docs/URDF_import/static/images/URDF_tutorial_RViz_test.png
  22. binární
      docs/URDF_import/static/images/URDF_tutorial_Tag_Input.png
  23. binární
      docs/URDF_import/static/images/URDF_tutorial_Vehicle_Model.png
  24. binární
      docs/URDF_import/static/images/URDF_tutorial_Wheel_controller.png
  25. binární
      docs/URDF_import/static/images/URDF_tutorial_apple_picking_component.png
  26. binární
      docs/URDF_import/static/images/URDF_tutorial_base_link_name.png
  27. binární
      docs/URDF_import/static/images/URDF_tutorial_kraken_effector.png
  28. binární
      docs/URDF_import/static/images/URDF_tutorial_manipulator_and_tree.png
  29. binární
      docs/URDF_import/static/images/URDF_tutorial_manipulator_link1.png
  30. binární
      docs/URDF_import/static/images/URDF_tutorial_manipulator_link2.png
  31. binární
      docs/URDF_import/static/images/URDF_tutorial_manipulator_link4.png

+ 1 - 1
.gitattributes

@@ -126,4 +126,4 @@ Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/marmoset_bake.tbs
 Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/Brass/brass_bake.spp filter=lfs diff=lfs merge=lfs -text
 Gems/AtomLyIntegration/CommonFeatures/Assets/Objects/Lucy/.wip/stone/stone_bake.spp filter=lfs diff=lfs merge=lfs -text
 static/screenshots/*.png filter= diff= merge= -text
-docs/URDF_import/static/images/*.png filter= diff= merge= -text
+docs/ImportingURDF/static/images/*.png filter= diff= merge= -text

+ 5 - 0
README.md

@@ -240,6 +240,11 @@ 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

+ 81 - 60
docs/URDF_import/HOWTO_import_urdf.md → docs/ImportingURDF/URDF_import_guide.md

@@ -1,18 +1,24 @@
-# Importing URDF robot - ROSConDemo tutorial
-
-This document contains a step-by-step tutorial guiding through a URDF import procedure. It covers setting up the vehicle part of the robot. Description of the manipulator part will follow.
+# 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
 
-- This tutorial uses the [ROSConDemo project](https://github.com/o3de/ROSConDemo). Follow the instructions in the [project README](https://github.com/o3de/ROSConDemo) to build and test the project.
-- URDF import requires `xacro` package. It can be installed using:
+- 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
 
-Enter ROSConDemo folder and:
+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
@@ -21,7 +27,11 @@ 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 apear in the `Entity Outliner`.
+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
 
@@ -70,6 +80,8 @@ In the `apple_kraken_new` prefab:
 
 ![](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
 
@@ -83,11 +95,16 @@ In the `apple_kraken_new` prefab:
 
 ## 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 on the keyboard.
+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.
 
-## 7. Add lidar
+URDF format by itself does not specify sensor behavior (unless through Gazebo extensions). Now, we will now add a LIDAR to our robot.
 
-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:
+## 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`
 
@@ -95,11 +112,13 @@ Select the `lidar_mount` entity in the `apple_kraken_new` prefab, open the right
 
 ## 8. Test robot navigation
 
-Select `base_link` entity and change it's name to `apple_kraken_rusty_1`. This step assures, that we are using correct namespace.
+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/RobotecAI/o3de_kraken_nav) to install the navigation stack. After the `Installation` part run the O3DE simulation (`Ctrl G`), switch to terminal and perform:
+Follow instructions in the [o3de_kraken_nav](https://github.com/RobotecAI/o3de_kraken_nav) 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
@@ -109,85 +128,87 @@ 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.
+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. Perform:
-- 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
+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. Perform:
-- 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
+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. Perform:
-- 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)
+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 `base_link` or `apple_kraken_rusty_1` if you performed test form step 8 entity and:
-- Add a `ManipulatorController` Component. Perform:
-  - Set `m_entityX` to `kraken_manipulator_link_2` (by dragging entity from the Entity Outliner)
-  - Set `m_entityY` to `kraken_manipulator_link_4` (by dragging entity from the Entity Outliner)
-  - Set `m_entityZ1` to `kraken_manipulator_link_1` (by dragging entity from the Entity Outliner)
-  - Set `vz` to `0.0, 0.0, -1.0` 
-  - Set `Rest entity` to `Rest` (by dragging entity from the Entity Outliner)
-  - Set `Effector` to `Effector` (by dragging entity from the Entity Outliner)
+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)
 
-- Add a `Apple picking component` Component. Perform:
-  - Set `Effector` to `base_link` or `apple_kraken_rusty_1` if you performed test form step 8 (by dragging entity from the Entity Outliner)
-  - Set `Fruit Storage` to `base_link` or `apple_kraken_rusty_1` if you performed test form step 8 (by dragging entity from the Entity Outliner)
-  - Set `Retrieval point` to `RetrievalChute` (by dragging entity from the Entity Outliner)
+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)
 
-- Add a `Kraken Effector` Component. Perform:
-  - Set `Kraken Reach entity` to `Reach_visual` (by dragging entity from the Entity Outliner)
-  - Set `Entity with manipulator` to `base_link` or `apple_kraken_rusty_1` if you performed test form step 8 (by dragging entity from the Entity Outliner)
-  - Set `BaseLinkToKinematic` to `base_link` or `apple_kraken_rusty_1` if you performed test form step 8 (by dragging entity from the Entity Outliner)
+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
 
-Place the Kraken next to one of apple trees:
+Drive or place the Apple Kraken next to one of apple trees:
 
 ![](static/images/URDF_tutorial_manipulator_and_tree.png)
 
-Run simulation (`Ctrl G`), switch to terminal and run:
+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

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_Lidar_Kraken.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed9b8f9118a5a049985616dd86fb250054d8f686bb346b41bc4c88f4de66313a
+size 43310

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_Manipulator_Controller.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:93f9fbcbf527bf0345bdf58148181c675244c6ac1773994f892d98eb118adda7
+size 39017

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_ROS2_Robot_Control.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dfd0dcb0346528edce97991fbcfec420ff35e67c19fa426d1882fb5088ef7a2f
+size 33871

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_RViz_test.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5d715cde9befd2da4f8e67e84486fccdff50c7a53e7754162cb1be0d25475881
+size 220543

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_Tag_Input.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1c653c1b74b36093534a97426953dc1eb4dd07169357485a71695ee47b4a9333
+size 15624

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_Vehicle_Model.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f8a26ca0b9293200b6163b495a24635dce39ca0f7f2d92a14789ec8cbc85ffe
+size 117846

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_Wheel_controller.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f622d5df39d48aa98fbae140eb5196db235cd50095a2ef83881b111f6f9dc6d2
+size 11346

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_apple_picking_component.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c5c85a8d74b053081ae0c19cc2160cf4fd0a0e4e7094e1ad185a1e6ed60e6472
+size 44408

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_base_link_name.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a600440b179fac88e36c590bf1f389dd3cfb53bacc809666ce80a58a5edba032
+size 25743

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_kraken_effector.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7b7478b477c844774a55de76f73fcee964346d88e6bc2220c5bd8464e41e2385
+size 32468

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_manipulator_and_tree.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e48e999406b25c01ee7696da78e4655af7dccdab108a81c62b0f48f3ff08a709
+size 444847

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link1.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d26386149deeb13a1ec29141dfbd15f62ba52fb329d00a3b4566c3230a8dd2f
+size 62724

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link2.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:985de37cca8f08e50eea5a3171fa492165559502ca93ac0e03b4c52291e165ed
+size 62715

+ 3 - 0
docs/ImportingURDF/static/images/URDF_tutorial_manipulator_link4.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:610e69e4ac063aa8d00fd67d549c5c630a256eaae232303697f97381e4ea5664
+size 67931

binární
docs/URDF_import/static/images/URDF_tutorial_Lidar_Kraken.png


binární
docs/URDF_import/static/images/URDF_tutorial_Manipulator_Controller.png


binární
docs/URDF_import/static/images/URDF_tutorial_ROS2_Robot_Control.png


binární
docs/URDF_import/static/images/URDF_tutorial_RViz_test.png


binární
docs/URDF_import/static/images/URDF_tutorial_Tag_Input.png


binární
docs/URDF_import/static/images/URDF_tutorial_Vehicle_Model.png


binární
docs/URDF_import/static/images/URDF_tutorial_Wheel_controller.png


binární
docs/URDF_import/static/images/URDF_tutorial_apple_picking_component.png


binární
docs/URDF_import/static/images/URDF_tutorial_base_link_name.png


binární
docs/URDF_import/static/images/URDF_tutorial_kraken_effector.png


binární
docs/URDF_import/static/images/URDF_tutorial_manipulator_and_tree.png


binární
docs/URDF_import/static/images/URDF_tutorial_manipulator_link1.png


binární
docs/URDF_import/static/images/URDF_tutorial_manipulator_link2.png


binární
docs/URDF_import/static/images/URDF_tutorial_manipulator_link4.png