Welcome to DroneKit-Python’s documentation!¶

Open source community¶

DroneKit-Python is an open source and community-driven project.

You can find all the source code on Github here and check out our permissive Apache v2 Licence. If you want to join the community, then see our contributing section for lots of ideas on how you can help.

Compatibility¶

DroneKit-Python is compatible with vehicles that communicate using the MAVLink protocol (including most vehicles made by 3DR and other members of the DroneCode foundation). It runs on Linux, Mac OS X, or Windows.

API features¶

The API provides classes and methods to:

• Connect to a vehicle (or multiple vehicles) from a script
• Get and set vehicle state/telemetry and parameter information.
• Receive asynchronous notification of state changes.
• Guide a UAV to specified position (GUIDED mode).
• Send arbitrary custom messages to control UAV movement and other hardware (GUIDED mode).
• Create and manage waypoint missions (AUTO mode).
• Override RC channel settings.

A complete API reference is available here.

Technical support¶

This documentation is a great place to get started with developing DroneKit Python APIs.

If you run into problems, the best place to ask questions is the DroneKit-Python Forum. If your problem turns out to be a bug, then it should be posted on Github.

Latest release¶

Changelog¶

All releases¶

For information about all past releases, please see this link on Github.

Working with releases¶

The following PyPI commands are useful for working with different version of DroneKit Python:

pip install dronekit    # Install the latest version
pip install dronekit --upgrade    # Update to the latest version
pip show dronekit    # Find out what release you have installed
pip install dronekit==2.0.0rc1    # Get a sepcific old release (in this case 2.0.0rc1)

See Release History on the package ranking page for a list of all releases available on PyPI.

Installation¶

DKPY 2.0 is now installed from pip on all platforms - see Installing DroneKit for more information.

Installation is generally simpler than on DK 1.x because there are far fewer dependencies (both MAVProxy and numpy are no longer needed).

Launching scripts¶

DroneKit-Python 2.0 apps are run from an ordinary Python command prompt. For example:

some_python_script.py    # or `python some_python_script.py`

api start some_python_script.py

Code changes¶

This section outlines the changes you will need to make to your DroneKit-Python scripts.

from dronekit import connect

# Connect to the Vehicle (in this case a UDP endpoint)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Get an instance of the API endpoint
api = local_connect()
# Get the connected vehicle (currently only one vehicle can be returned).
vehicle = api.get_vehicles()[0]

while not vehicle.armed   # and not api.exit:
    print " Waiting for arming..."
    time.sleep(1)

# About to exit script
vehicle.close()

api start my_script.py 101

my_argument = int(local_arguments[0])

import os.path
full_directory_path_of_current_script = os.path.dirname(os.path.abspath(__file__))

print "Global Location: %s" % vehicle.location.global_frame
print "Global Location (relative altitude): %s" % vehicle.location.global_relative_frame
print "Local Location: %s" % vehicle.location.local_frame

Debugging¶

DroneKit-Python 1.x scripts were run in the context of a MAVProxy. This made them difficult to debug because you had to instrument your code in order to launch the debugger, and debug messages were interleaved with MAVProxy output.

Debugging on DroneKit-Python 2.x is much easier. Apps are now just standalone scripts, and can be debugged using standard Python methods (including the debugger/IDE of your choice).

RaspberryPi¶

• Communicating with Raspberry Pi via MAVLink
• Making a Mavlink WiFi bridge using the Raspberry Pi

Intel Edison¶

• Edison for drones

BeagleBoneBlack¶

• BeaglePilot

Odroid¶

• Communicating with ODroid via MAVLink
• ODroid Wifi Access Point for sharing files via Samba

DroneKit-SITL¶

DroneKit-SITL is the simplest, fastest and easiest way to run SITL on Windows, Linux (x86 architecture only), or Mac OS X. It is installed from Python’s pip tool on all platforms, and works by downloading and running pre-built vehicle binaries that are appropriate for the host operating system.

This section provides an overview of how to install and use DroneKit-SITL. For more information, see the project on Github.

pip install dronekit-sitl -UI

dronekit-sitl copter

dronekit-sitl plane-3.3.0 --home=-35.363261,149.165230,584,353

dronekit-sitl -h            #List all parameters to dronekit-sitl.
dronekit-sitl copter -h     #List additional parameters for the specified vehicle (in this case "copter").
dronekit-sitl --list        #List all available vehicles.
dronekit-sitl --reset       #Delete all downloaded vehicle binaries.
dronekit-sitl ./path [args...]  #Start SITL instance at target file location.

vehicle = connect('tcp:127.0.0.1:5760', wait_ready=True)

Building SITL from source¶

You can natively build SITL from source on Linux, Windows and Mac OS X, or from within a Vagrant Linux virtual environment.

Building from source is useful if you want to need to test the latest changes (or any use a version for which DroneKit-SITL does not have pre-built binaries). It can also be useful if you have problems getting DroneKit-SITL to work.

SITL built from source has a few differences from DroneKit-SITL:

• MAVProxy is included and started by default. You can use MAVProxy terminal to control the autopilot.
• You connect to SITL via UDP on 127.0.0.1:14550. You can use MAVProxy’s output add command to add additional ports if needed.
• You may need to disable arming checks and load autotest parameters to run examples.
• It is easier to add a virtual rangefinder and add a virtual gimbal for testing.

The following topics from the ArduPilot wiki explain how to set up Native SITL builds:

• Setting up SITL on Linux
• Setting up SITL on Windows
• Setting up SITL using Vagrant

Connecting an additional Ground Station¶

You can connect a ground station to an unused port to which messages are being forwarded.

The most reliable way to add new ports is to use MAVProxy:

• If you’re using SITL built from source you will already have MAVProxy running. You can add new ports in the MAVProxy console using output add:

  output add 127.0.0.1:14552
  

• If you’re using Dronekit-SITL you can:

  • Install MAVProxy for your system.

  • In a second terminal spawn an instance of MAVProxy to forward messages from TCP 127.0.0.1:5760 to other UDP ports like 127.0.0.1:14550 and 127.0.0.1:14551:

    mavproxy.py --master tcp:127.0.0.1:5760 --sitl 127.0.0.1:5501 --out 127.0.0.1:14550 --out 127.0.0.1:14551
    

Once you have available ports you can connect to a ground station using one UDP address, and DroneKit-Python using the other.

For example, first connect the script:

vehicle = connect('127.0.0.1:14550', wait_ready=True)

Then connect Mission Planner to the second UDP port:

• Download and install Mission Planner

• Ensure the selection list at the top right of the Mission Planner screen says UDP and then select the Connect button next to it. When prompted, enter the port number (in this case 14552).

  

  Mission Planner: Listen Port Dialog

After connecting, vehicle parameters will be loaded into Mission Planner and the vehicle is displayed on the map.

General considerations¶

DroneKit-Python communicates with vehicle autopilots using the MAVLink protocol, which defines how commands, telemetry and vehicle settings/parameters are sent between vehicles, companion computers, ground stations and other systems on a MAVLink network.

Some general considerations from using this protocol are:

• Messages and message acknowledgments are not guaranteed to arrive (the protocol is not “lossless”).
• Commands may be silently ignored by the Autopilot if it is not in a state where it can safely act on them.
• Command acknowledgment and completion messages are not sent in most cases (and if sent, may not arrive).
• Commands may be interrupted before completion.
• Autopilots may choose to interpret the protocol in slightly different ways.
• Commands can arrive at the autopilot from multiple sources.

Developers should code defensively. Where possible:

• Check that a vehicle is in a state to obey a command (for example, poll on Vehicle.is_armable before trying to arm the vehicle).
• Don’t assume that a command has succeeded until the changed behaviour is observed. In particular we recommend a launch sequence where you check that the mode and arming have succeeded before attempting to take off.
• Monitor for state changes and react accordingly. For example, if the user changes the mode from GUIDED your script should stop sending commands.
• Verify that your script can run inside the normal latency limits for message passing from the vehicle and tune any monitoring appropriately.

