Add takeoff/landing doc - also covers other action APIs #42

hamishwillee · 2017-10-18T01:09:46Z

This adds documentation for the Action API.

It is named "Takeoff and Landing" as those are the main APIs, and I don't think that "Action" will necessarily be recognised by readers.
It refers to both sync and async APIs but only shows sync examples. IMO that makes sense as a) sync usage is much easier to understand b) will most often be used.
I don't show examples in every case, because the APIs are consistent. So I say something like "Used in the normal way"

hamishwillee · 2017-10-18T01:10:45Z

en/guide/taking_off_landing.md

+The code fragment below performs the same task, but additionally exits the app if calibration is required reports what conditions are still required before the vehicle is "healthy":
+
+```cpp
+// Exit if calibration is required


I haven't tested this part of the code because I can't get SITL to fail the calibration.

hamishwillee · 2017-10-18T01:12:06Z

en/guide/taking_off_landing.md

+}
+```
+
+The code fragment below performs the same task, but additionally exits the app if calibration is required reports what conditions are still required before the vehicle is "healthy":


@julianoes IMO This approach is much better than the default because it exits early in the case where vehicle cannot recover (requires calibration). Should we use this in examples? Pro is "more real world", con is "not as easy to read when getting started".

It's a bit verbose but certainly makes sense.

Yes it is. I'd welcome your proposal for a more concise approach, but this will do for now.

hamishwillee · 2017-10-18T01:13:32Z

en/guide/taking_off_landing.md

