nav2_ros_common: add lifecycle-managed Subscription wrapper

[Lotusymt]

---

Basic Info

Info	Please fill out this column
Ticket(s) this addresses	#5298
Primary OS tested on	Ubuntu
Robotic platform tested on	N/A (compile + unit tests only)
Does this PR contain AI generated software?	No
Was this PR description generated by AI software?	No

---

Description of contribution in a few bullet points

• Introduced a lifecycle-managed nav2::Subscription wrapper (similar to nav2::Publisher) using rclcpp_lifecycle::SimpleManagedEntity, so subscriptions can participate in lifecycle transitions.
• Gated user callbacks on is_activated() and emit a one-time warning when messages are received before activation (messages are dropped until activated).
• Kept non-lifecycle node compatibility: when constructed with a plain rclcpp::Node (no lifecycle manager to trigger activation), the wrapper auto-activates so behavior matches existing non-lifecycle usage.
• Updated test_actions slightly to make the callback type/signature match the new subscription wrapper expectations (no new tests added).

Description of documentation updates required from your changes

• Update after resolving the whole issue.

Description of how this change was tested

• Built nav2_ros_common and ran its test suite via colcon test (and verified results with colcon test-result).

---

Future work that may be required in bullet points

• Repeat the same pattern for services/clients/action servers/action clients incrementally.
• After those land, follow up with the LifecycleNode::activateInterfaces() ordering work (exporters before consumers; deactivate in reverse), and then remove the manual activation boilerplate in task servers.
• Finally, add the “autoactivate if node already active when interface is created” behavior across the remaining interfaces (matching nav2::Publisher).

For Maintainers:

• Check that any new parameters added are updated in docs.nav2.org
• Check that any significant change is added to the migration guide
• Check that any new features OR changes to existing behaviors are reflected in the tuning guide
• Check that any new functions have Doxygen added
• Check that any new features have test coverage
• Check that any new plugins is added to the plugins page
• If BT Node, Additionally: add to BT's XML index of nodes for groot, BT package's readme table, and BT library lists
• Should this be backported to current distributions? If so, tag with backport-*.

[mini-1235]

@Lotusymt check CI https://app.circleci.com/pipelines/github/ros-navigation/navigation2/17387/workflows/c2829a5d-9b2d-4eaf-8044-5e5871faee16/jobs/51482, this does not build :(

[Lotusymt]

@Lotusymt check CI https://app.circleci.com/pipelines/github/ros-navigation/navigation2/17387/workflows/c2829a5d-9b2d-4eaf-8044-5e5871faee16/jobs/51482, this does not build :(

Thanks for checking! This was just a draft attempt, and I haven’t addressed the CI issues yet. I’ll follow up after discussing the proposed approach for this issue.

[SteveMacenski]

Look good!

[SteveMacenski]

I think this is ready to be applied to all subscriptions now!

I still have to verify that below is correct, but otherwise LGTM. Can you clarify where you found this + the any_cb_ pattern? If that's established somewhere in ROS 2 core then I can just take that at face value

        // Use the appropriate dispatch method based on whether the message came from
        // intra-process (composition) or inter-process (DDS/serialization)
        if (info.get_rmw_message_info().from_intra_process) {
          any_cb_.dispatch_intra_process(msg, info);
        } else {
          auto non_const_msg = std::make_shared<MessageT>(*msg);
          any_cb_.dispatch(non_const_msg, info);
        }

[Lotusymt]

Hi @SteveMacenski, this is following ROS 2 core (rclcpp) behavior/pattern:

• any_cb_ is my member instance of rclcpp::AnySubscriptionCallback<...> (same type rclcpp stores as any_callback_ inside rclcpp::Subscription):

  • AnySubscriptionCallback API (dispatch() / dispatch_intra_process() signatures): https://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1AnySubscriptionCallback.html
  • rclcpp::Subscription stores any_callback_ and uses any_callback_.dispatch(...): https://docs.ros2.org/foxy/api/rclcpp/subscription_8hpp_source.html

• info.get_rmw_message_info().from_intra_process is rmw_message_info_t::from_intra_process exposed via rclcpp::MessageInfo::get_rmw_message_info():

  • MessageInfo: https://docs.ros2.org/foxy/api/rclcpp/classrclcpp_1_1MessageInfo.html
  • rmw_message_info_t flag: https://docs.ros2.org/foxy/api/rmw/structrmw__message__info__t.html

