Skip to content

2. Setting up your environment

Jump to bottom
Imad Issafras edited this page Oct 14, 2024 · 22 revisions

M1/M2 macs setup

Homebrew + conda

Getting Homebrew

Run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Getting Miniconda

Miniconda will be the environment manager

  1. Install it brew install --cask miniconda
  2. Initialize it: conda init "$(basename "${SHELL}")", restart the terminal.
  3. Create the ROS environment: conda create -n ros_env python3=11 && conda activate ros_env
  4. You are now ready to install the rest.

Getting PX4 and Gazebo-classic

More info in PX4 MacOS Setup guide

  1. Increases the maximum number of open files: echo ulimit -S -n 2048 >> ~/.zshenv
  2. Make sure you are in the conda env ros_env. Your terminal should say "(ros_env)" above the prompt.
  3. Install general tools: pip install pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
  4. Install the PX4 toolchain: 
    git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot
./Tools/setup/macos.sh --sim-tools
  5. First confirm you have gazebo-classic: gazebo --version
  6. Confirm everything work: in the PX4 root directory, run make px4_sitl gazebo-classic

Potential problems:

  • Problem: ./Tools/setup/macos.sh have some issues with the --user flag when installing python dependencies.

    Solution: edit the macos.sh file and remove the --user flag on the line python3 -m pip install --user -r ${DIR}/requirements.txt

  • Problem: make px4_sitl gazebo-classic throws an error involving the qt library. This is due to two conflicting qt libraries.

    Solution: Remove one of them: brew uninstall --ignore-dependencies qt and try to make again. If the error persist, reinstall it (brew install qt) and remove the other (brew uninstall --ignore-dependencies qt@5).

Getting ROS2

More info in RoboStack installation guide

  1. Activate the ros_env conda env.

  2. Get ROS2: conda install --override-channels -c conda-forge -c robostack-staging ros-humble-desktop -y

  3. Reactivate the env to initialize the ROS2 env:

     conda deactivate
 conda activate ros_env

  4. Install development tools for ROS2: conda install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep orgre

Virtual Machines for tool set and Gazebo server + Gazebo-classic client running natively

Virtual Machines

Windows

