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

ATTENTION STUDENTS: THERE WAS AN UPDATE TO THE LIDAR REGISTRATION ALGORITHM. If you are using the default templates or are relying on the LIDAR registration algorithm in them, the previous versions of these files contained a bug in the coordinate transforms. This bug has been fixed and you must update your files. Thanks to the student who pointed out the bug during office hours on 25 JAN.

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. There is a playlist showing successful execution of these commands.
4. If you have specific questions that are not answered by this document, check out the constantantly updating Q&A.

• 1. Install Ubuntu 18.04 LTS or 20.04 LTS
  • 1.1. Basic steps to install Ubuntu outside of a Virtual Machine
  • 1.2. Basic steps to install Ubuntu inside of a Virtual Machine
• 2. Install VS Code IDE
• 3. Get Gazebo and PX4
  • 3.1. Clone PX4 and install Gazebo
  • 3.2. Build PX4
• 4. OPTIONAL Install QGroundControl
  • 4.1. Fix problem where PX4 running Gazebo can't connect to QGroundControl
• 5. Install MAVSDK
• 6. Install navpy and numpy
• 7. Download py3gazebo
• 8. Adding LM-provided LiDAR and terrain
  • 8.1. Creating your own terrain and LiDAR
• 9. Install py3gazebo
• 10. Launch simulation
  • 10.1. Set home position
  • 10.2. Launch PX4 with Gazebo
  • 10.3. Set PX4 firmware parameters
  • 10.4. How to find sensor topic name, message type, and get sample output
  • 10.5. OPTIONAL Launch QGroundControl
• 11. Run a mission file
• 12. Query sensor values using py3gazebo - GPS Example
• 13. Getting started with MAVSDK
  • 13.1. Download MAVSDK examples
  • 13.2. Run a MAVSDK example (PX4 and Gazebo have to be running)

The software required for this project runs and is supported only in Ubuntu 18.04 or 20.04. As such, it is necessary to install this operating system to complete the project.

1. Download an Ubuntu image
2. Verify image download is not corrupted
3. Make a bootable live USB in current OS
   • Make live USB in Windows
   • Make live USB in Ubuntu
   • Make live USB in Mac
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.
5. Choose a location to make a persistent image
   • Install to dual boot with current OS (recommended)
   • Install with persistent storage onto a USB drive (advanced)
   • Install instead of current OS (not recommended)

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

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 . &

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.

Gazebo is similarly positioned in the robotics simulation world and is heavily used with ROS (Robot Operating System, not used in this project). Gazebo enables real-time physics simulation, sensor and terrain integration, and provides visual feedback for the user.

Summary of PX4 and Gazebo setup guide for ubuntu:

# Return to home project directory
cd ~/Momentum

# 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

#
# Log out and log back in.
#

Summary of PX4 simulation with Gazebo:

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

# Make the project with default drone target and gazebo simulation target
make px4_sitl gazebo

Take note:

• IP-address on the line that looks like [Msg] Publicized address: 192.168.0.10 will be useful if PX4 can't connect to QGroundControl when running Gazebo.
• IP-address on the line that looks like [Msg] Connected to gazebo master @ http://127.0.0.1:11345 will be useful when setting up py3gazebo.

QGroundControl can be seen as a companion application to PX4. It provides a GUI interface for some of the most commonly used parameters in PX4. It also provides a contextualized view of the running mission. This software is not necessary to complete the project, but it may be useful for debugging.

Summary of QGRoundControl installation instructions:

# Give yourself permissions to use the serial port
sudo usermod -a -G dialout $USER

# Remove modemmanager
sudo apt-get remove modemmanager -y

# Install dependencies
sudo apt install gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-gl -y

#
# Log out and log back in.
#

# Return to home
cd ~/Momentum

# Download QGroundControl app image
wget https://s3-us-west-2.amazonaws.com/qgroundcontrol/latest/QGroundControl.AppImage

# Add execution permissions to the downloaded file
chmod +x ./QGroundControl.AppImage

# Launch app
./QGroundControl.AppImage # (or double-click)

Summary of forum post solving this issue:

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

# Edit the startup script
gedit ROMFS/px4fmu_common/init.d-posix/rcS 

Add the IP address you see in the console when you run make px4_sitl gazebo to the line mavlink start -x -u $udp_gcs_port_local -r 4000000 using the syntax

-t 192.168.x.y