Connecting¶

In most cases you’ll use the normal way to connect to a vehicle, setting wait_ready=True to ensure that the vehicle is already populated with attributes when the connect() returns:

from dronekit import connect

# Connect to the Vehicle (in this case a UDP endpoint)
vehicle = connect('REPLACE_connection_string_for_your_vehicle', wait_ready=True)

The connect() call will sometimes fail with an exception. Additional information about an exception can be obtained by running the connect within a try-catch block as shown:

import dronekit
import socket
import exceptions


try:
    dronekit.connect('REPLACE_connection_string_for_your_vehicle', heartbeat_timeout=15)

# Bad TCP connection
except socket.error:
    print 'No server exists!'

# Bad TTY connection
except exceptions.OSError as e:
    print 'No serial exists!'

# API Error
except dronekit.APIException:
    print 'Timeout!'

# Other error
except:
    print 'Some other error!'

If a connection succeeds from a ground station, but not from DroneKit-Python it may be that your baud rate is incorrect for your hardware. This rate can also be set in the connect() method.

Launch sequence¶

Generally you should use the standard launch sequence described in Taking Off:

• Poll on Vehicle.is_armable until the vehicle is ready to arm.
• Set the Vehicle.mode to GUIDED
• Set Vehicle.armed to True and poll on the same attribute until the vehicle is armed.
• Call Vehicle.simple_takeoff with a target altitude.
• Poll on the altitude and allow the code to continue only when it is reached.

The approach ensures that commands are only sent to the vehicle when it is able to act on them (e.g. we know Vehicle.is_armable is True before trying to arm, we know Vehicle.armed is True before we take off). It also makes debugging takeoff problems a lot easier.

Movement commands¶

DroneKit-Python provides Vehicle.simple_goto for moving to a specific position (at a defined speed). It is also possible to control movement by sending commands to specify the vehicle’s velocity components.

For more information see: Guiding and Controlling Copter.

Vehicle information¶

Vehicle state information is exposed through vehicle attributes which can be read and observed (and in some cases written) and vehicle settings which can be read, written, iterated and observed using parameters (a special attribute). All the attributes are documented in Vehicle State and Settings.

Attributes are populated by MAVLink messages from the vehicle. Information read from an attribute may not precisely reflect the actual value on the vehicle. Commands sent to the vehicle may not arrive, or may be ignored by the autopilot.

If low-latency is critical, we recommend you verify that the update rate is achievable and perhaps modify script behaviour if Vehicle.last_heartbeat falls outside a useful range.

When setting attributes, poll their values to confirm that they have changed. This applies, in particular, to Vehicle.armed and Vehicle.mode.

Missions and waypoints¶

DroneKit-Python can also create and modify autonomous missions.

While it is possible to construct DroneKit-Python apps by dynamically constructing missions “on the fly”, we recommend you use guided mode for Copter apps. This generally results in a better experience.

Monitor and react to state changes¶

Almost all attributes can be observed - see Observing attribute changes for more information.

Exactly what state information you observe, and how you react to it, depends on your particular script:

• Most standalone apps should monitor the Vehicle.mode and stop sending commands if the mode changes unexpectedly (this usually indicates that the user has taken control of the vehicle).
• Apps might monitor Vehicle.last_heartbeat and could attempt to reconnect if the value gets too high.
• Apps could monitor Vehicle.system_status for CRITICAL or EMERGENCY in order to implement specific emergency handling.

Sleep the script when not needed¶

Sleeping your script can reduce the CPU overhead.

For example, at low speeds you might only need to check whether you’ve reached a target every few seconds. Using time.sleep(2) between checks will be more efficient than checking more often.

Exiting a script¶

Scripts should call Vehicle.close() before exiting to ensure that all messages have flushed before the script completes:

# About to exit script
vehicle.close()

Subclass Vehicle¶

If you need to use functionality that is specific to particular hardware, we recommend you subclass Vehicle and pass this new class into connect().

Example: Create Attribute in App shows how you can do this.

Debugging¶

DroneKit-Python apps are ordinary standalone Python scripts, and can be debugged using standard Python methods (including the debugger/IDE of your choice).

Launching scripts¶

Scripts are run from an ordinary Python command prompt. For example:

python some_python_script.py [arguments]

Command line arguments are passed into the script as sys.argv variables (the normal) and you can use these directly or via an argument parser (e.g. argparse).

Current script directory¶

You can use normal Python methods for getting file system information:

import os.path
full_directory_path_of_current_script = os.path.dirname(os.path.abspath(__file__))

Connection string options¶

The table below shows connection strings you can use for some of the more common connection types:

Connecting to multiple vehicles¶

You can control multiple vehicles from within a single script by calling connect() for each vehicle with the appropriate connection strings.

The returned Vehicle objects are independent of each other and can be separately used to control their respective vehicle.

Attributes¶

Vehicle state information is exposed through vehicle attributes. DroneKit-Python currently supports the following “standard” attributes: Vehicle.version, Vehicle.location.capabilities, Vehicle.location.global_frame, Vehicle.location.global_relative_frame, Vehicle.location.local_frame, Vehicle.attitude, Vehicle.velocity, Vehicle.gps_0, Vehicle.gimbal, Vehicle.battery, Vehicle.rangefinder, Vehicle.ekf_ok, Vehicle.last_heartbeat, Vehicle.home_location, Vehicle.system_status, Vehicle.heading, Vehicle.is_armable, Vehicle.airspeed, Vehicle.groundspeed, Vehicle.armed, Vehicle.mode.

Attributes are initially created with None values for their members. In most cases the members are populated (and repopulated) as new MAVLink messages of the associated types are received from the vehicle.

All of the attributes can be read, but only the Vehicle.home_location, Vehicle.gimbal Vehicle.airspeed, Vehicle.groundspeed, Vehicle.mode and Vehicle.armed status can be set.

Almost all of the attributes can be observed.

The behaviour of Vehicle.home_location is different from the other attributes, and is discussed in its own section below.

# vehicle is an instance of the Vehicle class
print "Autopilot Firmware version: %s" % vehicle.version
print "Autopilot capabilities (supports ftp): %s" % vehicle.capabilities.ftp
print "Global Location: %s" % vehicle.location.global_frame
print "Global Location (relative altitude): %s" % vehicle.location.global_relative_frame
print "Local Location: %s" % vehicle.location.local_frame    #NED
print "Attitude: %s" % vehicle.attitude
print "Velocity: %s" % vehicle.velocity
print "GPS: %s" % vehicle.gps_0
print "Groundspeed: %s" % vehicle.groundspeed
print "Airspeed: %s" % vehicle.airspeed
print "Gimbal status: %s" % vehicle.gimbal
print "Battery: %s" % vehicle.battery
print "EKF OK?: %s" % vehicle.ekf_ok
print "Last Heartbeat: %s" % vehicle.last_heartbeat
print "Rangefinder: %s" % vehicle.rangefinder
print "Rangefinder distance: %s" % vehicle.rangefinder.distance
print "Rangefinder voltage: %s" % vehicle.rangefinder.voltage
print "Heading: %s" % vehicle.heading
print "Is Armable?: %s" % vehicle.is_armable
print "System status: %s" % vehicle.system_status.state
print "Mode: %s" % vehicle.mode.name    # settable
print "Armed: %s" % vehicle.armed    # settable

#disarm the vehicle
vehicle.armed = False

#set the default groundspeed to be used in movement commands
vehicle.groundspeed = 3.2

vehicle.mode = VehicleMode("GUIDED")
vehicle.armed = True
while not vehicle.mode.name=='GUIDED' and not vehicle.armed and not api.exit:
    print " Getting ready to take off ..."
    time.sleep(1)

