Skip to content

Commit 55ea1bd

Browse files
tcr3drtcr3dr
committed
Merge pull request #272 from dronekit/hamishwillee-tmp_auto_mode_missions
Add Mission documentation, passing tests.
2 parents 8f0cb8f + 7c37927 commit 55ea1bd

File tree

7 files changed

+1062
-0
lines changed

7 files changed

+1062
-0
lines changed

‎docs/examples/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ during missions and outside missions using custom commands.
1616
Vehicle State <vehicle_state>
1717
Simple Goto <simple_goto>
1818
Guided Movement and Commands <guided-set-speed-yaw-demo>
19+
Basic Mission <mission_basic>
20+
Mission Import/Export <mission_import_export>
1921
Follow Me (Linux only)<follow_me>
2022
Drone Delivery <drone_delivery>
2123
Flight Replay <flight_replay>

‎docs/examples/mission_basic.rst‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
.. _example_mission_basic:
2+
3+
======================
4+
Example: Basic Mission
5+
======================
6+
7+
This example demonstrates the basic mission operations provided by DroneKit-Python, including:
8+
downloading missions from the vehicle, clearing missions, creating mission commands
9+
and uploading them to the vehicle, monitoring the current active command, and changing the active
10+
command.
11+
12+
The guide topic :ref:`auto_mode_vehicle_control` provides more detailed explanation of how the API
13+
should be used.
14+
15+
16+
Running the example
17+
===================
18+
19+
The vehicle and DroneKit should be set up as described in :ref:`get-started`.
20+
21+
If you're using a simulated vehicle remember to :ref:`disable arming checks <disable-arming-checks>` so
22+
that the example can run.
23+
24+
Once MAVProxy is running and the API is loaded, you can start the example by typing: ``api start mission_basic.py``.
25+
26+
.. note::
27+
28+
The command above assumes you started the *MAVProxy* prompt in a directory containing the example script. If not,
29+
you will have to specify the full path to the script (something like):
30+
``api start /home/user/git/dronekit-python/examples/mission_basic/mission_basic.py``.
31+
32+
33+
On the *MAVProxy* console you should see (something like):
34+
35+
.. code:: bash
36+
37+
MAV> api start mission_basic.py
38+
STABILIZE> Clear the current mission
39+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
40+
Requesting 0 waypoints t=Wed Jul 29 21:27:58 2015 now=Wed Jul 29 21:27:58 2015
41+
Create a new mission
42+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
43+
Sent waypoint 0 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 0, frame : 0, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.3632621765, y : 149.165237427, z : 584.0}
44+
Sent waypoint 1 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 1, frame : 3, command : 22, current : 0, autocontinue : 0, param1 : 0, param2 : 0, param3 : 0, param4 : 0, x : 0, y : 0, z : 10}
45+
Sent waypoint 2 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 2, frame : 3, command : 16, current : 0, autocontinue : 0, param1 : 0, param2 : 0, param3 : 0, param4 : 0, x : -35.3628118424, y : 149.164679124, z : 11}
46+
Sent waypoint 3 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 3, frame : 3, command : 16, current : 0, autocontinue : 0, param1 : 0, param2 : 0, param3 : 0, param4 : 0, x : -35.3628118424, y : 149.165780676, z : 12}
47+
Sent waypoint 4 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 4, frame : 3, command : 16, current : 0, autocontinue : 0, param1 : 0, param2 : 0, param3 : 0, param4 : 0, x : -35.3637101576, y : 149.165780676, z : 13}
48+
Sent waypoint 5 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 5, frame : 3, command : 16, current : 0, autocontinue : 0, param1 : 0, param2 : 0, param3 : 0, param4 : 0, x : -35.3637101576, y : 149.164679124, z : 14}
49+
Sent all 6 waypoints
50+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
51+
APM: flight plan received
52+
Basic pre-arm checks
53+
Arming motors
54+
Waiting for arming...
55+
Got MAVLink msg: COMMAND_ACK {command : 11, result : 0}
56+
Waiting for arming...
57+
APM: ARMING MOTORS
58+
APM: GROUND START
59+
Waiting for arming...
60+
GUIDED> Mode GUIDED
61+
APM: Initialising APM...
62+
Got MAVLink msg: COMMAND_ACK {command : 400, result : 0}
63+
Waiting for arming...
64+
ARMED
65+
Taking off!
66+
Altitude: 0.0
67+
Got MAVLink msg: COMMAND_ACK {command : 22, result : 0}
68+
GPS lock at 0 meters
69+
Altitude: 0.10000000149
70+
...
71+
Altitude: 8.84000015259
72+
Altitude: 9.60999965668
73+
Reached target altitude
74+
Starting mission
75+
Got MAVLink msg: COMMAND_ACK {command : 11, result : 0}
76+
waypoint 1
77+
waypoint 2
78+
AUTO> Mode AUTO
79+
Distance to waypoint (2): 79.3138466142
80+
Distance to waypoint (2): 79.1869592549
81+
Distance to waypoint (2): 77.8436803794
82+
...
83+
Distance to waypoint (2): 20.7677087176
84+
Distance to waypoint (2): 15.4592692026
85+
APM: Reached Command #2
86+
waypoint 3
87+
Distance to waypoint (3): 115.328425048
88+
Skipping to Waypoint 4 when reach waypoint 3
89+
waypoint 4
90+
Distance to waypoint (4): 152.376018911
91+
Distance to waypoint (4): 154.882233097
92+
...
93+
Distance to waypoint (4): 20.4052797291
94+
Distance to waypoint (4): 15.0592597507
95+
APM: Reached Command #4
96+
waypoint 5
97+
Distance to waypoint (5): 114.450267446
98+
Exit 'standard' mission when start heading to final waypoint (5)
99+
Return to launch
100+
APIThread-0 exiting...
101+
102+
103+
104+
How does it work?
105+
=================
106+
107+
The :ref:`source code <example_mission_basic_source_code>` is relatively self-documenting, and most of its main
108+
operations are explained in the guide topic :ref:`auto_mode_vehicle_control` .
109+
110+
In overview, the example first calls ``clear_mission()`` to clear the current mission and then creates and
111+
uploads a new mission using ``adds_square_mission(vehicle.location,50)``. This function defines a mission with a takeoff
112+
command and four waypoints arranged in a square around the central position.
113+
114+
After taking off (in guided mode using the ``takeoff()`` function) the example starts the mission by setting the mode to AUTO:
115+
116+
.. code:: python
117+
118+
print "Starting mission"
119+
# Set mode to AUTO to start mission
120+
vehicle.mode = VehicleMode("AUTO")
121+
vehicle.flush()
122+
123+
The progress of the mission is monitored in a loop. The convenience function
124+
:ref:`distance_to_current_waypoint() <auto_mode_mission_distance_to_waypoint>`
125+
gets the distance to the next waypoint and
126+
:py:func:`Vehicle.commands.next <droneapi.lib.CommandSequence.next>` gets the value of
127+
the next command.
128+
129+
We also show how to move to a specified command using
130+
:py:func:`Vehicle.commands.next <droneapi.lib.CommandSequence.next>` (note how we skip the third command below):
131+
132+
.. code:: python
133+
134+
while True:
135+
nextwaypoint =vehicle.commands.next
136+
if nextwaypoint > 1:
137+
print 'Distance to waypoint (%s): %s' % (nextwaypoint, distance_to_current_waypoint())
138+
if nextwaypoint ==3: #Skip to next waypoint
139+
print 'Skipping to Waypoint 4 when reach waypoint 3'
140+
vehicle.commands.next=4
141+
if nextwaypoint ==5: #Skip to next waypoint
142+
print "Exit 'standard' mission when start heading to final waypoint (5)"
143+
break;
144+
time.sleep(1)
145+
146+
When the vehicle starts the 5th command the loop breaks and the mode is set to RTL (return to launch).
147+
148+
149+
.. _example_mission_basic_known_issues:
150+
151+
Known issues
152+
============
153+
154+
This example works around the :ref:`known issues in the API <auto_mode_mission_known_issues>`.
155+
Provided that the vehicle is connected and able to arm, it should run through to completion.
156+
157+
158+
159+
.. _example_mission_basic_source_code:
160+
161+
Source code
162+
===========
163+
164+
The full source code at documentation build-time is listed below (`current version on github <https://github.com/dronekit/dronekit-python/blob/master/examples/mission_basic/mission_basic.py>`_):
165+
166+
.. literalinclude:: ../../examples/mission_basic/mission_basic.py
167+
:language: python
168+

