Example: Vehicle State

This example shows how to get/set vehicle attribute and parameter information, how to observe vehicle attribute changes, and how to get the home position.

The guide topic Vehicle State and Settings provides a more detailed explanation of how the API should be used.

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
    

Note

DroneKit-SITL does not automatically add a virtual gimbal and rangefinder, so these attributes will always report None.

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 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")