Merge branch 'master' into patch-3

common/source/docs/common-caddx-gimbal.rst

@@ -0,0 +1,71 @@
+.. _common-caddx-gimbal:
+
+[copywiki destination="plane,copter,rover"]
+
+=============
+CADDX Gimbals
+=============
+
+`CADDX <https://caddxfpv.com/products/caddxfpv-gm1-gm2-gm3.html>`__ GM1, GM2, GM3 gimbals are small 1, 2 and 3-axis gimbals weighing between 16g and 46g and can be paired with 19mm x 19mm FPV cameras
+
+.. image:: ../../../images/caddxfpv-gimbal.png
+    :target: https://caddxfpv.com/products/caddxfpv-gm1-gm2-gm3.html
+
+.. warning::
+
+    Support for these gimbals is available in ArduPilot 4.7 (and higher) and requires the gimbal's firmware be 3.4 (or higher)
+
+The `user manual can be found here <https://cdn.shopify.com/s/files/1/0036/3921/4169/files/GM_Series_Manual_V1.0_1.pdf>`__
+
+Where and What to Buy
+---------------------
+
+- The GM1, GM2 and GM3 gimbals can be purchased directly from `CADDXFPV <https://caddxfpv.com/products/caddxfpv-gm1-gm2-gm3.html>`__
+- The `GL and GM Upgrade Cable <https://caddxfpv.com/products/gl-and-gm-upgrade-cable>`__ is likely also required to upgrade the gimbal's firmware to 3.4 (or higher)
+
+Connecting to the Autopilot
+---------------------------
+
+.. image:: ../../../images/caddxfpv-gm3-autopilot.png
+    :target: ../_images/caddxfpv-gm3-autopilot.png
+    :width: 450px
+
+Connect the gimbal's RX, TX and GND pins to one of the autopilot's serial ports as shown above
+
+Connect with a ground station and set the following parameters.  The params below assume the autopilot's telem2 port is used
+
+- :ref:`SERIAL2_PROTOCOL <SERIAL2_PROTOCOL>` to 8 ("Gimbal")
+- :ref:`SERIAL2_BAUD <SERIAL2_BAUD>` to "115" for 115200 bps
+- :ref:`MNT1_TYPE <MNT1_TYPE>` to "13" ("CADDX") and reboot the autopilot
+- :ref:`MNT1_PITCH_MIN <MNT1_PITCH_MIN>` to -90
+- :ref:`MNT1_PITCH_MAX <MNT1_PITCH_MAX>` to 90
+- :ref:`MNT1_YAW_MIN <MNT1_YAW_MIN>` to -170
+- :ref:`MNT1_YAW_MAX <MNT1_YAW_MAX>` to 170
+- :ref:`MNT1_RC_RATE <MNT1_RC_RATE>` to 60 (deg/s) to control speed of gimbal when using RC targetting
+- :ref:`RC6_OPTION <RC6_OPTION>` = 213 ("Mount Pitch") to control the gimbal's pitch angle with RC channel 6
+- :ref:`RC7_OPTION <RC7_OPTION>` = 214 ("Mount Yaw") to control the gimbal's yaw angle with RC channel 7
+- :ref:`RC8_OPTION <RC8_OPTION>` = 163 ("Mount Lock") to switch between "lock" and "follow" mode with RC channel 8
+
+Configuring the Gimbal
+----------------------
+
+Firmware upgrade instructions are in the "Upgrade" section of the `user manual <https://cdn.shopify.com/s/files/1/0036/3921/4169/files/GM_Series_Manual_V1.0_1.pdf>`__ but in short:
+
+- Download the GimbalConfig windows application and latest gimbal firmware from the `CADDXFPV Download Center <https://caddxfpv.com/pages/download-center>`__ (look for the "Firmware / GM Gimbal Firmware" link near the bottom of the page)
+- Extract the contents of the downloaded zip file and run the GimbalConfig application
+- Connect the `Upgrade Cable <https://caddxfpv.com/products/gl-and-gm-upgrade-cable>`__ to the upgrade port shown below, connect the other end to your PC
+
+.. image:: ../../../images/caddx-firmware-update.png
+    :target: ../_images/caddx-firmware-update.png
+    :width: 450px
+
+- Open the GimbalConfig application, select the COM port, then "Open" and find the "CwGimbalZGV2Main_V3.4.cahf" file and push "Upgrade"
+
+.. image:: ../../../images/caddx-firmware-update-PC.png
+    :target: ../_images/caddx-firmware-update-PC.png
+    :width: 450px
+
+Control and Testing
+-------------------
+
+See :ref:`Gimbal / Mount Controls <common-mount-targeting>` for details on how to control the camera and gimbal using RC, GCS or Auto mode mission commands

