Module 0: UAV Environment Setup


Instructional Content Access

Throughout this course we leverage instructional content from various sources. For better or worse, some of those source require accounts. Please follow the links below for setting up accounts for MIT’s GitHub and BWSI’s edX platforms

MIT GitHub Account

MIT Touchstone Collaboration Account Instructions

BWSI edX Account

Instructions for BWSI’s edX application. Note: You should already have an account having completed the pre-requisite online portion of this course


Intel RTF Drone Setup

The purpose of this module is to walk you through the entire setup process for the Intel Ready-To-Fly Drone. In spite of its name, the Intel RTF isn’t quite “ready to fly” out of the box; you need to connect some peripheral hardware to install the most recent software. Furthermore we will need to customize some of the software and firmware in order to prepare it for our specific use cases in the UAV Class and Challenge.

Step 1: Initial Setup

Reference: Intel Documentation

Video Walkthrough

Intel has provided a thorough walkthrough for connecting peripheral hardware, installing appropriate operating systems, and “flashing” the needed firmware. The initial setup installs a Linux operating system that has been custom-made by Intel for the Ready-To-Fly Drone using Yocto. It is not important to understand what Yocto is, just that it is in contract to Ubuntu that we will install later.

In the following steps we’ve copied over many of the instructions directly from Intel’s documentation but we’ve added a few notes of our own. You should be able to walk through the steps on this page but we frequently link to Intel’s documentation in case you want further information.

Warning:

Both the USB hub and the monitor must be connected to wall power. An unpowered USB hub can lead to sneaky errors with the cameras that can be extremely hard to debug!!

  1. Hardware Setup

  2. OS Installation and Flashing Firmware

  3. Sensor & Radio Calibration

Note: Sensor & Radio Calibration

When calibrating and configuring the remote control, set Flight Mode 1 to Manual, Flight Mode 4 to Position, and Flight Mode 6 to Offboard

Step 2: Ubuntu Installation

Reference: Intel Documentation

Due to the wide range of robotics and computer vision libraries we will use on the drone, we need to overwrite the the default, Yocto-based operating system based that we just installed.

Note: Do not skip the Yocto installation and try to jump directly to Ubuntu! You need to install Yocto first to ensure BIOS and FPGA is properly installed

Intel’s documentation, link given above, is very thorough but you don’t want to make a few modifications. Follow these steps, taking note of the modifications we propose:

  1. Install Yocto First

  2. Install UbuntuNOTE: See additional instructions here

  3. Intel Aero Repo

  4. Maintenance ToolsNOTE: Skip the QGroundControl section. creating the file /etc/mavlink-router/config.d/qgc.conf seemed to cause problems with the drone accessing wifi and the internet. Since we plan to use our drones indoors within range of a wifi router, it is recommended that instead of creating the qgc.conf file, you connect the drone to wifi and then connect QGroundControl to drone using the drone’s IP address. See Network Setup for more information

  5. RealSense SDK

Notes: Install Ubuntu

Go through the Ubuntu setup instructions as you would on a computer.

  • Select English

  • Select “I don’t want to connect to a wifi-network right now”

  • Do NOT select “Istall third-party software for graphecs and Wi-Fi hardwar, Flash, MP3 and other media”

  • Select “Erase disk and install Ubuntu”. Note: Selecting this option will prompt a warning message. This is okay.

  • Select New York

  • Select English

In the section “Who are you?”, enter the following information if you setting up a drone as part of a class:

  • Your name: UAV

  • Your computer’s name: [ROBOT NAME] (names should be entered in lowercase with a ‘-’ between words)

  • Pick a username: uav

  • Password: (contact instructor about appropriate passwords)

Note: Whenever you start up the drone you need to boot Aero Compute into Advanced options for Ubuntu (which is set as the default), NOT normal ubuntu. Booting into normal Ubuntu can cause connection problems like QGroundControl not being able to connect with the drone (e.g. ‘Error on socket: Connection refused’)

Step 3: Network Setup

Reference: Intel Documentation

Since we plan to fly mostly/entirely indoors within range of a wireless router, our normal operating procedure will be to have the drone in “client” mode as opposed to “access point” mode. In client mode we can connect the drone to the internet and we can connect our groundstation (i.e. laptop) to the drone and the internet via the router. In contrast, while in “access point” mode, we can wirelessly connect our groundstation to the drone directly, without a router, but then neither drone nor groundstation can connect to the internet. This video gives more detail and instructions

Starting your drone with a monitor, mouse, and keyboard attached (i.e. “desktop configuration”), you should be able to connect to the internet just like you would on any other Linux computer using the wifi menu in upper right corner. If you are unable to connect to the internet, follow these instructions to ensure the drone is in wifi “client” mode. In brief, you can run the following commands on the drone:

