Here we will cover integrating a mobile robot fleet that offers the **Full Control** category of fleet adapter. 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.

Before such a fleet can be integrated, you will need to procure or produce a route map as described in the [previous section](./integration_nav-maps.md). 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 needed, so it is a good idea to have a balance of comprehensiveness and leanness.

The C++ API for full-control automated guided vehicle (AGV) fleets can be found in the [`rmf_fleet_adapter`](https://github.com/osrf/rmf_core/tree/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv) package of the `rmf_core` repo. The API consists of four critical classes:

* [`Adapter`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv/Adapter.hpp) - 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`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv/FleetUpdateHandle.hpp) - 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`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv/RobotUpdateHandle.hpp) - Use this to update the position of a robot and to notify the adapter if the robot's progress gets interrupted.

* [`RobotCommandHandle`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv/RobotCommandHandle.hpp) - 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.

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`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/include/rmf_fleet_adapter/agv/parse_graph.hpp) 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`s 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](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_adapter/src/full_control/main.cpp). 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.

You may also choose to use Python to implement your fleet adapter. You can find Python bindings for the C++ API in [this repo](https://github.com/osrf/rmf_fleet_adapter_python). 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](https://swagger.io/tools/open-source/getting-started/) which can help you generate client code for the fleet's REST API server.

In this section, we will cover the prototype API for integrating the **Read Only** category of mobile robot fleets. This means we assume the mobile robot fleet manager only allows RMF to see updates about where its robots are located and where they intend to go, but it does not offer any control over where the robots are going or how they can move around. This type of adapter is primarily aimed at legacy systems that were developed before RMF and did not anticipate the possibility of a third-party being able to command the robots.

The Fleet Driver API was an experimental API developed in the early stages of the RMF research project. It can still be used for a read-only fleet adapter implementation until an officially supported C++ API comes out to replace it.

The Fleet Driver API uses ROS2 messages from the [`rmf_fleet_msgs`](https://github.com/osrf/rmf_core/tree/master/rmf_fleet_msgs) package. To use this API, you will want to write a ROS2 application (using either rclcpp or rclpy) which we will refer to as the *Fleet Driver*. The job of the Fleet Driver is to transmit [`rmf_fleet_msgs/FleetState`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_msgs/msg/FleetState.msg) messages out to the `"fleet_states"` topic.

Inside the `FleetState` message is the `name` field. Be sure to fill in the correct name for your fleet state. There is also a collection of [`rmf_fleet_msgs/RobotState`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_msgs/msg/RobotState.msg) messages. For integrating a read-only fleet with RMF, the most crucial fields of the `RobotState` message are:

* `name` - The name of the robot whose state is being specified.

* `location` - The current location of the robot.

* `path` - The sequence of locations that the robot will be traveling through.

Inside the [`rmf_fleet_msgs/Location`](https://github.com/osrf/rmf_core/blob/master/rmf_fleet_msgs/msg/Location.msg) message, the `t` field (which represents time) is generally ignored by the read-only fleet adapter. We assume that it is too cumbersome for your Fleet Driver to make timing predictions, so we have the read-only fleet adapter make the predictions for you based on the traits of the vehicle.

For the prototype read-only integration, there are two applications that need to be launched:

1. The Fleet Driver mentioned above which you write specifically for your fleet's custom API

2. The `read_only` fleet adapter which must be launched through ROS2

To launch the fleet adapter, you will need to use `ros2 launch` and include `rmf_fleet_adapter/fleet_adapter.launch.xml` file with the required parameters filled in. An example of this using the XML front-end of ros2 launch [can be found in `rmf_demos`](https://github.com/osrf/rmf_demos/blob/master/demos/launch/include/adapters/caddy_adapter.launch.xml), copied below:

The critical parameters are:

* `fleet_name`: This must match the `name` value that the Fleet Driver gives to its `FleetState` messages.

* `control_type`: This must be `"read_only"`.

* `linear_velocity`, `angular_velocity`, `linear_acceleration`, and `angular_acceleration`: These are estimates of the kinematic properties of the vehicles. For the sake of effective scheduling, it is preferable to overestimate these values than underestimate them, so it is best to think of these parameters as upper bounds for the values.

* `footprint_radius`: The radius of physical space that the vehicle occupies. This should cover the maximum extent of the physical footprint.

* `vicinity_radius`: The radius around the robot in which other robots are forbidden to physically enter. It is assumed that another robot entering this radius will interfere with the ability of this robot to operate.

When the launch file and Fleet Driver application are both ready, you can launch them side-by-side and the integration of the read-only fleet adapter will be complete.

* **Full Control** *(API available)* - RMF is provided with live status updates and full control over the paths that each individual mobile robot uses when navigating through the environment. This control level provides the highest overall efficiency and compliance with RMF, which allows RMF to minimize stoppages and deal with unexpected scenarios gracefully.

* **No Interface** *(Not compatible)* - Without any interface to the fleet, other fleets cannot coordinate with it through RMF, and will likely result in deadlocks when sharing the same navigable environment or resource. This level will not function with an RMF-enabled environment.

Currently we provide a reusable C++ API (as well as Python bindings) for integrating the **Full Control** category of fleet. A preliminary ROS2-message API is available for the **Read Only** category, but that API will be deprecated in favor of a C++ API (with Python bindings available) in a future release. The **Traffic Light** control category is compatible with the core RMF scheduling system, but we have not yet implemented a reusable API for it. To implement a **Traffic Light** fleet adapter, a system integrator would have to use the core traffic schedule and negotiation APIs directly, as well as implement the integration with the various infrastructure APIs (e.g. doors, lifts, and dispensers).

The API for the **Full Control** category is described in the [Mobile Robot Fleets](./integration_fleets.md) section, and the **Read Only** category is described in the [Read Only Fleets](./integration_read-only.md) section.