UMA Environment Tools

Set of tools to install, update and use the uma environment

This repo offers a variety of scripts that can be useful to interact with ROS, catkin, git, and other programming tools.

Table of Contents

1. UMA environment
   1. install_uma_environment
   2. UMA tree
   3. update_uma_environment
2. Useful tools
   1. Terminator
   2. create_catkin_ws
   3. change_ros_ws
   4. create_ros2_pkg
   5. nt
   6. cb
   7. cc
3. Troubleshooting

1. UMA environment

1.1. Install UMA Environment

Create the uma environment, installing required packages and dependencies and creating an organized structure

Using WSL?

1. Install WSL:

• If you're running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11, you can install everything you need to run WSL with a single command. Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator", enter the following command:

  wsl --install

  After installing, restar yout machine.

• If you are on earlier versions please see the manual install page and follow the instructions.

2. Install Ubuntu 22.04:

   From windows terminal:

   wsl --install Ubuntu-22.04

   It will ask you for the username and password of the Ubuntu user. If you're not familiar with Linux terminal, when it asks for your password, it doesn't show what you're writting. So don't think you're not writing, it just simply doesn't show it.

   Enter new UNIX username: <YOUR_USERNAME>
   New password:
   Retype new password:
   passwd: password updated successfully
   Installation successful! 
   

   This installation process will take some time and it will ask you for confirmation to install some packages and dependencies (you need to say yes to all). After this, you can just open an Ubuntu terminal by searching for Ubuntu in your Windows applications.

Once you're inside the Ubuntu system

From the Ubuntu terminal:

cd
sudo apt update
sudo apt upgrade
git clone https://github.com/jmgandarias/uma_environment_tools.git
cd uma_environment_tools/scripts
./install_uma_environment.sh

Warning

If you find an error at this point, check the troubleshooting before continuing.

After installing the UMA environment, you can close that terminal and open a new one. By installing the UMA environment, you have installed Terminator (a specific Ubuntu terminal that will make your life easy). To open an Ubuntu terminator from Windows you just have to look for it in your Windows applications.

The first thing you need to do is to update the uma environment to finish the installation. Run:

update_uma_environment

Now, restart the terminal by running the new terminal alias (nt):

nt

Then, you need to create a catkin workspace, to do so, run the following alias:

create_catkin_ws

It will create a catkin_ws inside the folder ros. Remember that the UMA environment expects that all the workspace names end with _ws (i.e., <MY_ROS2_WORKSPACE_NAME>_ws). The default name is catkin_ws.

Once the workspace has been created, you need to compile it with colcon build, you can do it with the following alias:

cb

You should see that the workspace is automatically sourced. From now on, every new terminal you open will automatically source this workspace. Refer to create_catkin_ws and change_ros_ws if you want to create more workspaces and change the workspace to be sourced.

1.2. UMA Environment Organization

The last script you run above created in your home (~/) folder the following folder tree:

.
│
├── uma_environment_tools
│       ├── config
│       ├── README.md
│       └── scripts
├── ros
│    ├── my_first_ros2_ws
|    │   ├── build
|    │   ├── install
|    │   ├── log
|    │   └── src
|    |
│    ├── my_second_ros2_ws
|    │   ├── build
|    │   ├── install
|    │   ├── log
|    │   └── src
|    |
│    └── ...
|       
├── log
│   ├── my_logged_data__YYYY_MM_DD__HH_MM_SS.mat
│   └── ...
│
└── .uma_params.env

The structure above represents the UMA environment directory tree, subdivided in 4 main parts:

• uma_environment_tools: this folder contains the scripts and config files of the uma_environment_tools repo.
• ros: this folder hosts the workspaces the user will create.
• log: here is the place where you should save all your logged data.
• .uma_params.env: this hidden file is the only file you can modify thourgh the command modify_uma_params. It contains the user preferences that will be reflected in all the UMA environment. Example:

#####################
# UMA PARAMS V.0.1 #
#####################

#Set your ENV variables preferences
UMA_ENV_VERBOSITY=true

#Set git client preferences (GUI/kraken)
GIT_CLIENT=kraken

#Set ROS distro
ROS2_DISTRO_TO_INSTALL=humble

#Set ROS distro (one between the two above)
ROS_DISTRO_TO_SOURCE=humble

#Set your workspace source
WORKSPACES_PATH=~/ros
export WORKSPACE_TO_SOURCE=$WORKSPACES_PATH/catkin_ws

#Set the terminal colors style (style_1/style_2)
TERMINAL_COLORS=style_2

#Set the interface type (SIMULATION/HARDWARE)
export INTERFACE_TYPE=SIMULATION

#Set the catkin building type (make/build)
CATKIN_BUILD_TYPE=build

To edit this file type:

modify_uma_params

1.3. update_uma_environment

This script (alias) updates the UMA environment. Usage:

update_uma_environment

2. Useful Tools

2.1. Terminator

2.2. create_catkin_ws

This alias guides you to the creation of a new catkin workspace, the catkin build type (make or build) is retrieved from the config file stored in ~/.uma_params.env.
Usage:

create_catkin_ws

2.3. change_ros_ws

This alias provides an easy way to switch from one workspace to another.
Usage:

change_ros_ws
#Note that you can also use the alias 'crw'

2.4. create_ros2_pkg

This alias makes straightforward the creation of a ros2 pkg Usage:

create_ros2_pkg

2.5. nt

This alias can be used to restart the terminal Usage:

nt

2.6. cb

This alias can be used as a fast way to compile a ros2 workspace with colcon build Usage:

cb

2.7. cc

This alias can be used to remove the build, install, and log folders in the sourced workspace Usage:

cc

3. Troubleshooting

3.1. Error when installing python3-catkin-pkg

If you find an error when installing python3-catkin-pkg during the installation, run the following command:

sudo apt --fix-broken install

Then, you'll need to uninstall ros and install the environment again:

sudo apt remove ~nros-humble-* && sudo apt autoremove
sudo rm /etc/apt/sources.list.d/ros2.list
sudo apt update
sudo apt autoremove
# Consider upgrading for packages previously shadowed.
sudo apt upgrade
cd ~/uma_environment_tools/scripts
./install_uma_environment.sh