#Point the gimbal straight down
vehicle.gimbal.rotate(-90, 0, 0)
time.sleep(10)

#Set the camera to track the current home position.
vehicle.gimbal.target_location(vehicle.home_location)
time.sleep(10)

 #Callback to print the location in global frames. 'value' is the updated value
 def location_callback(self, attr_name, value):
     print "Location (Global): ", value


 # Add a callback `location_callback` for the `global_frame` attribute.
 vehicle.add_attribute_listener('location.global_frame', location_callback)

 # Wait 2s so callback can be notified before the observer is removed
 time.sleep(2)

 # Remove observer - specifying the attribute and previously registered callback function
 vehicle.remove_message_listener('location.global_frame', location_callback)

vehicle.add_attribute_listener('location.global_frame', location_callback)
vehicle.location.add_attribute_listener('global_frame', location_callback)

 last_rangefinder_distance=0

 @vehicle.on_attribute('rangefinder')
 def rangefinder_callback(self,attr_name):
     #attr_name not used here.
     global last_rangefinder_distance
     if last_rangefinder_distance == round(self.rangefinder.distance, 1):
         return
     last_rangefinder_distance = round(self.rangefinder.distance, 1)
     print " Rangefinder (metres): %s" % last_rangefinder_distance

# Demonstrate getting callback on any attribute change
def wildcard_callback(self, attr_name, value):
    print " CALLBACK: (%s): %s" % (attr_name,value)

print "\nAdd attribute callback detecting any attribute change"
vehicle.add_attribute_listener('*', wildcard_callback)


print " Wait 1s so callback invoked before observer removed"
time.sleep(1)

print " Remove Vehicle attribute observer"
# Remove observer added with `add_attribute_listener()`
vehicle.remove_attribute_listener('*', wildcard_callback)

Parameters¶

Vehicle parameters provide the information used to configure the autopilot for the vehicle-specific hardware/capabilities. The available parameters for each platform are documented in the ArduPilot wiki here: Copter Parameters, Plane Parameters, Rover Parameters (the lists are automatically generated from the latest ArduPilot source code, and may contain or omit parameters in your vehicle).

DroneKit downloads all parameters when you first connect to the UAV (forcing parameter reads to wait until the download completes), and subsequently keeps the values updated by monitoring vehicle messages for changes to individual parameters. This process ensures that it is always safe to read supported parameters, and that their values will match the information on the vehicle.

Parameters can be read, set, observed and iterated using the Vehicle.parameters attribute (a Parameters object).

# Print the value of the THR_MIN parameter.
print "Param: %s" % vehicle.parameters['THR_MIN']

# Change the parameter value (Copter, Rover)
vehicle.parameters['THR_MIN']=100

print "\nPrint all parameters (iterate `vehicle.parameters`):"
for key, value in vehicle.parameters.iteritems():
    print " Key:%s Value:%s" % (key,value)

@vehicle.parameters.on_attribute('THR_MIN')
def decorated_thr_min_callback(self, attr_name, value):
    print " PARAMETER CALLBACK: %s changed to: %s" % (attr_name, value)

#Callback function for "any" parameter
def any_parameter_callback(self, attr_name, value):
    print " ANY PARAMETER CALLBACK: %s changed to: %s" % (attr_name, value)

#Add observer for the vehicle's any/all parameters parameter (note wildcard string ``'*'``)
vehicle.parameters.add_attribute_listener('*', any_parameter_callback)

Known issues¶

Known issues and improvement suggestions can viewed on Github here.

Controlling vehicle movement¶

Copter movement can be controlled either by explicitly setting a target position, or by specifying the vehicle’s velocity components to guide it in a preferred direction.

# Set mode to guided - this is optional as the goto method will change the mode if needed.
vehicle.mode = VehicleMode("GUIDED")

# Set the target location in global-relative frame
a_location = LocationGlobalRelative(-34.364114, 149.166022, 30)
vehicle.simple_goto(a_location)

# Set airspeed using attribute
vehicle.airspeed = 5 #m/s

# Set groundspeed using attribute
vehicle.groundspeed = 7.5 #m/s

# Set groundspeed using `simple_goto()` parameter
vehicle.simple_goto(a_location, groundspeed=10)

def send_ned_velocity(velocity_x, velocity_y, velocity_z, duration):
    """
    Move vehicle in direction based on specified velocity vectors.
    """
    msg = vehicle.message_factory.set_position_target_local_ned_encode(
        0,       # time_boot_ms (not used)
        0, 0,    # target system, target component
        mavutil.mavlink.MAV_FRAME_LOCAL_NED, # frame
        0b0000111111000111, # type_mask (only speeds enabled)
        0, 0, 0, # x, y, z positions (not used)
        velocity_x, velocity_y, velocity_z, # x, y, z velocity in m/s
        0, 0, 0, # x, y, z acceleration (not supported yet, ignored in GCS_Mavlink)
        0, 0)    # yaw, yaw_rate (not supported yet, ignored in GCS_Mavlink)


    # send command to vehicle on 1 Hz cycle
    for x in range(0,duration):
        vehicle.send_mavlink(msg)
        time.sleep(1)

# Set up velocity mappings
# velocity_x > 0 => fly North
# velocity_x < 0 => fly South
# velocity_y > 0 => fly East
# velocity_y < 0 => fly West
# velocity_z < 0 => ascend
# velocity_z > 0 => descend
SOUTH=-2
UP=-0.5   #NOTE: up is negative!

#Fly south and up.
send_ned_velocity(SOUTH,0,UP,DURATION)

Guided mode commands¶

This section explains how to send MAVLink commands, what commands can be sent, and lists a number of real examples you can use in your own code.

msg = vehicle.message_factory.set_position_target_local_ned_encode(
    0,       # time_boot_ms (not used)
    0, 0,    # target_system, target_component
    mavutil.mavlink.MAV_FRAME_BODY_NED, # frame
    0b0000111111000111, # type_mask (only speeds enabled)
    0, 0, 0, # x, y, z positions
    velocity_x, velocity_y, velocity_z, # x, y, z velocity in m/s
    0, 0, 0, # x, y, z acceleration (not supported yet, ignored in GCS_Mavlink)
    0, 0)    # yaw, yaw_rate (not supported yet, ignored in GCS_Mavlink)
# send command to vehicle
vehicle.send_mavlink(msg)

msg = vehicle.message_factory.command_long_encode(
    0, 0,    # target_system, target_component
    mavutil.mavlink.MAV_CMD_CONDITION_YAW, #command
    0, #confirmation
    heading,    # param 1, yaw in degrees
    0,          # param 2, yaw speed deg/s
    1,          # param 3, direction -1 ccw, 1 cw
    is_relative, # param 4, relative offset 1, absolute angle 0
    0, 0, 0)    # param 5 ~ 7 not used
# send command to vehicle
vehicle.send_mavlink(msg)

def condition_yaw(heading, relative=False):
    if relative:
        is_relative=1 #yaw relative to direction of travel
    else:
        is_relative=0 #yaw is an absolute angle
    # create the CONDITION_YAW command using command_long_encode()
    msg = vehicle.message_factory.command_long_encode(
        0, 0,    # target system, target component
        mavutil.mavlink.MAV_CMD_CONDITION_YAW, #command
        0, #confirmation
        heading,    # param 1, yaw in degrees
        0,          # param 2, yaw speed deg/s
        1,          # param 3, direction -1 ccw, 1 cw
        is_relative, # param 4, relative offset 1, absolute angle 0
        0, 0, 0)    # param 5 ~ 7 not used
    # send command to vehicle
    vehicle.send_mavlink(msg)