• Core routing matches the same if/else split:

  • Intra-process path sets from_intra_process = true and calls dispatch_intra_process(...) (SubscriptionIntraProcess): https://api.nav2.org/rolling/html/subscription__intra__process_8hpp_source.html
  • Inter-process path initializes from_intra_process = false in Executor::execute_subscription(...): https://api.nav2.org/rolling/html/executor_8cpp_source.html

• The DDS-path copy is just to match the core API: dispatch() takes std::shared_ptr<MessageT> (non-const) while dispatch_intra_process() takes a const shared ptr / unique ptr (see the AnySubscriptionCallback link above).

[SteveMacenski]

OK sounds good! I think the remaining bit is to update for all the servers :-)

[SteveMacenski]

@Lotusymt any update? I would love to get this moving

[Lotusymt]

update for all the servers

@SteveMacenski sorry for the slow update, I misinterpreted “apply to all servers” as “move on to the remaining server interfaces.

I believe the “apply everywhere” step is already done, as remaining rclcpp::Subscription usages across Nav2 servers have been migrated to nav2::Subscription. Please correct me if I missed something.

[SteveMacenski]

Don't we need to activate all the subscriptions in on_activate() and deactivate respectively?

[Lotusymt]

Don't we need to activate all the subscriptions in on_activate() and deactivate respectively?

Yes, for now they(all interfaces) are activated/deactivated at call sites. Per the #5298 issue description:

“Step 3
Once we have all of them being lifecycle-enabled, we can then update the Nav2 Lifecycle Node implementation to use a nav2::LifecycleNode::activateInterfaces() whereas we create all publishers, then clients, then action clients, then subscriptions, services, and action servers, respectively. That way all 'processing' tasks are activated only once all 'information' tasks are provided. At that point, we can remove all of the activate() / on_activate() calls from the Nav2 lifecycle node transition functions which would make that code much more concise and handled behind the scenes.”

So my understanding is:

1. Interfaces (starting with nav2::Subscription) should support lifecycle transitions, but the activation routing should ultimately be centralized (via activateInterfaces() + ordering), rather than every server manually calling on_activate() / on_deactivate() for each interface.
2. I haven’t removed existing manual activation/deactivation at call sites yet because that cleanup depends on Step 3 (having all interfaces lifecycle-enabled + ordered activation/deactivation).

[Lotusymt]

Hi @SteveMacenski, just wanted to gently follow up here in case this got buried. Please let me know if I missed anything.

[SteveMacenski]

Sorry, I've been really slammed and haven't been able to clear all the github comments I need to respond to each day. Sorry that this was one that was temporarily deprioritized. I was traveling and this one was hard to review on my small laptop screen.

My bad that it was just Q&A, I thought it was going to be another full review of many files :-) Ooops.

Interfaces (starting with nav2::Subscription) should support lifecycle transitions, but the activation routing should ultimately be centralized (via activateInterfaces() + ordering), rather than every server manually calling on_activate() / on_deactivate() for each interface.

Eventually, to start, lets manually do it like we do for publishers and action servers. The ordering here is really important for bringup stability or segfaults, so I want that to be thoughtfully done

I haven’t removed existing manual activation/deactivation at call sites yet because that cleanup depends on Step 3 (having all interfaces lifecycle-enabled + ordered activation/deactivation).

I would want to change to use the auto activate part once we have pub/sub/service/service clients/action clients all (maybe action server; maybe not yet since that's a special child).

[Lotusymt]

Hi Steve , just want to let you know I am actively working on it and here's a little update. I manage to pass all tests expect for some in nav2_system_test. Seems like some activation deadlock issue? Hopefully I can solve it soon : )

[SteveMacenski]

Ready for me now? :-)

[SteveMacenski]

These don't need to be overrided if just calling the base class, no? :-)

[Lotusymt]

Ready for me now? :-)

Not yet, unfortunately qwq. I ran into a few more issues while testing this.

For now I’m trying a workaround: for any Transient Local topic, I avoid having the subscription exist in an “inactive” state at all. Concretely, I activate the managed-entity wrapper right before creating the underlying rclcpp::Subscription, so the subscription is effectively “active” for its entire lifespan and we don’t risk losing the latched/transient sample while the wrapper is inactive.

