Thruster Allocation Matrix for BlueROV2 Heavy

[lblunschi]

Hi Evan,

I am currently working on my Master’s thesis, where the main contribution is the integration of a local path planning framework for the BlueROV2 Heavy. As part of this work, we switched from ArduSub to your ll-control framework using the demos in the auv_controllers repository. This has allowed us to directly use our own state estimation and significantly simplified debugging compared to the ArduSub controllers. Thank you for making it accessible :).

I have a few questions on the thruster allocation matrix (TAM) you have implemented in the control demos in the blue repository

blue/blue_demos/control_integration/config/bluerov2_heavy_controllers.yaml

Lines 77 to 83 in 812fea6

	tam:
	x: [ -0.707, -0.707, 0.707, 0.707, 0.0, 0.0, 0.0, 0.0]
	y: [ 0.707, -0.707, 0.707, -0.707, 0.0, 0.0, 0.0, 0.0]
	z: [ 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 1.0]
	rx: [ 0.0, 0.0, 0.0, 0.0, -0.21805, 0.21805, -0.21805, 0.21805]
	ry: [ 0.0, 0.0, 0.0, 0.0, -0.12, -0.12, 0.12, 0.12]
	rz: [0.1888, -0.1888, -0.1888, 0.1888, 0.0, 0.0, 0.0, 0.0]

as well as in the auv_controllers repository

https://github.com/Robotic-Decision-Making-Lab/auv_controllers/blob/9ac9ebaa8d32184886542be0441f47302c31641d/auv_control_demos/chained_controllers/config/chained_controllers.yaml#L98-L104

Do you still remember the source of this TAM?

I have seen the open issue about the TAM here: #97
However, the "Simulated TAM" you posted in this response is not the same as the one in the control demos linked at the top of this post.

Therefore, I have some questions on the definitions used in the setup of the TAM as well as the thruster_allocation_matrix_controller using it:

0. Frame definitions
   Am I correct in assuming that you are using the body-axis aligned frame (Front, Right, Down)?

1. Forward Thrust Direction