‎docs/examples/mission_import_export.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _example_mission_import_export:
2+
3+
==============================
4+
Example: Mission Import/Export
5+
==============================
6+
7+
This example shows how to import and export files in the
8+
`Waypoint file format <http://qgroundcontrol.org/mavlink/waypoint_protocol#waypoint_file_format>`_.
9+
10+
The commands are first imported from a file into a list and then uploaded to the vehicle.
11+
Then the current mission is downloaded from the vehicle and put into a list, and finally
12+
saved into (another file).
13+
14+
The example does not show how missions can be modified, but once the mission is in a list,
15+
changing the order and content of commands is straightforward.
16+
17+
The guide topic :ref:`auto_mode_vehicle_control` provides information about
18+
missions and AUTO mode.
19+
20+
21+
Running the example
22+
===================
23+
24+
The vehicle and DroneKit should be set up as described in :ref:`get-started`.
25+
26+
Once MAVProxy is running and the API is loaded, you can start the example by typing: ``api start mission_import_export.py``.
27+
28+
.. note::
29+
30+
The command above assumes you started the *MAVProxy* prompt in a directory containing the example script. If not,
31+
you will have to specify the absolute path to the script. For example:
32+
``api start /home/user/git/dronekit-python/examples/mission_import_export/mission_import_export.py``.
33+
34+
35+
On the *MAVProxy* console you should see (something like):
36+
37+
.. code:: bash
38+
39+
STABILIZE> api start mission_import_export.py
40+
STABILIZE>
41+
Upload mission from a file: mpmission.txt
42+
Reading mission from file: mpmission.txt
43+
44+
STABILIZE> Import line: 0 1 0 16 0 0 0 0 -35.360500 149.172363 747.000000 1
45+
46+
Import line: 1 0 3 22 0.000000 0.000000 0.000000 0.000000 -35.359831 149.166334 100.000000 1
47+
48+
49+
Import line: 2 0 3 16 0.000000 0.000000 0.000000 0.000000 -35.363489 149.167213 100.000000 1
50+
51+
Import line: 3 0 3 16 0.000000 0.000000 0.000000 0.000000 -35.355491 149.169595 100.000000 1
52+
53+
Import line: 4 0 3 16 0.000000 0.000000 0.000000 0.000000 -35.355071 149.175839 100.000000 1
54+
55+
Import line: 5 0 3 113 0.000000 0.000000 0.000000 0.000000 -35.362666 149.178715 22222.000000 1
56+
Import line: 6 0 3 115 2.000000 22.000000 1.000000 3.000000 0.000000 0.000000 0.000000 1
57+
58+
Import line: 7 0 3 16 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 1
59+
60+
Clear mission
61+
Requesting 9 waypoints t=Wed Jul 29 20:12:17 2015 now=Wed Jul 29 20:12:17 2015
62+
ClearCount: 0
63+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
64+
Requesting 0 waypoints t=Wed Jul 29 20:12:17 2015 now=Wed Jul 29 20:12:17 2015
65+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
66+
Sent waypoint 0 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 0, frame : 0, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.3632621765, y : 149.165237427, z : 584.0}
67+
Sent waypoint 1 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 1, frame : 0, command : 16, current : 1, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.3605, y : 149.172363, z : 747.0}
68+
Sent waypoint 2 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 2, frame : 3, command : 22, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.359831, y : 149.166334, z : 100.0}
69+
Sent waypoint 3 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 3, frame : 3, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.363489, y : 149.167213, z : 100.0}
70+
Sent waypoint 4 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 4, frame : 3, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.355491, y : 149.169595, z : 100.0}
71+
Sent waypoint 5 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 5, frame : 3, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.355071, y : 149.175839, z : 100.0}
72+
Sent waypoint 6 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 6, frame : 3, command : 113, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : -35.362666, y : 149.178715, z : 22222.0}
73+
Sent waypoint 7 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 7, frame : 3, command : 115, current : 0, autocontinue : 1, param1 : 2.0, param2 : 22.0, param3 : 1.0, param4 : 3.0, x : 0.0, y : 0.0, z : 0.0}
74+
Sent waypoint 8 : MISSION_ITEM {target_system : 1, target_component : 0, seq : 8, frame : 3, command : 16, current : 0, autocontinue : 1, param1 : 0.0, param2 : 0.0, param3 : 0.0, param4 : 0.0, x : 0.0,y : 0.0, z : 0.0}
75+
Sent all 9 waypoints
76+
Got MAVLink msg: MISSION_ACK {target_system : 255, target_component : 0, type : 0}
77+
APM: flight plan received
78+
79+
Save mission from Vehicle to file: exportedmission.txt
80+
Requesting 9 waypoints t=Wed Jul 29 20:12:18 2015 now=Wed Jul 29 20:12:18 2015
81+
APIThread-1 exiting...
82+
83+
84+
85+
How does it work?
86+
=================
87+
88+
The :ref:`source code <example_mission_import_export_source_code>` is largely self-documenting.
89+
90+
More information about the functions can be found in the guide at
91+
:ref:`auto_mode_load_mission_file` and :ref:`auto_mode_save_mission_file`.
92+
93+
94+
95+
Known issues
96+
============
97+
98+
This example works around known issues in the API:
99+
100+
* A ``time.sleep(1)`` has been placed between uploading the mission to the vehicle (from the file) and downloading the mission.
101+
This is to avoid the race condition where the mission being downloaded has not yet successfully uploaded to the vehicle.
102+
This race condition (probably) shouldn't exist because the mission is flushed to the Vehicle -
103+
see `Race condition when updating and fetching commands <https://github.com/dronekit/dronekit-python/issues/227>`_
104+
105+
106+
107+
.. _example_mission_import_export_source_code:
108+
109+
Source code
110+
===========
111+
112+
The full source code at documentation build-time is listed below (`current version on github <https://github.com/dronekit/dronekit-python/blob/master/examples/mission_import_export/mission_import_export.py>`_):
113+
114+
.. literalinclude:: ../../examples/mission_import_export/mission_import_export.py
115+
:language: python
116+

0 commit comments

Comments
 (0)