Mobile Robot Fleet Integration

Here we will cover integrating a mobile robot fleet that offers the Full Control category of fleet adapter, as discussed in the RMF Core Overview chapter. This means we assume the mobile robot fleet manager allows us to specify explicit paths for the robot to follow, and that the path can be interrupted at any time and replaced with a new path. Furthermore, each robot's position will be updated live as the robots are moving.

Route Map

Before such a fleet can be integrated, you will need to procure or produce a route map as described in the previous section. The fleet adapter uses the route map to plan out feasible routes for the vehicles under its control, taking into account the schedules of all other vehicles. It will also use the route map to decide out how to negotiate with other fleet adapters when a scheduling conflict arises. The adapter will only consider moving the robots along routes that are specified on the route map, so it is important that the route coverage is comprehensive. At the same time, if there are extraneous waypoints on the route map, the adapter might spend more time considering all the possibilities than what should really be needed, so it is a good idea to have a balance of comprehensiveness and leanness.

C++ API

The C++ API for Full Control automated guided vehicle (AGV) fleets can be found in the rmf_fleet_adapter package of the rmf_core repo. The API consists of four critical classes:

  • Adapter - Initializes and maintains communication with the other core RMF systems. Use this to register one or more fleets and receive a FleetUpdateHandle for each fleet.
  • FleetUpdateHandle - Allows you to configure a fleet by adding robots and specifying settings for the fleet (e.g. specifying what types of deliveries the fleet can perform). New robots can be added to the fleet at any time.
  • RobotUpdateHandle - Use this to update the position of a robot and to notify the adapter if the robot's progress gets interrupted.
  • RobotCommandHandle - This is a pure abstract interface class. The functions of this class must be implemented to call upon the API of the specific fleet manager that is being adapted.
  • EasyTrafficLight - This is a simplified API of TrafficLight.hpp. It enables the traffic light fleet adapter to receive moving and waiting instructions from RMF. Also, use this to update the current position and path of a robot.

The basic workflow of developing a fleet adapter is the following:

  1. Create an application that links to the rmf_fleet_adapter library.
  2. Have the application read in runtime parameters in whatever way is desired (e.g. command line arguments, configuration file, ROS parameters, REST API calls, environment variables, etc).
  3. Construct a route graph for each fleet that this application is providing the adapter for (a single adapter application can service any number of fleets), and/or parse the route graph from a YAML file using the rmf_fleet_adapter::agv::parse_graph utility.
  4. Instantiate an rmf_fleet_adapter::agv::Adapter using Adapter::make(~) or Adapter::init_and_make(~).
  5. Add the fleets that the application will be responsible for adapting, and save the rmf_fleet_adapter::agv::FleetUpdateHandlePtr instances that are passed back.
  6. Implement the RobotCommandHandle class for the fleet manager API that is being adapted.
  7. Add the robots that the adapter is responsible for controlling. The robots can be added based on the startup configuration, or they can be dynamically added during runtime as they are discovered over the fleet manager API (or both).
    • When adding a robot, you will need to create a new instance of the custom RobotCommandHandle that you implemented.
    • You will also need to provide a callback that will be triggered when the adapter is finished registering the robot. This callback will provide you with a new RobotUpdateHandle for your robot. It is imperative to save this update handle so you can use it to update the robot's position over time.
  8. As new information arrives from the fleet manager API, use the collection of RobotUpdateHandle classes to keep the adapter up-to-date on the robots' positions.

An example of a functioning fleet adapter application can be found in the full_control backwards-compatability adapter. This is a fleet adapter whose fleet-side API is the "Fleet Driver API", which is a deprecated prototype API for the RMF Full Control category of fleet adapters. This fleet adapter exists temporarily to maintain backwards compatibility with the old "Fleet Driver" implementations and to serve as an example of how to implement a fleet adapter using the new C++ API.

Python Bindings

You may also choose to use Python to implement your fleet adapter. You can find Python bindings for the C++ API in the rmf_fleet_adapter_python repo. The Python bindings literally just port the C++ API into Python so that you can develop your fleet adapter using Python instead of C++. The above API and workflow are exactly the same, just in Python instead. This should be very useful for fleets that use REST APIs, because you'll have access to tools like Swagger which can help you generate client code for the fleet's REST API server.