In issue 97 you sepecify that you assume "forward" direction of thrust to be the case when the thruster pushes water TOWARDS the cable. Is that still true?
I am not trying to say that you have to follow this, but I am wondering if you have seen the definition of Blue Robotics on "forward" thrust direction: They seem to define the forward thrust direction in case the propeller pushes water FROM the side with the cable to the other side (https://bluerobotics.com/learn/thruster-usage-guide/#introduction, see section Thruster Direction).

2. Propeller spin direction
   Looking at the hardware and simulated TAMs in discussion on issue 97, you seem to incorporate the direction of rotation of the propeller in the TAM as well (contribution of thruster 5 in z is negative while thruster 6 is positive, while they are mounted in the direction while having propellers that spin in opposite direction).
   Is this observation correct?

From what I have seen in the Thruster User Guide (https://bluerobotics.com/learn/thruster-usage-guide/#introduction, see section Propeller Direction) the direction of the propeller spin does not change the definition of the forward thrust, because of the usage of mirrored thruster blades.

In that case the TAM would not map the individual thruster forces to the generalized wrench, but rather the force multiplied by the spinning direction?

I am sorry for the extensive questioning of this specific detail, but I have now seen a few different implementations of TAMs for the BlueROV2 heavy that all seem to disagree somehow and I wanted to make sure I can understand your implementation of it, because I do not want to compromise the ll-controller by changing the TAM inappropriately based on wrong assumptions.

(
For reference, I also looked at these alternative TAM implementations:
https://flex.flinders.edu.au/file/27aa0064-9de2-441c-8a17-655405d5fc2e/1/ThesisWu2018.pdf | Page 49
https://doi.org/10.3390/jmse10121898 | Page 23 Figure A4
)

Thank you very much in advance for your response as well as for your work on these repositories, it has been extremely helpful for my project.

Best,
Luis

[evan-palmer]

This is a great question!

Do you still remember the source of this TAM?

Most of the parameters (including hydrodynamic parameters) used in the examples are based on Chu-Jou's thesis that you have linked.

I have now seen a few different implementations of TAMs for the BlueROV2 heavy that all seem to disagree somehow and I wanted to make sure I can understand your implementation of it

The general answer to most of your questions here is that the matrix values themselves should be consistent (assuming a 45-degree mounting orientation), but - as you have seen - the signs can vary depending on an individual's hardware configuration, choice of body frame, and thruster interface. For example, someone's ESC wiring could be reversed, resulting in a sign mismatch (more on this below).

I would recommend that you follow a procedure similar to the following:

1. Define a coordinate frame for your system (e.g., FLU, FRD) - the controllers implemented in auv_controllers are implemented to be agnostic to this decision, but it should be consistent.
2. Launch your hardware interface (e.g., thruster_hardware), the thruster controllers, and the thruster allocation matrix controller using a baseline TAM.
3. Send a positive and negative force/torque to each of the TAM inputs and manually check that the resulting thruster directions match your expectations and produce motion that matches your body frame. I generally do this out-of-water. Nathalie has a nice visualization that can be used as a reference here. This process doesn't usually take longer than an hour to finish and will prevent any issues with someone's hardware configuration being inconsistent with your own.

To answer some of your more specific questions,

Am I correct in assuming that you are using the body-axis aligned frame (Front, Right, Down)?

The examples in this repository all use FRD. In practice, I personally have started using FLU to avoid friction with other ROS packages.

Forward Thrust Direction

I had not seen that link. Thank you for sharing 😄 I would be happy to update things to be consistent with it to avoid confusion in the future.

Looking at the hardware and simulated TAMs in discussion on issue 97, you seem to incorporate the direction of rotation of the propeller in the TAM as well (contribution of thruster 5 in z is negative while thruster 6 is positive, while they are mounted in the direction while having propellers that spin in opposite direction).

The TAM used in simulation is a mess - don't use that as a reference for your hardware!

From what I have seen in the Thruster User Guide the direction of the propeller spin does not change the definition of the forward thrust, because of the usage of mirrored thruster blades.

The nuance here stems from how the forces requested by the TAM are applied by the thrusters. To elaborate, there are two main ways that we can control the direction of the propellers in order to match what is defined as forward thrust: (1) we can change the signs in the TAM or (2) we can configure the thruster controllers to use a different thrust curve. The current implementation of the thruster controllers makes it easier to modify the TAM, which is why I recommend that.

Below are the configurations that I am actively using in our own hardware deployments (click dropdown)

controller_manager:
  ros__parameters:
    update_rate: 75 # Hz
    hardware_components_initial_state:
      inactive:
        - thruster_control_system

    impedance_controller:
      type: impedance_controller/ImpedanceController

    thruster_allocation_matrix_controller:
      type: thruster_allocation_matrix_controller/ThrusterAllocationMatrixController

    thruster1_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster2_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster3_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster4_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster5_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster6_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster7_controller:
      type: thruster_controllers/PolynomialThrustCurveController

    thruster8_controller:
      type: thruster_controllers/PolynomialThrustCurveController

impedance_controller:
  ros__parameters:
    reference_controller: thruster_allocation_matrix_controller
    use_external_measured_states: true
    gains:
      x:
        kp: 30.0
        kd: 2.5
      y:
        kp: 30.0
        kd: 2.5
      z:
        kp: 40.0
        kd: 1.0
      rx:
        kp: 5.0
        kd: 0.25
      ry:
        kp: 5.0
        kd: 0.25
      rz:
        kp: 5.0
        kd: 0.25

thruster_allocation_matrix_controller:
  ros__parameters:
    thrusters:
      - thruster1_joint
      - thruster2_joint
      - thruster3_joint
      - thruster4_joint
      - thruster5_joint
      - thruster6_joint
      - thruster7_joint
      - thruster8_joint
    reference_controllers:
      - thruster1_controller
      - thruster2_controller
      - thruster3_controller
      - thruster4_controller
      - thruster5_controller
      - thruster6_controller
      - thruster7_controller
      - thruster8_controller
    
    # the TAM is defined in the FLU frame to be consistent with the rest of ROS
    tam:
      x:  [  0.707,  0.707,   0.707,  0.707,      0.0,      0.0,     0.0,     0.0]
      y:  [ 0.707,  -0.707,   -0.707, 0.707,      0.0,      0.0,     0.0,     0.0]
      z:  [    0.0,    0.0,     0.0,    0.0,     1.0,      -1.0,     -1.0,    1.0]
      rx: [    0.0,    0.0,     0.0,    0.0, -0.21805, -0.21805, 0.21805, 0.21805]
      ry: [    0.0,    0.0,     0.0,    0.0,    -0.12,     0.12,   -0.12,    0.12]
      rz: [0.1888, -0.1888, 0.1888, -0.1888,      0.0,      0.0,     0.0,     0.0]

thruster1_controller:
  ros__parameters:
    thruster: thruster1_joint
    min_thrust: -20.0
    max_thrust: 20.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster2_controller:
  ros__parameters:
    thruster: thruster2_joint
    min_thrust: -20.0
    max_thrust: 20.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster3_controller:
  ros__parameters:
    thruster: thruster3_joint
    min_thrust: -20.0
    max_thrust: 20.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster4_controller:
  ros__parameters:
    thruster: thruster4_joint
    min_thrust: -20.0
    max_thrust: 20.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster5_controller:
  ros__parameters:
    thruster: thruster5_joint
    min_thrust: -30.0
    max_thrust: 30.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster6_controller:
  ros__parameters:
    thruster: thruster6_joint
    min_thrust: -30.0
    max_thrust: 30.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster7_controller:
  ros__parameters:
    thruster: thruster7_joint
    min_thrust: -30.0
    max_thrust: 30.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]

thruster8_controller:
  ros__parameters:
    thruster: thruster8_joint
    min_thrust: -30.0
    max_thrust: 30.0
    min_deadband: 1470
    max_deadband: 1530
    neutral_pwm: 1500
    thrust_curve_coefficients: [1498.0, 12.01, -0.04731, -0.002098, 0.00002251]
    ```

</details>

[lblunschi]

Thank you very much for the detailed response.

The TAMs built into blue_demos and auv_control_demos seem to work well for our simulation and hardware setup, so I think that it is probably best not to change them unnecessarily. We also explicitly handle thrusters with CCW spin direction in the low-level controller that publishes PWM through the Navigator board. https://github.com/BubbleRobotics/auv_controllers/blob/c4d9084b20c380532b4f71321a5b7ad06ab13bdc/bubble_ll_controller/src/ll_controller.py#L357-L365

Now that I am writing the thesis, however, I wanted to understand how the TAM is actually defined and derived, because I noticed some apparent physical inconsistencies. The TAM you shared for your hardware setup makes much more sense to me. It seems to consistently incorporate the CW/CCW spin direction into the TAM, assuming the standard thruster configuration you linked, especially since the vertically mounted thrusters 5–8 have alternating signs in the z direction.

By the way, did you also rename the min_deadband variable in your hardware setup? Otherwise, you might unintentionally be using the default values. I ran into this as well, since the corresponding parameter in your polynomial_thrust_curve_controller_parameters.yaml seems to be defined as min_deadband_pwm.

In general, I find incorporating spin direction directly into the TAM somewhat confusing, since it requires inferring propeller spin direction, frame conventions, mounting positions, and the definition of forward thrust from a single numeric matrix without explicit parameters or documentation.

This might also just be a point of confusion for me, though.

Nevertheless, I would argue that having a consistent definition of forward thrust direction, for example yours or the one from the T200 tutorial, would improve the understandability of the controller architecture. In my opinion, the TAM should map individual thruster forces to a generalized wrench. That means that, independently of propeller spin direction and the low-level controller architecture, the TAM should describe the effect of the force vector produced by thruster i on the vehicle.

Since the BlueROV2 variants all use the same thruster configuration when mounted correctly, this matrix could then be universal across systems.

The propeller spin direction could instead be handled by the polynomial thruster controller, for example through a spin_direction parameter that inverts the thrust-to-PWM behavior, similar to what we implemented in our low-level controller. I think this could reduce confusion and make debugging easier, since the exact configuration of each thruster would be explicit.

I may also be overlooking factors that make adopting such a universal TAM difficult, but I would be very interested to hear your opinion.

If you share this view or would like more details, I drafted a section on the TAM derivation here:
https://polybox.ethz.ch/index.php/s/9dSdtYqYe9zjTbL

Thank you again for your help.

[evan-palmer]

We also explicitly handle thrusters with CCW spin direction in the low-level controller that publishes PWM through the Navigator board.

Very cool. Do you like the Navigator interface? Replacing ArduSub and MAVROS with the Navigator interface has been on my backlog for quite some time.

By the way, did you also rename the min_deadband variable in your hardware setup? Otherwise, you might unintentionally be using the default values.

Ha! I am a victim of my own crime.

Nevertheless, I would argue that having a consistent definition of forward thrust direction, for example yours or the one from the T200 tutorial, would improve the understandability of the controller architecture. In my opinion, the TAM should map individual thruster forces to a generalized wrench.

I agree with this opinion, and I like your idea regarding removing this responsibility from the TAM. I have submitted a PR that implements your idea here: Robotic-Decision-Making-Lab/auv_controllers#84 Let me know what you think.

If you share this view or would like more details, I drafted a section on the TAM derivation here

I'll give it a read. Thank you for sharing! Best of luck with your writing and defense.

[lblunschi]

Awesome, thanks for adding it this quickly. That should work nicely I think. However, it might be beneficial for clarity's sake to explicitly make a note on the assumptions made on the nominal spin direction. So for example instead of reverse, you could say spin_direction_cw or explicitly write in the description what is defined as the reverse and what is defined as the nominal spin direction. Adding to this, the definition of the forward thrust direction either in the TAM controller or in the thruster controller would finally make overall control structure fully transparent with respect to the thruster configuration that this demo is designed for, and how it can be adapted. What do you think about these propositions?

In regards to ArduSub and MAVROS:

To be honest, I was not involved with the implementations regarding the replacement of ArduSub and MAVROS on this low level controller (or thruster driver) written for hardware use.
I did however, do the analogous task in the simulation environment. I hope it can help you in any way to take if off of your backlog. You can find the related implementations in the blue repo here: https://github.com/BubbleRobotics/bubble_blue/tree/feature/own_controller_developement

And the ll-controller, a fork of your auv_controllers repository (including a fake thruster hardware plugin to match the thruster controllers output) can be found here: https://github.com/BubbleRobotics/auv_controllers/tree/feature/simulation_version

Note that these branches are far from a stable version, have not been validated on hardware yet, and rely a custom state estimation based on the robot_localization package.

I did however find my adaptions to the polynomial thruster controller and the thruster actuation without ArduSub to improve the performance of the controller in simulation noticeably.
I am now using a sampling based conversion from PWM -> Thrust and (also for the inverse) based on the T200 datasheet measured data (https://bluerobotics.com/store/thrusters/t100-t200-thrusters/t200-thruster-r2-rp/ , under Technical Details -> Performance Charts).

Again, note that this was not yet validated on hardware and I also have not compared the performance of the sampling based version of the thruster controller against your original polynomial thruster controller , but I will hopefully have done it soon.