Setup Guide

Setting Up the Software Development Environment

Source Code

Team code can be accessed through our Github educational organization's repository. Refer to the git guide. Most of the code will be developed under the drone_code project, which is a private repositry only visible to active UAS@UCLA members on the github organization account.

Thanks to Docker containment, our software development platform works across multiple operating systems (Ubuntu, Debian, Arch, MacOS, and Windows to a limited extent) while retaining the flexibility provided by a traditional Debian-based operating system. Essentially all of our major tools will be accessible through our custom ./uas.sh script in the root of the drone_code repository, so check out the help text/source of that script for all of the options available.

Troubleshooting

Run into issues? See the Troubleshooting Page. If you don't see the error you're getting, message the #newbies channel on Slack.

Operating System

Please refer to your specific operating system for setting up the software development environment.

Linux

To install all necessary dependencies to build the code for UAS, run the below command.

./tools/scripts/install.sh

The install script assumes you have the Ubuntu 18.04 LTS version. If you have an alternative Linux distribution, please look through the /path/to/tools/scripts/install.sh file and install the necessary packages with the respective package manager.

Docker Configuration

To install Docker for Linux, here is a guide for Debian and a guide for Ubuntu. To allow use of docker as non-root, you will need to add you host user to the docker user group. Run the below command first, and then logout/restart your system for changes to take immediate effect.

sudo usermod -aG docker $(whoami)

If you are having problems installing Docker, then open the /etc/apt/sources.list file, scroll to the bottom of the file, and edit out the release files of Docker. Then attempt to install Docker again.

MacOS

Run the below command on a terminal.

./tools/scripts/install.sh

Brew is used to install the required software for Mac. The install script should install Brew automatically, if you don't already have it.

MacOS lacks a native implementation of containers, meaning that Docker will need to run in a Virtual Machine. Although code will still build successfully, this means that there will be a slight performance reduction and controls simulations may be less accurate due to the slower virtualized hardware.

Docker for Mac is a tool for running Docker on MacOS, but it is painfully slow with file system sharing. Using NFS (network file system) remedies this, and NFS is supported in Docker for Mac, but it's difficult to setup. For now, our code is geared toward the alternative to Docker for Mac, known as docker-machine. We use docker-machine-nfs to set up the NFS file system to speed up disc accesses from inside the container.

The install script will install everything you need to run Docker, with exception of VirtualBox.

Run ./tools/scripts/docker/start_machine_mac.sh to create the Docker VM.

Run ./uas.sh build to attempt to build the code. It should take care of starting up the Docker container system for you, but if it fails for whatever reason, try to manually execute the bash commands from the script here.

After testing, run ./uas.sh cleanup_docker and answer "y" to shut down Docker processes.

Windows

Please note that setting up the software development environment on Windows requires the following steps to be followed strictly. The following set of instructions will take approximately 1-2 hours. If you are really good with computers, then this setup could be done in 40 minutes. These set of instructions have a lot of external links. Rest assured that these links have been updated recently. Nevertheless, some errors may occur in this process. Please message the slack #newbies channel if such errors occur. If you consider this procedure too difficult, an alternative is to use Oracle VM Virtualbox and to download a Ubuntu 18.04 LTS ISO. Another great alternative is to dual-boot Windows with Ubuntu 18.04, and you can watch this YouTube video.

