diff --git a/docs/system/bashrc_configuration.md b/docs/system/bashrc_configuration.md index 97b49d28..3fcec1ef 100644 --- a/docs/system/bashrc_configuration.md +++ b/docs/system/bashrc_configuration.md @@ -1,15 +1,15 @@ --- layout: default -title: Configuration of .bashrc for real UAVs -parent: The UAV system +title: Configuring .bashrc for real UAVs +parent: The UAV System nav_order: 5 --- -| :warning: **Attention please: This page is outdated.** | +| :warning: **Attention please: This page needs work.** | | :--- | | The MRS UAV System 1.5 is being released and this page needs updating. Plase, keep in mind that the information on this page might not be valid. | -# What is .basrc?: +# What is the .bashrc? You can find the `.bashrc` file in the home folder of the UAV's onboard computer, it is a hidden file. The purpose of the `.bashrc` file is to set up environmental variables, aliases and other settings. @@ -20,28 +20,20 @@ We use it to define the current configuration of the UAV through a set of enviro In the `.bashrc` file of a typical UAV which is running the MRS UAV System, you will find a list of environmental variables similar to this: ```bash -export UAV_NAME="uav21" -export NATO_NAME="oscar" # lower-case name of the UAV frame {alpha, bravo, charlie, ...} -export UAV_MASS="2.9" # [kg], used only with real UAV -export RUN_TYPE="uav" # {simulation, uav} -export UAV_TYPE="x500" # {f550, f450, t650, eagle, naki} -export PROPULSION_TYPE="darpa" # {default, new_esc, ...} -export ODOMETRY_TYPE="gps" # {gps, optflow, hector, vio, ...} -export INITIAL_DISTURBANCE_X="0.2" # [N], external disturbance in the body frame -export INITIAL_DISTURBANCE_Y="-0.1" # [N], external disturbance in the body frame -export STANDALONE="false" # disables the core nodelete manager -export SWAP_GARMINS="false" # swap up/down garmins -export PIXGARM="true" # true if Garmin lidar is connected throught Pixhawk -export SENSORS="garmin_down, realsense_front" # {garmin_down, garmin_up, rplidar, realsense_front, teraranger, bluefox_optflow, realsense_brick, bluefox_brick} -export WORLD_NAME="cisar" # e.g.: "simulation" <= mrs_general/config/world_simulation.yaml -export MRS_STATUS="readme" # {readme, dynamics, balloon, avoidance, control_error, gripper} -export LOGGER_DEBUG="false" # sets the ros console output level to debug +export UAV_NAME=uav1 +export UAV_TYPE=x500 +export RUN_TYPE=realworld +export UAV_MASS=2.0 +export WORLD_NAME=temesvar_field +export INITIAL_DISTURBANCE_X=0.0 +export INITIAL_DISTURBANCE_Y=0.0 +export OLD_PX4_FW=0 ``` Let's run through all the important variables: ```bash -export UAV_NAME="uav21" +export UAV_NAME="uav1" ``` This variable defines the UAV's namespace, all the ROS nodes of the MRS UAV System will run under the namespace `/$UAV_NAME/node_name`. The `UAV_NAME` should match the `/etc/hostname` of the onboard computer. @@ -49,55 +41,29 @@ We also have a convention in place that the static IP address of the UAV should `uav21` will have a static IP of `192.168.69.121`. ```bash -export NATO_NAME="oscar" +export RUN_TYPE="realworld" ``` -This is an alternative name of the UAV frame, can be omitted. - -```bash -export UAV_MASS="2.9" -``` - -This is the total takeoff mass (including the battery) of the UAV in `kg`. -It is used as an initial condition for the mass estimator of the UAV, which is in turn used in the feedforward control actions of the controllers. -It is not critical to set this value precisely before every flight, as the mass estimator will correct errors after a few seconds of flying. -If the `UAV_MASS` is different than the real mass, the UAV can behave erraticaly during takeoff, it can jump up quickly or the takeoff can be slow. - -```bash -export RUN_TYPE="uav" -``` - -Set `RUN_TYPE` to `uav` on real UAVs, set it to `simulation` when you want to run just the simulation. +Setting `RUN_TYPE` to `realworld` will tell the system that we are **not** in simulation. ```bash export UAV_TYPE="x500" ``` -The `UAV_TYPE` variable defines the frame of the UAV, which can be tied to [specific default configs](https://github.com/ctu-mrs/mrs_uav_managers/tree/master/config/uav) for the frame, the propulsion and sensor configurations (explained lower down). - -```bash -export PROPULSION_TYPE="darpa" -``` - -This variable defines the proulsion configuration of the UAV. -The same frame can have different motors and propellers, which will result in different response to throttle commands. -The Pixhawk controller accepts total throttle as an input (0-100%) and we need to corellate this value to the actual physical thrust (and therefore the produced acceleration). -This is done through a quadratic expression that we call motor params. -Motor parameters for specific frames and `PROPULSION_TYPE` are defined in `the mrs_uav_controllers` package. -[Example configuration for the X500 frame is here.](https://github.com/ctu-mrs/mrs_uav_controllers/tree/master/config/uav/x500) +The `UAV_TYPE` variable used used within the tmux sessions to find the correct _platform configuration file_. ```bash -export ODOMETRY_TYPE="gps" +export UAV_MASS="2.9" ``` -`ODOMETRY_TYPE` defines the default lateral and altitude estimator which is used, as well as other estimators which should be running. - -The value of the variable defines [which odometry config file](https://github.com/ctu-mrs/mrs_uav_odometry/tree/master/config/uav) is used from here. - +This is the total takeoff mass (including the battery) of the UAV in `kg`. +It is used as an initial condition for the mass estimator of the UAV, which is in turn used in the feedforward control actions of the controllers. +It is not critical to set this value precisely before every flight, as the mass estimator will correct errors after a few seconds of flying. +If the `UAV_MASS` is different than the real mass, the UAV can behave erraticaly during takeoff, it can jump up quickly or the takeoff can be slow. ```bash -export INITIAL_DISTURBANCE_X="0.2" -export INITIAL_DISTURBANCE_Y="-0.1" +export INITIAL_DISTURBANCE_X="0.0" +export INITIAL_DISTURBANCE_Y="0.0" ``` The UAV can suffer from an intrinsic internal disturbance, like offset center of mass, motor which is not performing as well as the others and so on. @@ -108,52 +74,25 @@ It is defined in `Newtons` of thrust in the `X` or `Y` directions. You can leave the values at `0.0` and the UAV will estimate the disturbances on its own relatively quickly. Only when you require a precise and straight takeoff and the best possible performance right after takeoff, you should measure and define the `INITIAL_DITURBANCE` values. -```bash -export STANDALONE="false" -``` - -The core of the MRS UAV System runs in a single [nodelet](http://wiki.ros.org/nodelet) manager. -If you set `STANDALONE` to `true`, each node will run as a separate node, which can be beneficial for debugging. - -```bash -export SWAP_GARMINS="false" -``` - -This variable was used on UAVs with 2 Garmin rangefinders (one pointing up and one down). -It is deprecated and not used in most of the UAVs. - -```bash -export PIXGARM="true" -``` - -Most of our UAVs have a Garmin Lidar Lite V3 rangefinder. -This rangefinder can be connected to the Pixhawk's I2C port and stream the data to the onboard computer. -If this is the case, set `PIXGARM` to `true`. - ```bash export SENSORS="garmin_down, realsense_front" ``` This variable contains a list of sensors connected to the onboard computer. -It is read by the `mrs_uav_general` [sensors.launch](https://github.com/ctu-mrs/mrs_uav_general/blob/master/launch/sensors.launch) launch file, which will in turn launch the appropriate ROS drivers for the specified sensors, as well as publish a static tranformation between the UAV's FCU frame and the sensor frame. +It is read by the `mrs_uav_deployment` [sensors.launch](https://github.com/ctu-mrs/mrs_uav_deployment/blob/master/launch/sensors.launch) launch file, which will in turn launch the appropriate ROS drivers for the specified sensors, as well as publish a static tranformation between the UAV's FCU frame and the sensor frame. ```bash -export WORLD_NAME="cisar" +export WORLD_NAME="temesvar_field" ``` -This variable is used to specify a [world file](https://github.com/ctu-mrs/mrs_uav_general/tree/master/config/worlds) which is used for the flight. + +This variable is used to specify a [world file](https://github.com/ctu-mrs/mrs_uav_deployment/tree/master/config/worlds) which is used for the flight. The world file can define the origin of the global frame, the safety area in which filghts can be conducted and the minimum and maximum flight heights. Note that this only makes sense when a global localization like gps or rtk is used. If you use a non-global localization (like laser-slam or optflow), use the local world file. The origin of the local frame will be the starting position of the UAV. ```bash -export MRS_STATUS="readme" -``` - -This variable is deprecated and can be omitted. - -```bash -export LOGGER_DEBUG="false" # +export export OLD_PX4_FW=0 ``` -Sets the ros console output level to debug. +This variable is a teporary workaround for flying with both the _new_ version of Pixhawk6 (with PX4 1.13.2) and with the old Pixhawk4 (with older PX4). diff --git a/docs/system/custom_configs.md b/docs/system/custom_configs.md index e1add06f..d460e071 100644 --- a/docs/system/custom_configs.md +++ b/docs/system/custom_configs.md @@ -1,7 +1,7 @@ --- layout: default -title: Custom config files -parent: The UAV system +title: Configuring the MRS UAV System +parent: The UAV System nav_order: 6 --- @@ -9,70 +9,66 @@ nav_order: 6 | :--- | | The MRS UAV System 1.5 is being released and this page needs updating. Plase, keep in mind that the information on this page might not be valid. | -# How to use custom config files for uav_core modules +# Motivation -## Motivation +There are many configuration files _baked_ in the [mrs_uav_core](https://github.com/ctu-mrs/mrs_uav_core) and other packages of the system. +They contain many options for modifying the behavior of the system and users are **encouraged** to configure the system to their needs. +In this tutorial, we provide an efficient way ho customize the configuration **without the need to change** any files withing the installed system. -There are many configuration files in the [uav_core](https://github.com/ctu-mrs/uav_core). -They contain many options to modify the behavior of the control and estimation pipeline. -Since everyone needs to change some values for his experiments, the uav_core modules contain only a *general defaults* for each supported UAV type. -In this tutorial, we provide an efficient way ho customize the configuration **without the need to change** any files in the uav_core repository. -It is done by creating a custom configuration files which contain only the option you would like to change from the default values. -Those **custom configs** can be loaded over the defaults without the need to change the uav_core itself. +## The concept of a _custom config_ file -## The config file hierarchy - -The ROS launch files in the **uav_core** load three levels of configuration files. -1. A topmost general configuration, typically stored in a **default** subfolder of the packages. -2. A UAV-type specific configuration, which is already divided into two groups: for **simulation** and the real **uav**. The particular files are automatically selected using the environment variables `$UAV_TYPE` and `$RUN_TYPE`. -3. A user-defined **custom config** file provided through the launch file argument, which is the subject of this manual. - -## Activating a custom config file - -We assume you already have a custom *tmuxinator* session, as suggested by this [manual](https://ctu-mrs.github.io/docs/simulation/howto.html). -Let's say that you want to change the controller, which will be used after takeoff. -This option is originally defined in [uav_manager.yaml](https://github.com/ctu-mrs/mrs_uav_managers/blob/master/config/default/control_manager.yaml), in the [mrs_uav_manager](https://github.com/ctu-mrs/mrs_uav_managers/blob/master/config/default/uav_manager.yaml) package. -An example of how to use this technique is to create a `.yaml` file with the value of the parameter that you want to change. -The file is then passed to the [core.launch](https://github.com/ctu-mrs/mrs_uav_general/blob/master/launch/core.launch) launchfile. -Create a file `uav_manager.yaml` in a subfolder `custom_configs` within your tmuxinator session folder and fill it with the following lines: +Each launch file within our system loads appropriate config files from its package. +Changing these config files directly is **not recommended** as well as **copying them elsewehere and changing the launch file**. +Instead, a parameter can be used to pass a **custom config** file that only overrides the values that the used wants to change relative to the defaults. +This mechanism allows the user to store the changes locally. +In general, our launchfiles accept the argument ``` -takeoff: - after_takeoff: - controller: "Se3Controller" +custom_config:= ``` -Then add an optional argument to the [core.launch](https://github.com/ctu-mrs/mrs_uav_general/blob/master/launch/core.launch) line in your tmuxinator session: -``` -roslaunch mrs_uav_general core.launch config_uav_manager:=./custom_configs/uav_manager.yaml -``` -This will load your custom configuration file and it will override the default parameters from the [mrs_uav_managers](https://github.com/ctu-mrs/mrs_uav_managers) package. +which is used to pass the path to the custom config. + +## core.launch configs -We strongly suggest using [tmuxinator](https://github.com/ctu-mrs/simulation/tree/master/example_tmux_scripts) (for simulation) or a [tmux](https://github.com/ctu-mrs/uav_core/tree/master/tmux_scripts) (for a real UAV) scripts for starting the simulation. -In both cases, we usually create a subfolder `custom_configs` in the same path as the tmuxinator/tmux script. -This way, you can prepare a self-contained folder in your own repository, which you can save, version it with git and change independently on the uav_core. +The [MRS UAV System](https://github.com/ctu-mrs/mrs_uav_system) is launched throught the `core.launch` launch file. +The `core.launch` requires the following 2 custom configuration files: -**The lesson** from this should be: +## The Platform Config -* never edit config files directly in somewhere in [uav_core], -* always keep the **custom config** files at your tmux/tmuxinator session. +This file is supposed to override the defaults for a particular UAV platform. +Usually, this file is provided by us with each simulated (and realword) UAV. +The platform configs are stored in a location logically close the the source of the simulated UAV, e.g., -## Which parameters should I change? +* In [mrs_uav_gazebo_simulation](https://github.com/ctu-mrs/mrs_uav_gazebo_simulation/tree/master/ros_packages/mrs_uav_gazebo_simulation/config/mrs_uav_system) for our Gazebo simulation, +* In [mrs_multirotor_simulator](https://github.com/ctu-mrs/mrs_multirotor_simulator/tree/master/config/mrs_uav_system) for our MRS simulation, +* In [mrs_uav_coppelia_simulation](https://github.com/ctu-mrs/mrs_uav_coppelia_simulation/tree/master/mrs_uav_coppelia_simulation/config/mrs_uav_system) for our Coppelia simulation, +* In [mrs_uav_dji_tello_api](https://github.com/ctu-mrs/mrs_uav_dji_tello_api/tree/master/config/mrs_uav_system) for our DJI Tello interface. +* In [mrs_uav_deployment](https://github.com/ctu-mrs/mrs_uav_deployment/tree/master/config/mrs_uav_system) for our realword drones. -Deducing which parameters you want to change depends on your particular scenario. -We recommend to go through the description of all our packages ([link](https://ctu-mrs.github.io/docs/software/uav_core)) and familiarize yourself with their functions. -Their config files are typically contained within the `config/default` subfolder of each repository. +## The Custom Config -## How should I name the *core.launch* argument? +This file is dedicated for the user's relative changes to the default configuration that was already modified by the _platform config_. -Each program in each package the `[core.launch](https://github.com/ctu-mrs/mrs_uav_general/blob/master/launch/core.launch)` has an argument dedicated to the program's custom config file. -The simplest way how to find the argument is to look into the launch file. -However, generally, the argument name has a pattern `config_node_name`. -E.g., `config_control_manager`, `config_odometry` or `config_mpc_controller`. +## Which parameters can be changed? -## Complete examples +All parameters that can be changed by the users can be listed by +```bash +rosrun mrs_uav_core get_public_params.py +``` +The parameters are _scraped_ from the currently installed packages from the system, so the list is always going to be compatible with your current installation. + +For convenience, the parameters can be piped into a file and later inspected: +```bash +rosrun mrs_uav_core get_public_params.py > /tmp/params.yaml +``` +or piped to less: +```bash +rosrun mrs_uav_core get_public_params.py | less +``` +or piped to vim: +```bash +vim <(rosrun mrs_uav_core get_public_params.py) +``` -An example dedicated to **custom configs** is located within our tmux session examples: -[https://github.com/ctu-mrs/simulation/tree/master/example_tmux_scripts](https://github.com/ctu-mrs/simulation/tree/master/example_tmux_scripts) -under the name `one_drone_tmuxinator_custom_configs`. +## Example -Also, the [mrs_uav_testing](https://github.com/ctu-mrs/mrs_uav_testing) package has its test sessions customized this way. -See [https://github.com/ctu-mrs/mrs_uav_testing/tree/master/tmux](https://github.com/ctu-mrs/mrs_uav_testing/tree/master/tmux). +All the example tmux session that we provide are already pre-set with the _platform configs_ and the _custom config_ file. diff --git a/docs/system/frames_of_reference.md b/docs/system/frames_of_reference.md index e3c9e94c..12982e35 100644 --- a/docs/system/frames_of_reference.md +++ b/docs/system/frames_of_reference.md @@ -1,7 +1,7 @@ --- layout: default title: Frames of reference -parent: The UAV system +parent: The UAV System nav_order: 1 --- diff --git a/docs/system/index.md b/docs/system/index.md index bf59f676..455fca4f 100644 --- a/docs/system/index.md +++ b/docs/system/index.md @@ -1,8 +1,8 @@ --- layout: default -title: The UAV system +title: The UAV System nav_order: 3 has_children: true --- -# The UAV system +# The UAV System diff --git a/docs/system/preparing_for_a_real-world_experiment.md b/docs/system/preparing_for_a_real-world_experiment.md index 5036dd33..3d04c968 100644 --- a/docs/system/preparing_for_a_real-world_experiment.md +++ b/docs/system/preparing_for_a_real-world_experiment.md @@ -1,7 +1,7 @@ --- layout: default title: Preparing for a real-world experiment -parent: The UAV system +parent: The UAV System nav_order: 7 --- diff --git a/docs/system/relative_commands.md b/docs/system/relative_commands.md index c2f82645..5fa1fccd 100644 --- a/docs/system/relative_commands.md +++ b/docs/system/relative_commands.md @@ -1,7 +1,7 @@ --- layout: default title: Commanding the robot relative to its position -parent: The UAV system +parent: The UAV System nav_order: 9 --- diff --git a/docs/system/trajectories.md b/docs/system/trajectories.md index 00479295..64a59c96 100644 --- a/docs/system/trajectories.md +++ b/docs/system/trajectories.md @@ -1,7 +1,7 @@ --- layout: default title: Trajectories -parent: The UAV system +parent: The UAV System nav_order: 4 --- diff --git a/docs/system/transformations.md b/docs/system/transformations.md index 8928e0c0..e240f5cc 100644 --- a/docs/system/transformations.md +++ b/docs/system/transformations.md @@ -1,7 +1,7 @@ --- layout: default title: Transformations -parent: The UAV system +parent: The UAV System nav_order: 2 --- diff --git a/docs/system/uav_ros_interface.md b/docs/system/uav_ros_interface.md index 7bca45db..5ee2fb95 100644 --- a/docs/system/uav_ros_interface.md +++ b/docs/system/uav_ros_interface.md @@ -1,8 +1,8 @@ --- layout: default title: UAV-ROS interface -parent: The UAV system -nav_order: 3 +parent: The UAV System +nav_order: 1 --- | :warning: **Attention please: This page needs work.** |