Motion #

Introduction #

The VEX AIR Drone features four propellors, allowing it to move in any direction and rotate independently. Motion provides methods for movement, turning, speed adjustments, and position tracking.

Circular compass dial from 0-360 degrees surrounding a drone with 4 propellers. The front of the drone faces 0 degrees on the compass dial.

Below is a list of all available methods:

Actions

take_off – Lifts the drone to a specified height.
land – Lands the drone.
hover - Keeps the drone at its position.
climb – Moves the drone in a specified vertical direction.
climb_for – Moves the drone in a specified vertical direction for a specific distance.
climb_to – Moves the drone to a specific altitude.
move_at – Moves the drone at a specified heading and velocity.
move_for – Moves the drone at a specific heading for a specified distance.
turn – Turns the drone left or right.
turn_for – Turns the drone a set number of degrees.
turn_to – Turns the drone to face a specific heading.
move_with_vectors – Moves the drone using vector-based x, y, z, and rotation values.

Mutators

set_steering_mode – Sets the POV for steering the drone.
set_movement_mode – Sets the movement style of the drone.
set_climb_velocity – Sets the default climbing speed.
set_move_velocity – Sets the default movement speed.
set_turn_velocity - Sets the default turning speed.
set_max_altitude - Sets the maximum altitude.
set_xyz_position – Sets the drone’s current position.

Getters

get_altitude – Returns the drone’s altitude.
get_flight_state – Returns the current state of the drone.
get_x_position – Returns the drone’s x-coordinate.
get_y_position – Returns the drone’s y-coordinate.
get_z_position – Returns the drone’s z-coordinate.
get_safe_mode – Returns the drone’s propellor lock state.
is_climb_active – Returns whether the drone is currently climbing.
is_move_active – Returns whether the drone is currently moving.
is_turn_active – Returns whether the drone is currently turning.
is_hovering - Returns whether the drone is currently hovering.
is_taking_off – Returns whether the drone is currently taking off.
is_landing – Returns whether the drone is currently landing.
is_landed - Returns whether the drone is currently landed.

Actions #

take_off #

take_off starts the propellers and lifts the drone into the air. This method must be used before other movements can be made.

Usage:

drone.take_off(climb_to, units, wait)

Parameters	Description
`climb_to`	The altitude the drone will fly to.
`units`	The unit to use: `CM` - Centimeters `MM` - Millimeters `INCHES`
`wait`	Optional. `wait=True` (default) – The drone waits until `take_off` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `take_off` to finish.

Parameters

Description

climb_to

The altitude the drone will fly to.

units

The unit to use:

CM - Centimeters
MM - Millimeters
INCHES

wait

Optional.

wait=True (default) – The drone waits until take_off is complete before executing the next line of code.
wait=False – The drone starts the action and moves on to the next line of code right away, without waiting for take_off to finish.

# Fly for 1 second
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.land()

land #

land lowers the drone to the ground. The propellers will continue to run until the project is stopped.

Usage:

drone.land(wait)

Parameters	Description
`wait`	Optional. `wait=True` (default) – The drone waits until `land` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `land` to finish.

Parameters

Description

wait

Optional.

wait=True (default) – The drone waits until land is complete before executing the next line of code.
wait=False – The drone starts the action and moves on to the next line of code right away, without waiting for land to finish.

# Land after 1 second
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.land()

hover #

hover stops the drone from moving in any direction and holds its current position in the air.

Usage:
drone.hover()

Parameters	Description
	This method has no parameters.

# Hold current position for 3 seconds after moving forward
drone.take_off(climb_to=500)
drone.move_at(direction=0, velocity=50)
wait(1, SECONDS)
drone.hover()
wait(3, SECONDS)
drone.land()

climb #

climb moves the drone in a specified vertical direction.

Usage: drone.climb(direction, velocity)

Parameters

Description

direction

The direction in which the drone will fly:

UP
DOWN

velocity