Also note that VirtualBox and other VM software are incompatible with Docker due to conflicting settings in Windows. If any other software you need conflicts with Docker, it is reccomended that you dual-boot with Ubuntu instead.

  1. Enable Developer mode. Press the Windows key, and search For developer settings. Click on Developer mode and restart your machine.

  2. Enable the Linux Subsystem for Windows using PowerShell. Press the Windows key, search Windows PowerShell, right click and press Run as administrator. Then run the below command.

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
  1. Install the Ubuntu Subsystem for Windows version 18.04 LTS using the Windows Store.

  2. To install bash, open a Command prompt by opening the start menu and typing in cmd and opening the first result. With it open, type in bash and hit enter to install bash. This will handle downloading it and create the local Unix user.

  3. Install VS Code. This is the editor of choice for Windows machines due to its integrated bash terminal.

  4. Run the following commands to update all installed packages and install dos2unix.

    sudo apt-get update
    sudo apt-get upgrade
    sudo apt-get install dos2unix
  1. Clone with ssh the drone_code GitHub repository onto the C: folder. The path should be /mnt/c/. It is highly reccomended to use git bash to clone the repository as it will take care of converting the line endings from \r\n to \n. Refer to the git guide and the GitHub repository. You must be logged into GitHub and have permission to clone the drone_code repository.

  2. Configure the integrated terminal in VS Code such that the terminal defaults to Bash on Ubuntu. Change the default terminal to WSL Bash. Press F1 in VS code, and type Terminal: Select Default Shell.

  3. Open VS Code. Change directory to the drone_code folder. Press Ctrl+` to display the terminal. When that is done, VS Code should look similar to the below image. Please refer to the VS Code key bindings guide for editing hotkeys. One feature you may consider changing is the Toggle Integrated Terminal command to simply a ` press instead of combining Ctrl+`.

  1. Run the below commands and then reboot your machine. Note for the install.sh script, you may have to run dos2unix ./tools/scripts/install.sh.
    sudo apt install python2.7
    ./tools/scripts/install.sh
    sudo usermod -aG docker $(whoami)
  1. The next step involves installing Docker CE for Windows. However, Docker CE for Windows is restricted to only Windows 10 Pro, Enterprise, and Education versions due to the Hyper-v package needed to use dockers on Windows. You most likely have a Windows 10 Home version. You can check by pressing the Windows button, search About your PC, and scroll to the bottom to view your Windows 10 edition. The UCLA Engineering school does offer a Windows 10 Education edition. Please login to the UCLA MyEngineering website. On the left-hand side, click Software Download, then click Microsoft Imagine Premium. It should redirect you to the webstore. Shop for the Windows 10 Education edition, add to cart, and checkout for free. Save the product key. Press the Windows button, search for Settings. Scroll down to Update & Security. Press Activation. Update the product key to the Education edition. The Windows update should take about 7 minutes.

  2. Install Docker CE for Windows. You have to create a Docker account. The next step is to enable the Docker engine for Windows Subsystem for Linux. Right now, Docker is only installed in Linux. If you execute the command docker ps, you will see the error Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.

  3. Expose the Docker daemon on Windows. Run the Docker for Windows shortcut on your desktop. On the bottom right-hand corner of your Windows screen, right click the Docker icon and click Settings. Then check the Expose daemon on tcp://localhost:2375 without TLS setting. Refer to the image below.

  4. Enable Docker sharing on the Windows drive you intend to develop on. You must click the apply button. Refer to the image below.

  5. Link the Docker client to the location of the Docker host. Do this on the integrated terminal of VS Code.

    export DOCKER_HOST=localhost:2375
    echo "export DOCKER_HOST=localhost:2375" >> ~/.bash_profile

This is so that the Docker in the Linux subsystem is directed towards the Docker in Windows.

Notes on Windows

Due to the complex nature of Windows, members may be restricted to specific subteams when using Windows. It is for certain that ground station and vision development will work perfectly fine on Windows machines. At the moment, there is a 60% chance that Controls code will work on the Windows machine due to the complexity of the Bazel build.

If for any reason you run into any errors using the Linux subsystem for Windows, you can uninstall Ubuntu or any other Linux distribution like a normal application. Just right click on the Ubuntu application and click uninstall.

Lastly, every time Windows restarts, it takes approximately 2 minutes for Docker to load. Please be patient for Docker to run before executing Docker scripts.

Using Docker

See the Docker guide.

Verifying Setup Environment

This section describes how to verify your setup environment works.

Verify Installation

If the installation process was a success, then running the below command.

    ./uas.sh install

The output should yield the below image.

Verify Controls, Ground, and Vision Works

See the Docker guide.