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