My reasoning:

1. I couldn’t find an API that truly “disconnects” a subscription from DDS during init (i.e., not just dropping messages, but actually detaching at the middleware level).

2. Even if 1 is possible, Some (transient local)subscriptions likely need to be processed during configure, not activate. For example map_sub_ can involve heavier work, and if that happens in on_activate() it can make activation slow and potentially starve itself (or other components/tests that depend on activation finishing promptly).

Even with this change, I’m still seeing failures in some system tests. That makes me suspect there may be other subscriptions that also need to be processed earlier, but I’m still tracking down exactly which ones and why.

Does this workaround sound reasonable to you? Any suggestions would be really appreciated!!

[SteveMacenski]

@fujitatomoya a question for you based on the last comment - you don't need to read the whole thread:

Is there a way for the subscription callback to reject a message for a later delivery or create a subscriber object on the network but not add it to be serviced by the executor yet? We're trying to implement lifecycle versions of the subscriptions/services/clients since they don't exist in rclcpp_lifecycle and we're having a problem with how to indicate "No! I'm not active, don't even try it" for services and subscriptions.

Services will just happily accept a response of a default constructed result if we exit the callback when the node is not active, and we have problems with subscriptions that are transient local since the delivery will happen only once. Streaming data being dropped (like a sensor) is fine, but this is a case where its not fine.

We have long been able to do this with our Simple Action Server since there's an explicit "reject goal" API for actions so the client knows that its request was thrown out. I don't think that is sensible for services/subscriptions, but I feel like there should be a way to construct them and connect them on bringup without servicing them until active. This seems like a gap in the available API that after some digging I couldn't see how to address. But you're more in these details so I'm curious about your thoughts :-)

As always, I don't really want to maintain my own version of things that have general purpose; happy to have these all donated to rclcpp_lifecycle (and simple action server to rclcpp_actions) :-)

[SteveMacenski]

@Lotusymt all things should be processed in active state, with the sole exception of TF which is required to be running beforehand so we can check TF transformations as existing as part of the activation phase.

That makes me suspect there may be other subscriptions that also need to be processed earlier, but I’m still tracking down exactly which ones and why.

That is strange and should generally not be true. The nav2 lifecycle manager should bring all nodes into configure before all nodes into active. So by the time something is being activated, they're all configured but should not be processing data (except those already activated beforehand). There should not be dependency on anything processing messages in configure -- and if there are that's a bug we need to fix (again with the exception of TF). Could be ordering of bringup -- but also could be some interaction we should address. Do you know what node(s) or what topic(s) are the offenders?

What are the failures?

[fujitatomoya]

@SteveMacenski

1st thing's 1st to answer your question.

Is there a way for the subscription callback to reject a message for a later delivery or create a subscriber object on the network but not add it to be serviced by the executor yet?

AFAIK, no... unfortunately, there is no such things yet...

probably something you guys need is something like ros2/rclcpp#2715?

IMO LifecycleEntity makes sense for some use cases, there is a few primary states that we need to consider by design.

• unconfigured state (not configured just yet): i believe entities should not be discovered by ROS 2 network graph, in other words we cannot see this endpoint via ros2 service list or ros2 topic list. i believe this is the expected behavior from user's perspective. but it is hard to do this, because currently once we create the entity, underlying rmw implementation creates the corresponding rmw object (e.g DDS DataWriter and DataReader). after all, those entities will be discovered in ROS 2 (RMW) network graph anyway. IMO this could be TODO for future enhancement with another PR, because this can take some time and probably new interfaces between ROS 2 and RMW state control.
• inactive state: the entity will be discovered by ROS 2 RMW network graph, but not serviced just yet. i think this is the state that you guys need here, if i am correctly reading the discussion. in this state, the subscription (entity) is discovered by other remote nodes, so that we can see this subscription on the topic in the network. but this subscription will not take out the data from the RMW queue. again this also needs a basic design and more consideration, but i think a couple things that we can do here. the one is that when the data ready notification comes from the RMW, the subscription skip taking out the data from the queue. the other is that, adding the new state to RMW entity to keep the data in the queue, and does not interrupt at all. (the queue in RMW is managed by configured QoS setting underneath.)
• active state: it is now time to take the data out of the RMW queue, and call the user callback to process the data as normal endpoint. once it becomes into this state, there could be multiple data in the RMW queue based on the QoS configuration such as depth and so on, so that it needs to process all queued data to call the user callback multiple times at the beginning of this state.