The velocity at which the drone will climb as a float or integer.

# Climb upwards for 2 seconds
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.climb(UP, 50)
wait(2, SECONDS)
drone.land()

climb_for #

climb_for moves the drone in a specified vertical direction for a specific distance.

Usage:

drone.climb_for(direction, distance, units, velocity, wait)

Parameters	Description
`direction`	The direction in which the drone will fly: `UP` `DOWN`
`distance`	The distance the drone will fly for.
`units`	Optional. The unit that represents the distance: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`
`velocity`	Optional. The velocity at which the drone will climb as a float or integer. If the velocity is not specified, the default velocity is 50%.
`wait`	Optional. `wait=True` (default) – The drone waits until `climb_for` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `climb_for` to finish.

# Lower drone before landing
drone.take_off(climb_to=700)
wait(1, SECONDS)
drone.climb_for(direction=DOWN, distance=300, velocity=50, units=MM)
wait(1, SECONDS)
drone.land()

climb_to #

climb_to moves the drone to a specific altitude.

Usage:

drone.climb_to(z, velocity, units, wait)

Parameters	Description
`z`	The z position, as an integer or decimal, the drone will climb to.
`velocity`	Optional. The velocity at which the drone will climb as a float or integer. If the velocity is not specified, the default velocity is 50%.
`units`	Optional. The unit that represents the distance: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`
`wait`	Optional. `wait=True` (default) – The drone waits until `climb_to` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `climb_to` to finish.

# Reach 500 mm after takeoff
drone.take_off(climb_to=300)
wait(1, SECONDS)
drone.climb_to(z=500, velocity=50, units=MM)
wait(1, SECONDS)
drone.land()

move_at #

move_at moves the drone at a specified angle and velocity.

Usage:

drone.move_at(angle, velocity)

Parameters	Description
`angle`	The angle, as an integer or decimal, at which the drone moves, ranging from 0 to 360 degrees.
`velocity`	The velocity at which the drone will move as a float or integer.

# Move left for 1 second
drone.take_off(climb_to=500)
drone.move_at(angle=270, velocity=50)
wait(1, SECONDS)
drone.land()

move_for #

move_for moves the drone in a specific direction for a specific distance using the current set_move_velocity.

Usage:

drone.move_for(angle, distance, units, velocity, wait)

Parameters	Description
`angle`	The angle, as an integer or float, at which the drone moves, ranging from 0 to 360 degrees.
`distance`	The distance, as an integer or decimal, that the drone will move.
`units`	Optional. The unit that represents the distance: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`
`velocity`	Optional. The velocity at which the drone will move as a float or integer. If the velocity is not specified, the default velocity is 50%.
`wait`	Optional. `wait=True` (default) – The drone waits until `move_for` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `move_for` to finish.

# Move forward for 200 mm
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.move_for(direction=0, distance=200, velocity=50, units=MM)
wait(1, SECONDS)
drone.land()

move_to #

move_to moves the drone to a specified position in the air while maintaining the same heading and altitude.

Usage:

drone.move_to(x, y, z, units, move_velocity, climb_velocity, wait)

Parameters	Description
`x`	The x coordinate that the drone will move to.
`y`	The y coordinate that the drone will move to.
`z`	The z coordinate that the drone will move to.
`units`	Optional. The unit that represents the distance: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`
`move_velocity`	Optional. The velocity at which the drone will move as a float or integer. If the velocity is not specified, the default velocity is 50%.
`climb_velocity`	Optional. The velocity at which the drone will climb as a float or integer. If the velocity is not specified, the default velocity is 50%.
`wait`	Optional. `wait=True` (default) – The drone waits until `move_to` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `move_to` to finish.

# Move diagonally to (300, 300, 800)
drone.take_off(climb_to=300)
wait(2, SECONDS)
drone.move_to(x=300, y=300, z=800)
wait(2, SECONDS)
drone.land()

turn #

turn turns the drone in a specific direction using the current set_turn_velocity.