def set_roi(location):
    # create the MAV_CMD_DO_SET_ROI command
    msg = vehicle.message_factory.command_long_encode(
        0, 0,    # target system, target component
        mavutil.mavlink.MAV_CMD_DO_SET_ROI, #command
        0, #confirmation
        0, 0, 0, 0, #params 1-4
        location.lat,
        location.lon,
        location.alt
        )
    # send command to vehicle
    vehicle.send_mavlink(msg)

Frame conversion functions¶

The functions in this section help convert between different frames-of-reference. In particular they make it easier to navigate in terms of “metres from the current position” when using commands that take absolute positions in decimal degrees.

The methods are approximations only, and may be less accurate over longer distances, and when close to the Earth’s poles.

def get_location_metres(original_location, dNorth, dEast):
    """
    Returns a LocationGlobal object containing the latitude/longitude `dNorth` and `dEast` metres from the
    specified `original_location`. The returned LocationGlobal has the same `alt` value
    as `original_location`.

    The function is useful when you want to move the vehicle around specifying locations relative to
    the current vehicle position.

    The algorithm is relatively accurate over small distances (10m within 1km) except close to the poles.

    For more information see:
    http://gis.stackexchange.com/questions/2951/algorithm-for-offsetting-a-latitude-longitude-by-some-amount-of-meters
    """
    earth_radius=6378137.0 #Radius of "spherical" earth
    #Coordinate offsets in radians
    dLat = dNorth/earth_radius
    dLon = dEast/(earth_radius*math.cos(math.pi*original_location.lat/180))

    #New position in decimal degrees
    newlat = original_location.lat + (dLat * 180/math.pi)
    newlon = original_location.lon + (dLon * 180/math.pi)
    if type(original_location) is LocationGlobal:
        targetlocation=LocationGlobal(newlat, newlon,original_location.alt)
    elif type(original_location) is LocationGlobalRelative:
        targetlocation=LocationGlobalRelative(newlat, newlon,original_location.alt)
    else:
        raise Exception("Invalid Location object passed")

    return targetlocation;

def get_distance_metres(aLocation1, aLocation2):
    """
    Returns the ground distance in metres between two `LocationGlobal` or `LocationGlobalRelative` objects.

    This method is an approximation, and will not be accurate over large distances and close to the
    earth's poles. It comes from the ArduPilot test code:
    https://github.com/diydrones/ardupilot/blob/master/Tools/autotest/common.py
    """
    dlat = aLocation2.lat - aLocation1.lat
    dlong = aLocation2.lon - aLocation1.lon
    return math.sqrt((dlat*dlat) + (dlong*dlong)) * 1.113195e5

def get_bearing(aLocation1, aLocation2):
    """
    Returns the bearing between the two LocationGlobal objects passed as parameters.

    This method is an approximation, and may not be accurate over large distances and close to the
    earth's poles. It comes from the ArduPilot test code:
    https://github.com/diydrones/ardupilot/blob/master/Tools/autotest/common.py
    """
    off_x = aLocation2.lon - aLocation1.lon
    off_y = aLocation2.lat - aLocation1.lat
    bearing = 90.00 + math.atan2(-off_y, off_x) * 57.2957795
    if bearing < 0:
        bearing += 360.00
    return bearing;

Other information¶

• NED Frame
• MISSION_ITEM
• GUIDED Mode for Copter (wiki).
• GUIDED mode for Plane (wiki).
• Copter Commands in Guided Mode (wiki).
• MAVLink mission command messages (wiki).
• GCS_Mavlink.cpp (Copter)

Mission Command Overview¶

The mission commands (e.g. MAV_CMD_NAV_TAKEOFF, MAV_CMD_NAV_WAYPOINT ) supported for each vehicle type are listed here: Copter, Plane, Rover.

There are three types of commands:

• NAVigation commands (MAV_CMD_NAV_*) are used to control vehicle movement, including takeoff, moving to and around waypoints, changing altitude, and landing.
• DO commands (MAV_CMD_DO_*) are for auxiliary functions that do not affect the vehicle’s position (for example, setting the camera trigger distance, or setting a servo value).
• CONDITION commands (MAV_CMD_NAV_*) are used to delay DO commands until some condition is met. For example MAV_CMD_CONDITION_DISTANCE will prevent DO commands executing until the vehicle reaches the specified distance from the waypoint.

During a mission at most one NAV command and one DO or CONDITION command can be running at the same time. CONDITION and DO commands are associated with the last NAV command that was sent: if the UAV reaches the waypoint before these commands are executed, the next NAV command is loaded and they will be skipped.

The MAVLink Mission Command Messages (MAV_CMD) wiki topic provides a more detailed overview of commands.

Download current mission¶

The mission commands for a vehicle are accessed using the Vehicle.commands attribute. The attribute is of type CommandSequence, a class that provides ‘array style’ indexed access to the waypoints which make up the mission.

Waypoints are not downloaded from vehicle until download() is called. The download is asynchronous; use wait_ready() to block your thread until the download is complete:

# Connect to the Vehicle (in this case a simulated vehicle at 127.0.0.1:14550)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Download the vehicle waypoints (commands). Wait until download is complete.
cmds = vehicle.commands
cmds.download()
cmds.wait_ready()

Clearing current mission¶

To clear a mission you call clear() and then Vehicle.commands.upload() (to upload the changes to the vehicle):

# Connect to the Vehicle (in this case a simulated vehicle at 127.0.0.1:14550)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Get commands object from Vehicle.
cmds = vehicle.commands

# Call clear() on Vehicle.commands and upload the command to the vehicle.
cmds.clear()
cmds.upload()

Creating/adding mission commands¶

After downloading or clearing a mission new commands can be added and uploaded to the vehicle. Commands are added to the mission using add() and are sent to the vehicle (either individually or in batches) using upload().

Each command is packaged in a Command object (see that class for the order/meaning of the parameters). The supported commands for each vehicle are linked above.

# Connect to the Vehicle (in this case a simulated vehicle at 127.0.0.1:14550)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Get the set of commands from the vehicle
cmds = vehicle.commands
cmds.download()
cmds.wait_ready()

# Create and add commands
cmd1=Command( 0, 0, 0, mavutil.mavlink.MAV_FRAME_GLOBAL_RELATIVE_ALT, mavutil.mavlink.MAV_CMD_NAV_TAKEOFF, 0, 0, 0, 0, 0, 0, 0, 0, 10)
cmd2=Command( 0, 0, 0, mavutil.mavlink.MAV_FRAME_GLOBAL_RELATIVE_ALT, mavutil.mavlink.MAV_CMD_NAV_WAYPOINT, 0, 0, 0, 0, 0, 0, 10, 10, 10)
cmds.add(cmd1)
cmds.add(cmd2)
cmds.upload() # Send commands

Modifying missions¶

While you can add new commands after downloading a mission it is not possible to directly modify and upload existing commands in Vehicle.commands (you can modify the commands but changes do not propagate to the vehicle).

Instead you copy all the commands into another container (e.g. a list), modify them as needed, then clear Vehicle.commands and upload the list as a new mission:

# Connect to the Vehicle (in this case a simulated vehicle at 127.0.0.1:14550)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Get the set of commands from the vehicle
cmds = vehicle.commands
cmds.download()
cmds.wait_ready()

# Save the vehicle commands to a list
missionlist=[]
for cmd in cmds:
    missionlist.append(cmd)

# Modify the mission as needed. For example, here we change the
# first waypoint into a MAV_CMD_NAV_TAKEOFF command.
missionlist[0].command=mavutil.mavlink.MAV_CMD_NAV_TAKEOFF

# Clear the current mission (command is sent when we call upload())
cmds.clear()

#Write the modified mission and flush to the vehicle
for cmd in missionlist:
    cmds.add(cmd)
cmds.upload()

The changes are not guaranteed to be complete until upload() is called on the parent Vehicle.commands object.

Running and monitoring missions¶

To start a mission, change the mode to AUTO:

# Connect to the Vehicle (in this case a simulated vehicle at 127.0.0.1:14550)
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# Set the vehicle into auto mode
vehicle.mode = VehicleMode("AUTO")

