Restructuring hardware integration chapter

src/SUMMARY.md

@@ -8,8 +8,16 @@
     - [The ROS API](./ros2_api.md)
 - [Traffic Editor](./traffic-editor.md)
 - [Simulation](./simulation.md)
-- [RMF Core](./rmf-core.md)
+- [RMF Core Overview](./rmf-core.md)
+    - [Frequently Asked Questions](./rmf-core_faq.md)
 - [SOSS](./soss.md)
-- [Hardware](./hardware.md)
+- [Integration](./integration.md)
+    - [Navigation Maps](./integration_nav-maps.md)
+    - [Mobile Robot Fleets](./integration_fleets.md)
+    - [Free Fleet](./integration_free-fleet.md)
+    - [Read-Only Fleets](./integration_read-only.md)
+    - [Doors](./integration_doors.md)
+    - [Lifts (Elevators)](./integration_lifts.md)
+    - [Workcells](./integration_workcells.md)
 - [User Interfaces](./ui.md)
 - [Security](./security.md)

src/integration.md

@@ -0,0 +1,25 @@
+<!-- # Requirements -->
+
+<!-- robot, door, lift, workcell, etc. integration with RMF
+
+    I have a door door
+    I have an elevator / I have a lift arrow_up_down
+    I have a workcell robot mechanical_arm
+    I have a loose mobile robot and would like to use FreeFleet (F5)
+        robot runs ROS 1
+        robot runs ROS 2
+        robot runs something that I wrote
+        robot runs something somebody else wrote and I can't change
+    I have some mobile robots with their own fleet manager(s)
+        it has a REST API or some other formal API (XMLRPC)
+        it has some other communication mechanism (SQL database, etc.) -->
+
+# Integration
+
+In this chapter, we will describe the integration requirements and basic steps to have hardware working with RMF. These include [mobile robots](#mobile-robots), [doors](#doors), [elevators](#elevators) and [workcells](#workcells). In each section, we will go through how to build the necessary ROS 2 packages and interfaces that are used by `rmf_core`, as well as possible scenarios where such interactions occur.
+
+In general, all the interactions can be summed up with this system architecture diagram,
+
+<img src="https://raw.githubusercontent.com/osrf/rmf_core/master/docs/rmf_core_integration_diagram.png">
+
+RMF uses ROS 2 messages and topic interfaces. Hence, in most cases we use components called Adapters to bridge between the hardware interfaces and RMF with some exception for robot fleets which also have fleet drivers as part of the process. Robot fleets will be further elaborated in the next few sections.

src/integration_doors.md

@@ -0,0 +1,25 @@
+
+## Doors
+
+### Map requirements
+
+Before a door can be properly integrated, be sure to draw up the door locations with the correct door names on the navigation graph using `traffic_editor`. The instructions to do so can be found in Chapter 3. Traffic Editor.
+
+### Integration
+
+Door integration is required when integrating RMF into a new environment. For hopefully obvious reasons, only automated doors can be integrated with RMF though it may be possible to trigger an alert to a designated human to open a manual door but this is not recommended. An automated door can be defined as an electronically powered door that is remotely controllable, either using a remote trigger or has been outfitted with a computing unit capable of commanding the door to open and close when needed, using certain interfaces.
+
+Doors can be integrated with RMF using a ROS 2 door node and a door adapter, which we sometimes refer to as a door supervisor. The block diagram below displays the relationship and communication modes between each component.
+
+<img src="images/doors_block_diagram.png">
+
+The door node will have to be implemented based on the make and model of the door that is being integrated in order to address the specific API of the door controller module. The communication protocol will also be dependent on the door and controller model, which might be some form of `REST`, `RPCXML`, etc. The door node is in charge of publishing its state and receiving commands over ROS 2, using the messages and topics listed below.
+
+| Message Types | ROS2 Topic | Description |
+|---------------|------------|-------------|
+| `rmf_door_msgs/DoorState` | `/door_states` | State of the door published by the door node
+| `rmf_door_msgs/DoorRequest` | `/door_requests` | Direct requests subscribed by the door node and published by the door adapter
+| `rmf_door_msgs/DoorRequest` | `/adapter_door_requests` | Requests to be sent to the door adapter/supervisor to request safe operation of doors |
+
+
+The door adapter stands in between the rest of the RMF core systems, fleet adapters, and the door node, and acts like a state supervisor ensuring that the doors are not acting on requests that might obstruct an ongoing mobile robot task or accidentally closing on it. It keeps track of the door state from the door node, and receives requests from the `adapter_door_requests` topic which are published by either fleet adapters or other parts of the RMF core system. Only when the door adapter deems that a request is safe enough to be performed, it will instruct the door node using a request. It should also be noted that direct requests sent to the door node, without going through the door adapter will be negated by the door adapter, to return it to its prior state in order to prevent disruptions during operations with mobile robots.

src/integration_fleets.md

@@ -0,0 +1,7 @@
+# Fleet Integration
+
+Here we will cover integrating a mobile robot fleet that offers the **Path** 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.
+
+## 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](./integration_nav-maps.md).

src/integration_free-fleet.md

@@ -0,0 +1,127 @@
+
+### Free Fleet
+
+In the event that the user wishes to integrate a standalone mobile robot which doesn't come with its own fleet management system, the open source fleet management system `free_fleet` could be used.
+
+The `free_fleet` system is split into a client and a server. The client is to be run on each of these standalone mobile robots alongside their navigation software and is intended to have direct control over the mobile robot while at the same time monitor its status and report back to the server. The client's base implementation is designed to allow interaction with different configurations of mobile robots yet report to the same server. This way, users are able to use `free_fleet` to manage a heterogenrous fleet of robots, each using different distributions of ROS, versions of ROS, navigation software, or onboard communication protocols.
+
+The server is run on a central computer and consolidates the incoming status updates from each client to be either visualized using a UI, or relayed upstream to RMF. The server also relays commands from the user via the UI or from RMF down to the clients to be executed. Each server can work with multiple clients at a time, hence it serves the role of a fleet management system. The server can be implemented and used as its own fleet management system or work with larger systems like RMF, bridging the gap between each mobile robot's API and RMF's API and interface.
+
+The communication between the `free_fleet` server and `free_fleet` clients is implemented using `CycloneDDS`, therefore we are not concerned if the mobile robot or central computer is running different versions of ROS.
+
+In this section, we will address 4 different approaches of using `free_fleet` to integrate with RMF, specifically the navigation stack used by the robot. Each approach maintains a similar systems architecture, which is illustrated in the simple block diagram below, but there are specific examples depending on the software choice for the navigation stack used by the robot developer.
+
+<img src="images/free_fleet_block_diagram.png">
+
+#### ROS 1 Navigation Stack
+
+An implementation of a `free_fleet` client that works with a ROS 1 navigation stack can be found in the [repository](https://github.com/osrf/free_fleet). The implementation expects the transforms of the mobile robot to be fully defined, the mobile robot to accept navigation commands via the `move_base` action library, as well as publishing its battery status published using the `sensor_msgs/BatteryState` message.
+
+After following the build instructions on the README on the mobile robot, the user can launch the client as part of their launch script while at the same time define the necessary parameters using `rosparam`. Below is a small snippet example of how a client can be launched, with its paramters defined,
+
+```xml
+<node name="free_fleet_client_node"
+    pkg="free_fleet_client_ros1"
+    type="free_fleet_client_ros1" output="screen">
+
+  <!-- These parameters will be used to identify the mobile robots -->
+  <param name="fleet_name" type="string" value="example_fleet"/>
+  <param name="robot_name" type="string" value="example_bot"/>
+  <param name="robot_model" type="string" value="Turtlebot3"/>
+
+  <!-- These are the topics required to get battery and level information -->
+  <param name="battery_state_topic" type="string" value="example_bot/battery_state"/>
+  <param name="level_name_topic" type="string" value="example_bot/level_name"/>
+
+  <!-- These frames will be used to update the mobile robot's location -->
+  <param name="map_frame" type="string" value="example_bot/map"/>
+  <param name="robot_frame" type="string" value="example_bot/base_footprint"/>
+
+  <!-- The name of the move_base server for actions -->
+  <param name="move_base_server_name" type="string" value="example_bot/move_base"/>
+
+  <!-- These are DDS configurations used between Free Fleet clients and servers -->
+  <param name="dds_domain" type="int" value="42"/>
+  <param name="dds_state_topic" type="string" value="robot_state"/>
+  <param name="dds_mode_request_topic" type="string" value="mode_request"/>
+  <param name="dds_path_request_topic" type="string" value="path_request"/>
+  <param name="dds_destination_request_topic" type="string" value="destination_request"/>
+
+  <!-- This decides how long the client should wait for a valid transform and action server before failing -->
+  <param name="wait_timeout" type="double" value="10"/>
+
+  <!-- These define the frequency at which the client checks for commands and
+  publishes the robot state to the server -->
+  <param name="update_frequency" type="double" value="10.0"/>
+  <param name="publish_frequency" type="double" value="1.0"/>
+
+  <!-- The client will only pass on navigation commands if the destination or first waypoint
+  of the path is within this distance away, otherwise it will ignore the command -->
+  <param name="max_dist_to_first_waypoint" type="double" value="10.0"/>
+
+</node>
+```
+
+The running `free_fleet` client will communicate with the nodes running on the robot via ROS 1, while publishing its state and subscribing to requests over DDS with the `free_fleet` Server.
+
+The current implementation of the `free_fleet` server is implemented with ROS 2 and communicates with RMF using the aforementioned ROS 2 message and topic interfaces of an RMF fleet adapter. The ROS 2 build instructions can also be found on the same repository. Similar to the client, a simple ROS2 wrapper has been implemented, and it can be started using a `.launch.xml` file like so,
+
+```xml
+<node pkg="free_fleet_server_ros2"
+    exec="free_fleet_server_ros2"
+    name="free_fleet_server_node"
+    node-name="free_fleet_server_node"
+    output="both">
+
+  <!-- Fleet name will be used to identify robots -->
+  <param name="fleet_name" value="example_fleet"/>
+
+  <!-- These are the ROS2 topic names that will be used to communicate with RMF -->
+  <param name="fleet_state_topic" value="fleet_states"/>
+  <param name="mode_request_topic" value="robot_mode_requests"/>
+  <param name="path_request_topic" value="robot_path_requests"/>
+  <param name="destination_request_topic" value="robot_destination_requests"/>
+
+  <!-- These are the DDS specific configurations used to communicate with the clients -->
+  <param name="dds_domain" value="42"/>
+  <param name="dds_robot_state_topic" value="robot_state"/>
+  <param name="dds_mode_request_topic" value="mode_request"/>
+  <param name="dds_path_request_topic" value="path_request"/>
+  <param name="dds_destination_request_topic" value="destination_request"/>
+
+  <!-- This determines the frequency it checks for incoming state and request messages,
+  as well as how often it publishes its fleet state to RMF -->
+  <param name="update_state_frequency" value="20.0"/>
+  <param name="publish_state_frequency" value="2.0"/>
+
+  <!-- These transformations are required when the frame of the robot fleet is
+  different from that of RMF globally. In order to transform a pose from the RMF
+  frame to the free fleet robot frame, it is first scaled, rotated, then
+  translated using these parameters -->
+  <param name="scale" value="0.928"/>
+  <param name="rotation" value="-0.013"/>
+  <param name="translation_x" value="-4.117"/>
+  <param name="translation_y" value="27.26"/>
+
+</node>
+```
+
+Furthermore, an example of this configuration can be found in the repository as well, under the packages `ff_examples_ros1` and `ff_exmaples_ros2`. This example launches the example simulation from `ROBOTIS`, shown [here](https://emanual.robotis.com/docs/en/platform/turtlebot3/simulation/#ros-1-simulation), which has a small simulated world with 3 Turtlebot3 mobile robots, each running its own ROS 1 navigation stack.
+
+After successful builds for both ROS 1 and ROS 2 workspaces, the simulation can be launched following [these instructions](https://github.com/osrf/free_fleet#turtlebot3-simulation), which also includes a ROS 2 `free_fleet` server, publishing fleet state messages and accepting mode and navigation requests over ROS 2 messages and topics.
+
+#### ROS 2 Navigation Stack
+
+An implementation for a robot using ROS 2 would be similar to a ROS 1 navigation stack described earlier. At this time, the ROS 2 `free_fleet` client is still under development. This section will be updated once the refactoring, implementation and testing has been completed.
+
+The same ready `free_fleet` server implementation in the repository will work in this scenario, as the interfaces provided by the fleet adapters are still the same ROS 2 messages and topics.
+
+If required in the meantime, users can implement their own `free_fleet` client, by working with the `free_fleet` library that contains the base implementation and API for the DDS communication. This will be further elaborated in the next section [Custom Navigation Stack](#custom-navigation-stack).
+
+#### Developer Navigation Stack
+
+In this implementation, it is assumed that the software running on the mobile robot was written by the robot developers themselves (or their immediate subcontractors) and the developers fully understand and have access to their robot's internal control software, API's and interfaces. This level of understanding and access will be necessary for implementing your own `free_fleet` client wrapper. The block diagram below illustrate this configuration.
+
+<img src="images/free_fleet_custom_config.png">
+
+Once the developer's `free_fleet` client is fully functional, it will be a simple task of launching the same ROS 2 `free_fleet` server as mentioned earlier in this section to work with the fleet adapters through ROS 2 messages and topics.

src/integration_lifts.md

@@ -0,0 +1,23 @@
+# Lifts (a.k.a. Elevators)
+
+## Map requirements
+
+Before a lift can be properly integrated, be sure to draw up the lift locations with the correct lift names and levels on the navigation graph using `traffic_editor`. The instructions to do so can be found in Chapter 3. Traffic Editor.
+
+## Integration
+
+Elevator integration will allow RMF to work over multiple levels, resolving conflicts and managing shared resources on a larger scale. Similar to door integration, the basic requirement is that the lift controller accepts commands using a prescribed protocol, `OPC` is one such example.
+
+The elevators will be integrated in a similar fashion as doors as well, relying on a lift node and a lift adapter. The following block diagram shows how each component works with each other.
+
+<img src="images/lifts_block_diagram.png">
+
+The lift node will act as a driver to work with the lift controller. An example of a lift node can be found in this [repository](https://github.com/sharp-rmf/kone_lift_controller). The node will publish its state and receive lift requests over ROS 2, using the messages and topics listed below.
+
+| Message Types | ROS2 Topic | Description |
+|---------------|------------|-------------|
+| `rmf_lift_msgs/LiftState` | `/lift_states` | State of the lift published by the lift node
+| `rmf_lift_msgs/LiftRequest` | `/lift_requests` | Direct requests subscribed by the lift node and published by the lift adapter
+| `rmf_lift_msgs/LiftRequest` | `/adapter_lift_requests` | Requests to be sent to the lift adapter/supervisor to request safe operation of lifts |
+
+A lift adapter subscribes to `lift_states` while keeping track of the internal and desired state of the lift in order to prevent it from performing any actions that might interrupt mobile robot or normal operations. The lift adapter performs this task by receiving lift requests from the fleet adapters and the RMF core systems and only relaying the instructions to the lift node if it is deemed appropriate. Any requests sent directly to the lift node, without going through the lift adapter, will also be negated by the lift adapter, to prevent unwanted disruption to mobile robot fleet operations.

src/integration_nav-maps.md

@@ -0,0 +1,36 @@
+# Route Map data requirements for integration with RMF
+
+## Motivation
+RMF uses robot route maps to predict the navigation paths of robots working in the environment. RMF generates path predictions for all active robots in the environment which can be used to proactively avoid conflicts between the various robot path plans. This is often referred to as "traffic management" in RMF. Along with the traffic management, RMF can help enable multi-fleet visualization to building/robot operations staff, improve scheduling of resources (such as lifts and corridors), reduce robot deadlock and more.
+
+Robot route maps in large buildings are complex and may evolve over time in response to customer requests and building renovations. As a result, RMF works best when scripts can automatically import robot route maps, and re-import them in the future after changes are made.
+
+## Minimum Map Information Required
+- list of waypoints or nodes
+  - name of waypoint
+  - level name (B1, L1, L2, etc.)
+  - (x, y) location in meters within the level
+  - any special properties or flags, such as:
+    - is this a dropoff/pickup parking point?
+    - is this a charger?
+    - is this a safe parking spot during an emergency alarm?
+- list of edges or "travel lanes" between nodes
+  - (start, end) waypoint names
+  - two-way or one-way traffic?
+    - if one-way, identify direction of travel
+  - any other information, such as speed limit along this segment
+
+## Format requirements
+We can write import scripts to handle virtually any "open" file format that contains the required information. This includes, in order of preference:
+  - YAML
+  - XML
+  - plain text (space or comma-separated ASCII, etc.)
+  - DXF
+  - DWG
+  - SVG
+
+#### Remark
+If the map data is provided in textual form, screenshots are helpful for "sanity-checking" the coordinate system and alignment with building features.
+
+## Traffic Editor
+If the robot route map does not exist yet, then the [traffic editor tool](./traffic-editor.md) can be used to help create one. The traffic editor tool will also export the route map in an RMF-friendly format.

src/integration_workcells.md

@@ -0,0 +1,3 @@
+## Workcells
+
+Work in progress.