Added Localisation Hook

[cardboardcode]

New Feature Implementation 📦 ➕

Implemented Feature 📦

Added explicit addition of localise callback in RobotAdapter class make_callbacks function as well as implemented complimentary change_map function in RobotClientAPI class for when callback is triggered.

Implementation Description 📖

This new feature offers the following benefits:

• Implicitly documents localise callback for newer RMF developers who may not be able to find this functionality, given the closure of Open-RMF Discussion.
• Provides better controllability of Robot Fleet Adapter behaviour, particularly during lift-taking when timing of map-switching is crucial and varies largely due to robot-specific limitations.

In other words, with this feature, developers can control what robot can do when triggered by a change in robot map.

This feature is based on the following archived Open-RMF discussion.
Reference Link: https://discourse.openrobotics.org/t/localization-after-floor-change-415/44763/2

GenAI Use

We follow OSRA's policy on GenAI tools

• I used a GenAI tool in this PR.
• I did not use GenAI

Generated-by: Bey Hao Yun

[xiyuoh]

Some spelling changes from the previous review were overlooked, commented them below. I think one last step before approving is to test this template out with robots in multi-storey environments (i.e. with lifts), with the new localize callback populated, so that we know this is working well. Let me know if you have any difficulty validating it.

[cardboardcode]

Will update again once the requested validation has been done. Will see if this can be done with rmf_demos hotel simulation.

[cardboardcode]

@xiyuoh ✔️ Validation test has been done with the following circumstances and components:

• Environment: Kabam Office
• Robot: LionsBot R3 Scrub Pro

Validation Test Description

The test involves having Robot take a mock lift in Kabam Office multiple times. It shows that, with the new localisation hook, fleet_adapter_lionsbot which is based on this proposed iteration of fleet_adapter_template is able to reliably complete a RMF lift-taking task in the form of patrol tasks.

See video attached below for proof:

robot_multiple_lift_taking.mp4

[xiyuoh]

@cardboardcode Thanks for testing and patiently waiting for a review, it's great that this works! Just wanted to double check, any idea what's going on at 1:06? The robot disappeared from the L2 map when the localization hook was triggered at 1:00, but it re-appeared momentarily at 1:06 before disappearing for good.

[cardboardcode]

any idea what's going on at 1:06?

@xiyuoh Hmm... Good catch. Not exactly sure why Robot fleet marker flashed like that. I suspect the following occurred that might explain the observation:

1. Localisation hook was triggered.
2. Slow search through nav_graph.yaml to find matching target waypoint name (inside_lift_L2) using x, y fed from RMF Core.
3. RMF Core does not receive fleet adapter update.
   4. Robot fleet marker disappears. (at 1.00)
4. Slow search finishes.
5. RMF Core continues to receive fleet adapter update.
   7. Robot fleet marker appears again. (at 1.06)
6. Request to LionsBot API Cloud for map switching made.
7. Request to LionsBot API Cloud for localisation made (as seen by the yellow text behind RViz in terminal).
8. Robot map in LionsBot API Cloud updates to target map, L1_Kabam_Office .
9. LionsBot API Cloud updates Robot map in Robot status.
10. RMF Core continues to receive fleet adapter update with map changed.
    12. Robot fleet marker disappears again and appears in L1_Kabam_Office map in RViz. (at 1.12)

[xiyuoh]

Let's verify this with some logs, are you able to obtain the log output from your testing? Would it be possible to also run this again to check its reproducibility? I'm concerned we might accidentally introduce some unwanted behavior to the template, but if this happens to be a glitch/one-off inaccurate robot state update, then it's probably not an issue.

[cardboardcode]

@xiyuoh

Will run the test again and provide the log output. Probably next week, hopefully.

[cardboardcode]

@xiyuoh Just FYI. No actions needed.

Validation will be delayed on my side due to changing company circumstances. Will likely only be able to revisit this after End-Oct.

If there are any developers who have the bandwidth to help validate the added localisation hook, please proceed.