Skip to content

lmco/lm-mit-momentum22

BranchesTags

Repository files navigation

Getting started

This readme will walk you through getting your environment set up with the required software and running your first missions.

If you are viewing this file offline, the most up to date version of these instructions is located in the project GitHub.

NOTES:

  1. Unless otherwise specified, all instructions are to be entered into the terminal in your Ubuntu installation
  2. Commands that start with sudo will require your user password. Using sudo invokes superuser security privileges and is akin to running an application as an administrator in Windows.
  3. As we progress through the project, answers to common questions will be added to the Q&A.

Quick references

Note: If you're just getting started, walk through the steps after the table of contents first!

How to download this project to your computer

See Section 8 for more details.

# Create a folder for the Momentum project in your home (~) directory
mkdir -p ~/Momentum

# Change directories to the folder we created
cd ~/Momentum

# Clone the project from GitHub
git clone git@github.com:lmco/lm-mit-momentum22.git

# Pull updates from remote
cd ~/Momentum/lm-mit-momentum22
git pull

How to launch the simulation

See Section 9.1. for details.

# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

# Launch PX4 with the jMavSim simulation target and set the starting location to Boston Logan Airport (KBOS)
bash launch_px4_boston.bash
# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

 # Launch Visualizer with the test map
bokeh serve Visualizer --show --args -v boston_sar
# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

# Launch Student code
python3 student/student_SAR_example_boston.py

Table of Contents

1. Install Ubuntu 20.04 LTS

The software required for this project supports only Ubuntu 18.04 or 20.04. As such, if your system has another operating system, it is necessary to install the Ubuntu 20.04 operating system to complete the project. You may do so using one of the following options.

1.1. Basic steps to install Ubuntu outside of a Virtual Machine

  1. Download an Ubuntu image
  2. Verify image download is not corrupted
  3. Make a bootable live USB in current OS
  4. Boot from created USB
    • If your computer doesn't automatically boot from from the USB and F12 does not work to invoke the boot menu, pay attention to the bootscreen for the key specific for your computer.
    • Mac-specific instructions:
      • Instructions and setup specifics will vary depending on the host version of Mac hardware. It is strongly suggested to use a pc-based host. Apple hardware is proprietary, and requires numerous workarounds. If you have an M1 mac, your best bet is to either install inside a virtual machine, or get a loaner machine. LM will support your Mac install to the best of our ability, but our resources are quite limited. Proceed at your own risk.
      1. After creation of the live USB, shutdown your computer. Reboot it while holding CMD + R.
      2. The Recovery Menu will load. Select your user from the list and enter your password.
      3. In the top menubar, click "Utilities -> Startup Security Utility"
      4. Set Secure Boot to "No Security", and Allow Boot Media to "Allow booting from external or removable media". Close the window.
      5. In the Apple menu, choose shutdown.
      6. Press the power button to turn on your computer while holding down Option. Continue to hold until a boot menu appears. You will have the default MacOS option on the left, then two gold "EFI" options. One of these will allow you to boot into Linux (mine was the right-most option). If you get a message explaining that you need to install MacOS on the drive, follow the instructions above to reboot your machine again, and choose the other gold option.
      • Depending on your hardware, you may not be able to use the keyboard/mouse. You will need a wired, external mouse and keyboard to complete the install. This may be rectified later by installing kernal modules, but is beyond the scope of our support. Here is a reference which may help.
  5. Choose how to Install Ubuntu:

1.2. Basic steps to install Ubuntu inside of a Virtual Machine

  1. Install VirtualBox
  2. Download an Ubuntu image
  3. Verify image download is not corrupted
  4. Install Ubuntu in VirtualBox

2. Basic steps to install Google Chrome as the Default Browser

Due to compatibility issues between the Python Moving Map visualization and the Firefox browser, Google Chrome is the preferred browser for this project.

Summary of How to Install Google Chrome on Ubuntu 20.04:

cd ~/Downloads

# Download the Google Chrome installation file
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb

# Install Google Chrome
sudo dpkg -i google-chrome-stable_current_amd64.deb

# Launch Google Chrome and set as default browser
google-chrome

Installing chrome

3. Install VS Code IDE

VS Code is an open-source light-weight feature-rich IDE (Integrated Development Environment) developed by Microsoft. Using an IDE greatly enhances the developer's comfort when coding by enabling features such as syntax highlighting, suggestions, and linting.

Summary of VS Code setup instructions:

# Make the home directory for the project and step into it.
# You may install your software in a different directory, but then take care to change your home directory when following the instructions.
mkdir -p ~/Momentum
cd ~/Momentum

# Install VS Code from snap
sudo snap install --classic code

# Launch VS Code from current terminal directory (.) and put it in the background (&)
code . &

Installing code

4. Get PX4

PX4 is industry-standard autopilot software for hobbyist drone applications. It provides easy access to high quality control laws for a variety of drones, including in simulation. For the purposes of this project, this software will allow the user to simply set waypoints, while the PX4 software performs all of the necessary calculations to control and interface with the motors to get the drone to the next waypoint.

4.1. Clone and Build PX4

Summary of PX4 simulation with jMavSim:

# Return to home project directory
cd ~/Momentum

# Install GIT. Git is a free and open source version control system designed for storing/collaborating on files and projects.
# Many open-source software packages can be obtained via GIT. Project Momentum files are also stored using GIT.
sudo apt install git

# Make home directory for PX4
mkdir PX4
cd PX4

# Clone PX4
git clone https://github.com/PX4/PX4-Autopilot.git --recursive