nmcli c down hotspot
nmcli c modify hotspot connection.autoconnect no
# scan wifi networks
nmcli dev wifi
# connect
nmcli dev wifi connect <network name> password <password>

Connecting with QGroundControl

In order to connect the groundstation software (i.e. QGroundControl) to the drone via a router:

On the drone:

  • Open a terminal and run ifconfig

  • Get the IP address of the drone which is labeled inet addr under the wlp1s0 heading

On the groundstation:

  • Open QGroundControl

  • In the top left click on the “Q”

  • Select the “Comm Links” tap

  • Select “Add”

    • Set the “Type” to TCP

    • Set “Serial Port” to the IP address of the drone

    • Set “TCP Port” to 5760

    • Select “OK”

  • Select the new link and press “Connect”. This will connect QGroundControl to the drone

Connecting with SSH

Another common technique for interacting with the drone is to connect via ssh. With the drone in “desktop configuration” (i.e. monitor, mouse, keyboard attached), run the following command on the drone to get the ssh client

sudo apt install openssh-server

Once the openssh-server is installed, from your laptop you should be able to connect with the drone by running

ssh <username>@<ip address>

where <username> and <ip address> are substituted with the username you created during the Ubuntu setup and ip address is what you found from running ifconfig on the drone.

Once connected via your laptop, you should be able to navigate the the file system of the Ubuntu machine on your drone just as if you were navigating it with a keyboard and monitor directly plugged in. Note: graphics-based programs will not work, only command line

Note: When you get this far, it might be a good time to try a manual flight test of the drone. See instructions here

Step 4: PX4 Toolchain

Dronecode Documentation

We need the ability to modify, build, and flash the PX4 firmware being flown on the AeroFC flight controller; these instructions walk you through those steps

Toolchain Installation

Before you can build custom firmware, you need the proper toolchain setup on the drone. On your drone (as opposed to on your laptop/groundstation) follow the instructions under Development Toolchain and Pixhawk/NuttX (and jMAVSim) sections from the following tutorial:

Toolchain Install Tutorial - NOTE: only follow the steps in the Development Toolchain and Pixhawk/NuttX (and jMAVSim) sections

Customizing Firmware

In order to fly the drone indoors, we need to implement utilize optical flow capabilities. Without going into the details of what optical flow is, we need to update the firmware on the flight controller to prepare for this.

First clone the an existing stable branch of the PX4 firmware

cd ~
git clone --branch v1.8.0-beta1 https://github.com/PX4/Firmware.git
cd Firmware

Then you need to make one small change in the file Firmware/src/modules/ekf2/ekf2_main.cpp. Look for the line:

_ekf.setRangeData(range_finder.timestamp, range_finder.current_distance);

and change it to

_ekf.setRangeData(now, range_finder.current_distance);

Building & Flashing Firmware

