From 8b1be069c7dbc2c91bd2c7bc0f40c8ce8d823ca8 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 12 Dec 2024 15:15:41 +1100 Subject: [PATCH 1/5] Add gripper mission command timeout --- en/flying/package_delivery_mission.md | 2 +- en/peripherals/gripper.md | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/en/flying/package_delivery_mission.md b/en/flying/package_delivery_mission.md index 9b233376f2da..3ff6f8787451 100644 --- a/en/flying/package_delivery_mission.md +++ b/en/flying/package_delivery_mission.md @@ -88,7 +88,7 @@ So if you land, release the cargo, then have an RTL waypoint, the vehicle will i A gripper can be [manually controlled using a joystick button](../peripherals/gripper.md#qgc-joystick-configuration) (if configured) in any mode, including during a mission. Note however that if you manually command the gripper to close while a package delivery mission is opening the gripper, the gripper won't be able to finish the open action. -The mission will resume after the payload delivery mission item timeout ([MIS_PD_TO](../advanced_config/parameter_reference.md#MIS_PD_TO) expires, even if it has not released the package. +The mission will resume after the mission command timeout ([MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT)) expires, even if it has not released the package. #### Auto-disarming is Disabled in Missions diff --git a/en/peripherals/gripper.md b/en/peripherals/gripper.md index 1e52122eb19d..66c75d3ec7dc 100644 --- a/en/peripherals/gripper.md +++ b/en/peripherals/gripper.md @@ -75,7 +75,7 @@ To set the actuation timeout: - Run the `payload_deliverer` test in the QGC [MAVLink Shell](../debug/mavlink_shell.md): - ``` + ```sh > payload_deliverer gripper_test ``` @@ -88,20 +88,21 @@ To set the actuation timeout: 1. Set [PD_GRIPPER_TO](../advanced_config/parameter_reference.md#PD_GRIPPER_TO) to whichever of the gripper open and close time is larger. -### Mission Delivery Timeout +### Mission Command Timeout When running a [Payload Delivery Mission](../flying/package_delivery_mission.md) it is important that the mission is not halted in the case where the gripper does not report that it has opened (or closed). -This might happen if a gripper feedback sensor was damaged or UORB dropped the gripper actuator timout message. +This might happen if a gripper does not have a feedback sensor, if the feedback sensor was damaged, or if UORB dropped the gripper actuator timeout message. ::: info Gripper state feedback from a sensor is not actually supported yet, but it may be in future. ::: -The mission-delivery timout provides an additional safeguard, continuing the mission if the gripper's successful actuation acknowledgement is not received. +The mission command timeout provides an additional safeguard, continuing the mission if the gripper's successful actuation acknowledgement is not received. +This timeout is also used to provide a sufficient delay for other commands to complete in the case where sensor feedback is not provided or received, such as for winch deployment/retraction, and gimbal movement to a mission-commanded orientation. To set the timeout: -1. Set [MIS_PD_TO](../advanced_config/parameter_reference.md#MIS_PD_TO) to a value greater than the [gripper actuation timeout](#gripper-actuation-timeout). +1. Set [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) to a value greater than the [gripper actuation timeout](#gripper-actuation-timeout). ## QGC Joystick Configuration From b705eb7f9372b373b27391c83fbd11ebcbd63baf Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 12 Dec 2024 15:44:30 +1100 Subject: [PATCH 2/5] gimbal mission timout settings --- en/advanced/gimbal_control.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/en/advanced/gimbal_control.md b/en/advanced/gimbal_control.md index ce6235e52d38..3ee1cd17e69f 100644 --- a/en/advanced/gimbal_control.md +++ b/en/advanced/gimbal_control.md @@ -76,6 +76,18 @@ For example, you might have the following settings to assign the gimbal roll, pi The PWM values to use for the disarmed, maximum and minimum values can be determined in the same way as other servo, using the [Actuator Test sliders](../config/actuators.md#actuator-testing) to confirm that each slider moves the appropriate axis, and changing the values so that the gimbal is in the appropriate position at the disarmed, low and high position in the slider. The values may also be provided in gimbal documentation. +## Gimbal Control in Missions + +[Gimbal Manager commands](https://mavlink.io/en/services/gimbal_v2.html#gimbal-manager-messages) may be used in missions if supported by the vehicle type. +For example [MAV_CMD_DO_GIMBAL_MANAGER_PITCHYAW](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_GIMBAL_MANAGER_PITCHYAW) is supported in [multicopter mission mode](../flight_modes_mc/mission.md). + +In theory you can address commands to a particular gimbal, specifying its component id using the "Gimbal device id" parameter. +However at time of writing (December 2024) this is [not supported](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/gimbal/input_mavlink.cpp#L889): all commands are sent to the gimbal with id [MAV_COMP_ID_GIMBAL (154)](https://mavlink.io/en/messages/common.html#MAV_COMP_ID_GIMBAL) + +Gimbal movement is not immediate. +To ensure that the gimbal has time to move into position before the mission progresses to the next item (if gimbal feedback is not provided or lost), you should set [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) to be greater than the time taken for the gimbal to traverse its full range. +After this timeout the mission will proceed to the next item. + ## SITL The [Gazebo Classic](../sim_gazebo_classic/index.md) simulation [Typhoon H480 model](../sim_gazebo_classic/vehicles.md#typhoon-h480-hexrotor) comes with a preconfigured simulated gimbal. From e742d5627e8891add3ebcbf6c3fb6eb7cd38eefd Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 12 Dec 2024 16:14:46 +1100 Subject: [PATCH 3/5] Add info about the mission timeout to mission modes --- en/flight_modes_fw/mission.md | 13 ++++++++++++- en/flight_modes_mc/mission.md | 12 +++++++++++- en/flight_modes_vtol/mission.md | 10 ++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/en/flight_modes_fw/mission.md b/en/flight_modes_fw/mission.md index d5fb0f0e7073..10f147d326b3 100644 --- a/en/flight_modes_fw/mission.md +++ b/en/flight_modes_fw/mission.md @@ -177,7 +177,6 @@ Rally Points ::: info Please add an issue report or PR if you find a missing/incorrect message. -::: info: - PX4 parses the above messages, but they are not necessary _acted_ on. For example, some messages are vehicle-type specific. - PX4 does not support local frames for mission commands (e.g. [MAV_FRAME_LOCAL_NED](https://mavlink.io/en/messages/common.html#MAV_FRAME_LOCAL_NED)). @@ -186,6 +185,18 @@ Please add an issue report or PR if you find a missing/incorrect message. You can check the current set by inspecting the code. Support is `MavlinkMissionManager::parse_mavlink_mission_item` in [/src/modules/mavlink/mavlink_mission.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_mission.cpp). +::: + +## Mission Command Timeouts + +Some mission commands/items can take time to complete, such as a gripper opening and closing, a winch extending or retracting, or a gimbal moving to point at a region of interest. + +Where provided PX4 may use sensor feedback from the hardware to determine when the action has completed and then move to the next mission item. +If not provided, or if the feedback is lost, a mission command timeout can be used to ensure that these kinds of actions will progress to the next mission item rather than blocking progression. + +The timeout is set using the [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) parameter. +This should be set to be a small amount greater than the time required for the longest long-running action in the mission to complete. + ## Rounded turns: Inter-Waypoint Trajectory PX4 expects to follow a straight line from the previous waypoint to the current target (it does not plan any other kind of path between waypoints - if you need one you can simulate this by adding additional waypoints). diff --git a/en/flight_modes_mc/mission.md b/en/flight_modes_mc/mission.md index 9b663d51699b..0b5b9bced4c7 100644 --- a/en/flight_modes_mc/mission.md +++ b/en/flight_modes_mc/mission.md @@ -19,7 +19,7 @@ The mission is typically created and uploaded with a Ground Control Station (GCS ## Description Missions are usually created in a ground control station (e.g. [QGroundControl](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/plan_view/plan_view.html)) and uploaded prior to launch. -They may also be created by a developer API, and/or uploaded in flight. +They may also be created by a MAVLink API such as [MAVSDK](../robotics/mavsdk.md), and/or uploaded in flight. Individual [mission commands](#mission-commands) are handled in a way that is appropriate to multicopter flight characteristics (for example loiter is implemented as _hover_ ). @@ -191,6 +191,16 @@ Please add an issue report or PR if you find a missing/incorrect message. ::: +## Mission Command Timeouts + +Some mission commands/items can take time to complete, such as a gripper opening and closing, a winch extending or retracting, or a gimbal moving to point at a region of interest. + +Where provided PX4 may use sensor feedback from the hardware to determine when the action has completed and then move to the next mission item. +If not provided, or if the feedback is lost, a mission command timeout can be used to ensure that these kinds of actions will progress to the next mission item rather than blocking progression. + +The timeout is set using the [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) parameter. +This should be set to be a small amount greater than the time required for the longest long-running action in the mission to complete. + ## Rounded turns: Inter-Waypoint Trajectory PX4 expects to follow a straight line from the previous waypoint to the current target (it does not plan any other kind of path between waypoints - if you need one you can simulate this by adding additional waypoints). diff --git a/en/flight_modes_vtol/mission.md b/en/flight_modes_vtol/mission.md index 5bb8d8138478..0ad2b7414760 100644 --- a/en/flight_modes_vtol/mission.md +++ b/en/flight_modes_vtol/mission.md @@ -30,6 +30,16 @@ In fixed-wing mode there are the following exceptions: - [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) is transformed into [MAV_CMD_NAV_VTOL_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_VTOL_LAND) unless [NAV_FORCE_VT](../advanced_config/parameter_reference.md#NAV_FORCE_VT) is set to `0` (disabled). - [MAV_CMD_NAV_TAKEOFF](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_TAKEOFF) is not supported. +## Mission Command Timeouts + +Some mission commands/items can take time to complete, such as a gripper opening and closing, a winch extending or retracting, or a gimbal moving to point at a region of interest. + +Where provided PX4 may use sensor feedback from the hardware to determine when the action has completed and then move to the next mission item. +If not provided, or if the feedback is lost, a mission command timeout can be used to ensure that these kinds of actions will progress to the next mission item rather than blocking progression. + +The timeout is set using the [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) parameter. +This should be set to be a small amount greater than the time required for the longest long-running action in the mission to complete. + ## Mission Takeoff Plan a VTOL mission takeoff by adding a `VTOL Takeoff` mission item to the map. From 742d51cbd5eb399eb136e8ba7e98a36858f41143 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 12 Dec 2024 16:49:31 +1100 Subject: [PATCH 4/5] Add release note --- en/releases/main.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/en/releases/main.md b/en/releases/main.md index 445b4955f99f..a5b8929970ac 100644 --- a/en/releases/main.md +++ b/en/releases/main.md @@ -37,7 +37,11 @@ Please continue reading for [upgrade instructions](#upgrade-guide). - [Log Encryption](../dev_log/log_encryption.md) now generates an encrypted log that contains the public-key-encrypted symmetric key that can be used to decrypt it, instead of putting the key into a separate file. This makes log decryption much easier, as there is no need to download or identify a separate key file. ([PX4-Autopilot#24024](https://github.com/PX4/PX4-Autopilot/pull/24024)). - +- The generic mission command timeout [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.html#MIS_COMMAND_TOUT) parameter replaces the delivery-specific `MIS_PD_TO` parameter. + Mission commands that may take some time to complete, such as those for controlling gimbals, winches, and grippers, will progress to the next item when either feedback is received or the timeout expires. + This is often used to provide a minimum delay for hardware that does not provide completion feedback, so that it can reach the commanded state before the mission progresses. + ([PX4-Autopilot#23960](https://github.com/PX4/PX4-Autopilot/pull/23960)). + ### Control - TBD From 1c36be48e917e30098661593037e011b0b57c31e Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 12 Dec 2024 16:56:23 +1100 Subject: [PATCH 5/5] Update en/releases/main.md --- en/releases/main.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/releases/main.md b/en/releases/main.md index a5b8929970ac..fcc8ecfe23ba 100644 --- a/en/releases/main.md +++ b/en/releases/main.md @@ -37,7 +37,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide). - [Log Encryption](../dev_log/log_encryption.md) now generates an encrypted log that contains the public-key-encrypted symmetric key that can be used to decrypt it, instead of putting the key into a separate file. This makes log decryption much easier, as there is no need to download or identify a separate key file. ([PX4-Autopilot#24024](https://github.com/PX4/PX4-Autopilot/pull/24024)). -- The generic mission command timeout [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.html#MIS_COMMAND_TOUT) parameter replaces the delivery-specific `MIS_PD_TO` parameter. +- The generic mission command timeout [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) parameter replaces the delivery-specific `MIS_PD_TO` parameter. Mission commands that may take some time to complete, such as those for controlling gimbals, winches, and grippers, will progress to the next item when either feedback is received or the timeout expires. This is often used to provide a minimum delay for hardware that does not provide completion feedback, so that it can reach the commanded state before the mission progresses. ([PX4-Autopilot#23960](https://github.com/PX4/PX4-Autopilot/pull/23960)).