# Get into the PX4 project directory
cd PX4-Autopilot

# Run installer script
bash ./Tools/setup/ubuntu.sh

# Build the project with default drone target and jMavSim simulation target
HEADLESS=1 make px4_sitl jmavsim

Installing PX4

5. Install MAVSDK

MAVSDK provides the Python hooks to interface with PX4. This allows the user to control the drone in a programmatic way, enabling complex missions and performing intricate algorithms.

Summary of Python MAVSDK installation guide:

# Install MAVSDK Python library version 0.21.0 - later versions do not currently work
pip3 install --force-reinstall mavsdk==0.21.0

Installing mavsdk

6. Install navpy and numpy

navpy provides coordinate system conversion functions and numpy provides computation utilities.

pip3 install numpy
pip3 install navpy

This should look exactly the same as when installing mavsdk.

7. Install dependencies for Visualizer

pip3 install bokeh
pip3 install geopandas
pip3 install grpcio-tools
pip3 install Shapely
pip3 install Rtree

This should look exactly the same as when installing mavsdk.

Refer to the geopandas website if you experience issues with missing dependencies for geopandas.

8. Clone the Momentum22 project folder from GitHub

  1. Generate a new SSH key on your computer
  2. Add the SSH key to your GitHub account
  3. Create and navigate to the Momentum directory in your command prompt and clone the project
# Get into the main project folder
cd ~/Momentum

# Clone the project 
git clone git@github.com:lmco/lm-mit-momentum22.git

Clone Momentum

9. Launch simulation and run mission

9.1. Launch PX4, Visualizer, and Student Code with provided maps and scripts

There are three steps to running the simulation

  1. Launching PX4 and setting its parameters
  2. Launching the Visualizer
  3. Running the student code

The commands for this are below, with each run in a separate terminal window or tab. TIP: Press ctrl+alt+t to bring up a terminal and ctrl+t to open a new tab in your terminal.

# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

# Launch PX4 with the jMavSim simulation target and set the starting location to Boston Logan Airport (KBOS)
bash launch_px4_boston.bash
# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

 # Launch Visualizer with the test map
bokeh serve Visualizer --show --args -v boston_sar
# Get into the Momentum22 project folder
cd ~/Momentum/lm-mit-momentum22

# Launch Student code
python3 student/student_SAR_example_boston.py

If the student code fails with mavsdk.action.ActionError: COMMAND_DENIED: 'Command Denied', enter commander disarm -f in your PX4 window and restart the student code. You may need to restart the visualizer for accurate scoring.

Starting simulation

9.2. OPTIONAL: Set home position and launch PX4 Manually

Setting the home position will ensure that the Visualizer, PX4, and the Python mission are on the same page about where the drone is supposed to be. The provided launch scripts in the lm-mit-momentum22 project will automatically launch PX4 with the correct home position for the corresponding maps. These instructions are for manually setting your own home position.

To Manually set a home position:

# Get into the PX4 project folder
cd ~/Momentum/PX4/PX4-Autopilot

# https://dev.px4.io/master/en/simulation/gazebo.html#set-custom-takeoff-location
export PX4_HOME_LAT=0 # Deg
export PX4_HOME_LON=0 # Deg
export PX4_HOME_ALT=0 # Meters

To Launch PX4 Manually:

# Get into the PX4 project folder
cd ~/Momentum/PX4/PX4-Autopilot

# Launch PX4 with jmavsim as the simulation target
HEADLESS=1 make px4_sitl jmavsim

# HEADLESS=1 turns off the jmavsim visuals
# "sitl" == "Software in the Loop"
# jmavsim == simulation target

9.2.1 OPTIONAL: Set PX4 firmware parameters manually

The PX4 firmware parameters set the constants used in the control laws of the autopilot. The following shows how to set the maximum velocities for the drone and load/save these parameters to file, as well as reset them to defaults.

# Run from the shell (with pxh>) after launching PX4
# Set params manually
# https://dev.px4.io/master/en/advanced/parameter_reference.html
param set MPC_Z_VEL_MAX_DN 1.0 # m/s, max vertical velocity down
param set MPC_Z_VEL_MAX_UP 3.0 # m/s, max vertical velocity up
param set MPC_XY_VEL_MAX  12.0 # m/s, max horizontal velocity

# Or load from file (root location /PX4-Autopilot/build/px4_sitl_default/tmp/rootfs)
param load iris_defaults # Reset the parameters to when file was saved
param save # Optionally save params (not done automatically with load)

# Reset all params to default
param reset_all

9.3. OPTIONAL: Create and load your own Maps in the Visualizer

  1. Navigate your command line to the root folder of the project (this Visualizer folder should be a subfolder to the root)
  2. Run the visualizer in one of two modes (to either create or run with a map)
    1. Enter bokeh serve Visualizer --show --args -m on your commandline, press Enter for the MapMaker
    2. Enter bokeh serve Visualizer --show --args -v <mapname> on your commandline, where <mapname> is a map stored in the maps directory, press Enter for the Visualizer
  3. A web browser tab should open with the Visualizer utility at http://localhost:5006/Visualizer

NOTE: We advise using Chrome with the Visualizer. Graphical anomalies were observed when using the zoom feature in Firefox. Other browsers are untested.

About

LM provided files for MIT Momentum 22 (https://ome.mit.edu/programs/momentum).

Resources

Readme

License

BSD-3-Clause license
Activity
Custom properties

Stars

3 stars

Watchers

8 watching

Forks

0 forks
Report repository

Contributors 4

  •  
  •  
  •  
  •  

Languages