+}
+```
+
+> **Note** Vehicle health can also be checked using [Telemetry:health_all_ok_async()](../api_reference/classdronecore_1_1_telemetry.md#classdronecore_1_1_telemetry_1a83b384cd04b2ed17db805cfad8bafab5). 


Note again, not showing async usage, just pointing to API.

hamishwillee · 2017-10-18T01:14:45Z

en/guide/taking_off_landing.md

+}
+```
+
+Use [Telemetry::armed()](../api_reference/classdronecore_1_1_telemetry.md#classdronecore_1_1_telemetry_1a0ca7da7922c22509ce6d55d4ad19bcf7) to check that the vehicle has armed before calling the takeoff command.


Originally I just had a timer here. Then I tried using FlightMode::Ready - but during startup my SITL showed FlightMode::Hold, so decided just checking armed is more robust.

@julianoes - use this in example code?

This should not be necessary. If you do arm() and the command is accepted, it should always be armed.

@julianoes OK, I will remove armed-state checking code.

Should we update example code to include the calibration checks? I'd argue yes, because it is best practice. What about also adding the more verbose status info - should that also be added to example code.

Yes, that would be nice.

hamishwillee · 2017-10-18T01:15:47Z

en/guide/taking_off_landing.md

+
+> **Note** One alternative is to simply wait for enough time that the vehicle *should* have reached the takeoff altitude.
+
+The code below checks for takeoff completion by polling the current altitude until the target altitude is reached:


@julianoes When PX4 moves to HOLD after takeoff we can revisit this.

Yes, exactly.

hamishwillee · 2017-10-18T01:16:30Z

en/guide/taking_off_landing.md

+
+## Return/RTL
+
+[Return mode](https://docs.px4.io/en/flight_modes/rtl.html) (also known as "Return to Launch", "Return to Land", "Return to Home") flies the vehicle back to the home position and may also land the vehicle (depending on vehicle configuration). This mode is invoked from DroneCore using the [return_to_launch()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1a9af73101ce850e37cf7259dcdeda2eb9) or [return_to_launch_async()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1aa1253c356c7628d329dfa98d78eb39ee) methods. 


There is a big discussion on return modes going on now. For this purpose lets just ignore that :-)

Is there? ok

Yes. There are a couple more possible modes and variations on modes in the works - rally points (return to a safe point) and follow original path back to safety.

julianoes

This is good, thanks.

julianoes · 2017-10-18T12:45:40Z

en/guide/taking_off_landing.md

+}
+```
+
+The code fragment below performs the same task, but additionally exits the app if calibration is required reports what conditions are still required before the vehicle is "healthy":


It's a bit verbose but certainly makes sense.

julianoes · 2017-10-18T12:46:27Z

en/guide/taking_off_landing.md

+        std::cout << ERROR_CONSOLE_TEXT << "  - Local position estimate." << NORMAL_CONSOLE_TEXT << std::endl;
+    }
+    if (!current_health.home_position_ok) {
+        std::cout << ERROR_CONSOLE_TEXT << "  - Home position to be set." << NORMAL_CONSOLE_TEXT << std::endl;


This is nice.

julianoes · 2017-10-18T12:48:51Z

en/guide/taking_off_landing.md

+}
+```
+
+Use [Telemetry::armed()](../api_reference/classdronecore_1_1_telemetry.md#classdronecore_1_1_telemetry_1a0ca7da7922c22509ce6d55d4ad19bcf7) to check that the vehicle has armed before calling the takeoff command.


This should not be necessary. If you do arm() and the command is accepted, it should always be armed.

julianoes · 2017-10-18T12:49:29Z

en/guide/taking_off_landing.md

+
+> **Note** One alternative is to simply wait for enough time that the vehicle *should* have reached the takeoff altitude.
+
+The code below checks for takeoff completion by polling the current altitude until the target altitude is reached:


Yes, exactly.

julianoes · 2017-10-18T12:50:15Z

en/guide/taking_off_landing.md

+
+## Return/RTL
+
+[Return mode](https://docs.px4.io/en/flight_modes/rtl.html) (also known as "Return to Launch", "Return to Land", "Return to Home") flies the vehicle back to the home position and may also land the vehicle (depending on vehicle configuration). This mode is invoked from DroneCore using the [return_to_launch()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1a9af73101ce850e37cf7259dcdeda2eb9) or [return_to_launch_async()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1aa1253c356c7628d329dfa98d78eb39ee) methods. 


Is there? ok

julianoes · 2017-10-18T12:51:02Z

en/guide/taking_off_landing.md

+* Integration tests:
+  * [simple_hover.cpp](https://github.com/dronecore/DroneCore/blob/master/integration_tests/simple_hover.cpp)
+  * [async_hover.cpp](https://github.com/dronecore/DroneCore/blob/master/integration_tests/async_hover.cpp)
+  * [takeoff_and_kill.cpp](https://github.com/dronecore/DroneCore/blob/master/integration_tests/takeoff_and_kill.cpp)


hamishwillee added 2 commits October 18, 2017 12:05

Add takeoff/landing doc - also covers other action APIs

557fc68

Add takeoff/landing doc - also covers other action APIs

70cae7a

hamishwillee requested a review from julianoes October 18, 2017 01:09

hamishwillee commented Oct 18, 2017

View reviewed changes

hamishwillee mentioned this pull request Oct 18, 2017

Offboard example mavlink/MAVSDK#116

Merged

julianoes approved these changes Oct 18, 2017

View reviewed changes

hamishwillee added 2 commits October 19, 2017 10:12

Replace code to check armed status with a note

ecbf34b

Fix up merge conflicts

98681a1

hamishwillee merged commit 3401447 into mavlink:master Oct 18, 2017

hamishwillee deleted the takeoff_landing branch October 18, 2017 23:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add takeoff/landing doc - also covers other action APIs #42

Add takeoff/landing doc - also covers other action APIs #42

hamishwillee commented Oct 18, 2017

hamishwillee Oct 18, 2017

hamishwillee Oct 18, 2017 •

edited

julianoes Oct 18, 2017

hamishwillee Oct 18, 2017

hamishwillee Oct 18, 2017

hamishwillee Oct 18, 2017

julianoes Oct 18, 2017

hamishwillee Oct 18, 2017 •

edited

julianoes Oct 19, 2017

hamishwillee Oct 18, 2017

julianoes Oct 18, 2017

hamishwillee Oct 18, 2017

julianoes Oct 18, 2017

hamishwillee Oct 18, 2017

julianoes left a comment

julianoes Oct 18, 2017

julianoes Oct 18, 2017

julianoes Oct 18, 2017

julianoes Oct 18, 2017

julianoes Oct 18, 2017

julianoes Oct 18, 2017


		> Note One alternative is to simply wait for enough time that the vehicle should have reached the takeoff altitude.

		The code below checks for takeoff completion by polling the current altitude until the target altitude is reached:


		## Return/RTL

		[Return mode](https://docs.px4.io/en/flight_modes/rtl.html) (also known as "Return to Launch", "Return to Land", "Return to Home") flies the vehicle back to the home position and may also land the vehicle (depending on vehicle configuration). This mode is invoked from DroneCore using the [return_to_launch()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1a9af73101ce850e37cf7259dcdeda2eb9) or [return_to_launch_async()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1aa1253c356c7628d329dfa98d78eb39ee) methods.

Add takeoff/landing doc - also covers other action APIs #42

Add takeoff/landing doc - also covers other action APIs #42

Conversation

hamishwillee commented Oct 18, 2017

Choose a reason for hiding this comment

hamishwillee Oct 18, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee Oct 18, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julianoes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee Oct 18, 2017 •

edited

hamishwillee Oct 18, 2017 •

edited