You can stop/pause the current mission by switching out of AUTO mode (e.g. into GUIDED mode). If you switch back to AUTO mode the mission will either restart at the beginning or resume at the current waypoint - the behaviour depends on the value of the MIS_RESTART parameter (available on all vehicle types).

You can monitor the progress of the mission by polling the Vehicle.commands.next attribute to get the current command number. You can also change the current command by setting the attribute to the desired command number.

vehicle.commands.next=2
print "Current Waypoint: %s" % vehicle.commands.next
vehicle.commands.next=4
print "Current Waypoint: %s" % vehicle.commands.next

There is no need to upload() changes to send an update to the next attribute to the vehicle (and as with other attributes, if you fetch a value, it is updated from the vehicle).

Handling the end of a mission¶

At the end of the mission the vehicle will enter LOITER mode (hover in place for Copter, circle for Plane, stop for Rover). You can add new commands to the mission, but you will need to toggle from/back to AUTO mode to start it running again.

Currently there is no notification in DroneKit when a mission completes. If you need to detect mission end (in order to perform some other operation) then you can either:

• Add a dummy mission command and poll Vehicle.commands.next for the transition to the final command, or
• Compare the current position to the target position in the final waypoint.

Useful Mission functions¶

This example code contains a number of functions that might be useful for managing and monitoring missions:

def upload_mission(aFileName):
        """
        Upload a mission from a file.
        """
        #Read mission from file
        missionlist = readmission(aFileName)

        print "\nUpload mission from a file: %s" % import_mission_filename
        #Clear existing mission from vehicle
        print ' Clear mission'
        cmds = vehicle.commands
        cmds.clear()
        #Add new mission to vehicle
        for command in missionlist:
            cmds.add(command)
        print ' Upload mission'
        vehicle.commands.upload()

def readmission(aFileName):
    """
    Load a mission from a file into a list.

    This function is used by upload_mission().
    """
    print "Reading mission from file: %s\n" % aFileName
    cmds = vehicle.commands
    missionlist=[]
    with open(aFileName) as f:
        for i, line in enumerate(f):
            if i==0:
                if not line.startswith('QGC WPL 110'):
                    raise Exception('File is not supported WP version')
            else:
                linearray=line.split('\t')
                ln_index=int(linearray[0])
                ln_currentwp=int(linearray[1])
                ln_frame=int(linearray[2])
                ln_command=int(linearray[3])
                ln_param1=float(linearray[4])
                ln_param2=float(linearray[5])
                ln_param3=float(linearray[6])
                ln_param4=float(linearray[7])
                ln_param5=float(linearray[8])
                ln_param6=float(linearray[9])
                ln_param7=float(linearray[10])
                ln_autocontinue=int(linearray[11].strip())
                cmd = Command( 0, 0, 0, ln_frame, ln_command, ln_currentwp, ln_autocontinue, ln_param1, ln_param2, ln_param3, ln_param4, ln_param5, ln_param6, ln_param7)
                missionlist.append(cmd)
    return missionlist

def save_mission(aFileName):
    """
    Save a mission in the Waypoint file format (http://qgroundcontrol.org/mavlink/waypoint_protocol#waypoint_file_format).
    """
    missionlist = download_mission()
    output='QGC WPL 110\n'
    for cmd in missionlist:
        commandline="%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" % (cmd.seq,cmd.current,cmd.frame,cmd.command,cmd.param1,cmd.param2,cmd.param3,cmd.param4,cmd.x,cmd.y,cmd.z,cmd.autocontinue)
        output+=commandline
    with open(aFileName, 'w') as file_:
        file_.write(output)

def download_mission():
    """
    Downloads the current mission and returns it in a list.
    It is used in save_mission() to get the file information to save.
    """
    missionlist=[]
    cmds = vehicle.commands
    cmds.download()
    cmds.wait_ready()
    for cmd in cmds:
        missionlist.append(cmd)
    return missionlist

def distance_to_current_waypoint():
    """
    Gets distance in metres to the current waypoint.
    It returns None for the first waypoint (Home location).
    """
    nextwaypoint=vehicle.commands.next
    if nextwaypoint ==0:
        return None
    missionitem=vehicle.commands[nextwaypoint-1] #commands are zero indexed
    lat=missionitem.x
    lon=missionitem.y
    alt=missionitem.z
    targetWaypointLocation=LocationGlobalRelative(lat,lon,alt)
    distancetopoint = get_distance_metres(vehicle.location.global_frame, targetWaypointLocation)
    return distancetopoint

Useful Links¶

• MAVLink mission command messages (all vehicle types - wiki).

pdb - The Python Debugger¶

The Python Debugger - pdb can be used to debug DroneKit-Python apps.

The command below can be used to run a script in debug mode:

python -m pdb my_dronekit_script.py

You can also instrument your code to invoke the debugger at a certain point. To do this add set-trace() at the point where you want to break execution:

# Connect to the Vehicle on udp at 127.0.0.1:14550
vehicle = connect('127.0.0.1:14550', wait_ready=True)

import pdb; pdb.set_trace()
print "Global Location: %s" % vehicle.location.global_frame

The available debugger commands are listed here.

pudb - A full-screen, console-based Python debugger¶

If you prefer a IDE like debug you can use pudb - A full-screen, console-based Python debugger.

pip install pudb

To start debugging, simply insert:

from pudb import set_trace; set_trace()

Insert either of these snippets into the piece of code you want to debug, or run the entire script with:

pudb my-script.py

Print/log statements¶

The simplest and most common method of debugging is to manually add debug/print statements to the source.

# Connect to the Vehicle on udp at 127.0.0.1:14550
vehicle = connect('127.0.0.1:14550', wait_ready=True)

# print out debug information
print "Global Location: %s" % vehicle.location.global_frame

In addition to printing DroneKit variables, Python provides numerous inbuilt and add-on modules/methods for inspecting code (e.g. dir(), traceback, etc.)

Other IDEs/debuggers¶

There is no reason you should not be able to straightforwardly use other popular Python IDEs including IDLE and Eclipse.

Creating a message listener¶

The Vehicle.on_message() decorator can be used to set a particular function as the callback handler for a particular message type. You can create listeners for as many messages as you like, or even multiple listeners for the same message.

For example, the code snippet below shows how to set a listener for the RANGEFINDER message:

#Create a message listener using the decorator.
@vehicle.on_message('RANGEFINDER')
def listener(self, name, message):
    print message

The messages are classes from the pymavlink library. The output of the code above looks something like:

RANGEFINDER {distance : 0.0899999961257, voltage : 0.00900000054389}
...

You can access the message fields directly. For example, to access the RANGEFINDER message your listener function might look like this:

#Create a message listener using the decorator.
@vehicle.on_message('RANGEFINDER')
def listener(self, name, message):
    print 'distance: %s' % message.distance
    print 'voltage: %s' % message.voltage

Watching all messages¶

You can register a callback for all messages by setting the message name as the wildcard string (‘*’):

#Create a message listener for all messages.
@vehicle.on_message('*')
def listener(self, name, message):
    print 'message: %s' % message

Removing an observer¶

Callbacks registered using the Vehicle.on_message() decorator cannot be removed. This is generally not a problem, because in most cases you’re interested in messages for the lifetime of a session.

If you do need to be able to remove messages you can instead add the callback using Vehicle.add_message_listener, and then remove it by calling Vehicle.remove_message_listener.

Running the example¶

The example can be run as described in Running the Examples (which in turn assumes that the vehicle and DroneKit have been set up as described in Installing DroneKit).

In summary, after cloning the repository:

1. Navigate to the example folder as shown:

   cd dronekit-python/examples/vehicle_state/
   

