|
|
@@ -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:
|
|
|
|
|
|
|
|
|
|
|
|
+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.
|
|
|
|
|
|
|
|
|
|
|
|
-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:
|
|
|
|
|
|
|
|
|
|
|
|
+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
|
|
|
|
|
|
|
|
|
|
|
|
-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
|
|
|
|
|
|
|
|
|
|
|
|
-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)
|
|
|
|
|
|
|
|
|
|
|
|
-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`
|
|
|
|
|
|
|
|
|
|
|
|
-- 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`
|
|
|
|
|
|
|
|
|
|
|
|
-- 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`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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:
|
|
|
|
|
|
|
|
|
|
|
|
-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
|
Adam Dabrowski
