Vehicle State and Settings¶

Getting attributes¶

The code fragment below shows how to read and print almost all the attributes (values are regularly updated from MAVLink messages sent by the vehicle).

# 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

Setting attributes¶

The Vehicle.mode, Vehicle.armed , Vehicle.airspeed and Vehicle.groundspeed, attributes can all be “directly” written (Vehicle.home_location can also be directly written, but has special considerations that are discussed below).

These attributes are set by assigning a value:

#disarm the vehicle
vehicle.armed = False

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

Commands to change a value are not guaranteed to succeed (or even to be received) and code should be written with this in mind. For example, the code snippet below polls the attribute values to confirm they have changed before proceeding.

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)

Vehicle.gimbal can’t be written directly, but the gimbal can be controlled using the Vehicle.gimbal.rotate() and Vehicle.gimbal.target_location() methods. The first method lets you set the precise orientation of the gimbal while the second makes the gimbal track a specific “region of interest”.

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

Observing attribute changes¶

You can observe any of the vehicle attributes and monitor for changes without the need for polling.

Listeners (“observer callback functions”) are invoked differently based on the type of observed attribute. Attributes that represent sensor values or other “streams of information” are updated whenever a message is received from the vehicle. Attributes which reflect vehicle “state” are only updated when their values change (for example Vehicle.system_status, Vehicle.armed, and Vehicle.mode).

Callbacks are added using Vehicle.add_attribute_listener() or the Vehicle.on_attribute() decorator method. The main difference between these methods is that only attribute callbacks added with Vehicle.add_attribute_listener() can be removed (see remove_attribute_listener()).

The observer callback function is invoked with the following arguments:

• self - the associated Vehicle. This may be compared to a global vehicle handle to implement vehicle-specific callback handling (if needed).
• attr_name - the attribute name. This can be used to infer which attribute has triggered if the same callback is used for watching several attributes.
• value - the attribute value (so you don’t need to re-query the vehicle object).

The code snippet below shows how to add (and remove) a callback function to observe changes in Vehicle.location.global_frame using Vehicle.add_attribute_listener(). The two second sleep() is required because otherwise the observer might be removed before the the callback is first run.

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

The example below shows how you can declare an attribute callback using the Vehicle.on_attribute() decorator function.

 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

The examples above show how you can monitor a single attribute. You can pass the special name (‘*’) to specify a callback that will be called for any/all attribute changes:

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

Home location¶

The Home location is set when a vehicle first gets a good location fix from the GPS. The location is used as the target when the vehicle does a “return to launch”. In Copter missions (and often Plane) missions, the altitude of waypoints is set relative to this position.

Vehicle.home_location has the following behaviour:

• In order to get the current value (in a LocationGlobal object) you must first download Vehicle.commands, as shown:

  cmds = vehicle.commands
  cmds.download()
  cmds.wait_ready()
  print " Home Location: %s" % vehicle.home_location
  

  The returned value is None before you download the commands or if the home_location has not yet been set by the autopilot. For this reason our example code checks that the value exists (in a loop) before writing it.

  # 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.
  print "\n Home location: %s" % vehicle.home_location
  

• The attribute can be set to a LocationGlobal object (the code fragment below sets it to the current location):

  vehicle.home_location=vehicle.location.global_frame
  

  There are some caveats:

  • You must be able to read a non-None value before you can write it (the autopilot has to set the value initially before it can be written or read).
  • The new location must be within 50 km of the EKF origin or setting the value will silently fail.
  • The value is cached in the home_location. If the variable can potentially change on the vehicle you will need to re-download the Vehicle.commands in order to confirm the value.

• The attribute is not observable.

Getting parameters¶

The parameters are read using the parameter name as a key (case-insensitive). Reads will always succeed unless you attempt to access an unsupported parameter (which will result in a KeyError exception).

The code snippet below shows how to get the Minimum Throttle (THR_MIN) setting. On Copter and Rover (not Plane), this is the minimum PWM setting for the throttle at which the motors will keep spinning.

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

Setting parameters¶

Vehicle parameters are set as shown in the code fragment below, using the parameter name as a “key”:

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

Listing all parameters¶

Vehicle.parameters can be iterated to list all parameters and their values:

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

Observing parameter changes¶

You can observe any of the vehicle parameters and monitor for changes without the need for polling. The parameters are cached, so that callback functions are only invoked when parameter values change.

The code snippet below shows how to add a callback function to observe changes in the “THR_MIN” parameter using a decorator. Note that the parameter name is case-insensitive, and that callbacks added using a decorator cannot 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)

The observer callback function is invoked with the following arguments:

• self - the associated Parameters.
• attr_name - the parameter name (useful if the same callback is used for watching several parameters).
• msg - the parameter value (so you don’t need to re-query the Vehicle.parameters object).

The code snippet below demonstrates how you can add and remove a listener (in this case for “any parameter”) using the Parameters.add_attribute_listener() and Parameters.remove_attribute_listener().

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