common/source/docs/common-master-features.rst

@@ -6,31 +6,36 @@ Items in Master Branch Only
 
 This lists features or changes merged in master and build in the "latest" firmware, but not in a stable or beta release yet. They have passed all test suites and usually have already been flight tested. These items are considered in the broad flight testing stage and test users are encouraged. Eventually, they will released in a beta, then stable release.
 
-.. note:: Currently firmware is in the 4.6 beta or stable stage. Items listed are in "latest" but not 4.6 beta and stable releases.
+.. note:: Currently firmware is in the 4.6 beta or stable stage. Items listed are in "latest" (4.7dev) but not 4.6 beta or stable releases.
 
 
 [site wiki="plane,copter,rover"]
+New Peripherals
+===============
+.. toctree::
+    :maxdepth: 1
 
-
+    CADDXFPV GM1, GM2, GM3 gimbals <common-caddx-gimbal>
+[/site]
+[site wiki="plane"]
+New Features
+============
 .. toctree::
     :maxdepth: 1
 
-
-    Other wiki changes <common-future-wiki-changes>
+    AUTOLAND Mode <mode_autoland>
 [/site]
 [site wiki="rover"]
 
 .. toctree::
     :maxdepth: 1
 
-
-
 [/site]
 
 [site wiki="blimp"]
 .. toctree::
     :maxdepth: 1
 
-    Other wiki changes <common-future-wiki-changes>
 [/site]
+    Other wiki changes <common-future-wiki-changes>
 [copywiki destination="plane,copter,rover,blimp"]

dev/source/docs/companion-computers.rst

@@ -32,6 +32,7 @@ popular Companion Computer hardware are listed below.
     Holybro Pixhawk Rasberry Pi CM4/CM5 Baseboard <https://holybro.com/products/pixhawk-rpi-cm4-baseboard>
     Holybro Pixhawk Jetson Baseboard <https://holybro.com/products/pixhawk-jetson-baseboard>
     Raspberry Pi <raspberry-pi-via-mavlink>
+    VoidRay <https://idrobots.com/product/void-ray>
 
 The Companion Computer software refers to the programs and tools that run on the Companion
 Computer. They will take in MAVLink telemetry from the Flight Controller and can route and 
@@ -48,6 +49,7 @@ tools/suites are listed below.
     Maverick <https://goodrobots.github.io/maverick/#/>
     ROS <ros>
     Rpanion-server <https://www.docs.rpanion.com/software/rpanion-server>
+    Skyhub <https://idrobots.com/>
 
 A number of vendors also offer turnkey systems. See the below link for details.
 

dev/source/docs/plane-commands-in-guided-mode.rst

@@ -10,6 +10,7 @@ This article lists the MAVLink commands that affect the movement of a Plane or Q
 
    The code which processes these commands can be found `here in GCS_Mavlink.cpp <https://github.com/ArduPilot/ardupilot/blob/master/ArduPlane/GCS_Mavlink.cpp>`__
 
+.. _movement_commands:
 Movement commands
 =================
 
@@ -55,3 +56,21 @@ These MAV_CMDs can be processed if packaged within a `COMMAND_INT <https://mavli
 - `MAV_CMD_GUIDED_CHANGE_SPEED <https://mavlink.io/en/messages/common.html#MAV_CMD_DO_CHANGE_SPEED>`__
 - `MAV_CMD_GUIDED_CHANGE_ALTITUDE <https://mavlink.io/en/messages/common.html#MAV_CMD_DO_CHANGE_ALTITUDE>`__
 - `MAV_CMD_GUIDED_CHANGE_HEADING <https://mavlink.io/en/messages/common.html#MAV_CMD_GUIDED_CHANGE_HEADING>`__