2. You can run the example against a simulator (DroneKit-SITL) by specifying the Python script without any arguments. The example will download SITL binaries (if needed), start the simulator, and then connect to it:

   python vehicle_state.py
   

   On the command prompt you should see (something like):

   Connecting to vehicle on: tcp:127.0.0.1:5760
   >>> APM:Copter V3.3 (d6053245)
   >>> Frame: QUAD
   >>> Calibrating barometer
   >>> Initialising APM...
   >>> barometer calibration complete
   >>> GROUND START
   
   Get all vehicle attribute values:
    Autopilot Firmware version: APM:Copter-3.3.0-alpha64
      Major version number: 3
      Minor version number: 3
      Patch version number: 0
      Release type: rc
      Release version: 0
      Stable release?: True
    Autopilot capabilities
      Supports MISSION_FLOAT message type: True
      Supports PARAM_FLOAT message type: True
      Supports MISSION_INT message type: False
      Supports COMMAND_INT message type: False
      Supports PARAM_UNION message type: False
      Supports ftp for file transfers: False
      Supports commanding attitude offboard: False
      Supports commanding position and velocity targets in local NED frame: True
      Supports set position + velocity targets in global scaled integers: True
      Supports terrain protocol / data handling: True
      Supports direct actuator control: False
      Supports the flight termination command: True
      Supports mission_float message type: True
      Supports onboard compass calibration: False
    Global Location: LocationGlobal:lat=-35.363261,lon=149.1652299,alt=None
    Global Location (relative altitude): LocationGlobalRelative:lat=-35.363261,lon=149.1652299,alt=0.0
    Local Location: LocationLocal:north=None,east=None,down=None
    Attitude: Attitude:pitch=0.00294387154281,yaw=-0.11805768311,roll=0.00139428151306
    Velocity: [-0.03, 0.02, 0.0]
    GPS: GPSInfo:fix=3,num_sat=10
    Gimbal status: Gimbal: pitch=None, roll=None, yaw=None
    Battery: Battery:voltage=12.587,current=0.0,level=100
    EKF OK?: False
    Last Heartbeat: 0.769999980927
    Rangefinder: Rangefinder: distance=None, voltage=None
    Rangefinder distance: None
    Rangefinder voltage: None
    Heading: 353
    Is Armable?: False
    System status: STANDBY
    Groundspeed: 0.0
    Airspeed: 0.0
    Mode: STABILIZE
    Armed: False
    Waiting for home location ...
    ...
    Waiting for home location ...
    Waiting for home location ...
   
    Home location: LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=583.989990234
   
   Set new home location
    New Home Location (from attribute - altitude should be 222): LocationGlobal:lat=-35.363261,lon=149.1652299,alt=222
    New Home Location (from vehicle - altitude should be 222): LocationGlobal:lat=-35.3632621765,lon=149.165237427,alt=222.0
   
   Set Vehicle.mode=GUIDED (currently: STABILIZE)
    Waiting for mode change ...
   
   Set Vehicle.armed=True (currently: False)
    Waiting for arming...
    Waiting for arming...
    Waiting for arming...
   >>> ARMING MOTORS
   >>> GROUND START
    Waiting for arming...
    Waiting for arming...
   >>> Initialising APM...
    Vehicle is armed: True
   
   Add `attitude` attribute callback/observer on `vehicle`
    Wait 2s so callback invoked before observer removed
    CALLBACK: Attitude changed to Attitude:pitch=-0.000483880605316,yaw=-0.0960851684213,roll=-0.00799709651619
    CALLBACK: Attitude changed to Attitude:pitch=0.000153727291035,yaw=-0.0962921902537,roll=-0.00707155792043
    ...
    CALLBACK: Attitude changed to Attitude:pitch=0.00485319690779,yaw=-0.100129388273,roll=0.00181497994345
     Remove Vehicle.attitude observer
   
   Add `mode` attribute callback/observer using decorator
    Set mode=STABILIZE (currently: GUIDED) and wait for callback
    Wait 2s so callback invoked before moving to next example
    CALLBACK: Mode changed to VehicleMode:STABILIZE
   
    Attempt to remove observer added with `on_attribute` decorator (should fail)
    Exception: Cannot remove observer added using decorator
   
   Add attribute callback detecting ANY attribute change
    Wait 1s so callback invoked before observer removed
    CALLBACK: (attitude): Attitude:pitch=0.00716688157991,yaw=-0.0950401723385,roll=0.00759896961972
    CALLBACK: (heading): 354
    CALLBACK: (location): <dronekit.Locations object at 0x000000000767F2B0>
    CALLBACK: (airspeed): 0.0
    CALLBACK: (groundspeed): 0.0
    CALLBACK: (ekf_ok): True
    CALLBACK: (battery): Battery:voltage=12.538,current=3.48,level=99
    CALLBACK: (gps_0): GPSInfo:fix=3,num_sat=10
    CALLBACK: (location): <dronekit.Locations object at 0x000000000767F2B0>
    CALLBACK: (velocity): [-0.14, 0.1, 0.0]
    CALLBACK: (local_position): LocationLocal:north=-0.136136248708,east=-0.0430941730738,down=-0.00938374921679
    CALLBACK: (channels): {'1': 1500, '3': 1000, '2': 1500, '5': 1800, '4': 1500, '7': 1000, '6': 1000, '8': 1800}
    ...
    CALLBACK: (ekf_ok): True
    Remove Vehicle attribute observer
   
   Read and write parameters
    Read vehicle param 'THR_MIN': 130.0
    Write vehicle param 'THR_MIN' : 10
    Read new value of param 'THR_MIN': 10.0
   
   Print all parameters (iterate `vehicle.parameters`):
    Key:RC7_REV Value:1.0
    Key:GPS_INJECT_TO Value:127.0
    Key:FLTMODE1 Value:7.0
    ...
    Key:SR2_POSITION Value:0.0
    Key:SIM_FLOW_DELAY Value:0.0
    Key:BATT_CURR_PIN Value:12.0
   
   Create parameter observer using decorator
   Write vehicle param 'THR_MIN' : 20 (and wait for callback)
    PARAMETER CALLBACK: THR_MIN changed to: 20.0
   
   Create (removable) observer for any parameter using wildcard string
    Change THR_MID and THR_MIN parameters (and wait for callback)
    ANY PARAMETER CALLBACK: THR_MID changed to: 400.0
    PARAMETER CALLBACK: THR_MIN changed to: 30.0
    ANY PARAMETER CALLBACK: THR_MIN changed to: 30.0
   
   Reset vehicle attributes/parameters and exit
   >>> DISARMING MOTORS
    PARAMETER CALLBACK: THR_MIN changed to: 130.0
    ANY PARAMETER CALLBACK: THR_MIN changed to: 130.0
    ANY PARAMETER CALLBACK: THR_MID changed to: 500.0
   
   Close vehicle object
   Completed
   

3. You can run the example against a specific connection (simulated or otherwise) by passing the connection string for your vehicle in the --connect parameter.

   For example, to connect to SITL running on UDP port 14550 on your local computer:

   python vehicle_state.py --connect 127.0.0.1:14550
   

How does it work?¶

The guide topic Vehicle State and Settings provides an explanation of how this code works.

Known issues¶

This example has no known issues.

Source code¶

The full source code at documentation build-time is listed below (current version on github):

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
© Copyright 2015-2016, 3D Robotics.
vehicle_state.py: 

Demonstrates how to get and set vehicle state and parameter information, 
and how to observe vehicle attribute (state) changes.