i think that this is doable... but i am not sure if DDS or zenoh have these managed states internally to be mapped to lifecycle entities of ROS 2. even if they dont, maybe we can land somewhere on "skip to take out the data in inactive state". i may be missing some things here, we obviously need to take some time to consider more details and design before implementation.

[Lotusymt]

Thanks for the correction! I was initially suspicious that AMCL’s map_sub can’t be handled in the node's on_activate. But I looked into it again, it should be fine. Maybe I missed something, and the timeout error happened when I added buffering logic for transient-local in the subscription wrapper at that time. I’m currently not able to reliably reproduce the exact same timeout anymore.

So I think the next step would be to try again when

inactive state: the entity will be discovered by ROS 2 RMW network graph, but not serviced just yet. i think this is the state that you guys need here, if i am correctly reading the discussion. in this state, the subscription (entity) is discovered by other remote nodes, so that we can see this subscription on the topic in the network. but this subscription will not take out the data from the RMW queue. again this also needs a basic design and more consideration, but i think a couple things that we can do here. the one is that when the data ready notification comes from the RMW, the subscription skip taking out the data from the queue. the other is that, adding the new state to RMW entity to keep the data in the queue, and does not interrupt at all. (the queue in RMW is managed by configured QoS setting underneath.)

is available.

[SteveMacenski]

probably something you guys need is something like ros2/rclcpp#2715?

This suffers from the same issues, no? :( It creates the subscription on creation -- so if you send a message when the node is in the inactive state, it'll be received by the callback (even though its rejected for processing, if its transient local it will not be reattempted later resulting in meaningful loss).

Though @Lotusymt note the use of rclcpp::Subscription<MessageT, AllocatorT>::handle_message(message, message_info); -- maybe this is a cleaner way?

---

I think you pointed out the exact thing we need in inactive. I would like to have all the interfaces exposed in inactive, but if we create the subscription, then they are then serviceable when they should not be yet. We can instead create subscriptions in the transition to active, but then we lose interospectability at inactive when I'd like to have all the interfaces created but not yet doing anything.

This doesn't just impact subscriptions, but also services. Clients and publishers are easy because they can just come up and then just check a flag that if someone asks them to do something to simply say "no". subscriptions and services need something to say "no" before we try to execute a callback.

I think as such there should be something to create an interface, have it discoverable, but not serviceable until said its ready.

the one is that when the data ready notification comes from the RMW, the subscription skip taking out the data from the queue. the other is that, adding the new state to RMW entity to keep the data in the queue, and does not interrupt at all

Either of these (and I imagine more) would work.

[fujitatomoya]

IMO (i believe everybody agrees...) this feature should be implemented in the core base classes like LifecycleSubscription, not in the Nav2. but i do not have bandwidth for this, and being based in Tokyo makes it harder to join the PMC meeting... (2AM starts... 😓 ) i think creating the thread in the discourse would be nice to get more feedback and attention from the community, there could be someone who is willing to make contribution for this. maybe GSoC project?

[SteveMacenski]

OK - for now @Lotusymt I think we should create it on the active state to get past the issue (even if not ideal) for now. Do you also mind starting a thread in discourse with this? I could but I want you to get credit for uncovering this gap :-)

[Lotusymt]

Thanks Steve! really appreciate you encouraging me to start the Discourse thread.

I submitted the topic in Discourse, but it’s currently pending moderator approval. I’ll post the link here as soon as it’s visible. If there’s anything you’d like me to adjust, please let me know.

On the PR side: I also switched the workaround to the rclcpp::Subscription<...>::handle_message(msg, info) approach you pointed out. Almost all tests are passing now. I’m down to just one remaining failure in nav2_system_tests. Hopefully I can figure that out soon!

[SteveMacenski]

Great - thanks!

[Lotusymt]

I submitted the topic in Discourse, but it’s currently pending moderator approval. I’ll post the link here as soon as it’s visible. If there’s anything you’d like me to adjust, please let me know.

The link is here: https://discourse.openrobotics.org/t/design-discussion-discoverable-not-serviceable-ros-interfaces-for-lifecycle-nodes/52842

