{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Module 0: UAV Environment Setup\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "---\n", "## Instructional Content Access\n", "\n", "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\n", "\n", "### MIT GitHub Account\n", "\n", "[MIT Touchstone Collaboration Account Instructions](http://kb.mit.edu/confluence/display/istcontrib/Creating+a+Touchstone+Collaboration+Account)\n", "\n", "### BWSI edX Account\n", "\n", "[Instructions for BWSI's edX application](https://beaverworks.ll.mit.edu/CMS/bw/bwsiapply). Note: You should already have an account having completed the pre-requisite online portion of this course" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "---\n", "## Intel RTF Drone Setup\n", "\n", "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.\n", "\n", "### Step 1: Initial Setup \n", "\n", "[__Reference: Intel Documentation__](https://github.com/intel-aero/meta-intel-aero/wiki/02-Initial-setup)\n", "\n", "[__Video Walkthrough__](https://www.youtube.com/watch?v=e9MLnRbMDHo&index=7&list=PLTQSXsG86pGfyZm5ac6-ZtQsEniUJIE9o)\n", "\n", "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.\n", "\n", "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.\n", "\n", "
\n", "\n", "**Warning:** \n", "\n", "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!!\n", "\n", "
\n", "\n", "
    \n", "
  1. [Hardware Setup](https://github.com/intel-aero/meta-intel-aero/wiki/02-Initial-setup#hardware)
    2. \n", "
  2. [OS Installation and Flashing Firmware](https://github.com/intel-aero/meta-intel-aero/wiki/02-Initial-setup#flashing)
    3. \n", "
  3. [Sensor & Radio Calibration](https://github.com/intel-aero/meta-intel-aero/wiki/02-Initial-setup#calibration)\n", "
\n", "\n", "
\n", "\n", "**Note: Sensor & Radio Calibration** \n", "\n", "When calibrating and configuring the remote control, set Flight Mode 1 to `Manual`, Flight Mode 4 to `Position`, and Flight Mode 6 to `Offboard`\n", "\n", "
\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Step 2: Ubuntu Installation\n", "\n", "[__Reference: Intel Documentation__](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation)\n", "\n", "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. \n", "\n", "
\n", "**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\n", "
\n", "\n", "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:\n", "
    \n", "
  1. [Install Yocto First](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation#upgrade-yocto-first)
    2. \n", "
  2. [Install Ubuntu](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation#os) --- __NOTE:__ See additional instructions [here](#install_ubuntu_notes)
    3. \n", "
  3. [Intel Aero Repo](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation#intel-aero-repository)
    4. \n", "
  4. [Maintenance Tools](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation#intel-aero-maintenance-tools) --- __NOTE:__ 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](#network_setup) for more information
    5. \n", "
  5. [RealSense SDK](https://github.com/intel-aero/meta-intel-aero/wiki/90-%28References%29-OS-user-Installation#intel-realsense-sdk)
    6. \n", "
\n", "\n", "#### Notes: Install Ubuntu \n", "\n", "Go through the Ubuntu setup instructions as you would on a computer.\n", "\n", "- Select English\n", "- Select \"I don't want to connect to a wifi-network right now\"\n", "- Do NOT select \"Istall third-party software for graphecs and Wi-Fi hardwar, Flash, MP3 and other media\"\n", "- Select \"Erase disk and install Ubuntu\". Note: Selecting this option will prompt a warning message. This is okay.\n", "- Select New York\n", "- Select English\n", "\n", "In the section \"Who are you?\", enter the following information if you setting up a drone as part of a class:\n", "\n", "- Your name: UAV\n", "- Your computer's name: \\[ROBOT NAME\\] (names should be entered in lowercase with a '-' between words)\n", "- Pick a username: uav\n", "- Password: (contact instructor about appropriate passwords)\n", "\n", "
\n", "**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')\n", "
\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Step 3: Network Setup \n", "\n", "[**Reference: Intel Documentation**](https://github.com/intel-aero/meta-intel-aero/wiki/08-Aero-Network-and-System-Administration)\n", "\n", "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](https://www.youtube.com/watch?v=5w6A0IIXnto)\n", "\n", "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](https://github.com/intel-aero/meta-intel-aero/wiki/08-Aero-Network-and-System-Administration#networking-wifi) to ensure the drone is in wifi \"client\" mode. In brief, you can run the following commands on the drone:\n", "```\n", "nmcli c down hotspot\n", "nmcli c modify hotspot connection.autoconnect no\n", "# scan wifi networks\n", "nmcli dev wifi\n", "# connect\n", "nmcli dev wifi connect password \n", "```\n", "\n", "\n", "#### Connecting with QGroundControl\n", "\n", "In order to connect the groundstation software (i.e. QGroundControl) to the drone via a router:\n", "\n", "On the drone:\n", "\n", "\n", "On the groundstation:\n", "\n", "\n", "#### Connecting with SSH\n", "\n", "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\n", "```\n", "sudo apt install openssh-server\n", "```\n", "\n", "Once the `openssh-server` is installed, from your laptop you should be able to connect with the drone by running\n", "```\n", "ssh @\n", "```\n", "where `` and `` are substituted with the username you created during the Ubuntu setup and ip address is what you found from running `ifconfig` on the drone.\n", "\n", "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\n", "\n", "
\n", "**Note:** When you get this far, it might be a good time to try a manual flight test of the drone. [See instructions here](https://github.com/intel-aero/meta-intel-aero/wiki/03-First-flight)\n", "
" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Step 4: PX4 Toolchain\n", "\n", "[**Dronecode Documentation**](https://dev.px4.io/en/setup/dev_env_linux.html)\n", "\n", "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\n", "\n", "#### Toolchain Installation\n", "\n", "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:\n", "\n", "[Toolchain Install Tutorial](https://dev.px4.io/en/setup/dev_env_linux.html) - NOTE: only follow the steps in the __Development Toolchain__ and __Pixhawk/NuttX (and jMAVSim)__ sections \n", "\n", "\n", "#### Customizing Firmware\n", "\n", "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.\n", "\n", "First clone the an existing stable branch of the PX4 firmware\n", "```\n", "cd ~\n", "git clone --branch v1.8.0-beta1 https://github.com/PX4/Firmware.git\n", "cd Firmware\n", "```\n", "\n", "Then you need to make one small change in the file `Firmware/src/modules/ekf2/ekf2_main.cpp`. Look for the line:\n", "```\n", "_ekf.setRangeData(range_finder.timestamp, range_finder.current_distance);\n", "```\n", "and change it to\n", "```\n", "_ekf.setRangeData(now, range_finder.current_distance);\n", "```\n", "\n", "#### Building & Flashing Firmware\n", "\n", "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\n", "```\n", "cd ~/Firmware\n", "make\n", "make aerofc-v1_default\n", "```\n", "\n", "Once the make has succeeded, it needs to be _flashed_ to the AeroFC board in order to be utilized by the flight controller. \n", "```\n", "cd ~/Firmware\n", "sudo aerofc_update.sh build/aerofc-v1_default/aerofc-v1_default.px4\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Step 5: Optical Flow Libraries\n", "\n", "\n", "\n", "Flying with optical-flow requires a distance sensor. This project uses TeraBee's [Teraranger One](https://www.terabee.com/portfolio-item/teraranger-one/). This sensor is connected to the drone's compute board via USB port which requires this driver.\n", "\n", "#### Installing Teraranger Hardware\n", "\n", "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.\n", "\n", "![teraranger_install_1.jpg](https://github.com/BWSI-UAV/website/blob/master/docs/images/teraranger_install_1.jpg?raw=true)\n", "\n", "![teraranger_install_2.jpg](https://github.com/BWSI-UAV/website/blob/master/docs/images/teraranger_install_2.jpg?raw=true)\n", "\n", "#### Installing the Serial Library\n", "\n", "
\n", "**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\n", "
\n", "\n", "The drivers require the SerialLib from [WjwWood](https://github.com/wjwwood/serial.git) with a slight modification installed. Please clone the Lib from [RSS_DRONE/serial](https://github.mit.edu/RSS-DRONE/serial).\n", "```\n", "cd\n", "git clone git@github.mit.edu:RSS-DRONE/serial.git\n", "```\n", "\n", "_If you clone the above directory to your laptop/groundstation:_ copy it to the drone before proceeding with `scp -rp serial/ uav@.beaver.works:~/`\n", "\n", "Then on the drone, run:\n", "\n", "```\n", "cd serial\n", "make \n", "sudo make install\n", "```\n", "\n", "#### Installing the teraranger-mavlink driver\n", "\n", "```\n", "cd\n", "git clone git@github.mit.edu:RSS-DRONE/intel_tera_mavlink.git\n", "```\n", "\n", "_If you clone the above directory to your laptop/groundstation:_ copy it to the drone before proceeding with `scp -rp intel_tera_mavlink/ uav@.beaver.works:~/`\n", "\n", "Then on the drone run:\n", "\n", "```\n", "cd ~/intel_tera_mavlink\n", "git submodule update --init --recursive\n", "mkdir build\n", "cd build\n", "cmake ..\n", "make\n", "sudo make install\n", "sudo cp aero-teraranger.service /lib/systemd/system/\n", "sudo cp intel_tera_mavlink /usr/bin\n", "```\n", "\n", "#### Setting PX4 Parameters\n", "\n", "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\n", "\n", " EKF2_AID_MASK: 2\n", "\n", " EKF2_HGT_MODE: 2\n", "\n", " COM_POS_FS_EPH: 50000\n", "\n", "\n", "#### Starting Optical Flow Services\n", "\n", "\n", "
\n", "\n", "**Warning:** \n", "\n", "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\n", "```\n", "sudo du -sh /var/log\n", "```\n", "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\n", "\n", "
\n", "\n", "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:\n", "\n", "```\n", "sudo systemctl start aero-teraranger.service\n", "sudo systemctl start aero-optical-flow.service\n", "```\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Step 6: ROS Installation\n", "\n", "[**Intel Documentation**](https://github.com/intel-aero/meta-intel-aero/wiki/05-Autonomous-drone-programming-with-ROS)\n", "\n", "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](https://github.com/intel-aero/meta-intel-aero/wiki/05-Autonomous-drone-programming-with-ROS) under the sections; specifically:\n", "\n", " - https://github.com/intel-aero/meta-intel-aero/wiki/05-Autonomous-drone-programming-with-ROS#why-ros\n", " - https://github.com/intel-aero/meta-intel-aero/wiki/05-Autonomous-drone-programming-with-ROS#installation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "---\n", "## Laptop Setup\n", "\n", "In short, when working with the embedded systems involved with robotics, you need a Linux environment on your laptop or desktop. __Period__.\n", "\n", "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.\n", "\n", "Below we layout the steps necessary to get you laptop or desktop setup to develop the Intel Ready-To-Fly Drone\n", "\n", "### Install Ubunutu Linux (Operating System)\n", "\n", "There are many \"flavors\" of Linux; this course will utilize the most popular (arguably) version known as [Ubuntu](https://www.ubuntu.com/). \n", "\n", "
\n", "\n", "**NOTE:** \n", "\n", "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.\n", "\n", "
\n", "\n", "#### Option 1: Dual Boot Native Linux\n", "\n", "_This option tends to be preferred by full-time Linux users. It's how I set up my personal computers_\n", "\n", "[Dual booting](https://en.wikipedia.org/wiki/Multi-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](https://en.wikipedia.org/wiki/Virtual_machine) which is more like one computer running a _simulation_ of another computer.\n", "\n", "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\n", "\n", "https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop#0\n", "\n", "
\n", "\n", "**DISCLAIMER 1:** \n", "\n", "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. \n", "\n", "
\n", "\n", "
\n", "\n", "**DISCLAIMER 2:** \n", "\n", "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.\n", "\n", "
\n", "\n", "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!_\n", "\n", "\n", "#### Option 2: Virtual Machine Linux Guest\n", "\n", "_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_\n", "\n", "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](https://bwsix.mit.edu). \n", "\n", "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](https://www.virtualbox.org/):\n", "\n", "[Medium Article on Linux VM Install](https://medium.com/@tushar0618/install-ubuntu-16-04-lts-on-virtual-box-desktop-version-30dc6f1958d0)\n", "\n", "### PX4 Development Environment (UAV Firmware)\n", "\n", "https://dev.px4.io/en/setup/dev_env_linux.html\n", "\n", "### Install ROS (Robot Middleware)\n", "\n", "http://wiki.ros.org/kinetic/Installation/Ubuntu\n", "\n", "### Install Gazebo (Robot Simulator)\n", "\n", "http://gazebosim.org/tutorials?tut=ros_wrapper_versions#Kinetic\n", "\n", "### Miniconda & Jupyter Notebooks (Package Manager & Interactive Coding)\n", "\n", "### Content Publishing\n", "\n", "To publish content we need to make use of `jupyter notebooks` and `sphinx`\n", "\n", "Instructions: \n", "+ https://nbsphinx.readthedocs.io/en/0.3.3/installation.html\n", "+ https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html\n", "\n", "
\n", "\n", "**Note:** \n", "\n", "There appears to be a conflict between ROS and Sphinx that presents with the error \n", "```\n", "Could not import extension sphinx.builders.latex (exception: No module named roman)\n", "```\n", "To resolve this we have a [conda environment](https://github.com/BWSI-UAV/website/blob/master/environment.yaml) dedicated to publishing\n", "\n", "
\n", "\n", "\n", "\n", "Spell checker (__NOTE:__ Need to ensure this doesn't spell check in the cloud)\n", "+ http://www.simulkade.com/posts/2015-04-07-spell-checking-in-jupyter-notebooks.html\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Troubleshooting\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 2", "language": "python", "name": "python2" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.5" } }, "nbformat": 4, "nbformat_minor": 2 }