Feature: Backup and Restore Fleet Adapters

rmf_fleet_adapter/CMakeLists.txt

@@ -33,9 +33,16 @@ set(dep_pkgs
   rmf_task_msgs
   rmf_traffic
   rmf_traffic_ros2
+  rmf_task_ros2
   rmf_battery
   rmf_task
+  rmf_task_sequence
   std_msgs
+  rmf_api_msgs
+  websocketpp
+  nlohmann_json
+  nlohmann_json_schema_validator_vendor
+  SQLite3
 )
 foreach(pkg ${dep_pkgs})
   find_package(${pkg} REQUIRED)
@@ -70,21 +77,29 @@ target_link_libraries(rmf_fleet_adapter
     rmf_traffic_ros2::rmf_traffic_ros2
     rmf_battery::rmf_battery
     rmf_task::rmf_task
+    rmf_task_sequence::rmf_task_sequence
+    rmf_task_ros2::rmf_task_ros2
     yaml-cpp
     ${rmf_fleet_msgs_LIBRARIES}
     ${rclcpp_LIBRARIES}
     ${rmf_task_msgs_LIBRARIES}
   PRIVATE
     rmf_rxcpp
+    nlohmann_json::nlohmann_json
+    rmf_api_msgs::rmf_api_msgs
     ${rmf_door_msgs_LIBRARIES}
     ${rmf_lift_msgs_LIBRARIES}
     ${rmf_dispenser_msgs_LIBRARIES}
     ${rmf_ingestor_msgs_LIBRARIES}
+    ${websocketpp_LIBRARIES}
+    nlohmann_json_schema_validator
+    ${SQLite3_LIBRARIES}
 )
 
 target_include_directories(rmf_fleet_adapter
   PUBLIC
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/rmf_api_generate_schema_headers/include> # for auto-generated schema headers
     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
     ${rmf_traffic_ros2_INCLUDE_DIRS}
     ${rmf_fleet_msgs_INCLUDE_DIRS}
@@ -96,6 +111,10 @@ target_include_directories(rmf_fleet_adapter
     ${rmf_lift_msgs_INCLUDE_DIRS}
     ${rmf_dispenser_msgs_INCLUDE_DIRS}
     ${rmf_ingestor_msgs_INCLUDE_DIRS}
+    ${rmf_api_msgs_INCLUDE_DIRS}
+    ${WEBSOCKETPP_INCLUDE_DIR}
+    ${nlohmann_json_schema_validator_INCLUDE_DIRS}
+    ${SQLite3_INCLUDE_DIRS}
 )
 
 if (BUILD_TESTING)
@@ -130,7 +149,10 @@ if (BUILD_TESTING)
       ${rmf_lift_msgs_INCLUDE_DIRS}
       ${rmf_dispenser_msgs_INCLUDE_DIRS}
       ${rmf_ingestor_msgs_INCLUDE_DIRS}
+      ${rmf_api_msgs_INCLUDE_DIRS}
       ${std_msgs_INCLUDE_DIRS}
+      ${WEBSOCKETPP_INCLUDE_DIR}
+      ${nlohmann_json_schema_validator_INCLUDE_DIRS}
   )
   target_link_libraries(test_rmf_fleet_adapter
     PRIVATE
@@ -143,7 +165,10 @@ if (BUILD_TESTING)
       ${rmf_ingestor_msgs_LIBRARIES}
       rmf_fleet_adapter
       rmf_utils::rmf_utils
+      rmf_api_msgs::rmf_api_msgs
       ${std_msgs_LIBRARIES}
+      ${websocketpp_LIBRARIES}
+      nlohmann_json_schema_validator
   )
 
   target_compile_definitions(test_rmf_fleet_adapter
@@ -453,17 +478,16 @@ target_include_directories(close_lanes
 
 # -----------------------------------------------------------------------------
 
-ament_export_targets(rmf_fleet_adapter HAS_LIBRARY_TARGET)
-ament_export_dependencies(
-  rmf_task
-  rmf_traffic_ros2
-  rmf_fleet_msgs
-  rmf_door_msgs
-  rmf_lift_msgs
-  rmf_ingestor_msgs
-  rmf_dispenser_msgs
+rmf_api_generate_schema_headers(
+  PACKAGE rmf_fleet_adapter
+  SCHEMAS_DIR ${CMAKE_CURRENT_LIST_DIR}/schemas
 )
 
+# -----------------------------------------------------------------------------
+
+ament_export_targets(rmf_fleet_adapter HAS_LIBRARY_TARGET)
+ament_export_dependencies(${dep_pkgs})
+
 install(
   TARGETS
     rmf_fleet_adapter
@@ -499,4 +523,3 @@ install(
 )
 
 ament_package()
-

rmf_fleet_adapter/include/rmf_fleet_adapter/StandardNames.hpp

@@ -60,6 +60,9 @@ const std::string DockSummaryTopicName = "dock_summary";
 const std::string LaneClosureRequestTopicName = "lane_closure_requests";
 const std::string ClosedLaneTopicName = "closed_lanes";
 
+const std::string TaskApiRequests = "task_api_requests";
+const std::string TaskApiResponses = "task_api_responses";
+
 } // namespace rmf_fleet_adapter
 
 #endif // RMF_FLEET_ADAPTER__STANDARDNAMES_HPP

rmf_fleet_adapter/include/rmf_fleet_adapter/agv/Adapter.hpp

@@ -93,10 +93,27 @@ class Adapter : public std::enable_shared_from_this<Adapter>
   ///
   /// \param[in] navigation_graph
   ///   Specify the navigation graph used by the vehicles in this fleet.
+  ///
+  /// \param[in] server_uri
+  ///   Specify the URI for the websocket server that receives updates on tasks
+  ///   and states. If nullopt, data will not be published.
+  ///
+  /// \param[in] backup_file_path
+  ///   Loads and logs backup data to the specified file. If the file already,
+  ///   exists the fleet handle will be restored to the last backup state. If
+  ///   the file does not exist, a new one will be created.
+  ///   If nullopt, the fleet adapter will not perform any backup/restore.
+  ///
+  /// TODO(YV): Add this param
+  /// \param[in] restore_from_backup
+  ///   If true, fleet adapter will be restored to last known backup state.
+  ///   [Not implemented yet]
   std::shared_ptr<FleetUpdateHandle> add_fleet(
     const std::string& fleet_name,
     rmf_traffic::agv::VehicleTraits traits,
-    rmf_traffic::agv::Graph navigation_graph);
+    rmf_traffic::agv::Graph navigation_graph,
+    std::optional<std::string> server_uri = std::nullopt,
+    std::optional<std::string> backup_file_path = std::nullopt);
 
   /// Create a traffic light to help manage robots that can only support pause
   /// and resume commands.

rmf_fleet_adapter/include/rmf_fleet_adapter/agv/FleetUpdateHandle.hpp

@@ -30,6 +30,11 @@
 
 #include <rmf_task/RequestFactory.hpp>
 
+#include <nlohmann/json.hpp>
+#include <rmf_task/Activator.hpp>
+#include <rmf_task_sequence/Phase.hpp>
+#include <rmf_task_sequence/Event.hpp>
+
 namespace rmf_fleet_adapter {
 namespace agv {
 
@@ -70,6 +75,131 @@ class FleetUpdateHandle : public std::enable_shared_from_this<FleetUpdateHandle>
     rmf_traffic::agv::Plan::StartSet start,
     std::function<void(std::shared_ptr<RobotUpdateHandle> handle)> handle_cb);
 
+  /// Confirmation is a class used by the task acceptance callbacks to decide if
+  /// a task description should be accepted.
+  class Confirmation
+  {
+  public:
+
+    /// Constructor
+    Confirmation();
+
+    /// Call this function to decide that you want to accept the task request.
+    /// If this function is never called, it will be assumed that the task is
+    /// rejected.
+    Confirmation& accept();
+
+    /// Check whether
+    bool is_accepted() const;
+
+    /// Call this function to bring attention to errors related to the task
+    /// request. Each call to this function will overwrite any past calls, so
+    /// it is recommended to only call it once.
+    Confirmation& errors(std::vector<std::string> error_messages);
+
+    /// Call this function to add errors instead of overwriting the ones that
+    /// were already there.
+    Confirmation& add_errors(std::vector<std::string> error_messages);
+
+    /// Check the errors that have been given to this confirmation.
+    const std::vector<std::string>& errors() const;
+
+    class Implementation;
+  private:
+    rmf_utils::impl_ptr<Implementation> _pimpl;
+  };
+
+  /// Signature for a callback that decides whether to accept a specific
+  /// category of task request.
+  ///
+  /// \param[in] description
+  ///   A description of the task that is being considered
+  ///
+  /// \param[in] confirm
+  ///   Use this object to decide if you want to accept the task
+  using ConsiderRequest =
+    std::function<void(
+      const nlohmann::json& description,
+      Confirmation& confirm)
+    >;
+
+  /// Allow this fleet adapter to consider delivery requests.
+  ///
+  /// Pass in nullptrs to disable delivery requests.
+  ///
+  /// By default, delivery requests are not accepted until you provide these
+  /// callbacks.
+  ///
+  /// The FleetUpdateHandle will ensure that the requests are feasible for the
+  /// robots before triggering these callbacks.
+  ///
+  /// \param[in] consider_pickup
+  ///   Decide whether to accept a pickup request. The description will satisfy
+  ///   the event_description_PickUp.json schema of rmf_fleet_adapter.
+  ///
+  /// \param[in] consider_dropoff
+  ///   Decide whether to accept a dropoff request. The description will satisfy
+  ///   the event_description_DropOff.json schema of rmf_fleet_adapter.
+  FleetUpdateHandle& consider_delivery_requests(
+    ConsiderRequest consider_pickup,
+    ConsiderRequest consider_dropoff);
+
+  /// Allow this fleet adapter to consider cleaning requests.
+  ///
+  /// Pass in a nullptr to disable cleaning requests.
+  ///
+  /// By default, cleaning requests are not accepted until you provide this
+  /// callback.
+  ///
+  /// \param[in] consider
+  ///   Decide whether to accept a cleaning request. The description will
+  ///   satisfy the event_description_Clean.json schema of rmf_fleet_adapter.
+  ///   The FleetUpdateHandle will ensure that the request is feasible for the
+  ///   robots before triggering this callback.
+  FleetUpdateHandle& consider_cleaning_requests(ConsiderRequest consider);
+
+  /// Allow this fleet adapter to consider patrol requests.
+  ///
+  /// Pass in a nullptr to disable patrol requests.
+  ///
+  /// By default, patrol requests are always accepted.
+  ///
+  /// \param[in] consider
+  ///   Decide whether to accept a patrol request. The description will satisfy
+  ///   the task_description_Patrol.json schema of rmf_fleet_adapter. The
+  ///   FleetUpdateHandle will ensure that the request is feasible for the
+  ///   robots before triggering this callback.
+  FleetUpdateHandle& consider_patrol_requests(ConsiderRequest consider);
+
+  /// Allow this fleet adapter to consider composed requests.
+  ///
+  /// Pass in a nullptr to disable composed requests.
+  ///
+  /// By default, composed requests are always accepted, as long as the events
+  /// that they are composed of are accepted.
+  ///
+  /// \param[in] consider
+  ///   Decide whether to accept a composed request. The description will
+  ///   satisfy the task_description_Compose.json schema of rmf_fleet_adapter.
+  ///   The FleetUpdateHandle will ensure that the request is feasible for the
+  ///   robots before triggering this callback.
+  FleetUpdateHandle& consider_composed_requests(ConsiderRequest consider);
+
+  /// Allow this fleet adapter to execute a PerformAction activity of specified
+  /// category which may be present in sequence event.
+  ///
+  /// \param[in] category
+  ///   A string that categorizes the action. This value should be used when
+  ///   filling out the category field in event_description_PerformAction.json
+  ///   schema.
+  ///
+  /// \param[in] consider
+  ///   Decide whether to accept the action based on the description field in
+  ///   event_description_PerformAction.json schema.
+  FleetUpdateHandle& add_performable_action(
+    const std::string& category,
+    ConsiderRequest consider);
+
   /// Specify a set of lanes that should be closed.
   void close_lanes(std::vector<std::size_t> lane_indices);
 
@@ -142,6 +272,7 @@ class FleetUpdateHandle : public std::enable_shared_from_this<FleetUpdateHandle>
   /// compatible with the requested payload, pickup, and dropoff behavior
   /// settings. The path planning feasibility will be taken care of by the
   /// adapter internally.
+  [[deprecated("Use the consider_..._requests functions instead")]]
   FleetUpdateHandle& accept_task_requests(AcceptTaskRequest check);
 
   /// A callback function that evaluates whether a fleet will accept a delivery
@@ -164,7 +295,7 @@ class FleetUpdateHandle : public std::enable_shared_from_this<FleetUpdateHandle>
   /// compatible with the requested payload, pickup, and dropoff behavior
   /// settings. The path planning feasibility will be taken care of by the
   /// adapter internally.
-  [[deprecated("Use accept_task_requests() instead")]]
+  [[deprecated("Use consider_delivery_requests() instead")]]
   FleetUpdateHandle& accept_delivery_requests(AcceptDeliveryRequest check);
 
   /// Specify the default value for how high the delay of the current itinerary
@@ -176,12 +307,31 @@ class FleetUpdateHandle : public std::enable_shared_from_this<FleetUpdateHandle>
   /// Get the default value for the maximum acceptable delay.
   std::optional<rmf_traffic::Duration> default_maximum_delay() const;
 
+  /// The behavior is identical to fleet_state_topic_publish_period
+  [[deprecated("Use fleet_state_topic_publish_period instead")]]
+  FleetUpdateHandle& fleet_state_publish_period(
+    std::optional<rmf_traffic::Duration> value);
+
   /// Specify a period for how often the fleet state message is published for
   /// this fleet. Passing in std::nullopt will disable the fleet state message
   /// publishing. The default value is 1s.
-  FleetUpdateHandle& fleet_state_publish_period(
+  FleetUpdateHandle& fleet_state_topic_publish_period(
     std::optional<rmf_traffic::Duration> value);
 
+  /// Specify a period for how often the fleet state is updated in the database
+  /// and to the API server. This is separate from publishing the fleet state
+  /// over the ROS2 fleet state topic. Passing in std::nullopt will disable
+  /// the updating, but this is not recommended unless you intend to provide the
+  /// API server with the fleet states through some other means.
+  ///
+  /// The default value is 1s.
+  FleetUpdateHandle& fleet_state_update_period(
+    std::optional<rmf_traffic::Duration> value);
+
+  // Do not allow moving
+  FleetUpdateHandle(FleetUpdateHandle&&) = delete;
+  FleetUpdateHandle& operator=(FleetUpdateHandle&&) = delete;
+
   class Implementation;
 private:
   FleetUpdateHandle();