uxrce_dds: support multi-instance uORB topics

[haumarco]

This PR is part of the split up of #26151

Note: This PR was force-pushed with a completely reworked approach. The original version mapped N separate DDS topics (with suffix naming like _A, _B, _C, _D) to N uORB instances. The new approach uses a single DDS topic and demultiplexes to multi-instance uORB at runtime based on a message field. This is simpler (one DDS reader instead of N), requires no naming conventions on the DDS side, and handles dynamic source assignment.

Solved Problem

The DDS bridge could only map single-instance uORB topics to DDS topics. This prevented external systems from publishing multiple instances of the same message type (e.g., multiple positioning sources) through DDS.

Solution

Add a subscriptions_demux category in dds_topics.yaml that receives a single DDS topic and demultiplexes it to multi-instance uORB publications based on a message field.

How it works:

• A single DDS topic (e.g., /fmu/in/aux_global_position) carries messages from multiple sources
• A configurable route_field (e.g., id) in the message is used to distinguish sources
• On first encounter of a new field value, a uORB multi-instance slot is assigned dynamically
• Subsequent messages with the same field value are routed to the assigned instance

Directly used as:

subscriptions_demux:
  - topic: /fmu/in/aux_global_position
    type: px4_msgs::msg::AuxGlobalPosition
    route_field: id
    max_instances: 4

Changelog Entry

For release notes:

Feature: DDS bridge subscription demux to multi-instance uORB topics
- New dds_topics.yaml `subscriptions_demux` category with `route_field` and `max_instances`
- Enables external systems to publish multiple instances of the same message type over a single DDS topic

Test coverage

Tested with aux_global_position topic configured for 4 instances with routing by id field.

Additional Notes

This is a prerequisite for multi-instance AGP fusion in EKF2. The same pattern can be extended to other multi-instance topics.

[beniaminopozzan]

Thanks for splitting them up @haumarco !

This looks good to me but I'll approve once #26306 is merged

[github-actions]

🔎 FLASH Analysis

px4_fmu-v5x [Total VM Diff: 128 byte (0.01 %)]

    FILE SIZE        VM SIZE    
--------------  -------------- 
+0.0%    +128  +0.0%    +128    .text
  +1.0%     +72  +1.0%     +72    on_topic_update()
  +0.9%     +32  +0.9%     +32    UxrceddsClient::run()
  +1.7%     +16  +1.7%     +16    RcvTopicsPubs::~RcvTopicsPubs()
  +0.0%      +8  +0.0%      +8    [section .text]
+0.0%     +57  [ = ]       0    .debug_abbrev
+0.0%      +8  [ = ]       0    .debug_frame
+0.0%    +731  [ = ]       0    .debug_info
+0.0%    +436  [ = ]       0    .debug_line
  [NEW]      +7  [ = ]       0    [Unmapped]
  +0.0%    +429  [ = ]       0    [section .debug_line]
+0.0%    +177  [ = ]       0    .debug_loclists
+0.0%    +110  [ = ]       0    .debug_rnglists
  [DEL]      -2  [ = ]       0    [Unmapped]
  +0.0%    +112  [ = ]       0    [section .debug_rnglists]
-0.0%    -323  [ = ]       0    .debug_str
-1.2%    -128  [ = ]       0    [Unmapped]
+0.0% +1.17Ki  +0.0%    +128    TOTAL

px4_fmu-v6x [Total VM Diff: 128 byte (0.01 %)]

    FILE SIZE        VM SIZE    
--------------  -------------- 
+0.0%    +128  +0.0%    +128    .text
  +1.0%     +72  +1.0%     +72    on_topic_update()
  +0.9%     +32  +0.9%     +32    UxrceddsClient::run()
  +1.7%     +16  +1.7%     +16    RcvTopicsPubs::~RcvTopicsPubs()
  +0.0%      +8  +0.0%      +8    [section .text]
+0.0%     +57  [ = ]       0    .debug_abbrev
+0.0%      +8  [ = ]       0    .debug_frame
+0.0%    +731  [ = ]       0    .debug_info
+0.0%    +428  [ = ]       0    .debug_line
  [DEL]      -1  [ = ]       0    [Unmapped]
  +0.0%    +429  [ = ]       0    [section .debug_line]
+0.0%    +177  [ = ]       0    .debug_loclists
+0.0%    +112  [ = ]       0    .debug_rnglists
-0.0%    -737  [ = ]       0    .debug_str
-2.7%    -128  [ = ]       0    [Unmapped]
+0.0%    +776  +0.0%    +128    TOTAL

Updated: 2026-03-03T12:58:09

[hamishwillee]

@beniaminopozzan Will this need docs, and if so can you work with @haumarco to make them happen?

[beniaminopozzan]

@hamishwillee sure!

@haumarco why did the non-uxrcedds changes have been added to this PR? shall it go back to draft?

[haumarco]

@beniaminopozzan
I reworked the approach...
The reason for the change is maintainability. The original approach would require creating and versioning N DDS topics per multi-instance type, which adds significant overhead as each topic needs its own type mapping and must be kept in sync across ROS2/DDS and PX4. With the new approach there is only one DDS topic to maintain regardless of the number of instances.

I also removed the non-uxrcedds changes from this PR as you flagged.

[bkueng]

Looks good

[beniaminopozzan]

Thanks @haumarco , a couple of notes on my side.
On top of those, could you also update the documentation, please?
Let me know if I can help

[github-actions]

No broken links found in changed files.

[beniaminopozzan]

@haumarco I've fixed a bunch of ROS2 typos. It was faster than multiple change suggestions :)

[beniaminopozzan]

Looking good to me!
@haumarco just a note on badge format

[haumarco]

@beniaminopozzan I applied the final change and rebased on latest main to get rid of "missing new line" CI-failure

[hamishwillee]

@haumarco @beniaminopozzan FYI only, I had a discussion about <Badge type="tip" text="main (planned for: PX4 v1.18)" /> vs <Badge type="tip" text="PX4 v1.18)" /> last week.

For v1.18 we are allowed to assume the next release will be v1.18, so you can use the second form. I plan on removing all the "planned for" now. The following release may well be a major update, so we won't be able to make this assumption going forward - hopefully we will know by the time 1.18 branches though>

This should make things a little easier.

[haumarco]

@beniaminopozzan I just now stumbled across this change in the following commit: 74a0054

was this an intentional change or did you test it with this?