Merge branch 'master' of github.com:ctu-mrs/mrs_uav_gazebo_simulation

README.md

@@ -33,73 +33,68 @@ Metapackage for the MRS UAV Gazebo simulation pipeline.
 
 Use one of the prepared Tmuxinator sessions:
 
-- [tmux/one_drone_gps](tmux/one_drone_gps)
+- [tmux/one_drone](tmux/one_drone)
 
-## Customizing drone using the "spawner parameters"
+## Using the MRS drone spawner in your simulations
 
-**TODO** the wiki page [https://ctu-mrs.github.io/docs/simulation/drone_spawner.html](https://ctu-mrs.github.io/docs/simulation/drone_spawner.html) contains potentially duplicit or contradicting information.
-These two pages should be merged and the information should be presented at only one of the locations.
+The drone models are dynamically created in runtime using the [MRS drone spawner](https://ctu-mrs.github.io/docs/simulation/gazebo/gazebo/drone_spawner.html). The UAV platforms can be additionally equipped by adding [components](ros_packages/mrs_uav_gazebo_simulation/models/mrs_robots_description/sdf/component_snippets.sdf.jinja) (rangefinders, LiDARs, cameras, plugins etc.).
 
-The UAV platforms can be additionaly equipped with sensors (rangefinders, 2d lidars, stereo cameras etc.).
+### Start the Gazebo simulator
 
-### Start of the Gazebo simulator
-
-To start the prepared example of Gazebo world call:
+To start the example Gazebo world call:
 
 ```bash
-roslaunch mrs_simulation simulation.launch world_file:='$(find mrs_gazebo_common)/worlds/grass_plane.world' gui:=true
+roslaunch mrs_uav_gazebo_simulation simulation.launch world_name:=grass_plane.world gui:=true
 ```
 
 At this point the Gazebo world will only contain the environment with grass plane but with no vehicles yet.
 
-### Spawning of UAVs
+### Spawning the UAVs
 
-The `simulation.launch` will automatically start the `mrs_drone_spawner` python node. If you use a custom launch file to start the simulation, you can start it separately:
+The `simulation.launch` will automatically start the `mrs_drone_spawner` as a ROS node. If you use a custom launch file to start Gazbo, you can launch the spawner separately:
 
 ```bash
-roslaunch mrs_simulation mrs_drone_spawner.launch
+roslaunch mrs_uav_gazebo_simulation mrs_drone_spawner.launch
 ```
 
 The `mrs_drone_spawner` will perform the following tasks:
 
-* Spawn vehicle models in the Gazebo simulation (ids from 0 to 250). This is done internally by calling the command `rosrun gazebo_ros spawn_model`.
+* Generate SDF models from the UAV templates
+
+* Add optional components (sensors, plugins...) based on the user input
+
+* Run PX4 SITL and Mavros, and ensure that all ports are correctly linked with the Gazebo simulator
 
-* For each vehicle, PX4 firmware and mavros is started at specific port numbers depending on the vehicle ID.
+* Remove all subprocesses on exit
 
 Vehicles are added to the simulation by calling the `spawn` service of the `mrs_drone_spawner`.
 The service takes one string argument, which specifies the vehicle ID, type and sensor configuration.
-Example: spawn a single vehicle with a down-facing laser rangefinder:
-
-```bash
-rosservice call /mrs_drone_spawner/spawn "1 --enable-rangefinder"
-```
+Example: spawn a single vehicle with ID 1, type X500, with a down-facing laser rangefinder:
 
-To display the manual containing a list of all available arguments, perform a dry-run of the script:
 ```bash
-rosrun mrs_simulation mrs_drone_spawner
+rosservice call /mrs_drone_spawner/spawn "1 --x500 --enable-rangefinder"
 ```
 
-The arguments are also listed in the `mrs_simulation/config/spawner_params.yaml` file.
-Note that not all sensors are available for all the vehicle types.
-The config file stores the available configurations in the following format: `parameter: [default_value, help_description, [compatible_vehicles]]`
+To display the basic use manual for the spawner, call the service with the argument ` --help`. **NOTE**: String argument cannot start with a dash. Add a space before the dashes to avoid errors. The service call returns the full help text, but the formatting may be broken. Please refer to the terminal running `simulation` or `mrs_drone_spawner` where the help text is also printed with proper formatting.
 
-Multiple vehicles may be spawned with one service call:
 ```bash
-rosservice call /mrs_drone_spawner/spawn "1 2 3 4 5 --t650 --enable-bluefox-camera --enable-rangefinder"
+rosservice call /mrs_drone_spawner/spawn " --help"
 ```
 
-Spawn position may be specified by a command line argument `--pos x y z heading`: [m, m, m, rad]
+You can also display a manual for a specific platform. This will list all the components that can be equipped to the selected platform, and their brief description.
 ```bash
-rosservice call /mrs_drone_spawner/spawn "1 --f550 --enable-rangefinder --pos 10 -15 0.3 0.7"
+rosservice call /mrs_drone_spawner/spawn " --x500 --help"
 ```
-For multiple vehicles, `--pos` defines the spawn point of the first vehicle. Following vehicles will be spawned in a line, with an x-offset of 2 meters from the previous vehicle.
 
-Spawn position may be specified by a `.csv` or a `.yaml` file using `--file absolute_path_to_file`:
+Multiple vehicles may be spawned with one service call:
 ```bash
-rosservice call /mrs_drone_spawner/spawn "1 --f450 --enable-rangefinder --enable-ouster --use-gpu-ray --ouster-model OS1-64 --file `pwd`/spawn_poses.yaml"
+rosservice call /mrs_drone_spawner/spawn "1 2 3 4 5 --t650 --enable-bluefox-camera --enable-rangefinder"
 ```
 
-Use a whitespace instead of an ID to get an available ID automatically assigned by the spawner.
+The default parameters of some components may be reconfigured by adding `param:=value` after the component keyword. Multiple params may be used at the same time:
 ```bash
-rosservice call /mrs_drone_spawner/spawn " --f450 --enable-rangefinder"
+rosservice call /mrs_drone_spawner/spawn "1 --x500 --enable-rangefinder --enable-ouster model:=OS0-32 use_gpu:=True horizontal_samples:=128 update_rate:=10"
 ```
+The list of components and their reconfigurable parameters can be displayed using the platform-specific help.
+
+For more details, please refer to the [MRS drone spawner](https://ctu-mrs.github.io/docs/simulation/gazebo/gazebo/drone_spawner.html) page.