Interacting with the Environment
Containers🔗
VS Code is now connected to a container, a container is an instance of an image which was just created. This image is defined from the .devcontainer/Dockerfile which imperatively describes steps to be applied to a base image, in this case osrf/ros:humble-desktop-full which is itself based off of Ubuntu 22.04.
VS Code does a lot of heavy lifting and the result is the same UI you might be used to with a few key differences.
In the bottom left you will see Dev Container: UAS PX4+ROS2 this is similar to the remote development feature of VS Code and lets you know that you are not developing on your host OS.
A container is actually mostly isolated from the entire system, this means that it cannot access you local file system unless we tell it to. We mount the dev_env directory to the ~/workspace path on the container, this shows up in the file explorer on the side bar. Any changes you make here will be reflected if you open this directory on the host system.
Anything you do outside of ~/workspace (which you can do via the terminal) will contained to the container and will be lost if you rebuild it.
The terminal is also bound to the container and does not interact directly with the host.
The Terminal🔗
Open the terminal with the default hotkey ctrl+` (or whatever you're used to), this is the window with which we will interact with the system.
This terminal by default opens bash a shell that enables us to command the OS. This is similar to cmd or powershell from Windows, macOS by default uses Zsh which is a superset of bash.
If you have not cloned any repos you will most likely see:
bash: /home/uas/workspace/uas_ws/install/local_setup.bash: No such file or directory
This is because we do not have a ROS2 colcon workspace setup yet (covered in ROS2 tutorials).
You will see uas@ros-dev:~/workspace$, this is the command prompt where you will write commands. uas is the name of the user and is set by the container, ros-dev is the hostname of the system and is set by the container. ~/workspace is the current directory you are in, in UNIX like systems ~ is a shorthand for the "home" directory of the user. On this system this expands to /home/uas, this is similar to C:\Users\<username> on Windows.
Type ls and press enter, you should see a list of files and directories present in the workspace directory. As noted before these are actual files from your host OS that the container has been given access to.
Type cd .. to go one directory up and press enter, you should now see uas@ros-dev:~$ you are now in ~ or /home/uas. Type the ls command again, you will see workspace (and maybe some other directories) which is present on your host system! Type cd workspace to go back to where you were before.
ls can also be extended with optional arguments. Try ls -la you should see that the files have now been printed in a column with additional information on each row, you should also see more files/directories than last time. To learn more about these arguments use the man command (short for manual). Try man ls to see all possible options you can use. Nearly all commands have an associated man page that you can read.
This wiki and most external tutorials will provide commands for you to run, but if you'd like to learn what exactly these commands here are some places to start:
- https://ubuntu.com/tutorials/command-line-for-beginners#1-overview
- https://www.freecodecamp.org/news/bash-scripting-tutorial-linux-shell-script-and-command-line-for-beginners
Tip: files in the container can be opened in VS Code with code <filename>. Try it with code /build/PX4-Autopilot/README.md, this opens the PX4 README which was installed to /build by the container! You can also use tools like vim and nano to edit files from the command line, but they will not be covered here.
Package Installation🔗
On Ubuntu and most Linux distributions installation and management of software is done through a package manager. On Ubuntu the apt command can be used to interact with this system.
Try typing speedtest-cli you should see bash: speedtest-cli: command not found this is because we need to install it. Try sudo apt install speedtest-cli to install. (type y and enter if prompted)
Now if you type speedtest-cli you will get an internet speed test. We can install most programs you can think of this way, if you'd like to view the official list of packages see here: https://packages.ubuntu.com/jammy/
sudo?
Just as Windows sometimes needs administrator privileges to install software, on most Linux distributions package management must be done with elevated permissions. We call a user with such privileges a "super user". The sudo or "super user do" command enables a normal user to run a command with elevated permissions. In this container the uas user has been granted passwordless sudo, on most other Linux systems you will find that you will need to enter a password.
If you are coming from Windows apt is similar to winget, scoop, or choco. On macOS the equivalent is homebrew.
The Simulation🔗
Before you start you will have to enable X11 pass through, X11 is a windowing system that allows programs to draw to the screen and is how the container will create windows on our host computer.
For Linux the container is already setup to mount the X11 socket and configure $DISPLAY, but you may have to run xhost +local:docker if nothing shows up when you run the simulation. (this command allows non-network local connections to access the X server)
For Windows see: https://medium.com/@potatowagon/how-to-use-gui-apps-in-linux-docker-container-from-windows-host-485d3e1c64a3
For macOS try: https://gist.github.com/sorny/969fe55d85c9b0035b0109a31cbcb088
The dev_env comes preconfigured with a task for running the default simulation. Open command palette ctrl+shift+p and search for Tasks: Run Task, press enter and choose Launch simulator. This will spawn three terminals that will open two windows, the Gazebo sim and QGroundControl. See .vscode/tasks.json if you'd like to see what shell commands get run.
If you pan around the scene with your mouse and you are getting more than 10fps then the container is using your GPU correctly. If panning is not smooth and your RTF (real time factor) represented as a percentage in the bottom right is more than 80% than your container is not using your GPU correctly. If you are getting low frames and your RTF is also low than your computer is bad or you have not allocated enough resources to your container.
GPU support
See the README.md in the dev_env repo to check if someone has already written instructions/tips for your system topology.
If you are on Linux you probably need to install some packages, a good a place to start is to search docker linux <amd/intel/nvidia> <desktop/laptop> gpu
If you are on Windows see the WSL2 note back on Developer Environment
Otherwise try searching for docker <operating system> <amd/intel/nvidia> <desktop/laptop> gpu
If you want to fly the drone you can use the commands on the left of the app like Takeoff, after the drone takes off you can also click on places on the map and tell the drone to fly there. If the simulator does not let you take off please resolve the warnings.
You can also control the drone with a virtual joystick (a little difficult to use without a touch screen) to enable go to Application Settings > Fly View > Virtual Joystick.
Status warnings
The top left section of the status bar is yellow because we have flight warnings, the simulator will probably let you take off without resolving them but if you would to anyways:
Click on the Ready To Fly text in yellow. Under Overall Status you should see No manual control input, you are getting this warning because you have no joystick connected to the simulator. Either enable the virtual joystick or select the COM_RC_IN_MODE parameter in the blue text, change it to Stick input disabled and press save (you should only use this setting in sim).
If you see any other warnings try waiting or restarting the sim, otherwise check the forums.
Physical joystick
You can use various controllers with QGroundControl as a "joystick" to control the drone, most RC controllers should be detected by default. See https://github.com/UTAT-UAS/dev_env?tab=readme-ov-file#joystick for enabling /dev pass through.
When ready kill the simulator (close the windows and/or press ctrl+c in the terminal windows).