Usage:

drone.turn(direction, velocity)

Parameters

Description

direction

The direction the drone will turn:

LEFT
RIGHT

velocity

Optional. The velocity at which the drone will turn as a float or integer. If the velocity is not specified, the default velocity is 50%.

# Turn to the right for 2 seconds
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.turn(RIGHT, 50)
wait(2, SECONDS)
drone.land()

turn_for #

turn_for turns the drone in a specified direction for a set distance relative to its current facing direction using the current set_turn_velocity.

Usage:

drone.turn_for(direction, angle, velocity, wait)

Parameters	Description
`direction`	The direction the drone will turn: `LEFT` `RIGHT`
`angle`	The angle, as an integer or float, at which the drone turns, ranging from 0 to 360 degrees.
`velocity`	The velocity at which the drone will turn as a float or integer. If the velocity is not specified (`velocity` = 0), the default velocity is 50%.
`wait`	Optional. `wait=True` (default) – The drone waits until `turn_for` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `turn_for` to finish.

# Turn around, then land
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.turn_for(RIGHT, 180, 50)
wait(1, SECONDS)
drone.land()

turn_to #

turn_to turns the drone to face a specific heading using the current set_turn_velocity.

Usage:

drone.turn_to(heading, velocity, wait)

Parameters	Description
`heading`	The heading that the drone will turn to face from 0 to 360 degrees.
`velocity`	Optional. The velocity at which the drone will turn as a float or integer. If the velocity is not specified, the default velocity is 50%.
`wait`	Optional. `wait=True` (default) – The drone waits until `turn_to` is complete before executing the next line of code. `wait=False` – The drone starts the action and moves on to the next line of code right away, without waiting for `turn_to` to finish.

Parameters

Description

heading

The heading that the drone will turn to face from 0 to 360 degrees.

velocity

Optional. The velocity at which the drone will turn as a float or integer. If the velocity is not specified, the default velocity is 50%.

wait

Optional.

wait=True (default) – The drone waits until turn_to is complete before executing the next line of code.
wait=False – The drone starts the action and moves on to the next line of code right away, without waiting for turn_to to finish.

# Turn to face each of the cardinal headings
drone.take_off(climb_to=500)
drone.turn_to(heading=90, velocity=50)
wait(3, SECONDS)
drone.turn_to(heading=180, velocity=50)
wait(3, SECONDS)
drone.turn_to(heading=270, velocity=50)
wait(3, SECONDS)
drone.turn_to(heading=0, velocity=50)
wait(3, SECONDS)
drone.land()

move_with_vectors #

move_with_vectors moves the drone using vector-based motion, combining movement on the X-axis, Y-axis, and Z-axis while having the drone rotate at the same time.

Usage:

drone.move_with_vectors(forward, rightward, upward, rotation)

Parameters	Description
`forward`	The drone’s velocity along the Y-axis (forward and backward movement). Accepts a value from -100 to 100 as a percent, where negative values move backward and positive values move forward.
`rightward`	The drone’s velocity along the X-axis (side-to-side movement). Accepts a value from -100 to 100 as a percent, where negative values move left and positive values move right.
`upward`	The drone’s velocity along the Z-axis (up and down movement). Accepts a value from -100 to 100 as a percent, where negative values move down and positive values move up.
`rotation`	The drone’s rotational velocity. Accepts a value from -100 to 100 as a percent, where negative values rotate counterclockwise and positive values rotate clockwise.

# Move with controller
drone.take_off(climb_to=500)
while True:
    drone.move_with_vectors(
        forward=controller.axis4.position(),
        rightward=controller.axis3.position(),
        upward=controller.axis1.position(),
        rotation=controller.axis2.position()
    )
    wait(5, MSEC)

Mutators #

set_steering_mode #

set_steering_mode sets the viewpoint that is used when steering the drone.

Usage:

drone.set_steering_mode(style)