Full documentation is provided at http://python.dronekit.io/examples/vehicle_state.html
"""
from __future__ import print_function
from dronekit import connect, VehicleMode
import time

#Set up option parsing to get connection string
import argparse  
parser = argparse.ArgumentParser(description='Print out vehicle state information. Connects to SITL on local PC by default.')
parser.add_argument('--connect', 
                   help="vehicle connection target string. If not specified, SITL automatically started and used.")
args = parser.parse_args()

connection_string = args.connect
sitl = None


#Start SITL if no connection string specified
if not connection_string:
    import dronekit_sitl
    sitl = dronekit_sitl.start_default()
    connection_string = sitl.connection_string()


# Connect to the Vehicle. 
#   Set `wait_ready=True` to ensure default attributes are populated before `connect()` returns.
print("\nConnecting to vehicle on: %s" % connection_string)
vehicle = connect(connection_string, wait_ready=True)

vehicle.wait_ready('autopilot_version')

# Get all vehicle attributes (state)
print("\nGet all vehicle attribute values:")
print(" Autopilot Firmware version: %s" % vehicle.version)
print("   Major version number: %s" % vehicle.version.major)
print("   Minor version number: %s" % vehicle.version.minor)
print("   Patch version number: %s" % vehicle.version.patch)
print("   Release type: %s" % vehicle.version.release_type())
print("   Release version: %s" % vehicle.version.release_version())
print("   Stable release?: %s" % vehicle.version.is_stable())
print(" Autopilot capabilities")
print("   Supports MISSION_FLOAT message type: %s" % vehicle.capabilities.mission_float)
print("   Supports PARAM_FLOAT message type: %s" % vehicle.capabilities.param_float)
print("   Supports MISSION_INT message type: %s" % vehicle.capabilities.mission_int)
print("   Supports COMMAND_INT message type: %s" % vehicle.capabilities.command_int)
print("   Supports PARAM_UNION message type: %s" % vehicle.capabilities.param_union)
print("   Supports ftp for file transfers: %s" % vehicle.capabilities.ftp)
print("   Supports commanding attitude offboard: %s" % vehicle.capabilities.set_attitude_target)
print("   Supports commanding position and velocity targets in local NED frame: %s" % vehicle.capabilities.set_attitude_target_local_ned)
print("   Supports set position + velocity targets in global scaled integers: %s" % vehicle.capabilities.set_altitude_target_global_int)
print("   Supports terrain protocol / data handling: %s" % vehicle.capabilities.terrain)
print("   Supports direct actuator control: %s" % vehicle.capabilities.set_actuator_target)
print("   Supports the flight termination command: %s" % vehicle.capabilities.flight_termination)
print("   Supports mission_float message type: %s" % vehicle.capabilities.mission_float)
print("   Supports onboard compass calibration: %s" % vehicle.capabilities.compass_calibration)
print(" Global Location: %s" % vehicle.location.global_frame)
print(" Global Location (relative altitude): %s" % vehicle.location.global_relative_frame)
print(" Local Location: %s" % vehicle.location.local_frame)
print(" Attitude: %s" % vehicle.attitude)
print(" Velocity: %s" % vehicle.velocity)
print(" GPS: %s" % vehicle.gps_0)
print(" Gimbal status: %s" % vehicle.gimbal)
print(" Battery: %s" % vehicle.battery)
print(" EKF OK?: %s" % vehicle.ekf_ok)
print(" Last Heartbeat: %s" % vehicle.last_heartbeat)
print(" Rangefinder: %s" % vehicle.rangefinder)
print(" Rangefinder distance: %s" % vehicle.rangefinder.distance)
print(" Rangefinder voltage: %s" % vehicle.rangefinder.voltage)
print(" Heading: %s" % vehicle.heading)
print(" Is Armable?: %s" % vehicle.is_armable)
print(" System status: %s" % vehicle.system_status.state)
print(" Groundspeed: %s" % vehicle.groundspeed)    # settable
print(" Airspeed: %s" % vehicle.airspeed)    # settable
print(" Mode: %s" % vehicle.mode.name)    # settable
print(" Armed: %s" % vehicle.armed)    # settable



# Get Vehicle Home location - will be `None` until first set by autopilot
while not vehicle.home_location:
    cmds = vehicle.commands
    cmds.download()
    cmds.wait_ready()
    if not vehicle.home_location:
        print(" Waiting for home location ...")
# We have a home location, so print it!        
print("\n Home location: %s" % vehicle.home_location)


# Set vehicle home_location, mode, and armed attributes (the only settable attributes)

print("\nSet new home location")
# Home location must be within 50km of EKF home location (or setting will fail silently)
# In this case, just set value to current location with an easily recognisable altitude (222)
my_location_alt = vehicle.location.global_frame
my_location_alt.alt = 222.0
vehicle.home_location = my_location_alt
print(" New Home Location (from attribute - altitude should be 222): %s" % vehicle.home_location)

#Confirm current value on vehicle by re-downloading commands
cmds = vehicle.commands
cmds.download()
cmds.wait_ready()
print(" New Home Location (from vehicle - altitude should be 222): %s" % vehicle.home_location)


print("\nSet Vehicle.mode = GUIDED (currently: %s)" % vehicle.mode.name) 
vehicle.mode = VehicleMode("GUIDED")
while not vehicle.mode.name=='GUIDED':  #Wait until mode has changed
    print(" Waiting for mode change ...")
    time.sleep(1)


# Check that vehicle is armable
while not vehicle.is_armable:
    print(" Waiting for vehicle to initialise...")
    time.sleep(1)
    # If required, you can provide additional information about initialisation
    # using `vehicle.gps_0.fix_type` and `vehicle.mode.name`.
    
#print "\nSet Vehicle.armed=True (currently: %s)" % vehicle.armed 
#vehicle.armed = True
#while not vehicle.armed:
#    print " Waiting for arming..."
#    time.sleep(1)
#print " Vehicle is armed: %s" % vehicle.armed 


# Add and remove and attribute callbacks

#Define callback for `vehicle.attitude` observer
last_attitude_cache = None
def attitude_callback(self, attr_name, value):
    # `attr_name` - the observed attribute (used if callback is used for multiple attributes)
    # `self` - the associated vehicle object (used if a callback is different for multiple vehicles)
    # `value` is the updated attribute value.
    global last_attitude_cache
    # Only publish when value changes
    if value!=last_attitude_cache:
        print(" CALLBACK: Attitude changed to", value)
        last_attitude_cache=value

print("\nAdd `attitude` attribute callback/observer on `vehicle`")     
vehicle.add_attribute_listener('attitude', attitude_callback)

print(" Wait 2s so callback invoked before observer removed")
time.sleep(2)

print(" Remove Vehicle.attitude observer")    
# Remove observer added with `add_attribute_listener()` specifying the attribute and callback function
vehicle.remove_attribute_listener('attitude', attitude_callback)


        
# Add mode attribute callback using decorator (callbacks added this way cannot be removed).
print("\nAdd `mode` attribute callback/observer using decorator") 
@vehicle.on_attribute('mode')   
def decorated_mode_callback(self, attr_name, value):
    # `attr_name` is the observed attribute (used if callback is used for multiple attributes)
    # `attr_name` - the observed attribute (used if callback is used for multiple attributes)
    # `value` is the updated attribute value.
    print(" CALLBACK: Mode changed to", value)

print(" Set mode=STABILIZE (currently: %s) and wait for callback" % vehicle.mode.name) 
vehicle.mode = VehicleMode("STABILIZE")

print(" Wait 2s so callback invoked before moving to next example")
time.sleep(2)

print("\n Attempt to remove observer added with `on_attribute` decorator (should fail)") 
try:
    vehicle.remove_attribute_listener('mode', decorated_mode_callback)
except:
    print(" Exception: Cannot remove observer added using decorator")



 
# Demonstrate getting callback on any attribute change
def wildcard_callback(self, attr_name, value):
    print(" CALLBACK: (%s): %s" % (attr_name,value))

print("\nAdd attribute callback detecting ANY attribute change")     
vehicle.add_attribute_listener('*', wildcard_callback)


print(" Wait 1s so callback invoked before observer removed")
time.sleep(1)

print(" Remove Vehicle attribute observer")    
# Remove observer added with `add_attribute_listener()`
vehicle.remove_attribute_listener('*', wildcard_callback)
    


# Get/Set Vehicle Parameters
print("\nRead and write parameters")
print(" Read vehicle param 'THR_MIN': %s" % vehicle.parameters['THR_MIN'])

print(" Write vehicle param 'THR_MIN' : 10")
vehicle.parameters['THR_MIN']=10
print(" Read new value of param 'THR_MIN': %s" % vehicle.parameters['THR_MIN'])


print("\nPrint all parameters (iterate `vehicle.parameters`):")
for key, value in vehicle.parameters.iteritems():
    print(" Key:%s Value:%s" % (key,value))
    

print("\nCreate parameter observer using decorator")
# Parameter string is case-insensitive
# Value is cached (listeners are only updated on change)
# Observer added using decorator can't be removed.
 
@vehicle.parameters.on_attribute('THR_MIN')  
def decorated_thr_min_callback(self, attr_name, value):
    print(" PARAMETER CALLBACK: %s changed to: %s" % (attr_name, value))


print("Write vehicle param 'THR_MIN' : 20 (and wait for callback)")
vehicle.parameters['THR_MIN']=20
for x in range(1,5):
    #Callbacks may not be updated for a few seconds
    if vehicle.parameters['THR_MIN']==20:
        break
    time.sleep(1)


#Callback function for "any" parameter
print("\nCreate (removable) observer for any parameter using wildcard string")
def any_parameter_callback(self, attr_name, value):
    print(" ANY PARAMETER CALLBACK: %s changed to: %s" % (attr_name, value))

#Add observer for the vehicle's any/all parameters parameter (defined using wildcard string ``'*'``)
vehicle.parameters.add_attribute_listener('*', any_parameter_callback)     
print(" Change THR_MID and THR_MIN parameters (and wait for callback)")    
vehicle.parameters['THR_MID']=400  
vehicle.parameters['THR_MIN']=30


## Reset variables to sensible values.
print("\nReset vehicle attributes/parameters and exit")
vehicle.mode = VehicleMode("STABILIZE")
#vehicle.armed = False
vehicle.parameters['THR_MIN']=130
vehicle.parameters['THR_MID']=500


#Close vehicle object before exiting script
print("\nClose vehicle object")
vehicle.close()

# Shut down simulator if it was started.
if sitl is not None:
    sitl.stop()

print("Completed")

Running the example¶

The example can be run as described in Running the Examples (which in turn assumes that the vehicle and DroneKit have been set up as described in Installing DroneKit).

In summary, after cloning the repository:

1. Navigate to the example folder as shown:

   cd dronekit-python/examples/simple_goto/
   

2. You can run the example against a simulator (DroneKit-SITL) by specifying the Python script without any arguments. The example will download SITL binaries if needed, start the simulator, and then connect to it:

   python simple_goto.py
   

   On the command prompt you should see (something like):

   Starting copter simulator (SITL)
   SITL already Downloaded.
   Connecting to vehicle on: tcp:127.0.0.1:5760
   >>> APM:Copter V3.3 (d6053245)
   >>> Frame: QUAD
   >>> Calibrating barometer
   >>> Initialising APM...
   >>> barometer calibration complete
   >>> GROUND START
   Basic pre-arm checks
    Waiting for vehicle to initialise...
    ...
    Waiting for vehicle to initialise...
   Arming motors
    Waiting for arming...
    ...
    Waiting for arming...
   >>> ARMING MOTORS
   >>> GROUND START
    Waiting for arming...
   >>> Initialising APM...
   Taking off!
    Altitude:  0.0
    ...
    Altitude:  7.4
    Altitude:  9.0
    Altitude:  9.65
   Reached target altitude
   Set default/target airspeed to 3
   Going towards first point for 30 seconds ...
   Going towards second point for 30 seconds (groundspeed set to 10 m/s) ...
   Returning to Launch
   Close vehicle object
   

   Tip

   It is more interesting to watch the example run on a map than the console. The topic Connecting an additional Ground Station explains how to set up Mission Planner to view a vehicle running on the simulator (SITL).

3. You can run the example against a specific connection (simulated or otherwise) by passing the connection string for your vehicle in the --connect parameter.

   For example, to connect to SITL running on UDP port 14550 on your local computer:

   python simple_goto.py --connect 127.0.0.1:14550
   

How does it work?¶

The code has three distinct sections: arming and takeoff, flight to two locations, and return-to-home.

# set the default travel speed
vehicle.airspeed=3

point1 = LocationGlobalRelative(-35.361354, 149.165218, 20)
vehicle.simple_goto(point1)

# sleep so we can see the change in map
time.sleep(30)

vehicle.simple_goto(point2, groundspeed=10)

vehicle.mode    = VehicleMode("RTL")

Source code¶

The full source code at documentation build-time is listed below (current version on Github):

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
© Copyright 2015-2016, 3D Robotics.
simple_goto.py: GUIDED mode "simple goto" example (Copter Only)

Demonstrates how to arm and takeoff in Copter and how to navigate to points using Vehicle.simple_goto.

Full documentation is provided at http://python.dronekit.io/examples/simple_goto.html
"""