Now that the firmware has been updated to suit our needs, let’s build it (note these commands will likely take several minutes to complete

cd ~/Firmware
make
make aerofc-v1_default

Once the make has succeeded, it needs to be flashed to the AeroFC board in order to be utilized by the flight controller.

cd ~/Firmware
sudo aerofc_update.sh build/aerofc-v1_default/aerofc-v1_default.px4

Step 5: Optical Flow Libraries

Flying with optical-flow requires a distance sensor. This project uses TeraBee’s Teraranger One. This sensor is connected to the drone’s compute board via USB port which requires this driver.

Installing Teraranger Hardware

The Teraranger distance sensor and USB adapter need to be integrated to the Intel RTF Drone using zip ties and/or velcro straps as shown in the following pictures. Note that the exact position of the Teraranger is not particularly important, but it does need to be point straight down.

teraranger_install_1.jpg teraranger_install_2.jpg

Installing the Serial Library

Note: The following steps require cloning from github.mit.edu repo onto the drone. Since the drones are connected to a single user, they don’t have an rsa token in to give permission to the drone in order to perform the clone. Until we move these directories to a public GitHub account or add appropriate deploy keys to the drone, it is necessary to clone the directories to your computer and then copy them over to the drone

The drivers require the SerialLib from WjwWood with a slight modification installed. Please clone the Lib from RSS_DRONE/serial.

cd
git clone git@github.mit.edu:RSS-DRONE/serial.git

If you clone the above directory to your laptop/groundstation: copy it to the drone before proceeding with scp -rp serial/ uav@<DRONENAME>.beaver.works:~/

Then on the drone, run:

cd serial
make
sudo make install

Setting PX4 Parameters

The estimators on PX4 have to be reconfigured in order to utilize optical flow. From you laptop/ground station, connect to the drone with QGroundControl, click on the “gears” menu, click on Parameters menu, and set

EKF2_AID_MASK: 2

EKF2_HGT_MODE: 2

COM_POS_FS_EPH: 50000

Starting Optical Flow Services

Warning:

At the time of this writing there was an unresolved, intermittent bug associated with the following commands that could cause error messages to spam /var/log/syslog so badly that it threatens to overfill the entire hard drive on the drone. To ensure this does not happen, check the size of that directory with

sudo du -sh /var/log

If at any time in this process that directory it is growing at a more than a MB every few seconds, shut down the drone and try restarting this process

These steps setup install the necessary libraries for optical flow, but they don’t enable it to run automatically. To start the services for optical flow you must run:

sudo systemctl start aero-teraranger.service
sudo systemctl start aero-optical-flow.service

Step 6: ROS Installation

Intel Documentation

All the high level, onboard control of the drone will be performed on the Aero Compute Board using ROS (as opposed to the AeroFC that is responsible for low level control using PX4). We therefore need to install ROS onboard the drone. Follow the instructions here under the sections; specifically:


Laptop Setup

In short, when working with the embedded systems involved with robotics, you need a Linux environment on your laptop or desktop. Period.

There are plenty of hacks and tricks for trying to get Windows or MacOS to play nicely with the software tools and libraries used in robotics, but in the end you will waste more time—and endure more frustration—trying to get those tools working than you would if you just commit to working in Linux from the beginning. In short, this class is designed around a Linux operating system and we do not have the bandwidth to provide equivalent instruction for other operating systems.

Below we layout the steps necessary to get you laptop or desktop setup to develop the Intel Ready-To-Fly Drone

Install Ubunutu Linux (Operating System)

There are many “flavors” of Linux; this course will utilize the most popular (arguably) version known as Ubuntu.

NOTE:

As of the Summer of 2019, we are still using Ubuntu 16.04 LTS for this course. Please select this version of Ubuntu while installing using one of the following options.

Option 1: Dual Boot Native Linux

This option tends to be preferred by full-time Linux users. It’s how I set up my personal computers

Dual booting is kinda like creating a separate computer inside your computer. Think of it like your computer having a split personality: any time you turn on your computer it can either be a Windows computer or a Linux computer, depending on what option you pick during startup. This is different from Virtual Machine which is more like one computer running a simulation of another computer.

There are many tutorials online that describe how to create a dual boot Windows/Linux computer; I find Ubuntu’s tutorial the most refined. Please follow instructions below

https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop#0

DISCLAIMER 1:

Dual booting requires partitioning your hard drive which poses risk of losing data on your computer if done incorrectly. It is strongly recommended to backup your hard drive before proceeding.

DISCLAIMER 2:

This process may take roughly an hour for someone who knows what they are doing, but several hours for someone who is doing it for the first time. Plan accordingly.

We argue that, in the long term, the power and flexibility of Linux is worth the risk and effort. It’s almost impossible to be an effective roboticist without it!

Option 2: Virtual Machine Linux Guest

This option can be good when getting started with Linux as it requires less “surgery” on your computer, but it will eventually hit roadblocks/difficulties that a dual-boot avoids

An alternative to dual booting is the create a virtual machine to run a “guest” Linux machine as a program within you native operating system. You should have already done this as part of the online pre-requisite course.

As with Dual Booting, there are many online tutorials to follow for creating a Ubuntu Linux virtual machine. Here is a link to one tutorial that uses VirtualBox:

Medium Article on Linux VM Install

PX4 Development Environment (UAV Firmware)

https://dev.px4.io/en/setup/dev_env_linux.html

Install ROS (Robot Middleware)

http://wiki.ros.org/kinetic/Installation/Ubuntu

Install Gazebo (Robot Simulator)

http://gazebosim.org/tutorials?tut=ros_wrapper_versions#Kinetic

Miniconda & Jupyter Notebooks (Package Manager & Interactive Coding)

Content Publishing

To publish content we need to make use of jupyter notebooks and sphinx

Instructions: + https://nbsphinx.readthedocs.io/en/0.3.3/installation.html + https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html

Note:

There appears to be a conflict between ROS and Sphinx that presents with the error

Could not import extension sphinx.builders.latex (exception: No module named roman)

To resolve this we have a conda environment dedicated to publishing

Spell checker (NOTE: Need to ensure this doesn’t spell check in the cloud) + http://www.simulkade.com/posts/2015-04-07-spell-checking-in-jupyter-notebooks.html

Troubleshooting