In Windows, we need to install Ubuntu 22.04 (Jammy) under WSL 2. This is only possible on Windows 10 version 2004 and higher or Windows 11. To do so, open the Windows command prompt as administrator and run wsl --install. Once that's done, restart your computer and open the Terminal application (Use the search bar if you need to, I also recommend pinning it to your taskbar once it's open). Click on the "v" next to the "+" in the top bar, go to settings, and change "Default profile" to "Ubuntu" (If Ubuntu doesn't appear as a possible choice, it was not installed properly, try wsl --install again). Then, under the "Profiles" section, find your Ubuntu profile, and enable "Run this profile as Administrator". Finally, press the "+" to open your Ubuntu terminal. Run cd && git clone https://github.com/mcgill-robotics/drone to be on the same page as Mac users.

Mac

In Mac, we don't have WSL and thus have to go through the normal means of getting a virtual machine. Install VirtualBox, this will be our virtual machine's type 2 hypervisor. Depending on if you have an Intel chip (amd64) or an Apple Silicon chip (M1/M2) (arm64), you will need to install a different image (.iso) file of Ubuntu 22.04 (Jammy). For Intel chips, download the x86_64/amd64 image. Otherwise, download the arm64 image. Open VirtualBox, go to Machine -> New, give your VM a name, and select the ISO file you just downloaded. Enter a new username and password (or keep the default). Allocate as much Base Memory and as many Processors as you can while still staying in the green zone. Give the VM around 70 GB for the Disk Size. Then press Finish. This should launch the VM, which may launch an installer, follow the steps of the installer if you need to do so. Once the installer is done, you should be prompted to enter your username and password. Once you have your command prompt, run cd && git clone https://github.com/mcgill-robotics/drone && cd drone/setup_scripts && source setup_ubuntu.sh. This will install a graphical user interface, which is going to make your life easier and make it possible for you to run the Gazebo server. The user interface the script installs is the i3 window manager, which is a tiling window manager. For now, all you need to know is that to run a terminal emulator (get a shell prompt), you press <Alt>+<Enter>, but there are plenty of other key combinations to perform various actions. More information can be found here and its configuration file is under ~/.config/i3/config.

Toolset

We need to clone the PX4 repo and install ROS2 humble, Gazebo classic 11.10.2, and PX4's build dependencies. These can be done through the setup_tools.sh script under setup_scripts. Run cd ~/drone/setup_scripts && source setup_tools.sh. This will take a while so carry on to the next section while it's running. Avoid killing the virtual machine in the meantime or turning off your computer and keep an eye on it as it may prompt you for your sudo password again.

Gazebo

We need Gazebo version 11.10.2 running natively, Gazebo is the simulator we use. We will do so by using the Conda package manager.

  1. Install MiniConda by selecting the right installer for your OS, make sure to check the add to PATH box during the installation to not have to do it manually later
  2. Open the command prompt
    • Search for cmd.exe on Windows
    • Search for Terminal on MacOS
  3. Run conda install git in the prompt if you don't have git
  4. Once that's done, run conda create -n ros_env && conda activate ros_env
    • This creates a Conda environment that is self-contained, similar to a Python venv, named "ros_env"
    • Then you run conda activate to enter the environment
    • This should prefix your prompt with "(ros_env)"
    • Later, you can run conda deactivate to exit the environment
    • More on managing conda environments here
  5. Run
conda config --env --add channels conda-forge
conda config --env --add channels robostack-staging
conda config --env --remove channels defaults
  • This ensures packages are installed from conda-forge or robostack-staging
  1. Install Gazebo 11.10.2 by running conda install gazebo=11.10.2
  2. Once the installation is done, close your terminal
  3. From a new terminal, run conda activate ros_env, then try running gazebo --version
    • This should not throw an error
  4. Run gazebo in your terminal, this should open a GUI
  5. Close the GUI (either CTR+C from the terminal or press the x at the top right of the gazebo GUI)
  6. From the terminal change directory into your home directory
  • In Mac and Linux, this can be done with cd ~
  • In Windows, cd %userprofile%
  1. Run cd .gazebo && git clone https://github.com/PX4/PX4-gazebo-models.git
  • We need the various meshes and scripts inside this repository so that our gazebo client can render the simulation properly
  1. Move all of the files and folders of the cloned repository to the .gazebo directory

Connecting VM with Gazebo classic

Theory

Quick intro to TCP/IP

An IP address is a number that identifies a device on the Internet or in a local area network (LAN), namely, public IP addresses are used for the Internet while private IP addresses are used for LANs. IPv4 addresses are composed of 4 bytes, then shown with a period separating the various digital values of the bytes (of the form : [0-255].[0-255].[0-255].[0-255]). IP addresses aid in the internet layer. Once we have the right machine through the IP address, a port is a number used to identify a connection endpoint on a computer. Ports aid in the transport layer. TCP and UDP are 2 common transport layer protocols. Through the Internet Protocol suite (TCP/IP), data is sent in small chunks called packets. TCP is reliable, sends one packet at a time, and makes sure the current packet is received before sending the next. UDP is "best effort", it sends packets without bothering to check that the previous packets reached their destination. They are both useful and are used for different use cases. UDP may be used for an FPS video game's communication where we only care about the latest state of the game. TCP may be used for a file transfer where the protocol's reliability is necessary to ensure no parts of the file are lost. On top of the transport layer sits the application layer. This layer has various protocols such as HTTP, SSH, NTP, etc. These usually are always used with either TCP or UDP, HTTP is for instance always used with TCP. This video gives an overview of TCP/IP communication, and this video goes more in-depth on the concept of protocols. A Uniform Ressource Identifier (URI) is a sequence of characters that distinguish one resource from another, a Uniform Resource Locator (URL) is a type of URI. URIs may be composed of 4 parts: a scheme name, authority, path, query, and fragment. Only the schema name, authority, and path are mandatory. The scheme name may be the application protocol. For instance, the URI http://192.168.0.3:1134/ has "HTTP" as the scheme name, 192.168.0.3:1134 as the authority (which is an <IP>:<Port> composition named a socket) and / as the path. A firewall is a network security device that monitors traffic to or from a network. It allows or blocks traffic based on a defined set of security rules. These could be rules like allowing all communication from any IP address on a specific port or blocking all communication from a specific IP address on all ports.

Quick Intro to LAN

Local Area Networks allow 2 or more computers to communicate without going through the internet. Imagine, that the internet is like the postal service. In this metaphor, why would you go through the postal service if you want to deliver mail to your neighbor? Just go to his address and deliver the mail to him directly. Not only is this faster, but this also means that a postal service isn't even needed in the first place, communication can be done without the Internet. Private IP addresses are used in the context of LAN communication and come with an address mask, which can be used to easily tell if another IP address could be in the same LAN. For instance, 192.168.0.0/16 is a private IP address with a forward slash and a network mask (in number of bits), this says that all IP addresses starting with the same 16 bits (2 bytes) as the IP address, all addresses starting with 192.168.x.x, could be reachable without needing to go through the internet. The IP of your computer as well as the network mask are defined by your router or can be statically set then need to match on another computer on the same network for both computers to communicate (netmask mask compliant but different IP addresses + same network mask). More on private IP addresses, in this video explaining LAN, WAN, and subnet and this video explaining subnet masks.

All that to say

We need our host and our VM/WSL machines to be in the same network, and we need to set the GAZEBO_MASTER_URI variable to both the client and server gazebo instances to be a URI inside the VM/WSL instance. We also need to configure the firewall on the VM/WSL and on our host machine to allow communications between the 2 computers.

Practice

In general

On Ubuntu, you run the command ip a to see all your network adapters and your IP address/netmask for each adapter, or ifconfig.

WSL

On WSL, the network adapter of interest is called eth0 and everything should work out of the box. Copy the IP address (also called inet) you get for the eth0 adapter from your WSL, run export GAZEBO_MASTER_URI="http://<the_WSL_ip_address_here>:11345" on the WSL instance, and run set GAZEBO_MASTER_URI=http://<the_WSL_ip_address_here>:11345 on your command prompt. This will tell the Gazebo server and client where to find the Gazebo master, syncing both applications and allowing them to communicate whenever they are running. This step needs to be done every time.

VM

Close your VM, go into the settings for your VM, into "Network" and change the adapter's "Attached to" setting from NAT to bridged. Re-open your VM and now, when you run ip a in the Ubuntu shell, you should see that the inet for your non-loopback adapter starts the same as your host's IP address, meaning they are on the same network. just follow similar steps to the WSL instructions, but instead of eth0, the adapter may have a different name.

Optional customization

For an enjoyable coding experience, you need a comfortable and familiar environment, while still being able to challenge yourself here and there in a rewarding fashion. This will also aid you in being more efficient in the long run.

Code Editor

While VS Code will work quite fine, I recommend looking into NeoVim. Not only will you develop an understanding of the various parts that make your code editor so good at assisting you, but you will also find that Neovim's focus on hyperextensibility means that, often, someone has already made a NeoVim plugging exactly for your use case (ex, showing a preview of a markdown file as you're writing it). It is also lightweight, runs from the terminal, and is highly configurable. Not to mention that, like Vim, NeoVim has a high skill cap, and figuring out the fastest way to perform a task and mastering it through repeatedly using it is highly rewarding and keeps coding exciting, challenging, and fun. I recommend starting with following the kickstart.nvim repo's instructions and watching the video made by it's creator to get into NeoVim.

