Copter: Mission Command List gets Do-Winch

common/source/docs/common-daiwa-winch.rst

@@ -38,6 +38,7 @@ Connect the winch to the autopilot as shown below
 
 - Connect the 3-pin Winch Control wire (red cable tie) to AUX OUT 1 (aka Servo9)
 - Connect the 3-pin Winch Clutch wire (yellow cable tie) to AUX OUT 2 (aka Servo10)
+- Connect the 3-pin Winch Zero Reset wire (blue cable tie) to AUX OUT 3 (aka Servo11)
 - Connect the 3-pin Winch Telemetry wire (blue cable tie) to the Autopilot's Telem2 (or any other telemetry port)
 - The Zero Reset (green cable tie) used to calibrate the winch should be left disconnected
 - A 7.2V to 22.2V power supply is required to power the motors
@@ -54,17 +55,53 @@ Set the following parameters
 - :ref:`SERVO10_MIN <SERVO10_MIN>` = 1000
 - :ref:`SERVO10_TRIM <SERVO10_TRIM>` = 1500
 - :ref:`SERVO10_MAX <SERVO10_MAX>` = 2000
+- :ref:`SERVO11_FUNCTION <SERVO11_FUNCTION>` = 0 (Disabled)
+- :ref:`SERVO11_MIN <SERVO11_MIN>` = 1000
+- :ref:`SERVO11_TRIM <SERVO11_TRIM>` = 1500
+- :ref:`SERVO11_MAX <SERVO11_MAX>` = 2000
 - :ref:`SERIAL2_PROTOCOL <SERIAL2_PROTOCOL>` = 31 (Winch).  Note this assumes the Winch's telemetry is connected to SERIAL2 which is usually TELEM2 on most boards. Note that this does not necessarily correspond to UART2 on some boards.
 - :ref:`SERIAL2_BAUD <SERIAL2_BAUD>` = 38 (38400 baud) or 115 (115200 baud), depending on version of winch.
 - :ref:`RC6_OPTION <RC6_OPTION>` = 45 (Winch Control) to allow controlling the winch speed from the transmitter's channel 6 knob
 - :ref:`RC6_DZ <RC6_DZ>` = 30.  This deadzone is used to detect whether the pilot has moved the winch control knob to retake control from autonomous operation
 - :ref:`RC6_TRIM <RC6_TRIM>` = The mid value between :ref:`RC6_MIN <RC6_MIN>` and :ref:`RC6_MAX <RC6_MAX>` which is normally close to 1500
 - :ref:`RC8_OPTION <RC8_OPTION>` = 44 (Winch Enable) to allow relaxing the winch by pulling the transmitter's channel 8 switch low
 
-Controlling during Missions
----------------------------
+Winch Telemetry
+---------------
 
-The Winch can be controlled during Autonomous missions using the DO_WINCH mission command.
+The status of the winch can be viewed in real-time using Mission Planner or QGC's MAVLink Inspector window.  If using Mission Planner push the "MAVLink Inspector" button found under Setup, Advanced.
+
+.. image:: ../../../images/daiwa-winch-telemetry.png
+    :target: ../_images/daiwa-winch-telemetry.png
+    :width: 400px
+
+The winch's current draw, length of line, current speed (in m/s) temperature and voltage can all be seen.
+
+Zero Reset Line Length
+----------------------
+
+The winch constantly estimates how much line has been deployed and will stop retracting line once this estimated line length has reached zero in order to protect the line from being broken.  This estimate is prone to drift however meaning that you may find it impossible to completely retract the line or (less likely) it may retract too far and break the line.  To avoid these issues the line length estimate should be periodically reset to zero using the following procedure:
+
+- Power on the autopilot and winch
+- Connect with Mission Planner, open the Setup, Advanced screen and push the "MAVLink Inspector" button and check the current line length.
+- Retract the line (perhaps using the RC6 tuning knob) to within 20cm or so of the ideal minimum length
+- Open Mission Planner's Data, Servo/Relay tab, find the row for output 11
+- Push the "High" button to simultaneously retract the line and reset the line length to zero
+- Push the "Low" button to retracting the line
+
+.. image:: ../../../images/daiwa-winch-MP-zero-reset.png
+    :target: ../_images/daiwa-winch-MP-zero-reset.png
+    :width: 400px
+
+Control during Missions
+-----------------------
+
+The Winch can be controlled during Autonomous missions using the DO_WINCH mission command.  See the bottom of the :ref:`Copter Mission Command List <copter:mission-command-list>` for more details
+
+Winch-test Lua Script
+---------------------
+
+In cases where the vehicle will be well outside of RC range and no joystick is being used, the `winch-test lua script <https://raw.githubusercontent.com/ArduPilot/ardupilot/master/libraries/AP_Scripting/examples/winch-test.lua>`__ may be useful in order to allow manually raise or lower the line using Mission Planner's Aux Function page.
 
 Video
 -----