from __future__ import print_function
import time
from dronekit import connect, VehicleMode, LocationGlobalRelative


# Set up option parsing to get connection string
import argparse
parser = argparse.ArgumentParser(description='Commands vehicle using vehicle.simple_goto.')
parser.add_argument('--connect',
                    help="Vehicle connection target string. If not specified, SITL automatically started and used.")
args = parser.parse_args()

connection_string = args.connect
sitl = None


# Start SITL if no connection string specified
if not connection_string:
    import dronekit_sitl
    sitl = dronekit_sitl.start_default()
    connection_string = sitl.connection_string()


# Connect to the Vehicle
print('Connecting to vehicle on: %s' % connection_string)
vehicle = connect(connection_string, wait_ready=True)


def arm_and_takeoff(aTargetAltitude):
    """
    Arms vehicle and fly to aTargetAltitude.
    """

    print("Basic pre-arm checks")
    # Don't try to arm until autopilot is ready
    while not vehicle.is_armable:
        print(" Waiting for vehicle to initialise...")
        time.sleep(1)

    print("Arming motors")
    # Copter should arm in GUIDED mode
    vehicle.mode = VehicleMode("GUIDED")
    vehicle.armed = True

    # Confirm vehicle armed before attempting to take off
    while not vehicle.armed:
        print(" Waiting for arming...")
        time.sleep(1)

    print("Taking off!")
    vehicle.simple_takeoff(aTargetAltitude)  # Take off to target altitude

    # Wait until the vehicle reaches a safe height before processing the goto
    #  (otherwise the command after Vehicle.simple_takeoff will execute
    #   immediately).
    while True:
        print(" Altitude: ", vehicle.location.global_relative_frame.alt)
        # Break and return from function just below target altitude.
        if vehicle.location.global_relative_frame.alt >= aTargetAltitude * 0.95:
            print("Reached target altitude")
            break
        time.sleep(1)


arm_and_takeoff(10)

print("Set default/target airspeed to 3")
vehicle.airspeed = 3

print("Going towards first point for 30 seconds ...")
point1 = LocationGlobalRelative(-35.361354, 149.165218, 20)
vehicle.simple_goto(point1)

# sleep so we can see the change in map
time.sleep(30)

print("Going towards second point for 30 seconds (groundspeed set to 10 m/s) ...")
point2 = LocationGlobalRelative(-35.363244, 149.168801, 20)
vehicle.simple_goto(point2, groundspeed=10)

# sleep so we can see the change in map
time.sleep(30)

print("Returning to Launch")
vehicle.mode = VehicleMode("RTL")

# Close vehicle object before exiting script
print("Close vehicle object")
vehicle.close()

# Shut down simulator if it was started.
if sitl:
    sitl.stop()