Parameters	Description
`style`	Sets the POV that is used to steer the drone. `HEADLESS` – The drone moves relative to where it was facing at the start of the project. `STANDARD` (default) – The drone moves relative to where it is facing.

Parameters

Description

style

Sets the POV that is used to steer the drone.

HEADLESS – The drone moves relative to where it was facing at the start of the project.
STANDARD (default) – The drone moves relative to where it is facing.

# Steer based on the drone's starting orientation
# until button 7 is pressed
drone.take_off(climb_to=500)
drone.set_steering_mode(HEADLESS)
while not controller.button7.pressing():
    drone.move_with_vectors(
        forward=controller.axis4.position(),
        rightward=controller.axis3.position(),
        upward=controller.axis1.position(),
        rotation=controller.axis2.position()
    )
    wait(5, MSEC)
drone.land()

set_movement_mode #

set_movement_mode sets the drone’s movement style.

This movement style is used when flying the drone with a controller.

Usage:

drone.set_movement_mode(style)

Parameters	Description
`style`	Sets the speed that is used to steer the drone. `BALANCED` – The drone moves at a medium base speed. `PERFORMANCE` – The drone moves at a faster base speed. `PRECISION` (default) – The drone moves at a slower base speed.

Parameters

Description

style

Sets the speed that is used to steer the drone.

BALANCED – The drone moves at a medium base speed.
PERFORMANCE – The drone moves at a faster base speed.
PRECISION (default) – The drone moves at a slower base speed.

# Control the drone with the balanced movement style
drone.take_off(climb_to=500)
drone.set_movement_mode(BALANCED)
while not controller.button5.pressing():
    drone.move_with_vectors(
        forward=controller.axis4.position(),
        rightward=controller.axis3.position(),
        upward=controller.axis1.position(),
        rotation=controller.axis2.position()
    )
    wait(5, MSEC)
drone.land()

set_climb_velocity #

set_climb_velocity sets the default climbing speed as a percentage. This will affect any following methods related to climbing. The default climb velocity is 50%.

Usage:

drone.set_climb_velocity(velocity)

Parameters	Description
`velocity`	The velocity at which the drone will climb as a float or integer.

# Raise the drone quickly before landing
drone.take_off(climb_to=300)
wait(1, SECONDS)
drone.set_climb_velocity(100)
drone.climb_for(direction=UP, distance=500)
wait(1, SECONDS)
drone.land()

set_move_velocity #

set_move_velocity sets the default movement speed as a percentage. This will affect any following methods related to moving. The default move velocity is 50%.

Usage:

drone.set_move_velocity(velocity)

Parameters	Description
`velocity`	The velocity at which the drone will move as a float or integer.

# Move forward quickly, then reverse slowly
drone.take_off(climb_to=500)
drone.set_move_velocity(100)
drone.move_for(direction=0, distance=500)
wait(3, SECONDS)
drone.set_move_velocity(20)
drone.move_for(direction=180, distance=500)
wait(5, SECONDS)
drone.land()

set_turn_velocity #

set_turn_velocity sets the default movement speed as a percentage. This will affect any following methods related to turning. The default turn velocity is 50%.

Usage:

drone.set_turn_velocity(velocity)

Parameters	Description
`velocity`	The velocity at which the drone will turn as a float or integer.

# Turn clockwise quickly, then counterclockwise slowly
drone.take_off(climb_to=500)
drone.set_turn_velocity(100)
drone.turn_for(RIGHT, 360)
wait(3, SECONDS)
drone.set_turn_velocity(20)
drone.turn_for(LEFT, 360)
wait(5, SECONDS)
drone.land()

set_max_altitude #

set_max_altitude creates a limit to how high the drone will fly.

Usage:

drone.set_max_altitude(altitude, units)