+
+Position Targets
+================
+
+To command the altitude in any supported frame, use `SET_POSITION_TARGET_GLOBAL_INT <https://mavlink.io/en/messages/common.html#SET_POSITION_TARGET_GLOBAL_INT>`__.
+Ensure to set the `POSITION_TARGET_TYPEMASK <https://mavlink.io/en/messages/common.html#POSITION_TARGET_TYPEMASK>`__ bit 3.
+
+To command the altitude in LOCAL frame, use `SET_POSITION_TARGET_LOCAL_NED <https://mavlink.io/en/messages/common.html#SET_POSITION_TARGET_LOCAL_NED>`__.
+It is currently not necessary to bother with `POSITION_TARGET_TYPEMASK <https://mavlink.io/en/messages/common.html#POSITION_TARGET_TYPEMASK>`__.
+The `MAV_FRAME <https://mavlink.io/en/messages/common.html#MAV_FRAME>`__ must be ``MAV_FRAME_LOCAL_OFFSET_NED``.
+
+No other fields in position target messages are currently supported. Use :ref:`movement_commands` to send a lat lon alt target.
+
+Attitude Targets
+================
+
+The low level attitude of the vehicle can be controlled with `SET_ATTITUDE_TARGET <https://mavlink.io/en/messages/common.html#SET_ATTITUDE_TARGET>`__.
+

plane/source/docs/mode_autoland.rst

@@ -0,0 +1,31 @@
+.. _mode_autoland:
+
+=============
+AUTOLAND Mode
+=============
+
+AUTOLAND mode provides a fully automatic fixed wing landing which can also be used as an RC failsafe action.
+
+In Mode Takeoff or during a NAV_TAKEOFF in AUTO, the takeoff direction will be captured from the GPS ground course once a GPS ground speed of 5m/s is obtained. This usually occurs early in the takeoff run of a rolling takeoff or almost immediately during a hand or bungee launch.
+
+It will setup a parameterized base leg and final approach waypoint/altitude, based on the takeoff direction, and proceed to it and switch to an automatic landing at home. It can also be selected as a :ref:`FS_LONG_ACTN<FS_LONG_ACTN>` for RC failsafes.
+
+This is useful when programming a mission with a ``DO_LAND_START`` landing sequence is not convenient since it requires a GCS on a laptop or phone, such as traveling with impromptu stops to fly FPV or photograph. Simply use Mode TAKEOFF or a simple loaded before travel with a ``NAV_TAKEOFF`` waypoint. It is also useful for fields which have varying wind directions, which would prevent using a single home-loaded autolanding mission or require using the MissionSelector LUA script to slect from several missions with different approaches.
+
+Operation
+=========
+To use simply make an automatic takeoff and at any point later switch into AUTOLAND. A final approach waypoint will be created behind the HOME landing target at :ref:`AUTOLAND_WP_DIST<AUTOLAND_WP_DIST>` (400m by default) at :ref:`AUTOLAND_WP_ALT<AUTOLAND_WP_ALT>`  (55m by default)using the takeoff direction plus :ref:`AUTOLAND_DIR_OFF<AUTOLAND_DIR_OFF>` ("0" default) and land using all the parametrics of a normal autolanding. A base leg to the final approach waypoint is also created at the same altitude and 1/3 :ref:`AUTOLAND_WP_DIST<AUTOLAND_WP_DIST>` from the final approach waypoint as shown below:
+
+.. image:: ../../../images/autoland_mode.png
+    :target: ../_images/autoland_mode.png
+
+``LAND`` parameter defaults are usually acceptable for most planes in the 1-2m wingspan, <2kg class) and should yeild a safe, if not optimally tuned, autolanding. ``LAND`` parameters can be optimized with test flights (See :ref:`automatic-landing`).
+
+Notes:
+======
+
+- Switching out of AUTOLAND to another mode aborts the landing and returns control to that new mode.
+- Throttle aborts of the final landing sequence are not supported. (:ref:`LAND_ABORT_THR<LAND_ABORT_THR>`)
+- If the plane has taken off not using either Mode Takeoff or NAV_LAND, the mode cannot be entered since the takeoff direction has not been captured. If it is selected as a long failsafe action ("5"), :ref:`FS_LONG_ACTN<FS_LONG_ACTN>`, it will switch to normal RTL instead of AUTOLAND on failsafe, in this case.
+- The mode co-exists with any mission autolanding sequence, which can be used in AUTO mode, or with :ref:`RTL_AUTOLAND<RTL_AUTOLAND>`.
+- QuadPlanes cannot use this mode unless :ref:`Q_OPTIONS<Q_OPTIONS>` bit 2 (ALLOW_FW_LAND) is set and a Mode Takeoff or AUTO NAV_TAKEOFF has been used.

