Skip to content

Commit

Permalink
wip custom configs
Browse files Browse the repository at this point in the history
  • Loading branch information
@klaxalk
klaxalk committed Oct 12, 2023
1 parent 0b42665 commit 230fa24
Show file tree
Hide file tree
Showing 9 changed files with 88 additions and 153 deletions.
119 changes: 29 additions & 90 deletions docs/system/bashrc_configuration.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -20,84 +20,50 @@ 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.
We also have a convention in place that the static IP address of the UAV should correspond to the `UAV_NAME`, e.g.
`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.
Expand All @@ -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).
104 changes: 50 additions & 54 deletions docs/system/custom_configs.md
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,74 @@
---
layout: default
title: Custom config files
parent: The UAV system
title: Configuring the MRS UAV System
parent: The UAV System
nav_order: 6
---

| :warning: **Attention please: This page is outdated.** |
| :--- |
| 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:=<path to the file>
```
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.
2 changes: 1 addition & 1 deletion docs/system/frames_of_reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: default
title: Frames of reference
parent: The UAV system
parent: The UAV System
nav_order: 1
---

Expand Down
4 changes: 2 additions & 2 deletions docs/system/index.md
View file
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion docs/system/preparing_for_a_real-world_experiment.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: default
title: Preparing for a real-world experiment
parent: The UAV system
parent: The UAV System
nav_order: 7
---

Expand Down
2 changes: 1 addition & 1 deletion docs/system/relative_commands.md
View file
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down
2 changes: 1 addition & 1 deletion docs/system/trajectories.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: default
title: Trajectories
parent: The UAV system
parent: The UAV System
nav_order: 4
---

Expand Down
2 changes: 1 addition & 1 deletion docs/system/transformations.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: default
title: Transformations
parent: The UAV system
parent: The UAV System
nav_order: 2
---

Expand Down
4 changes: 2 additions & 2 deletions docs/system/uav_ros_interface.md
View file
Original file line number Diff line number Diff line change
@@ -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.** |
Expand Down

0 comments on commit 230fa24

Please sign in to comment.