Shell

First and foremost, consider switching from bash to Zsh for your shell. This article explains why the switch may be worth your time. Here is another article that explains how to switch and rice your Zsh. If you use Oh My Zsh, you don't need to do the Shell prompt customization through Oh My Posh.

Shell prompt

Customizing your shell prompt is also a nice way to customize your environment. Oh My Posh offers a way to easily customize your prompt, through special JSON files. Oh My Posh also comes with a bunch of default themes which can be either used directly or used as a template to modify and make yours.

Terminal emulator

Your terminal emulator is Terminal on Windows, which can be customized through the Profiles section in the Terminal Settings. On the VM, the installed terminal emulator if you used the setup_ubuntu.sh script is Terminator which can also be customized.

Window Manager (on VM only)

If you used the setup_ubuntu.sh script to set up your VM, then you have the I3 Window Manager, which is a very popular window manager in the ricing community. Linux Ricing is when effort is put into the aesthetic of software, here, the window manager. Thus there are plenty of tutorials out there for customizing the look and feel of I3, here is a playlist recommended by the main Linux Ricing subreddit.

Considered approaches (For future lead's reference)

We want a way to have our system run the simulation smoothly to make development enjoyable, this requires GPU-accelerated graphics. In the case of a graphics card that is within the same chip as the CPU, a virtual machine or WSL should work fine. The issue arises when the computer has a dedicated GPU, thus making it complicated for the simulator to access the GPU from a virtual machine. Without a hypervisor type 1, only one OS can use the GPU at a time, meaning only the host OS uses the GPU, meaning no GPU for our virtual machine. Not to mention that a good proportion of students use Mac, so our solution should be OS agnostic. In the bellow list, + means a positive aspect, - means a negative aspect, X means a dealbreaker

  1. Dual-booting
    • - Non-trivial to set up
    • X Not universal, notably, complicated on Mac.
    • - Trickier to restart from 0 than virtual machines
    • + Bare metal performance
  2. WSL by itself
    • X Requires Windows machine
    • - Doesn't work with some GPUs, notably Intel Iris Xe GPU
    • + Supports most GPUs
    • + As easy to experiment with as any virtual machine, can always scrap it and restart from new
  3. Virtual machine by itself
    • X Doesn't work with GPUs at all
  4. Docker for tool set + Gazebo ignition running natively
    • + Can easily share an image with all the tools needed for development
    • Supported platforms for gazebo
    • X Gazebo's Windows support doesn't include the GUI at the time of writing
    • - Untested on Mac
  5. Docker for tool set + AirSim running natively
    • + Can easily share an image with all the tools needed for development
    • + Runs on top of Unreal Engine, making it ideal for realistic computer vision
    • X AirSim doesn't work on MacOS
    • - Microsoft, AirSim's developers, have stopped working on it since 2022
      • Colosseum is a successor to AirSim which supports PX4, sadly only for multi-rotors as well
    • - Only supports PX4 multi-rotor, no VTOL
  6. Docker for tool set Gazebo server + Gazebo-classic client running natively
    • + Can easily share an image with all the tools needed for development
    • - Gazebo-classic is reaching End Of Life (EOL) in 2025
      • Hopefully, by the time it reaches EOL, gazebo ignition will work on more than just Linux
    • + Easy to setup
    • + Uses Conda for Gazebo which is cross-platform
    • + Gazebo classic works on all platforms (supposedly), meaning simulation is running natively
    • X Docker desktop doesn't support X11 which is needed by Gzserver
      • No way around Docker desktop on Windows and Mac
  7. (WSL for Windows, VM for Mac) for tool set and Gazebo server + Gazebo-classic client running natively
    • - A bit more complicated to setup
    • + Uses Conda for Gazebo which is cross-platform
    • + Gazebo classic works on all platforms (supposedly), meaning simulation is running natively
  8. RECOMMENDED APPROACH FOR FUTURE: (WSL for Windows, VM for Mac) for tool set and Gazebo server + Gazebo ignition client running natively
    • Gazebo-classic is being deprecated soon, but we're forced to use it as the Windows version of Gazebo Ignition doesn't have a working client.
Clone this wiki locally