Update TransponderReport.msg - correct "heading" description

[slgrobotics]

Solved Problem

When TransponderReport message is published, the "heading" field must be filled with course over ground in aviation terms, 0..2PI radians (0 to 360 degrees). But the comment/description wrongly specifies -PI..PI range.

Fixes #24780

Solution

• edit TransponderReport.msg to specify correct range in the comment to avoid confusion.

To fill "heading" field correctly, a wrap should be used - something like: wrap_2pi(....gps_cog_rad)

Context

Please see discussion and example code in #24780

[slgrobotics]

@dakejahl - here it is, please review.

[dakejahl]

I'm not sure that's correct, the SagetechMXS driver publishes heading as [-PI, PI]
https://github.com/PX4/PX4-Autopilot/blob/main/src/drivers/transponder/sagetech_mxs/SagetechMXS.cpp#L617

[slgrobotics]

That's a good question to ask SagetechMXS driver's authors. Do we know it is working correctly? Because my code works fine, and when I tried wrap_pi() it didn't.

You can play with it yourself:

mkdir src10
cd src10
git clone https://github.com/slgrobotics/PX4-Autopilot.git --single-branch -b dev --recursive
cd PX4-Autopilot

make px4_sitl gz_lawnmower

# plan or just go to map clicks and see ADSB logo following the vehicle
# code in src/modules/rover_lawnmower is self-explanatory

There's also src/lib/adsb/AdsbConflict.cpp with its AdsbConflict::fake_traffic() method and comments suggesting atan2() - may be wrong too.

[dakejahl]

@qtweng @sfuhrer can you guys take a look?

[slgrobotics]

This is how src/modules/mavlink/streams/ADSB_VEHICLE.hpp fills the MAVLink message:

			mavlink_adsb_vehicle_t msg{};
			msg.heading = pos.heading / M_PI_F * 180.0f * 100.0f;

 90 deg:  1/2 * 180.0 * 100.0     = 9000
180 deg:  1 * 180.0 * 100.0       = 18000
270 deg:  3 * 1/2 * 180.0 * 100.0 = 27000
360 deg:  2 * 1 * 180.0 * 100.0   = 36000

These are also the values I see for heading in MAVLink Inspector when I drive my SIM lawnmower around.

Heading is an int16_t field in MAVLink, all values above are below 65535:

<field type="uint16_t" name="heading" units="cdeg">Course over ground</field>

src/modules/mavlink/mavlink/message_definitions/v1.0/common.xml has many lines with cdeg type,
when it defines direction - it is mostly 0..359.99 range. Natural for aviation, it's either 270 degrees or nine o'clock ;-)

After all, it's not how we fantacize about these fields, it's how well we feed QGC that matters...

[qtweng]

Oh, I think this actually makes sense. I think SagetechMXS may need to be updated to wrap into the positive range. I missed this in my initial consideration. The mavlink message expects a positive centidegree heading. However, the SagetechMXS driver outputs a range between [-pi, pi].

So currently TransponderReport can be in two different conventions depending on the source.

1. SagetechMXS([-pi, pi]) -> TransponderReport([-pi, pi]) -> Mavlink ([0, 180]), this probably means [-pi, 0] isn't represented properly. I think I may have not tested this thoroughly enough when I was monitoring the ADSB handling during my live testing (reference vehicles I saw were eastbound).
2. Mavlink receiver [0, 360] -> TransponderReport([0, 2pi]) -> Mavlink ([0, 360]), this is correct when forwarded from a system that forwards mavlink.

I think I can correct this by correcting SagetechMXS to use range [0, 2pi] and checking that it works. This way both cases the same positive-only range. And the docs can be updated accordingly.

[slgrobotics]

I'd suggest merging this PR first, if we've recognized that TransponderReport.msg comment needs correction.

Then open a separate PR to deal with SagetechMXS fixing and testing.

[qtweng]

I made an error and did not fully address the issue with my commit. This was likely the two cases prior to #24780 fix:

1. SagetechMXS([-pi, pi]) -> +pi adds bias so 0 is due south-> TransponderReport([0, 2pi]) -> +pi back to due north -> Mavlink ([0, 360])
2. Mavlink receiver [0, 360] -> -pi adds bias so 0 is due south -> TransponderReport([-pi, pi]) -> +pi back to due north -> Mavlink ([0, 360])

[slgrobotics]

@qtweng - this PR is strictly for fixing TransponderReport.msg comment, and maybe related documentation.

Please deal with SagetechMXS issues in separate PRs. Thank you.

Take it easy, my friend, the sunny side is that we haven't crashed into something heavy with 200+ souls aboard. Test it well :-)

[hamishwillee]

FWIW (just to be pedantic) If as driver is written to the uORB documentation then arguably it is correct, and the implementation of the MAVLink stream, which does not convert the uorb type correctly to match specification is what is incorrect.

It doesn't matter really though, as long as all the authors agree and everything is changed to match. In particular because this isn't exported to ROS as well. https://docs.px4.io/main/en/middleware/dds_topics.html

[slgrobotics]

@hamishwillee - pedantic is my second name, welcome to the family! ;-) - and thanks for bringing this up.

I have a feeling (not direct knowledge) that after the TransponderReport.msg is merged into main, some documetation will be auto-generated and thus updated. Let me know if I can help with docs otherwise.

[slgrobotics]

For documentation (auto?)updates watch https://docs.px4.io/main/en/msg_docs/TransponderReport.html

[DronecodeBot]

This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:

https://discuss.px4.io/t/px4-dev-call-july-2-2025-team-sync-and-community-q-a/46266/1

[hamishwillee]

For documentation (auto?)updates watch https://docs.px4.io/main/en/msg_docs/TransponderReport.html

You might not them until @mrpollo finishes his CI updates. I do these manually at the moment. It is very frustrating.