e.g.

mavlink start -x -u $udp_gcs_port_local -r 4000000 -t 192.168.0.10

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
pip3 install mavsdk

Navpy provides coordinate system conversion functions

pip3 install numpy
pip3 install navpy

Similar to MAVSDK, py3gazebo provides Python hooks to interface with Gazebo and its messages. This software is necessary in this project to read sensor data from Gazebo.

# Step into project home directory
cd ~/Momentum

# Clone py3gazebo from GitHub and cd into the folder
git clone https://github.com/wil3/py3gazebo.git
cd py3gazebo

# Run 2to3 on the project
sudo apt-get install 2to3
2to3 -w *.py

# Replace all instances of deprecated `asyncio.async` with `asyncio.ensure_future`
sudo find ./ -type f -exec sed -i 's/asyncio.async/asyncio.ensure_future/g' {} \;

# Update proto definitions from the root of the py3gazebo project
export GAZEBO_HOME=/usr/include/gazebo-11
protoc --proto_path=$GAZEBO_HOME/gazebo/msgs --python_out=pygazebo/msg $GAZEBO_HOME/gazebo/msgs/*proto

The Python library is not yet installed. LM is providing an updated setup.py script that will be copied in the next step and there will be a prompt to install the library in section 8.

Based on this forum post.

1. Download the LM provided assets from this repository and place parallel to your PX4 top folder

   # Get into the project directory
   cd ~/Momentum
   
   # Clone project
   git clone https://github.com/katabeta/lm-mit-momentum.git
   
   # Check directory tree
   sudo apt-get install tree
   tree -L 2

   • After downloading, your workspace directory should look like this (otherwise the script will fail):

     .
      ├── lm-mit-momentum
      │   ├── ...
      ├── PX4
      │   └── PX4-Autopilot
      ├── py3gazebo
      │   └── ...
      └── ...
     

2. Run the bash script in the downloaded folder

   # Step into the lm directory
   cd lm-mit-momentum
   
   # Add execution permissions to the script and execute
   chmod +x lm_setup.sh
   sudo ./lm_setup.sh

   • If you see the following printed to the terminal and no error messages, the script has succeded:

     gazebo_iris_lmlidar__terrain2d
     gazebo_iris_lmlidar__terrain3d

You should not need to create your own terrain or LiDAR for this project. If you are still looking for instruction on making your own assets, refer to making_terrain_lidar.md.

Because there were specific changes required, the lm_setup.sh script had to copy a file over before you could install the library. To install the library, do the following:

# Step into the py3gazebo folder
cd ~/Momentum/py3gazebo

# Install the Python library
pip3 install .

Setting the home position will ensure that Gazebo, PX4, and the Python mission are on the same page about where the drone is supposed to be.

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

# Source home position
source set_home.sh

# or do this from anywhere by hand
# 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

Summary of PX4 simulation using Gazebo:

Launching PX4 and Gazebo (the make... command) will start the real-time simulation. From here, you can interact with the drone, send missions, move it in the world, and peek at the messages sent in and out of Gazebo.

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

# Launch PX4 and Gazebo with the lidar and 2D terrain
make px4_sitl gazebo___terrain2d

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

The following commands only work with Gazebo running and drone spawned in the simulation.

Get a list of all gazebo topics, filter for the word scan

gz topic -l | grep scan
# /gazebo/default/iris_lmlidar/lmlidar/link/lmlidar/scan

Get the details on the lidar topic specifically

gz topic -i /gazebo/default/iris_lmlidar/lmlidar/link/lmlidar/scan
# Type: gazebo.msgs.LaserScanStamped
# 
# Publishers:
#   192.168.0.10:43455
# 
# Subscribers:
#   192.168.0.10:46127

Echo the topic to the terminal - this will spam to your terminal, so press Ctrl+C to stop.

gz topic -e /gazebo/default/iris_lmlidar/lmlidar/link/lmlidar/scan
# time {
#   sec: 12
#   nsec: 404000000
# }
# scan {
#   frame: "iris_lmlidar::lmlidar::link"
#   world_pose {
#     position {
#       x: 1.1076721818607924
#       y: 0.97990294068076067
#       z: -3.0112717917544356
#     }
#     orientation {
#       x: -9.72964361274114e-05
#       y: -0.0223892966197638
#       z: 0.000623484894630627
#       w: 0.99974912913033442
#     }
#   }
#   angle_min: -0.5236
#   angle_max: 0.5236
#   angle_step: 0.055115789473684208
#   range_min: 0.2
#   range_max: 10
#   count: 20
#   vertical_angle_min: -1.57
#   vertical_angle_max: 0
#   vertical_angle_step: 0.19625
#   vertical_count: 9
#   ranges: 0.34457796070222135
#   ...
#   ranges: 0.57489344102911
#   intensities: 0
#   ...
#   intensities: 0
# }

Summary of QGRoundControl installation instructions:

# Get into the project home directory
cd ~/Momentum/

# Launch QGroundControl
./QGroundControl.AppImage # (or double-click)

# Get into the folder with the mission file
cd ~/Momentum/lm-mit-momentum/demos

# Run mission file
python3 demo_mission.py

Get the available Gazebo topics and get the information on the topic of interest (take note of the message type). Gazebo and PX4 have to be running for this to work.

gz topic -l | grep gps
# /gazebo/default/iris_lmlidar/gps0/link/gps

gz topic -i /gazebo/default/iris_lmlidar/gps0/link/gps
# Type: gazebo.msgs.GPS
# 
# Publishers:
#   192.168.0.10:45247
# 
# Subscribers:

Create a message subscriber class with a message callback and a way to poll the data when needed. Get your Gazebo Master IP-Address and Port from the following message when launching PX4 [Msg] Connected to gazebo master @ http://127.0.0.1:11345. The following is the same as in the file demo_gps_read.py.

import time # For the example only
import asyncio
import pygazebo

# What you import here depends on the message type you are subscribing to
import pygazebo.msg.v11.gps_pb2



# This is the gazebo master from PX4 message
# `[Msg] Connected to gazebo master @ http://127.0.0.1:11345`
HOST, PORT = "127.0.0.1", 11345


class GazeboMessageSubscriber: 

    def __init__(self, host, port, timeout=30):
        self.host = host
        self.port = port
        self.loop = asyncio.get_event_loop()
        self.running = False
        self.timeout = timeout

    async def connect(self):
        connected = False
        for i in range(self.timeout):
            try:
                self.manager = await pygazebo.connect((self.host, self.port))
                connected = True
                break
            except Exception as e:
                print(e)
            await asyncio.sleep(1)

        if connected: 
            # info from gz topic -l, gz topic -i arg goes here
            self.gps_subscriber = self.manager.subscribe('/gazebo/default/iris_lmlidar/gps0/link/gps',
                                                         'gazebo.msgs.GPS',
                                                         self.gps_callback)

            await self.gps_subscriber.wait_for_connection()
            self.running = True
            while self.running:
                await asyncio.sleep(0.1)
        else:
            raise Exception("Timeout connecting to Gazebo.")

    def gps_callback(self, data):
        # What *_pb2 you use here depends on the message type you are subscribing to
        self.GPS = pygazebo.msg.v11.gps_pb2.GPS()
        self.GPS.ParseFromString(data)
    
    async def get_GPS(self):
        for i in range(self.timeout):
            try:
                return self.GPS
            except Exception as e:
                # print(e)
                pass
            await asyncio.sleep(1)
    

async def run():
    gz_sub = GazeboMessageSubscriber(HOST, PORT)
    asyncio.ensure_future(gz_sub.connect())
    gps_val = await gz_sub.get_GPS()
    # Simulate doing stuff and polling for the gps values only when needed
    start = time.time()
    current_time = 0
    last_time = 0
    while (current_time < 20):
        current_time = round(time.time() - start)
        if(current_time % 5 == 0 and last_time < current_time):
            gps_val = await gz_sub.get_GPS()
            print(gps_val)
            last_time = current_time
        if(current_time % 1  == 0 and last_time < current_time):
            print(current_time)
            last_time = current_time


if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(run())

Follow the MAVSDK quickstart guide to get a headstart on using MAVSDK with your setup. The API reference is useful for understanding how the examples work and for figuring out how to write your own code.

# Install subversion if not already installed
sudo apt install subversion

# Get into project home directory
cd ~/Momentum

# Download MAVSDK Python examples from the GitHub repository
svn checkout https://github.com/mavlink/MAVSDK-Python/trunk/examples

# Step into the examples folder
cd ~/Momentum/examples

# Launch example mission to takeoff, hover, then land
python3 takeoff_and_land.py