diff --git a/docs/en/frames_sub/bluerov2.md b/docs/en/frames_sub/bluerov2.md index 1f528766f8..1843edca45 100644 --- a/docs/en/frames_sub/bluerov2.md +++ b/docs/en/frames_sub/bluerov2.md @@ -33,14 +33,67 @@ the [Airframe Reference](../airframes/airframe_reference.md#vectored-6-dof-uuv): - **MAIN7:** motor 7 CCW, stern starboard vertical, propeller CW - **MAIN8:** motor 8 CCW, stern port vertical, propeller CCW +## Basic Control Axes + +For underwater vehicles, motion is defined in terms of body axes: + +- **Surge:** forward/back motion - translation along the body X axis. +- **Sway:** left/right motion - translation along the body Y axis. +- **Heave:** up/down motion - translation along the body Z axis. +- **Yaw:** rotation about the (vertical) body Z axis. + +### Stick Mapping (Mode 2) + +The mapping below illustrates the default joystick behavior: + +- **Pitch stick (forward/back):** surge +- **Roll stick (left/right):** sway +- **Throttle stick (up/down):** heave +- **Yaw stick (left/right):** yaw + +![RC Basic Commands](../../assets/flying/rc_mode2_mc_position_mode.png) + ## Manual Modes -| Mode | Description | -| -------- | -------------------------------------------------------------------------------------------------------------------- | -| Manual | Direct manual control of yaw and thrust. | -| Acro | Manual control of yaw/thrust, but keeps roll/pitch zero | -| Altitude | Manual control of x/y thrust and yaw. Control of height with PID, manually controlled by user. Keeps roll/pitch zero | -| Position | Controls x/y/z and yaw. Manually controlled by user. Keeps roll/pitch zero | +The following manual and assisted modes are currently supported on BlueROV2 Heavy: + +| Mode | Description | +| ---------- | --------------------------------------------------------------------------------------------------------------------------- | +| Manual | Direct manual control of thrust and yaw. | +| Stabilized | Manual control of thurst and yaw with roll/pitch stabilization. | +| Acro | Manual control of yaw-rate and direct thrust commands with roll/pitch stabilization. | +| Altitude | Manual control of x/y thrust and yaw. Control of height with PID, manually controlled by user. Keeps roll/pitch stabilized. | +| Position | Controls x, y, z and yaw with position hold when sticks are released. Keeps roll/pitch stabilized. | + +## Joystick Stick Mode + +BlueROV2 supports two joystick mappings for manual control, selected using the +[UUV_STICK_MODE](../advanced_config/parameter_reference.md#uuv_stick_mode) parameter. + +By default, `UUV_STICK_MODE` is set to `0`, which enables the UUV stick mapping intended for vectored underwater vehicles. + +### UUV_STICK_MODE = 0 (default) + +This mode is intended for normal BlueROV2 operation. +In `Manual`, `Stabilized`, and `Acro` modes, the sticks command: + +- **Pitch stick:** surge - moving stick up -> moving forward, +X translation in body frame. +- **Roll stick:** sway - moving stick right -> moving sideways right, +Y translation in body frame. +- **Throttle stick:** heave - moving stick up -> moving upwards, -Z translation in body frame (note the Z axis points Down of the vehicle in PX4). +- **Yaw stick:** yaw - moving stick right -> yawing to the right, +Z rotation in body frame. + +In this mode, roll and pitch are kept level rather than commanded directly. + +### UUV_STICK_MODE = 1 + +This mode enables the legacy multicopter-style stick mapping for `Manual`, `Stabilized`, and `Acro` modes: + +- **Throttle stick:** surge - moving stick up -> moving forward, +X translation in body frame. +- **Roll stick:** roll - moving stick right -> rolling to the right side, +X rotation in body frame. +- **Pitch stick:** pitch - moving stick up -> pitching down, -X translation in body frame (note signs are switched to follow PX4 standard). +- **Yaw stick:** yaw - moving stick right -> yawing to the right, +Z rotation in body frame. + +This mode is mainly provided for compatibility with older setups and user preference. ## Airframe Configuration diff --git a/docs/en/frames_sub/index.md b/docs/en/frames_sub/index.md index 943746541a..0d056b8be5 100644 --- a/docs/en/frames_sub/index.md +++ b/docs/en/frames_sub/index.md @@ -6,15 +6,15 @@ Support for UUVs is [experimental](../airframes/index.md#experimental-vehicles). Maintainer volunteers, [contribution](../contribute/index.md) of new features, new frame configurations, or other improvements would all be very welcome! -At time of writing it has only been tested using ROS in offboard mode. +At time of writing manual and assisted manual modes are available for supported UUV frames, as well as ROS in offboard mode. The following features have not been implemented: -- Modes like missions, depth hold, stabilised manual control, etc. +- Autonomous mission-style underwater workflows are still limited compared to aerial vehicles. - BlueRobotics gripper support. ::: -PX4 has basic support for UUVs. +PX4 has basic support for UUVs. For BlueROV2 Heavy, PX4 currently supports Manual, Stabilized, Acro, Altitude and Position modes. ## Supported Frames diff --git a/src/modules/uuv_att_control/uuv_att_control.cpp b/src/modules/uuv_att_control/uuv_att_control.cpp index fc81b0a310..bd17b2df48 100644 --- a/src/modules/uuv_att_control/uuv_att_control.cpp +++ b/src/modules/uuv_att_control/uuv_att_control.cpp @@ -270,9 +270,9 @@ void UUVAttitudeControl::generate_attitude_setpoint(float dt) if (js_heave_sway_mode) { // XYZ thrust - _attitude_setpoint.thrust_body[0] = _manual_control_setpoint.throttle * throttle_manual_attitude_gain; // surge +x + _attitude_setpoint.thrust_body[0] = _manual_control_setpoint.pitch * throttle_manual_attitude_gain; // heave +z down _attitude_setpoint.thrust_body[1] = _manual_control_setpoint.roll * throttle_manual_attitude_gain; // sway +y - _attitude_setpoint.thrust_body[2] = -_manual_control_setpoint.pitch * throttle_manual_attitude_gain; // heave +z down + _attitude_setpoint.thrust_body[2] = -_manual_control_setpoint.throttle * throttle_manual_attitude_gain; // surge +x } else { // Throttle only on +x (surge) @@ -295,9 +295,9 @@ void UUVAttitudeControl::generate_rates_setpoint(float dt) _rates_setpoint.pitch = 0.0f; _rates_setpoint.yaw = _manual_control_setpoint.yaw * dt * _param_rgm_yaw.get(); - _rates_setpoint.thrust_body[0] = _manual_control_setpoint.throttle * throttle_manual_rate_gain; // surge +x + _rates_setpoint.thrust_body[0] = _manual_control_setpoint.pitch * throttle_manual_rate_gain; // heave +z down _rates_setpoint.thrust_body[1] = _manual_control_setpoint.roll * throttle_manual_rate_gain; // sway +y - _rates_setpoint.thrust_body[2] = -_manual_control_setpoint.pitch * throttle_manual_rate_gain; // heave +z down + _rates_setpoint.thrust_body[2] = -_manual_control_setpoint.throttle * throttle_manual_rate_gain; // surge +x } else { // Roll/pitch/yaw are rate commands; thrust only surge @@ -404,9 +404,9 @@ void UUVAttitudeControl::Run() const float pitch_u = 0.0f; const float yaw_u = _manual_control_setpoint.yaw * _param_mgm_yaw.get(); - const float thrust_x = _manual_control_setpoint.throttle * throttle_manual_gain; // surge + const float thrust_x = _manual_control_setpoint.pitch * throttle_manual_gain; // heave const float thrust_y = _manual_control_setpoint.roll * throttle_manual_gain; // sway - const float thrust_z = -_manual_control_setpoint.pitch * throttle_manual_gain; // heave + const float thrust_z = -_manual_control_setpoint.throttle * throttle_manual_gain; // surge constrain_actuator_commands(roll_u, pitch_u, yaw_u, thrust_x, thrust_y, thrust_z);