How to integrate the fleet_adapter_template step by step?

[SuperTunaa]

Hi @Yadunund,
I'm trying to integrate my robot using this template but I want more describe about how to use fleet adapter with my robot. What files do I need to create besides fleeter adapter template. Can you explain step by step to me?

Environment:
Ubuntu 20.04 + ROS2 Galactic

Thank you in advance.

[Yadunund]

You'll need run all the other Open-RMF nodes. Take a look at the launch file here. For running with your robot, you can just replace this block with the instructions to run your fleet adapter.

Before that you would need to generate traffic lanes for your specific robot. Take a look at our documentation here to learn how to use rmf_traffic_editor to do so.

[SuperTunaa]

For running with your robot, you can just replace this block with the instructions to run your fleet adapter.

Replaced by running this file?

Before that you would need to generate traffic lanes for your specific robot. Take a look at our documentation here to learn how to use rmf_traffic_editor to do so.

I have a 0.yaml file created from ros2 run rmf_building_map_tools building_map_generator nav

Another question @Yadunund

1. Where can I find reference_coordinates robot in config.yaml.
2. Before running the fleet_adapter_template do I have to run the server? Because I see in the fleet_adapter_ecobot has sim-server
3. How does fleet adapter control robot. where can I see the command line?

[calvintanct]

Hello @Yadunund ,
I am currently exploring the fleet adapter, and I realize something, the reference coordinates for config.yaml only related to one RMF map and one robot map.
What should you do if the robot actually run on different map (e.g. the RMF run the robot on 10 different maps)?
How to reference each single map with different reference coordinates to align each different maps on RMF and robot?

[Yadunund]

@calvintanct apologies for the overdue response.

There are many ways to handle coordinate transforms for multiple maps. The approach in this template is very rudimentay and works best for a single set of transforms. Here are some ideas that come to mind:

1. Update the reference_coordinate YAML key to store a list of cooresponding coordinates for each level. Then update the fleet_adapter.py script to parse all the levels and generate the transforms for each. You'll then pass a dict of level_name:Transform objects to the RobotCommandHandle which can lookup the right transform depending on which level the robot is on.

reference_coordinates:
  level_1:
    rmf: [[20.33, -3.156],
          [8.908, -2.57],
          [13.02, -3.601],
          [21.93, -4.124]]
    robot: [[59, 399],
          [57, 172],
          [68, 251],
          [75, 429]]
  level_2:
    ...

2. You could have another ROS 2 node running that provides the transform information for each level. ie, its running a Service server which you can query and get a geometry_msgs::msg::Transform object (or your own msg). This way you can offload the responsibility of computing the transforms to an external node. Maybe on initialization of this adapter, you get all the transforms.

[cardboardcode]

Hi @SuperTunaa cc @xiyuoh

A step-by-step guide for fleet_adapter_template is being worked on.

Query 💬

Are there any specific details you would like to see in this guide?

Aiming to have the guide done by end of Oct or early Nov 2025.

Instructions 📘

While the guide is being done up, here are my own set of steps I do myself in integrating Fleet Adapters for newer custom robots using fleet_adapter_template:

1. Identify the following Application Programming Interface (API) RESTful endpoints on the robot in question:
   a. Post navigation command to Robot.
   b. Get battery level from Robot.
   c. Get positional values from Robot.
   d. Post localisation command to Robot.
   e. Post map switch command to Robot.
   f. Get navigation status from Robot.
   g. Get authentication token from Robot Cloud Server.
   h. Get current robot map name from Robot.
   i. Get activity/mission status from Robot.
   j. Get robot maps as image file from Robot.
   k. Post stop command to Robot.
   l. Post dock command to Robot.
   m. Post undock command to Robot.

2. Rename the following files to the specific package name:

├── fleet_adapter_template <--- RENAME TO NEW PACKAGE NAME
│   ├── config.yaml
│   ├── fleet_adapter_template <--- RENAME TO NEW PACKAGE NAME
│   │   ├── fleet_adapter.py
│   │   ├── __init__.py
│   │   └── RobotClientAPI.py
│   ├── package.xml
│   ├── resource
│   │   └── fleet_adapter_template <--- RENAME TO NEW PACKAGE NAME
│   ├── setup.cfg
│   ├── setup.py <--- MODIFY TO NEW PACKAGE NAME
│   └── test
│       ├── __init__.py
│       ├── test_copyright.py
│       ├── test_flake8.py
│       └── test_pep257.py
├── LICENSE
└── README.md

3. Complete python implementations in the placeholders for RobotClientAPI.py using the Step 1's identified API endpoints:

# ------------------------ #
# IMPLEMENT YOUR CODE HERE #
# ------------------------ #

Link to RobotClientAPI.py: Click Here

4. Populate config.yaml based on details of the robot you are attempting to integrate:

Doing so allows RMF to achieve the following 3 objectives for better integration:
a. Plan optimal trajectories given unique robotic attributes
b. Make calls to vendor-specific API servers
c. Align map transforms between RMF Map and Robot Map for all concerned floors.

For further details, please refer to this article on the ros2multirobotbook

Test/Verify 🧪/ ✔️

In order to test your custom fleet_adapter_template, you will need the following RMF components minimally:

1. RMF Core
2. RMF Dashboard (RMF-Web)
3. RMF API Server (RMF-Web)

With tasks issued from RMF-Web, RMF Core would dispatch tasks to your custom fleet_adapter_template.

Expected Behaviour 🟢

If your custom fleet_adapter_template can work in conjunction with the above RMF components to at least complete a basic RMF Patrol task, you have successfully (but also minimally) integrated fleet_adapter_template for your user-defined deployment.

Remarks 👁️‍🗨️

Aiming to close this issue once the guide has been created and shared on ros2multirobotbook.