Parameters	Description
`altitude`	The maximum altitude, as an integer or decimal, that the drone will not fly above, in a range from 1000 to 5000 mm.
`units`	Optional. The distance units are: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`

Parameters

Description

altitude

The maximum altitude, as an integer or decimal, that the drone will not fly above, in a range from 1000 to 5000 mm.

units

Optional. The distance units are:

CM – Centimeters
MM (default) – Millimeters
INCHES

# Fly with controller under 1000 mm
drone.set_max_altitude(1000, MM)
drone.take_off(climb_to=500)
while not controller.button7.pressing():
    drone.move_with_vectors(
        forward=controller.axis4.position(),
        rightward=controller.axis3.position(),
        upward=controller.axis1.position(),
        rotation=controller.axis2.position()
    )
drone.land()

set_xyz_position #

set_xyz_position sets the drone’s current position to specified coordinate values.

Usage:

drone.set_xyz_position(x, y, z, units)

Parameters	Description
`x`	The x coordinate to set for the drone in `units` as a float or integer.
`y`	The y coordinate to set for the drone in `units` as a float or integer.
`z`	The z coordinate to set for the drone in `units` as a float or integer.
`units`	Optional. The unit that represents the distance: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`

# Set a new (0, 0, 0), then fly to position (0, 0, -300)
drone.take_off(climb_to=800)
drone.set_xyz_position(x=0, y=0, z=0, units=MM)
wait(1, SECONDS)
drone.climb(DOWN, 50)
while not drone.get_z_position() < -300:
    wait(5, MSEC)
drone.hover()
wait(1, SECONDS)
drone.land()

Getters #

get_flight_state #

get_flight_state returns the drone’s current flying state as a DroneFlightStateType:

MOTORS_OFF - No other flight state is true.
CALIBRATION - The drone is calibrating its sensors.
MOTOR_START - The drone is starting its motors.
FLIGHT_READY - The drone is ready to fly.
FLIGHT - The drone is in flight.

Usage:
drone.get_flight_state()

Parameters	Description
	This method has no parameters.

# Report the flight status as the drone takes off
controller.screen.print("Preparing for flight!")
controller.screen.next_row()
drone.take_off(climb_to=800, wait=False)
while not drone.get_flight_state() == MOTOR_START:
    wait(5, MSEC)
controller.screen.print("Motors starting...")
controller.screen.next_row()
while not drone.get_flight_state() == FLIGHT:
    wait(5, MSEC)
controller.screen.print("Take off!")

get_x_position #

get_x_position returns the drone’s x coordinate as a float.

Usage:

drone.get_x_position(units)

Parameters	Description
`units`	Optional. The unit that represents the position: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`

Parameters

Description

units

Optional. The unit that represents the position:

CM – Centimeters
MM (default) – Millimeters
INCHES

# Move to (200, 0, 500)
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.move_at(direction=90, velocity=50)
while not drone.get_x_position() > 200:
    wait(5, MSEC)
drone.hover()
wait(1, SECONDS)
drone.land()

get_y_position #

get_y_position returns the drone’s y coordinate as a float.

Usage:

drone.get_y_position(units)

Parameters	Description
`units`	Optional. The unit that represents the position: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`

Parameters

Description

units

Optional. The unit that represents the position:

CM – Centimeters
MM (default) – Millimeters
INCHES

# Move to (0, 200, 500)
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.move_at(direction=0, velocity=50)
while not drone.get_y_position() > 200:
    wait(5, MSEC)
drone.hover()
wait(1, SECONDS)
drone.land()

get_z_position #

get_y_position returns the drone’s z coordinate as a float.

Usage:

drone.get_z_position(units)

Parameters	Description
`units`	Optional. The unit that represents the position: `CM` – Centimeters `MM` (default) – Millimeters `INCHES`

Parameters

Description

units

Optional. The unit that represents the position:

CM – Centimeters
MM (default) – Millimeters
INCHES

# Move to (0, 0, 800)
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.climb(UP, 50)
while not drone.get_z_position() > 800:
    wait(5, MSEC)
drone.hover()
wait(1, SECONDS)
drone.land()