plane/source/docs/quadplane_rtl.rst

@@ -98,9 +98,12 @@ The phases of the approach are:
 
 - in a fixed wing mode when further than 2 times the greater of either :ref:`RTL_RADIUS<RTL_RADIUS>` or :ref:`WP_LOITER_RADS<WP_LOITER_RAD>` (MAXRAD) **plus** a calculated distance needed to descend from :ref:`RTL_ALTITUDE<RTL_ALTITUDE>` to :ref:`Q_RTL_ALT<Q_RTL_ALT>`, the plane will attempt to climb or descend to :ref:`RTL_ALTITUDE<RTL_ALTITUDE>`. If within that range, it will attempt to climb/descend to a linear descent slope, meet it, and continue to descend, as shown above.
 - if started further than 2X "MAXRAD" but closer than above, at 2x MAXRAD it will continue in fixed wing mode at :ref:`Q_RTL_ALT<Q_RTL_ALT>`.
-- when it reaches a point that is within the VTOL stopping distance of the landing point (at the VTOL deceleration parameter limits and current speed), it will transition to VTOL mode and send a message that it is in "VTOL Position1" and continue moving to the land point. If the vehicle is NOT a tailsitter, an "AIRBRAKING" phase may occur before the VTOL transition, spinning up the VTOL motors to create additional braking.
-- once the QuadPlane is within 5m of the land point and moving less than 2 m/s, it will send a GCS message declaring that it is in "VTOL Position2, and final position itself over the land point and begin its landing descent, which will also be indicated by GCS messages
-- if the approach is entered less than 1.5X MAXRAD, it will immediately move to VTOL Position1 state, whether entered from fixed wing or vtol modes, and move toward the landing site attempting to obtain :ref:`Q_RTL_ALT<Q_RTL_ALT>` as it does so.
+- when it reaches a point that is within the VTOL stopping distance of the landing point (calculated using the VTOL deceleration parameter :ref:`Q_TRANS_DECEL<Q_TRANS_DECEL>` which gives the deceleration that will occur as the vehicle transitions to VTOL and the vehicle's current speed), it will transition to VTOL mode and send a message that it is in "VTOL Position1" and continue moving to the land point. If the vehicle is NOT a tailsitter, an "AIRBRAKING" phase may occur before the VTOL transition, spinning up the VTOL motors to create additional braking.
+
+.. note:: if the vehicle is overshooting "VTOL Position1", try decreasing  :ref:`Q_TRANS_DECEL<Q_TRANS_DECEL>` in steps. However, this increases the point before "VTOL Position1" that the vehicle will transition to VTOL.
+
+- once the QuadPlane is within 5m of the land point and moving less than 2 m/s, it will send a GCS message declaring that it is in "VTOL Position 2", and final position itself over the land point and begin its landing descent, which will also be indicated by GCS messages
+- if the approach is entered less than 1.5X MAXRAD, it will immediately move to "VTOL Position 1" state, whether entered from fixed wing or VTOL modes, and move toward the landing site attempting to obtain :ref:`Q_RTL_ALT<Q_RTL_ALT>` as it does so.
 - if in VTOL mode at greater than 1.5X MAXRAD, the  vehicle will climb to :ref:`Q_RTL_ALT<Q_RTL_ALT>`, if below, then transition to fixed wing and start a normal fixed wing RTL, and attempt to navigate to home, executing the approach. The climb and turn toward the landing point will occur at even low altitudes as determined by :ref:`Q_RTL_ALT<Q_RTL_ALT>`, so the :ref:`FLIGHT_OPTIONS<FLIGHT_OPTIONS>` bit 4 for "Climb before turn in RTL" and/or :ref:`Q_OPTIONS<Q_OPTIONS>` bit 0 for "Level Transitions" might be worth considering for the fixed wing initial phases.
 
 .. note:: In cases where it is feared that using the approach feature may result in it being initiated too close to HOME due to the 1.5X MAXRAD distance being too close in VTOL modes, instead of using :ref:`Q_OPTIONS<Q_OPTIONS>` bit 16 to disable the feature entirely, the :ref:`Q_APPROACH_DIST<Q_APPROACH_DIST>` to increase the distance from HOME that the vehicle needs to be to transition to fixed wing and execute an approach,