[SteveMacenski]

LMK when you want me to review / test :-)

[codecov]

Codecov Report

❌ Patch coverage is 86.06272% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...stmap_2d/plugins/costmap_filters/binary_filter.cpp	0.00%	10 Missing ⚠️
...os_common/include/nav2_ros_common/subscription.hpp	85.00%	6 Missing ⚠️
nav2_costmap_2d/src/costmap_2d_ros.cpp	73.33%	4 Missing ⚠️
nav2_costmap_2d/plugins/static_layer.cpp	62.50%	3 Missing ⚠️
...v2_waypoint_follower/plugins/photo_at_waypoint.cpp	50.00%	3 Missing ⚠️
nav2_behaviors/src/behavior_server.cpp	75.00%	2 Missing ⚠️
..._monitor/include/nav2_collision_monitor/source.hpp	0.00%	2 Missing ⚠️
...nav2_costmap_2d/costmap_filters/costmap_filter.hpp	0.00%	2 Missing ⚠️
...v2_waypoint_follower/plugins/input_at_waypoint.cpp	50.00%	2 Missing ⚠️
nav2_collision_monitor/src/circle.cpp	87.50%	1 Missing ⚠️
... and 5 more

Files with missing lines	Coverage Δ
nav2_amcl/src/amcl_node.cpp	89.09% <100.00%> (-0.48%)	⬇️
...include/nav2_behaviors/plugins/assisted_teleop.hpp	100.00% <ø> (ø)
nav2_behaviors/plugins/assisted_teleop.cpp	89.15% <100.00%> (+1.15%)	⬆️
nav2_bt_navigator/src/bt_navigator.cpp	91.80% <ø> (-3.28%)	⬇️
..._collision_monitor/src/collision_detector_node.cpp	97.36% <100.00%> (+0.07%)	⬆️
nav2_collision_monitor/src/costmap.cpp	93.75% <100.00%> (+0.56%)	⬆️
...monitor/src/lifecycle_point_cloud_subscription.cpp	100.00% <100.00%> (ø)
nav2_collision_monitor/src/pointcloud.cpp	81.25% <100.00%> (+1.03%)	⬆️
nav2_collision_monitor/src/polygon_source.cpp	95.08% <100.00%> (+0.34%)	⬆️
nav2_collision_monitor/src/range.cpp	95.34% <100.00%> (+0.47%)	⬆️
... and 33 more

... and 15 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Lotusymt]

test failed without it and line 66 above

[Lotusymt]

Hi Steve, I think it is ready for a review, although codecov didn't pass. I will add tests if the current direction is ok!

[SteveMacenski]

I did a brief look through before going camping for the weekend!

[SteveMacenski]

Why this specialization?

[SteveMacenski]

I thought we talked about actually creating the subscription objcet on activation instead for now? I don't think we should be doing something like this, its a hack and we should not be activating anything preemptively.

[SteveMacenski]

I'm also not sure about why this is using the subscription factory now (?)

[SteveMacenski]

or - maybe you can explain this more to me if this somehow gets around all the issues we had!

[Lotusymt]

Yeah I misunderstood. Having a second thought, I think creating subs in activation is more consistent with our intent to make everything start working only after activation.

One thing I want to make sure before proceeding: Should I create every sub in activation as a work around for now, or only transient local subs?

And subcriptionfactory is used is because we need a custom subscription type that overrides the handle_ methods* (and thus can’t be the default rclcpp::Subscription)

[SteveMacenski]

Should I create every sub in activation as a work around for now, or only transient local subs?

I'd say all. Sorry for the delay, I was traveling

[Lotusymt]

Got it! Thanks for the reply. I am a bit busy lately, but I should be able to address this in a few days!

[SteveMacenski]

I appreciate your time! I know this has been ongoing to for a long time -- your time here is valuable and thanks!

[Lotusymt]

Hello Steve. I am really sorry for the delay, I have done this modification but new test failures occurred. I am trying to fix those failures in a more automatic manner, but it didn't go very smoothly. I still want to explore this approach in the next few days, but I would aim to solve it by next Wednesday even if this doesn't work out.
I hope this plan sound ok to you : )

[SteveMacenski]

Please revert changes to these geojson files

[mergify]

This pull request is in conflict. Could you fix it @Lotusymt?