get_safe_mode #

get_safe_mode returns a Boolean indicating whether the Propeller Lock is enabled on the drone.

True – Propeller Lock is enabled.
False – Propeller Lock is not enabled.

Usage:

drone.get_safe_mode()

Parameters	Description
	This method has no parameters.

# Change the sound by enabling the Propeller Lock
while True:
    if drone.get_safe_mode():
        controller.sound.play(FAULT)
        while controller.sound.is_active():
            wait(50, MSEC)
    else:
        controller.sound.play(SUCCESS)
        while controller.sound.is_active():
            wait(50, MSEC)
    wait(5, MSEC)

is_climb_active #

is_climb_active returns a Boolean indicating whether the drone is climbing.

True – The drone is currently climbing.
False – The drone is not climbing.

Usage:

drone.is_climb_active()

Parameters	Description
	This method has no parameters.

# After the drone starts to climb, play a sound and land
drone.take_off(climb_to=500)
drone.climb(UP, 50)
wait(3, SECONDS)
if drone.is_climb_active():
    controller.sound.play(SUCCESS)
    drone.land()

is_move_active #

is_move_active returns a Boolean indicating whether the drone is currently using a move method.

True – The drone is currently using a move method.
False – The drone is not currently using a move method.

Usage:

drone.is_move_active()

Parameters	Description
	This method has no parameters.

# After the drone starts to move, play a sound and land
drone.take_off(climb_to=500)
drone.move_at(direction=0, velocity=50)
wait(2, SECONDS)
if drone.is_move_active():
    controller.sound.play(SUCCESS)
    drone.land()

is_turn_active #

is_turn_active returns a Boolean indicating whether the drone is turning.

True – The drone is currently turning.
False – The drone is not turning.

Usage:

drone.is_turn_active()

Parameters	Description
	This method has no parameters.

# After the drone starts to turn, play a sound and land
drone.take_off(climb_to=500)
drone.turn(RIGHT)
wait(2, SECONDS)
if drone.is_turn_active():
    controller.sound.play(LOOPING)
    while controller.sound.is_active():
        wait(50, MSEC)
    drone.land()

is_hovering #

is_hovering returns a Boolean indicating whether the drone is maintaining its position (hovering).

True – The drone is currently maintaining its position (hovering).
False – The drone is currently changing its position.

Usage:

drone.is_hovering()

Parameters	Description
	This method has no parameters.

# Example coming soon
drone.take_off(climb_to=700)
while not drone.is_hovering():
    wait(5, MSEC)
controller.sound.play(PAUSE)
wait(2, SECONDS)
drone.land()

is_taking_off #

is_taking_off returns a Boolean indicating whether the drone is in the process of taking off.

True – The drone is currently in the process of taking off.
False – The drone is not in the process of taking off.

Usage:

drone.is_taking_off()

Parameters	Description
	This method has no parameters.

# Play sounds while the drone is taking off
drone.take_off(700, wait=False)
wait(1, SECONDS)
while drone.is_taking_off():
    controller.sound.play(LOOPING)
    wait(5, MSEC)

is_landing #

is_landing returns a Boolean indicating whether the drone is in the process of landing.

True – The drone is currently in the process of landing.
False – The drone is not in the process of landing.

Usage:

drone.is_landing()

Parameters	Description
	This method has no parameters.

# Play sounds while the drone is landing
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.land(wait=False)
wait(1, SECONDS)
while drone.is_landing():
    controller.sound.play(LOOPING)
    wait(5, MSEC)

is_landed #

is_landed returns a Boolean indicating whether the drone is currently landed.

True – The drone is landed.
False – The drone is not landed.

Usage:

drone.is_landed()

Parameters	Description
	This method has no parameters.

# Celebrate a successful landing
drone.take_off(climb_to=500)
wait(1, SECONDS)
drone.land()
wait(1, SECONDS)
if drone.is_landed():
    controller.sound.play(SUCCESS)