common/source/docs/common-mavlink-mission-command-messages-mav_cmd.rst

@@ -203,6 +203,7 @@ This list of commands was inferred from the command handler in
 - :ref:`MAV_CMD_DO_GUIDED_LIMITS <mav_cmd_do_guided_limits>` (NAV_GUIDED only)
 - :ref:`MAV_CMD_DO_SET_RESUME_REPEAT_DIST <mav_cmd_do_set_resume_repeat_dist>`
 - :ref:`MAV_CMD_DO_FENCE_ENABLE <mav_cmd_do_fence_enable>`
+- :ref:`MAV_CMD_DO_WINCH<mav_cmd_do_winch>`
 - :ref:`MAV_CMD_STORAGE_FORMAT <mav_cmd_storage_format>`
 [/site]
 
@@ -4645,4 +4646,64 @@ Format SD Card. Useful for vehicles where SD card is inaccessible. Param1 and Pa
    </tbody>
    </table>
 
+[site wiki="copter" heading="off"]
+.. _mav_cmd_do_winch:
+
+MAV_CMD_DO_WINCH
+----------------
+
+Supported by: Copter.
+
+Control Winch operation.
+
+**Command parameters**
+
+.. raw:: html
+
+   <table border="1" class="docutils">
+   <tbody>
+   <tr>
+   <th>Command Field</th>
+   <th>Mission Planner Field</th>
+   <th>Description</th>
+   </tr>
+   <tr>
+   <td><strong>param1</strong></td>
+   <td>Winch no</td>
+   <td>Not currently used</td>
+   </tr>
+   <tr>
+   <td><strong>param2</strong></td>
+   <td>action</td>
+   <td>0 to relax the winch, 1 for Length control, 2 for Rate control</td>
+   </tr>
+   <tr>
+   <td><strong>param3</strong></td>
+   <td>length</td>
+   <td>should be filled in with the meters of line to release.  Positive numbers release the line, negative retract the line.  Note "action" should be "1"</td>
+   </tr>
+   <tr>
+   <td><strong>param4</strong></td>
+   <td>rate</td>
+   <td>should be filled in with the speed (in m/s) to release the line.  Positive numbers release the line, negative retract the line.  Note "action" should be "2".</td>
+   </tr>
+   <tr style="color: #c0c0c0">
+   <td>param5</td>
+   <td></td>
+   <td>Empty</td>
+   </tr>
+   <tr style="color: #c0c0c0">
+   <td>param6</td>
+   <td></td>
+   <td>Empty</td>
+   </tr>
+   <tr style="color: #c0c0c0">
+   <td>param7</td>
+   <td></td>
+   <td>Empty</td>
+   </tr>
+   </tbody>
+   </table>
+[/site]
+
 [copywiki destination="copter,plane,rover,planner,dev"]

copter/source/docs/mission-command-list.rst

@@ -486,3 +486,16 @@ Do-Gripper
 
 This command allows opening and closing a :ref:`servo gripper <common-gripper-servo>` or :ref:`EPM gripper <common-cameras-and-gimbals>`.
 Set the "drop/grab" column to 0 to close the gripper, 1 to open the gripper.  The first column, "Gripper No" is ignored because we currently only support a single gripper per vehicle.
+
+Do-Winch
+~~~~~~~~
+
+.. image:: ../../../images/MissionList_DoWinch.png
+    :target: ../_images/MissionList_DoWinch.png
+
+This command allows controlling a :ref:`winch <common-daiwa-winch>` to raise or lower a package.
+
+- "winch no" is not used
+- "action" should be 0 to relax the winch, 1 for Length control, 2 for Rate control
+- "length" should be filled in with the meters of line to release.  Positive numbers release the line, negative retract the line.  Note "action" should be "1".
+- "rate" should be filled in with the speed (in m/s) to release the line.  Positive numbers release the line, negative retract the line.  Note "action" should be "2".