diff --git a/subteams/flight/installation_guide/installation_guide.md b/subteams/flight/installation_guide/installation_guide.md index ae22d98..efc7ab6 100644 --- a/subteams/flight/installation_guide/installation_guide.md +++ b/subteams/flight/installation_guide/installation_guide.md @@ -6,284 +6,299 @@ permalink: /flight/installation_guide/ [Back to Flight Docs](/docs/flight/) -# Virtual Machine Installation Process +## Installation Process -**Step 1: Install a Linux Virtual Machine** +### Step 1: Install a Linux Virtual Machine (Optional) -In order to run Multirotor code and program effectively with DroneKit and ArduPilot, a -Linux virtual machine (VM) with Ubuntu 22.04 is recommended. Use the following link to -download the Ubuntu OS: +In order to run Multirotor code and program effectively with DroneKit and ArduPilot, a Linux virtual machine (VM) with Ubuntu 24.04 is recommended. If you're on Windows 11, [using Windows Subsystem for Linux (WSL) is recommended](#alternative-using-windows-subsystem-for-linux-wsl), instead. -### Ubuntu Link: +Use the following link to download the Ubuntu OS: -- [https://releases.ubuntu.com/jammy/](https://releases.ubuntu.com/jammy/) +- [https://releases.ubuntu.com/noble/](https://releases.ubuntu.com/noble/) -And choose among the following links for your preferred virtual machine: +And choose among the following links for your preferred hypervisor: -### Virtual Machine Links: +- [https://www.virtualbox.org/wiki/Downloads](https://www.virtualbox.org/wiki/Downloads) +- [https://www.vmware.com/products/workstation-player.html](https://www.vmware.com/products/workstation-player.html) -- [https://www.virtualbox.org/wiki/Downloads](https://www.virtualbox.org/wiki/Downloads) -- [https://www.vmware.com/products/workstation-player.html](https://www.vmware.com/products/workstation-player.html) +#### Alternative: Using Windows Subsystem for Linux (WSL): -A Linux VM is not required; it is entirely possible to run Multirotor code using macOS. -However, **_please_** do not use Windows. The following instructions are based on Ubuntu -22.04. +On Windows, you can install a more lightweight Linux VM using Windows +Subsystem for Linux (WSL). To install Ubuntu 24.04 using WSL, open a PowerShell instance and run the following: -### Alternative: Using Windows Subsystem for Linux (WSL): - -Alternatively, on Windows, you can install a more lightweight Linux VM using Windows -Subsystem for Linux (WSL). Simply install -[Ubuntu 22.04 from the Microsoft Store](https://www.microsoft.com/store/productId/9PN20MSR04DW). -Then, in the Windows Terminal app, click the + button in the title bar and choose Ubuntu -to open a new terminal in your Ubuntu VM. +```ps1 +wsl --install "Ubuntu-24.04" +``` -### More Information on Virtual Machines +To run your virtual machine, execute `wsl` in any PowerShell/Terminal. To see more commands, you can use `wsl --help`. -You can read more about virtual machines on -[our page about virtual machines](/docs/virtual_machines/). +If you will be using our custom Unreal-based simulation (or need to network between native Windows programs and programs running in WSL), it is easiest to use mirrored networking mode. Unfortunately, this is only compatible with WSL2, meaning that Windows 11 is required. -\ -**Step 2: Installing Basic Software** +Run the following command in PowerShell to set up mirrored networking: -Since you have created a new virtual machine, some basic software must be installed before -we can proceed. First and foremost, Git. Use the following command: - -``` -sudo apt install git +```powershell +"[wsl2]`nnetworkingMode=mirrored" | Out-File -Encoding ascii -FilePath "$env:UserProfile\.wslconfig" ``` -Next is Python, the language we will be programming in for the majority of the semester. -We will be using Python 3.10 which can be installed through the terminal. The first -command to copy is: +Alternatively, you may copy the following into a file named `.wslconfig` within your user directory: -``` -sudo apt install software-properties-common -y +```txt +[wsl2] +networkingMode=mirrored ``` -After that command finishes, use the next command: +For your changes to take effect, you need to restart WSL. To do this, run: -``` -sudo add-apt-repository ppa:deadsnakes/ppa +```ps1 +wsl --shutdown +wsl # restart wsl ``` -When prompted, hit enter and allow the downloads to finish. These commands allow for this -version of Python to be easily updated from the command line using +#### More Information on Virtual Machines -``` -sudo apt update -``` +You can read more about virtual machines on +[our page about virtual machines](/docs/virtual_machines/). -Finally, use the command +### Step 2: Installing Git -``` -sudo apt install python3.10 -``` +> For the rest of this guide, make sure to execute commands within your virtual machine! -to install Python 3.10 on your virtual machine. +We manage our source files using [Git](https://git-scm.com) and [GitHub](https://github.com); you will need Git installed on your computer and a GitHub account to contribute to our projects. -You will need to change the Python interpreter within your IDE of choice, however, -independently. +#### Install Git -You can verify the version of Python installed to your computer using the following -command: (The V should be capitalized) +##### Linux/WSL (Ubuntu) -``` -python3.10 -V +Run the following command: + +```bash +sudo apt update && sudo apt install git ``` -If everything was installed correctly, you should see Python 3.10.4 or above. +##### Windows Native -\ -**Step 2.5: Installing Visual Studio Code (Optional)** +To install on Windows natively, you must use an installer: -Visual Studio Code (VS Code) is a popular code editor with numerous free extensions you -can download to add features and customizations. If you are using WSL, VS Code might -already be installed. You can check if VS Code is installed by seeing if the following -command has any output: +- [https://git-scm.com/downloads/win](https://git-scm.com/downloads/win) -``` -which code -``` +WSL has access to your files on your Windows machine, so you can use Git directly on Windows if you desire. Keep in mind that only the commands involving `git` will work outside of WSL in the context of this guide; everything else should be executed within WSL. -If VS Code is not installed, you can run the following command to install VS Code: +#### Create a GitHub Account -``` -sudo snap install --classic code -``` +_If you don't have a GitHub account_, visit this link to create an account: -Then, to open VS Code, simply run the following command in the directory you want to edit -code in: +- [https://github.com/signup](https://github.com/signup) -``` -code . -``` +It is recommended you use a personal email and not your school email when creating your account so you have complete control over your account even after you graduate. -\ -**Step 3: Installing ArduPilot Firmware** +##### SSH Keys -Copy the following Git command into a terminal: +You will need to associate an SSH key with your GitHub account to push to our repository. GitHub has a good tutorial on how to set this up, so check it out: -``` -git clone --recurse-submodules https://github.com/ArduPilot/ardupilot.git -``` +- [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) -After the repo has fully downloaded, copy the following commands into a terminal to setup -ArduPilot: +### Step 3: Environment Setup -``` -cd ardupilot -Tools/environment_install/install-prereqs-ubuntu.sh -y -./waf configure --board sitl -./waf copter -cd .. -``` +#### Clone The Repository -After ArduPilot is completely installed, you will need to add the DroneKit functionality -to Python’s package manager. The version of DroneKit we use is newer than the version -available on PyPI. Run the following commands to install DroneKit: +First, you must clone the flight team's Git repository. Run the following in your shell: -``` -wget https://github.com/MissouriMRR/docs/raw/refs/heads/main/subteams/flight/installation_guide/dronekit-2.9.2-py310-none-any.whl -pip3 install dronekit-2.9.2-py310-none-any.whl +```bash +git clone git@github.com:MissouriMRR/SUAS-2025.git ``` -_Note: pip installs Python packages, whereas apt installs system packages._ +> This will create a new folder, `SUAS-2025`, in your current working directory. Make sure to run that command in the folder into which you want to download the code! +> You will need to have [SSH Keys](#ssh-keys) set up for this command to work. -\ -**Step 4: Cloning Important Repositories** +#### Install Host Dependencies -First, you need to create an SSH key to be allowed to push to our repositories. Run the -following command to create an SSH key: +Next, change directories to the repository: -``` -ssh-keygen -f ~/.ssh/my_github_key +```bash +cd SUAS-2025 ``` -**_Note: never share the contents of your SSH key._** +In the repository, we have a script to install the necessary host packages. If you will not need GPU access when coding, run the following: -To add the SSH key to your GitHub account, go to https://github.com/settings/keys, click -the button labeled 'New SSH key', and then for the Key field paste the output of the -following command: - -``` -cat ~/.ssh/my_github_key.pub +```bash +./install.sh ``` -Then, whenever you open a new terminal, enter the following commands to activate your SSH -key: +If you need GPU access, run the following: -``` -eval $(ssh-agent -s) -ssh-add ~/.ssh/my_github_key +```bash +./install.sh nvidia # if you have an nvidia GPU +# OR +./install.sh amd # if you have an AMD GPU ``` -This will allow you to push to our repositories on GitHub. +> AMD GPUs are currently not supported (I have an nvidia GPU, so I don't know the AMD install stuff). If you have an AMD GPU, feel free to add to the install script and docs! -To clone our main SUAS repository, run the following command: +You will also need the drivers corresponding to your GPU: -``` -git clone git@github.com:MissouriMRR/SUAS-2025.git --recursive -``` +- Nvidia CUDA Toolkit: +- AMD ROCm Install: -\ -**Step 5: Installing Useful Programming Tools** +**You will need to restart your terminal/shell for the installation to complete.** -With the next command, install the Poetry software into the Virtual Machine: +#### Building Containers -``` -sudo pip3 install poetry -``` +To simplify (most) of environment setup, we have [containerized](https://en.wikipedia.org/wiki/Containerization_(computing)) our environment. Specifically, we use [Podman](https://podman.io), which is pretty much the same as its more popular counterpart, [Docker](https://www.docker.com). (Podman and Docker both follow the [Open Container Initiative](https://opencontainers.org) standards, so they are largely interchangable.) -Poetry is used to create a virtual environment that we use to safely and conveniently -manage the libraries that our code depends on. +We use a companion command called `podman-compose` (similar to `docker-compose`) that allows us to define how to run our containers in a `compose.yml` file. -Next, install pre-commit with the following command: +To build our containers, run the following command from within the `SUAS-2025` folder: -``` -sudo pip3 install pre-commit +```bash +podman-compose build ``` -Before you push any code to a branch in a Multirotor repo, run Pre-commit by typing -pre-commit into the terminal before pushing code, and after adding files to a commit. This -will auto-format your code and make it look somewhat nice. +This may take a while, so do something else in the meantime. -### QGroundControl (non-WSL users) +### Step 4: Running Containers (Using the Environment) -For the next piece of software, open a web browser and use the following link: +We have two containers: `env` and `sim`. The `env` container contains everything you need to run your code; the `sim` container will run an [ArduPilot](https://ardupilot.org) drone simulation upon startup. -- [https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html) +> By default, the `sim` container is meant to be used with the Simulation Subteam's Unreal simulation. If you need to override this, use the `compose.override.yml` file to override the `command` property for the `sim` service to the desired command you can run ([see here](#example-overriding-the-sim-containers-start-command)). If you don't know how compose files work, you can look to `compose.yml` for reference or [read this](https://docs.docker.com/compose/). -This page redirects you to the instructions for downloading QGroundControl, a -supplementary software that allows you to get an overhead map of the drone during flight. -Follow the instructions for Linux download, or if you’re the brave soul using macOS, use -the instructions for that operating system. Be sure to follow the instructions for -downloading the installer file as well as any extra packages required (like libfuse2). +For ease of use, we have a `run_container.sh` script. To run both `env` and `sim`, simply run: -### Mission Planner (WSL users) +```bash +./run_container.sh +``` -If you're using WSL, you should install Mission Planner instead of QGroundControl: -[https://ardupilot.org/planner/docs/mission-planner-installation.html](https://ardupilot.org/planner/docs/mission-planner-installation.html). +To run the `env` container on its own, run: -\ -**Step 6: Creating a Convenience File (Optional)** +```bash +./run_container.sh env +``` -In a blank text page, copy the following lines of text: +To attach to the `env` container (connect to it using an interactive shell), run: +```bash +./run_container.sh attach env ``` -if [ ! -d "./ardupilot" ]; then - echo $'Either ardupilot has not been downloaded yet or you are running this script in the wrong place.\nTo install ardupilot, follow the instructions at\n\thttps://ardupilot.org/dev/docs/building-setup-linux.html#setting-up-the-build-environment-linux-ubuntu\nThen build ardupilot by running:\n\t./waf configure --board sitl\n\t./waf copter\nIf you already installed it, then you most likely didn\'t put this script in the parent folder of the ardupilot folder.' - exit 1 -fi -cd ardupilot +> Your local SUAS repository code will be mounted in the `env` container, so any changes made to your local copy of the code is automatically reflected in the container, and vice versa. Essentially, the `env` container is a glorified virtual environment. -if ! grep -q "Multirotor Locations" Tools/autotest/locations.txt; then - echo "GolfCourse not found, adding Multirotor Locations to Tools/autotest/locations.txt..." - echo $'# Multirotor Locations\nGolfCourse=37.9490953,-91.7848293,0,0' >> Tools/autotest/locations.txt -fi +To detach, run the following: -python3.10 Tools/autotest/sim_vehicle.py -v copter -L GolfCourse --map +```bash +exit ``` -Save the file as opensitl.sh +> This will also shut down the `env` container; you'll need to start it again. -Now, each time you want to start the drone simulator, use the bash command +To shutdown any running containers, do: +```bash +./run_containers.sh shutdown ``` -./opensitl.sh + +For more commmands, run: + +```bash +./run_containers.sh help ``` -If you attempt to run this new bash script and you receive the following error: +If you want to take matters into your own hands, you'll need to know how to run/use containers: -bash: ./opensitl.sh: Permission denied +- `podman` Documenation: https://docs.podman.io/en/latest/Tutorials.html +- `podman-compose` Documentation: https://docs.podman.io/en/latest/markdown/podman-compose.1.html +- `docker` Documentation: https://docs.docker.com/build/ + - 99% of stuff that applies to Docker applies to Podman +- `docker-compose` Documentation: https://docs.docker.com/compose/ -You can easily resolve this by changing the file permissions using the following command: +#### Configuring the Containers -``` -chmod u+x opensitl.sh -``` +If you need to configure how a container is run, create a file called `compose.override.yml` in the `SUAS` repository's root directory. This file will allow you to override parameters set in `compose.yml` without modifying up `compose.yml`. If you ran `install.sh` with a GPU selected, `compose.override.yml` should already exist. + +For more information on compose files, see the following: + +- `podman-compose` Documentation: https://docs.podman.io/en/latest/markdown/podman-compose.1.html +- `docker-compose` Documentation: https://docs.docker.com/compose/ -\ -**Step 7: Installing Dependencies in Poetry** +##### Example: Overriding The `sim` Container's Start Command -Navigate to the SUAS repo in your terminal. Then, activate the Poetry virtual environment: +By default, the `sim` container is configured to run the following command on startup: +```bash +python /ardupilot/Tools/autotest/sim_vehicle.py -v ArduCopter -f airsim-copter --out=127.0.0.1:14550 ``` -poetry shell + +This is the command needed to connect to AirSim (the foundation of the Simulation Subteam's Unreal-based simulation of the SUAS competition). If you need to run a different command, you can use `compose.override.yml`: + +```yaml +version: "3" +services: + sim: + command: python /ardupilot/Tools/autotest/sim_vehicle.py -v copter -L GolfCourse --map ``` -You will need to do this every time you work in the SUAS repo to be able to use the -dependencies our code requires. +This will override the `command` field for the `sim` service; essentially, whatever is in the `command` field will run upon container startup. The example above works for a non-Unreal based drone simulation. -Next, run the following command to install the dependencies (you need to do this only -once): +If you already have content in `compose.override.yml`, such as enabling GPU usage, just append what you need to the file: +```yaml +version: "3" +services: + env: + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + sim: + command: python /ardupilot/Tools/autotest/sim_vehicle.py -v copter -L GolfCourse --map ``` -poetry install + +The above combines the alternate `sim` command with an Nvidia GPU-enabled `env` container. + +### Step 5: Installing Useful Programming Tools + +#### Visual Studio Code + +Visual Studio Code (VS Code) is a popular code editor with numerous free extensions you +can download to add features and customizations; however, if you wish to use a different IDE/text editor, feel free to do so. + +If you are using WSL, VS Code might already be installed. You can check if VS Code is installed by seeing if the following command has any output: + +```bash +which code ``` -You can exit Poetry by running the following command while Poetry is active: +If VS Code is not installed, you can run the following command to install VS Code: +```bash +sudo snap install --classic code ``` -exit + +Then, to open VS Code, simply run the following command in the directory you want to edit +code in: + +```bash +code . ``` + +Before you push any code to a branch in a Multirotor repo, run Pre-commit by typing +`pre-commit` into the terminal (from within the `env` container if you don't have it installed locally) before pushing code, and after adding files to a commit. This +will auto-format your code and make it look somewhat nice. + +### QGroundControl (non-WSL users) + +For the next piece of software, open a web browser and use the following link: + +- [https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html) + +This page redirects you to the instructions for downloading QGroundControl, a +supplementary software that allows you to get an overhead map of the drone during flight. +Follow the instructions for Linux download, or if you’re the brave soul using macOS, use +the instructions for that operating system. Be sure to follow the instructions for +downloading the installer file as well as any extra packages required (like libfuse2). + +#### Mission Planner (WSL users) + +If you're using WSL, you should install Mission Planner instead of QGroundControl: +[https://ardupilot.org/planner/docs/mission-planner-installation.html](https://ardupilot.org/planner/docs/mission-planner-installation.html). diff --git a/subteams/simulation/installation/simulation_install.md b/subteams/simulation/installation/simulation_install.md new file mode 100644 index 0000000..40f1af5 --- /dev/null +++ b/subteams/simulation/installation/simulation_install.md @@ -0,0 +1,46 @@ +--- +permalink: /simulation/install/ +--- + +# Simulation Docs + +[Back to Simulation Docs](/docs/simulation/) + +# Installation Process + +## Step 1: Basic Environment Setup + +Follow the [flight install instructions](/docs/flight/installation_guide/). + +## Step 2: Install Unreal Engine & AirSim + +### Installing Unreal Engine + +We will be using Unreal Engine for simulating virtual drones. If you have the Epic Games Launcher installed already (e.g., if you own *Fortnite*), you can download Unreal Engine from the "Unreal Engine" tab. If you don't have the Epic Games Launcher, then you will have to [download](https://store.epicgames.com/en-US/download) it to install Unreal Engine. + +The Unreal Engine version you will download is **4.27.2**. AirSim, which allows us to simulate multirotors in Unreal, does *not* work with Unreal Engine 5 or greater. + +Finally, run Unreal Engine at least once before continuing to the next steps. + +### Installing AirSim + +#### Visual Studio + +To install AirSim, you must first install Microsoft's [Visual Studio Community 2022](https://visualstudio.microsoft.com). This will also be the IDE you will use for programming C++ code for Unreal. + +When installing, you must select the following: +- `C++ Development Pack` +- `Windows SDK 10` + +#### AirSim + +AirSim is an Unreal Engine plugin for simulating multirotors and cars that was previously maintained by Microsoft; it is the backbone of simulation. + +To install AirSim, follow these steps: + +1. clone the AirSim GitHub repository: `git clone https://github.com/Microsoft/AirSim` + - the location of your local copy does not matter +2. Launch `x64 Native Tools Command Prompt for VS 2022` (using Windows search) + - navigate to where you cloned AirSim with the `cd` command + - run the command `.\build.cmd` + - wait for AirSim to build diff --git a/subteams/simulation/installation/simulation_installs.md b/subteams/simulation/installation/simulation_installs_legacy.md similarity index 81% rename from subteams/simulation/installation/simulation_installs.md rename to subteams/simulation/installation/simulation_installs_legacy.md index 6bb3167..9fcc41a 100644 --- a/subteams/simulation/installation/simulation_installs.md +++ b/subteams/simulation/installation/simulation_installs_legacy.md @@ -1,17 +1,18 @@ ---- -permalink: /simulation/install/ ---- - -# Simulation Installations - -[Back to Simulation Docs](/docs/simulation/) - -There are several pieces of software needed to get up and running with the simulator. Go to the page corresponding to your system for installation instructions. - -- [Installation for Windows](/docs/simulation/install/windows) -- [Installation for Linux](/docs/simulation/install/linux) - - Mac users go here too - - Windows is currently the only system that Simulation is known to function on - -After you have completed the installations, you can proceed to [Flying the Drone with Code](/docs/simulation/flying/). - +--- +permalink: /simulation/install/legacy/ +--- + +# Simulation Installations + +[Back to Simulation Docs](/docs/simulation/) + +There are several pieces of software needed to get up and running with the simulator. Go to the page corresponding to your system for installation instructions. + +- [Pre-Configured Installation](/docs/simulation/install/pre-configured/easy/) +- [Installation for Windows](/docs/simulation/install/windows) +- [Installation for Linux](/docs/simulation/install/linux) + - Mac users go here too + - Windows is currently the only system that Simulation is known to function on + +After you have completed the installations, you can proceed to [Flying the Drone with Code](/docs/simulation/flying/). + diff --git a/subteams/simulation/simulation.md b/subteams/simulation/simulation.md index d48c6d0..2efc982 100644 --- a/subteams/simulation/simulation.md +++ b/subteams/simulation/simulation.md @@ -10,7 +10,7 @@ Here you will find documentation and tutorials relating to the simulation subtea ## Getting Started -To get started with installation of the simulator, follow the guide here: [Simulation Installations](/docs/simulation/install/) +To get started with installation of the simulator, follow the guide here: [Simulation Installation](/docs/simulation/install/) After you have installed the simulator, proceed to [Flying the Drone with Code](/docs/simulation/flying/). @@ -21,13 +21,12 @@ After you have installed the simulator, proceed to [Flying the Drone with Code]( ## Docs Directory -- [Simulation Installations](/docs/simulation/install) - - [Docker Install for Ardupilot] - - [Intalling Pre-Configured Enviroment](/docs/simulation/install/pre-configured/easy) - - [Installing on Windows (Advanced)](/docs/simulation/install/windows) - - [Installing on Linux (Advanced)](/docs/simulation/install/linux) +- [Simulation Installation](/docs/simulation/install) + - [Simulation Installation (Old)](/docs/simulation/install/legacy) - [Flying the Drone with Code](/docs/simulation/flying/) - [Environment Debugging (Windows)](/docs/simulation/environment-debug/windows) -- [Using Satellite Data in Unreal Engine](/docs/simulation/importing_satellite_data) - [Using RealityScan to Create 3-D Models](/docs/simulation/realityscan) + +### Legacy - [Loading Real World Data with Cesium for Unreal](/docs/simulation/cesiumforunreal/) +- [Using Satellite Data in Unreal Engine](/docs/simulation/importing_satellite_data)