diff --git a/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx b/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx index ee7a9147..43eb0e51 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/autonomy_api.mdx @@ -16,6 +16,49 @@ The OutdoorNav software publishes to the topics in this section either all the time or while an autonomous navigation missions is running. They can be used to monitor the behaviour of OutdoorNav. + +#### /assisted_teleop/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** The safe output velocity from the assisted teleop node +computes. If assisted teleop is enabled the UGV will use this velocity. + +#### /assisted_teleop/footprint + +  **Message Type:** geometry_msgs/Polygon + +  **Description:** The footprint that the assisted teleop node uses to compute +if it is in a collision state. + +#### /assisted_teleop/obstacle_map + +  **Message Type:** [clearpath_safety_msgs/ObstacleMap](definitions.mdx#msg-obstacle-map) + +  **Description:** The radial mapping of detected obstacles used to populate the joystick +on the OutdoorNav UI. + +#### /assisted_teleop/safe_path + +  **Message Type:** nav_msgs/Path + +  **Description:** The path used by assisted teleop to lookahead for collisions. + +#### /assisted_teleop/safety_footprints + +  **Message Type:** nav_msgs/Path + +  **Description:** Footprint sets used for detecting obstacles and slowing +down the robot to a standstill. The footprints are modular in size +according to the current velocity of the robot. + +#### /assisted_teleop/state + +  **Message Type:** [clearpath_safety_msgs/AssistedTeleopState](definitions.mdx#msg-assisted-teleop-state) + +  **Description:** The current state of the assisted teleop node including +any error conditions that may occur. + #### /control_selection/control_state   **Message Type:** [clearpath_control_msgs/ControlSelectionState](definitions.mdx#msg-control-selection-state) @@ -116,7 +159,7 @@ Unknown space that the robot uses to detect obstacles. #### /navigation/local_plan -  **Message Type:** nav_msgs/msg/Path +  **Message Type:** nav_msgs/Path   **Description:** The MPC local plan that the navigation uses to control the robot along the reference path. diff --git a/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx b/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx index fc20e59a..76842af3 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/definitions.mdx @@ -147,6 +147,49 @@ float32[] cn0 # The carrier-to-noise ratio of each connected satellite float64 correction_age # Age of RTK corrections. -1 indicates none received ``` +#### clearpath_mission_manager_msgs/msg/NetworkEdgeReq.msg {#storage-networkedgereq} + +``` +string start_point_id +string end_point_id + +float32 speed_limit + +float32 radius +``` + +#### clearpath_mission_manager_msgs/msg/NetworkMapState.msg {#storage-networkmapstate} + +``` +# The UUID of the map +string uuid + +# True if the map actually exists and was found +bool exists + +# The number of disconnected sub-graphs of the map +# Normally this will be 1 (i.e. the map is a single graph that is connected) +# but there are circumstances where the user may intentionally want 2+ disconnected graphs +# (e.g. a separate graph for each side of a fence, where the only connection between the two +# sides is an out-of-bounds, teleop-only road) +int32 num_subgraphs + +# If the map has any disconnected vertices, we enumerate them here by their ID +# If size_exceeded is true, this list may be empty or incomplete (see below) +string[] disconnected_point_ids + +# True if the map is too big for the validation to run on it +# Maps with more than 1000 vertices or 8000 edges will not be fully tests +bool size_exceeded +``` + +#### clearpath_mission_manager_msgs/msg/NetworkMapValidityState.msg {#storage-networkmapvaliditystate} + +``` +# Reports the validity of all network of paths maps registered with the mission manager +clearpath_mission_manager_msgs/NetworkMapState[] map_states +``` + #### clearpath_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} ``` @@ -165,6 +208,12 @@ clearpath_navigation_msgs/Waypoint[] waypoints # All tasks defined in the database clearpath_navigation_msgs/Task[] tasks + +# All network of paths missions in the database +clearpath_navigation_msgs/NetworkMission[] network_missions + +# All network of paths maps in the database +clearpath_navigation_msgs/NetworkMap[] network_maps ``` #### clearpath_mission_scheduler_msgs/msg/NextSchedule.msg @@ -539,6 +588,36 @@ uint8 trigger_type string message ``` +#### clearpath_safety_msgs/AssistedTeleopState.msg {#msg-assisted-teleop-state} + +``` +# Assisted teleoperation message indicating the current state of the protection + +uint8 STATE_ACTIVE = 0 +uint8 STATE_DISABLED = 1 +uint8 STATE_COLLISION_IMMINENT = 2 +uint8 STATE_STOPPED = 3 +uint8 STATE_COLLISION = 4 +uint8 STATE_ERROR = 5 +uint8 state + +uint8 ASSIST_ON = 100 +uint8 ASSIST_OFF_SERVICE = 101 +uint8 ASSIST_OFF_JOYSTICK_OVERRIDE = 102 +uint8 ASSIST_OFF_SENSOR_TIMEOUT = 103 +uint8 assist_off_trigger + +string error_message +``` + +#### clearpath_safety_msgs/ObstacleMap.msg {#msg-obstacle-map} + +``` +# Assisted teleoperation message indicating the threat level of obstacles surrounding the platform + +float32[] threat_level +``` + #### clearpath_safety_msgs/WatchdogStatus.msg {#msg-safety-watchdog} ``` @@ -647,6 +726,81 @@ uint32 gnss_samples --- bool success ``` +#### clearpath_mission_manager_msgs/srv/AddNetworkEdge.srv {#storage-addnetworkedge} + +``` +# The UUID of the map we're operating on +string map_id + +# The UUIDs of the start and end points for this edge +string start_point_id +string end_point_id + +# The operational radius around the edge +float32 radius + +# The speed limit when driving along this edge +float32 speed_limit + +# An additional cost factor to prioritize certain edges over others in the planner +# Higher costs -> edge is less likely to be included in the planned route +# Expected range is (0.0, 100.0) (exclusive range). +# Values outside the expected range will be treated as the default 1.0 +float32 cost_factor + +# If true, we add 2 edges, with the second one having inverted start and end points +bool symmetrical + +--- + +# The generated edge(s) +clearpath_navigation_msgs/NetworkEdge[] edges +``` + +#### clearpath_mission_manager_msgs/srv/AddNetworkPath.srv {#storage-addnetworkpath} + +``` +# The lat-lon locations of the points to add +float64[] latitudes +float64[] longitudes + +# The UUID of the map we're adding points to +string map_id + +# If true, bidirectional edges are added between the points +bool symmetrical + +--- +bool success +string message +``` + +#### clearpath_mission_manager_msgs/srv/AddNetworkPoint.srv {#storage-addnetworkpoint} + +``` +# The location of this point on the map +float64 latitude +float64 longitude + +# The UUID of the map we're adding this point to +string map_id + +# Optional list of node IDs in the map we want to connect to the new node +# This specifies edges originating in the given nodes, pointing to the new node +string[] connect_from + +# Optional list of node IDs in the map we want to connect to the new node +# This specifies edges originating at the new node, pointing to the nodes with the given UUIDs +string[] connect_to + +# If true, bidirectional edge are added between the nodes specified in connect_from and connect_to +bool symmetrical + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint point +``` #### clearpath_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} @@ -688,6 +842,38 @@ The `reverse` parameter was added in 0.9.0 ::: +#### clearpath_mission_manager_msgs/srv/CloneNetworkMap.srv {#storage-clonenetworkmap} + +``` +# The UUID of the map to clone +string uuid + +# The new name for the map +# If blank, the old map name will be re-used with -copy appended to the end +string new_name + +--- +# The newly-created copy of the original map, with a new name and new UUID +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/CloneNetworkMission.srv {#storage-clonenetworkmission} + +``` +# The UUID of the mission to clone +string uuid + +# The new name for the mission +# If blank, the old mission name will be re-used with -copy appended to the end +string new_name + +# If true, the order of the waypoints within the cloned mission are reversed +bool reverse +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/NetworkMission mission +``` + #### clearpath_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} ``` @@ -791,6 +977,9 @@ bool ok ``` # A list of UUIDs of items we want to delete string[] uuids + +# An optional ID of the parent object we're deleting from +string parent_id --- # A list of UUIDs that we were asked to delete, but failed to string[] failed_uuids @@ -814,6 +1003,21 @@ string data clearpath_navigation_msgs/Mission[] missions ``` +#### clearpath_mission_manager_msgs/srv/GetAllNetworkMaps.srv {#storage-getallnetworkmaps} + +``` +--- +clearpath_navigation_msgs/NetworkMap[] maps +``` + +#### clearpath_mission_manager_msgs/srv/GetAllNetworkMissions.srv {#storage-getallnetworkmissions} + +``` +--- +# An array of all Missions defined in the database +clearpath_navigation_msgs/NetworkMission[] missions +``` + #### clearpath_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} ``` @@ -848,6 +1052,25 @@ string uuid clearpath_navigation_msgs/Mission mission ``` +#### clearpath_mission_manager_msgs/srv/GetnetworkMap.srv {#storage-getnetworkmap} + +``` +# The UUID of the NetworkMap we want to retrieve +string uuid +--- +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/GetNetworkMission.srv {#storage-getnetworkmission} + +``` +# The UUID of the NetworkMission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/NetworkMission mission +``` + #### clearpath_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} ``` @@ -890,6 +1113,50 @@ clearpath_navigation_msgs/Mission mission clearpath_navigation_msgs/Mission mission ``` +#### clearpath_mission_manager_msgs/srv/ImportNetworkMap.srv {#storage-importnetworkmap} + +``` +# The map to import. UUIDs that do not already exist are added, but objects with existing UUIDs +# are re-used +clearpath_navigation_msgs/NetworkMap map +--- +# The imported map +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/ImportNetworkMission.srv {#storage-importnetworkmission} + +``` +# The mission to import. UUIDs that do not already exist are added, but objects with existing UUIDs +# are re-used +clearpath_navigation_msgs/NetworkMission mission +--- +# The imported mission +clearpath_navigation_msgs/NetworkMission mission +``` + +#### clearpath_mission_manager_msgs/srv/SplitNetworkEdge.srv {#storage-splitnetworkedge} + +``` +# Splits an edge on a NetworkMap to connect to a new point + +# The UUID of the map to edit +string map_id + +# The UUID of the edge we want to split +string edge_id + +# The position of the new point to create +float64 new_point_latitude +float64 new_point_longitude + +# If true, we also split the reverse edge (if it exists) +bool symmetrical +--- +# The map in its new state +clearpath_navigation_msgs/NetworkMap result +``` + #### clearpath_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} ``` @@ -909,6 +1176,161 @@ string[] waypoint_ids clearpath_navigation_msgs/Mission result ``` +#### clearpath_mission_manager_msgs/srv/UpdateNetworkEdge.srv {#storage-updatenetworkedge} + +``` +# The UUID of the map we're operating on +string map_id + +# The UUID of the edge to edit +string uuid + +# The UUIDs of the start & end points of the edge we're editing +# Ignored if null/empty +string start_point_id +string end_point_id + +# The operational radius around the edge +float32 radius + +# The speed limit when driving along this edge +float32 speed_limit + +# An additional cost factor to prioritize certain edges over others in the planner +# Higher costs -> edge is less likely to be included in the planned route +# Expected range is (0.0, 100.0) (exclusive range). +# Values outside the expected range will be treated as the default 1.0 +float32 cost_factor + +--- + +# The updated edge +clearpath_navigation_msgs/NetworkEdge result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkEdges.srv {#storage-updatenetworkedges} + +``` +# Update multiple edges in a single map + +# The UUID of the map we're operating on +string map_id + +# The UUIDs of edges to edit +string[] uuids + +# The operational radii around the edges +# Ignored if negative +float32[] radii + +# The speed limit when driving along the edges +# Ignored if negative +float32[] speed_limits + +# The cost factors of the edges +float32[] cost_factors + +--- + +# The updated edge +clearpath_navigation_msgs/NetworkEdge[] result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkMap.srv {#storage-updatenetworkmap} + +``` +string uuid + +string name +float32 default_radius +float32 default_speed_limit +--- +clearpath_navigation_msgs/NetworkMap result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkMission.srv {#storage-updatenetworkmission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The desired name for the new mission +string name + +# The additional configuration options +# see clearpath_navigation_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids + +# The ordered list of Task UUIDs to include in the on_start Task Array +string[] on_start_ids + +# The ordered list of Task UUIDs to include in the on_stop Task Array +string[] on_stop_ids + +# Boolean value indicating whether robot should attempt 'return to dock' behavior +# when battery level drops below return_to_dock_battery_level +bool return_to_dock_enabled + +# Dock UUID that the robot should return to for 'return to dock' behavior +string return_to_dock_id + +# Value from 0 to 1 indicating what charge level the robot will return to dock at +float32 return_to_dock_battery_level + +# Value from 0 to 1 indicating what charge level the robot should resume this mission at +# after returning to dock for recharging +float32 resume_mission_battery_level + +# Boolean value indicating whether 'network' level replanning should be performed +# in the event that a network edge is deemed un-traversable (e.g., due to obstacles) +bool network_replan_enabled + +--- +# The resulting Mission, with an auto-generated UUID is returned +clearpath_navigation_msgs/NetworkMission result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkPoint.srv {#storage-updatenetworkpoint} + +``` +# The UUID of the map we're working on +string map_id + +# The UUID of the point to edit +string uuid + +# The location of this point on the map +float64 latitude +float64 longitude + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkPoints.srv {#storage-updatenetworkpoints} + +``` +# The UUID of the map we're working on +string map_id + +# The UUID of the points to edit +string[] uuids + +# The location of the points on the map, in the same order as uuids +float64[] latitudes +float64[] longitudes + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint[] result +``` + #### clearpath_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} ``` @@ -965,6 +1387,17 @@ string[] task_ids clearpath_navigation_msgs/Waypoint result ``` +#### clearpath_mission_manager_msgs/srv/ValidateNetworkMap.srv {#storage-validatenetworkmap} + +``` +# Checks that a Network of Paths map is valid and error/warning-free + +# The UUID of the map to check +string uuid +--- +clearpath_mission_manager_msgs/NetworkMapState state +``` + #### clearpath_mission_scheduler_msgs/srv/CloneSchedule.srv {#scheduler-cloneschedule} ``` @@ -1238,7 +1671,7 @@ float32 percent_complete string uuid # Wait this long before starting the schedule (ros:Duration msg, so the units are secs/nsecs) -duration delay +duration delay --- # Did the schedule terminate successfully? bool success diff --git a/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx b/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx index b60ca9c5..406e009f 100644 --- a/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx +++ b/docs_outdoornav_user_manual/api/api_endpoints/mission_manager_api.mdx @@ -12,6 +12,12 @@ API provides the ability to write your own UI if desired. ### Topics Exported by Mission Manager +#### mission_manager/network_maps_validity + +**Message Type:** [clearpath_mission_manager_msgs/msg/NetworkMapValidityState](definitions.mdx#storage-networkmapvaliditystate) + +**Description:** Latched topic that publishes the validity state of all network of paths maps defined on the robot. + #### mission_manager/state **Message Type:** [clearpath_mission_manager_msgs/msg/StorageState](definitions.mdx#storage-storagestate) @@ -20,6 +26,27 @@ API provides the ability to write your own UI if desired. ### Services Exported by Mission Manager +#### mission_manager/add_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkEdge](definitions.mdx#storage-addnetworkedge) + +**Description:** Adds an edge between two vertices in a network of paths map. Edges are unidirectional, but symmetrical +edges can be added by setting `symmetrical` to `true`. + +#### mission_manager/add_network_path + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkEdge](definitions.mdx#storage-addnetworkpath) + +**Description:** Adds multiple points and edges to an existing network of paths map. Vertices are supplied in-order, +with edges automatically added between adjacent vertices. + +#### mission_manager/add_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkPoint](definitions.mdx#storage-addnetworkpoint) + +**Description:** Adds a single vertex to a network of paths map. The new vertex can optionally be connected to +existing vertices by specifying the connecting points' UUIDs. + #### mission_manager/add_task_to_waypoint **Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) @@ -56,6 +83,18 @@ The `reverse` parameter was added in 0.9.0 and is not available in older version ::: +#### mission_manager/clone_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneNetworkMap](definitions.mdx#storage-clonenetworkmap) + +**Description:** Create a deep-copy of a network of paths map + +#### mission_manager/clone_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneNetworkMission](definitions.mdx#storage-clonenetworkmission) + +**Description:** Create a deep-copy of a network of paths mission + #### mission_manager/clone_task **Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions.mdx#storage-gettask) @@ -64,7 +103,7 @@ The `reverse` parameter was added in 0.9.0 and is not available in older version #### mission_manager/clone_waypoint -**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions.mdx#storage-GetWaypoint) +**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions.mdx#storage-getwaypoint) **Description:** Create a deep-copy of a Waypoint. The new Waypoint will be renamed to have `-copy` at the end. All Tasks in the original Waypoint are also duplicated. @@ -81,6 +120,18 @@ In 0.8.0 onward, all missions are required to have unique names. Creating a mis ::: +#### mission_manager/create_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateNetworkMap](definitions.mdx#storage-createnetworkmap) + +**Description:** Create a new network of paths map + +#### mission_manager/create_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateNetworkMission](definitions.mdx#storage-createnetworkmission) + +**Description:** Create a new network of paths mission + #### mission_manager/create_task **Service Type:** [clearpath_mission_manager_msgs/srv/CreateTask](definitions.mdx#storage-createtask) @@ -119,6 +170,44 @@ deleted, as they may be referenced by other Missions. **Description:** Delete the missions with the given IDs. Waypoints that are part of these missions are not deleted, as they may be referenced by other Missions. +#### mission_manager/delete_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Delete an edge from a network of paths map + +#### mission_manager/delete_network_edges + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete multiple edges from a network of paths map + +#### mission_manager/delete_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete a network of paths map. All vertices and edges contained within the map are also deleted. + +#### mission_manager/delete_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete a network of paths mission + +#### mission_manager/delete_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Delete a vertex from a network of paths map. All edges that connect to this vertex at either end +are also deleted. + +#### mission_manager/delete_network_points + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete multiple vertices from a network of paths map. All edges that connect to the deleted vertices +are also deleted. + #### mission_manager/delete_orphan_objects **Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions.mdx#storage-deleteeverything) @@ -192,6 +281,18 @@ should subscribe to the `mission_manager/state` topic. **Description:** Get all Missions defined in the database. +#### mission_manager/get_all_network_maps + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllNetworkMaps](definitions.mdx#storage-getallnetworkmaps) + +**Description:** Get all network of paths maps defined in the database. + +#### mission_manager/get_all_network_missions + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllNetworkMissions](definitions.mdx#storage-getallnetworkmissions) + +**Description:** Get all network of paths missions defined in the database. + #### mission_manager/get_all_tasks **Service Type:** [clearpath_mission_manager_msgs/srv/GetAllTasks](definitions.mdx#storage-getalltasks) @@ -210,6 +311,18 @@ should subscribe to the `mission_manager/state` topic. **Description:** Get the Mission with the specified ID. +#### mission_manager/get_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetNetworkMap](definitions.mdx#storage-getnetworkmap) + +**Description:** Get the network of paths map with the specified ID. + +#### mission_manager/get_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetNetworkMission](definitions.mdx#storage-getnetworkmission) + +**Description:** Get the network of paths mission with the specified ID. + #### mission_manager/get_task **Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions.mdx#storage-gettask) @@ -274,6 +387,14 @@ service instead. ::: +#### mission_manager/split_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/SplitNetworkEdge](definitions.mdx#storage-splitnetworkedge) + +**Description:** Split an edge of network of paths map to create 2 edges connected to a new vertex between them. If +`symmetrical` is set to `true` the new edges will be bidirectional, otherwise only the edge going in one direction is +split. + #### mission_manager/update_mission **Service Type:** [clearpath_mission_manager_msgs/srv/UpdateMission](definitions.mdx#storage-updatemission) @@ -287,6 +408,42 @@ in an error. ::: +#### mission_manager/update_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdge](definitions.mdx#storage-updatenetworkedge) + +**Description:** Modify a network of paths edge + +#### mission_manager/update_network_edges + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdges](definitions.mdx#storage-updatenetworkedges) + +**Description:** Modify multiple network of paths edges + +#### mission_manager/update_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdge](definitions.mdx#storage-updatenetworkmap) + +**Description:** Modify a network of paths map + +#### mission_manager/update_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkMission](definitions.mdx#storage-updatenetworkmission) + +**Description:** Modify a network of paths map + +#### mission_manager/update_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkPoint](definitions.mdx#storage-updatenetworkpoint) + +**Description:** Modify a network of paths vertex + +#### mission_manager/update_network_points + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkPoints](definitions.mdx#storage-updatenetworkpoints) + +**Description:** Modify multiple network of paths vertices + #### mission_manager/update_task **Service Type:** [clearpath_mission_manager_msgs/srv/UpdateTask](definitions.mdx#storage-updatetask) @@ -298,3 +455,9 @@ in an error. **Service Type:** [clearpath_mission_manager_msgs/srv/UpdateWaypoint](definitions.mdx#storage-updatewaypoint) **Description:** Modify a Waypoint. All attributes of the Waypoint are replaced with the provided values. + +#### mission_manager/validate_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/ValidateNetworkMap](definitions.mdx#storage-validatenetworkmap) + +**Description:** Manually run the network of paths validation on a specific map. diff --git a/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx b/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx index 32daf5e7..333bd135 100644 --- a/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx +++ b/docs_outdoornav_user_manual/api/api_examples/api_examples.mdx @@ -7,7 +7,7 @@ toc_max_heading_level: 4 --- The OutdoorNav API examples are now available and accesible to everyone. A -[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along with some example scripts are available to build and use for our application. A few examples scripts follow with detailed explanations: @@ -15,6 +15,7 @@ A few examples scripts follow with detailed explanations: - [Execute Mission from File](./mission_from_file.mdx) - [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) - [Status Monitoring](./monitor_status.mdx) +- [Network of Paths](./network_of_paths.mdx) The documentation for the Python API library can be built following the instructions in the above linked GitHub repository. diff --git a/docs_outdoornav_user_manual/api/api_examples/network_of_paths.mdx b/docs_outdoornav_user_manual/api/api_examples/network_of_paths.mdx new file mode 100644 index 00000000..c5944070 --- /dev/null +++ b/docs_outdoornav_user_manual/api/api_examples/network_of_paths.mdx @@ -0,0 +1,764 @@ +--- +title: Network of Paths +sidebar_label: Network of Paths +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Overview + +Network of paths uses a directed graph to define the robot's valid driving area. When executing a mission the robot +plans its route to follow the edges of the graph to get from waypoint to waypoint. The exact route taken is dynamic +and may change depending on the robot's exact starting location, detected obstacles along some edges, and the geometry +of the graph itself. + +![](/img/outdoornav_images/parking_lot_map.png) + +:::note + +All services in the `mission_manager` namespace are provided by OutdoorNav's `misssion_manager` node. This node is part +of the `autonomy` docker service. + +::: + +## Creating a map + +To create a map, use the `/mission_manager/create_network_map` service: + +```python +#!/usr/bin/env python3 + +import rospy +from clearpath_mission_manager_msgs.srv import * + +rospy.init_node("map_maker_example") + +map_maker_service = rospy.ServiceProxy("/mission_manager/create_network_map", CreateNetworkMap) +map = map_maker_service("Example Map", 2.5, 1.0, [], []).result + +print(map) +``` + +This program produces an empty map with an automatically generated UUID: + +```yaml +name: "Example Map" +uuid: "c7c6bd2e-06dd-4f61-9ab0-f81fa896a915" +default_radius: 2.5 +default_speed_limit: 1.0 +points: [] +connections: [] +``` + +From here you can use the `/mission_manager/add_network_point` and `/mission_manager/add_network_edge` services to +add vertices and connect them. However, this can be very slow if your map is large. A faster way is to include the +vertices and edges in the request to create the map: + +```python +#!/usr/bin/env python3 + +import rospy + +from clearpath_mission_manager_msgs.msg import * +from clearpath_mission_manager_msgs.srv import * +from clearpath_navigation_msgs.msg import * + +# A tuple of (TAG, longitude, latitude, altitude), copied from a Google Earth KML file +# Tags are added manually to identify each coordinate +# The tag is used as a placeholder for the generated UUIDs to simplify defining the edges ourselves +COORDINATES = [ + ("A", -97.28322817327727,50.12300747122199,0), + ("B", -97.28217525643019,50.12171056479555,0), # the first intersection, connects to C and L + ("C", -97.28326793963477,50.11981930442499,0), # the second intersection, connects to D and H + ("D", -97.28483408203536,50.11926816962462,0), + ("E", -97.28486964915798,50.11761512315844,0), + ("F", -97.28166555083155,50.11758334859005,0), + ("G", -97.28229122963415,50.11952637327663,0), + ("H", -97.28167846932446,50.11913714171172,0), # the third intersection, connects to I and C + + # A dead-end side-branch + ("I", -97.28219097560832,50.11973533270263,0), # forks from H + ("J", -97.28249905504131,50.1199092365631,0), + ("K", -97.28242834054022,50.12013941719884,0), + + # Another dead-end side-branch + ("L", -97.28242899160524,50.12209511863426,0), # forks from B + ("M", -97.28246941874356,50.12229616417419,0), + ("N", -97.28325139122391,50.12230651895854,0), +] + +DEFAULT_RADIUS = 2.5 +DEFAULT_SPEED_LIMIT = 1.0 + +rospy.init_node("map_maker_example_2") + +map_maker_service = rospy.ServiceProxy("/mission_manager/create_network_map", CreateNetworkMap) +map = map_maker_service( + "Example Map", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT, + + # The vertices + # This is just a simple array of NetworkPoint objects. Each must have a unique ID, a one-letter tag in this + # example + [ + NetworkPoint(c[1], c[0], c[2]) for c in COORDINATES # Note that NetworkPoint uses latitude first! + ], + + # The edges. This defines the geometry of the map + # Edges are unidirectional, so we must manually add edges going in both directions where necessary + [ + NetworkEdgeReq("A", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("B", "A", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("B", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("C", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("C", "D", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("D", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("D", "E", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("E", "D", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("E", "F", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("F", "E", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("F", "G", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("G", "F", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("G", "H", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("H", "G", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("H", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), # end of the main road & loop + NetworkEdgeReq("H", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("H", "I", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("I", "H", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("I", "J", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("J", "I", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("J", "K", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("K", "J", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), # end of one fork + + NetworkEdgeReq("B", "L", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("L", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("L", "M", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("M", "L", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("M", "N", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("N", "M", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + ] +).result + +print(map) +``` + +The program's output looks like this: +```yaml +name: "Example Map" +uuid: "3b3bed4e-bcfb-40d4-bc2e-3d5e904890cf" +default_radius: 2.5 +default_speed_limit: 1.0 +points: + - + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + - + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + - + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + - + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + - + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + - + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + - + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + - + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + - + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + - + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + - + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + - + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + - + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + - + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 +connections: + - + uuid: "9152c6ee-6cb0-4a6a-a1a3-a156c137e10b" + start_point: + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "af77ee8c-9460-4c4a-bb23-d8eab4877bd8" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "077e176e-531a-4afa-9c55-48496ddb19a3" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "8f605876-10d0-43bf-ade3-4acec11b90a4" + start_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "98cdf58f-76d1-4b00-8119-44850b20c006" + start_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + end_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "94f20e66-aea9-4ea8-8029-31eba37ba800" + start_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "356d56a0-1165-48ef-87ab-b3e289b6d275" + start_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + end_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "40438b94-fd92-4e95-bb31-1737d235c8ca" + start_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + end_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "97e40361-123c-4f33-9dae-3bd293d5a001" + start_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + end_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "5ca07677-1ec9-4355-bfdb-f04801d18feb" + start_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + end_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "ac299ea0-18f0-42ed-ab82-01c4789c979d" + start_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + end_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "754ad065-c3e8-41de-b0c2-a32e7247db40" + start_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + end_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "dcd5ca9f-5ad7-4404-a6a2-c5ab8b3bb0f5" + start_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + end_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "66884078-ab62-439b-be51-3446cf92809e" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "948eca22-3bf2-443a-b117-a551c6503c2a" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "9e445547-0e42-4ba4-8411-6228288d3ae8" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "d15e27d7-e4aa-479c-b9bf-705c70ccbdfc" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "1295c8da-65df-4b5b-a214-f7579ad7179d" + start_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + end_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "be0f8c9f-0f42-4f9a-9140-050ac617cd10" + start_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + end_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "6b1a04c8-e5d9-441d-b7d2-5426070d210f" + start_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + end_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "bee2318d-0e19-427b-aa15-a5aa195212be" + start_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + end_point: + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "159619a1-9a8e-41d0-b41b-918b187ac70c" + start_point: + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + end_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "79e510bd-5f24-4251-9169-995f30212966" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "720679a5-2eda-4f21-b430-9ea34be3076d" + start_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "40fdd435-c7da-4e91-895b-e3dd3c872dbd" + start_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + end_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "fff60db8-90ce-484b-ba44-a0637263f727" + start_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + end_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "995875bd-55dd-418b-81cc-72f3d957d119" + start_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + end_point: + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "9fc59ccd-75a7-4b0a-ab3e-d3c6e9bd9fb9" + start_point: + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 + end_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 +``` + +Note that in the process of creating the map, all of the points' UUIDs have been regenerated. This is to ensure that +all points saved on the robot have unique identifiers. + +### Getting the coordinates for vertices + +The coordinates for the vertices in the example above were generated by drawing the desired paths using Google Earth's +path tool. The project was exported as a KML file, which can be opened in a text editor: + +```xml + + + + Untitled + + + + + + + + + normal + #__managed_style_1EF00888ED2FB5E604EF + + + highlight + #__managed_style_2832AC86D92FB5E604EF + + + + Main Path + + -97.28114320519418 + 50.1207190898435 + 255.3655780539208 + 1.174355479883316 + 0 + 35 + 1653.897493233089 + absolute + + #__managed_style_08F931B1C22FB5E604EF + + + -97.28322817327727,50.12300747122199,0 -97.28326793963477,50.11981930442499,0 -97.28483408203536,50.11926816962462,0 -97.28486964915798,50.11761512315844,0 -97.28166555083155,50.11758334859005,0 -97.28167846932446,50.11913714171172,0 -97.28229122963415,50.11952637327663,0 -97.28219097560832,50.11973533270263,0 -97.28249905504131,50.1199092365631,0 -97.28242834054022,50.12013941719884,0 + + + + + Side Path + + -97.28114320516248 + 50.1207190898435 + 255.3655780539208 + 1.174355479883316 + 0 + 35 + 1653.897493233089 + absolute + + #__managed_style_08F931B1C22FB5E604EF + + + -97.28217525643019,50.12171056479555,0 -97.28242899160524,50.12209511863426,0 -97.28246941874356,50.12229616417419,0 -97.28325139122391,50.12230651895854,0 + + + + + +``` + +![](/img/outdoornav_images/network-map-google-earth.png) + +The `` tags contain space-separated lists of the form `lon_0,lat_0,alt_0 lon_1,lat_1,alt_1 lon_2,lat_2,alt_2 ...`. +By copying these lists into Python and converting them to Lists or Tuples you can create the lists of coordinates: + +```python +# KML coordinates: +# +# -97.28217525643019,50.12171056479555,0 -97.28242899160524,50.12209511863426,0 -97.28246941874356,50.12229616417419,0 -97.28325139122391,50.12230651895854,0 +# + +lon_lat_alt = [ + (-97.28217525643019, 50.12171056479555, 0), + (-97.28242899160524, 50.12209511863426, 0), + (-97.28246941874356, 50.12229616417419, 0), + (-97.28325139122391, 50.12230651895854, 0) +] +``` + +## Executing a mission + +To execute a Network of Paths mission, you need to know the UUID of the mission to execute and the UUID of the map. The +UUIDs are generated when the objects are created, so you may need to search the available objects to determine the +appropriate mission & map if you have more than one. + +```python +from clearpath_mission_manager_msgs.msg import * +from clearpath_mission_manager_msgs.srv import * + +import actionlib +import rospy + +# 1) Get all of the Network of Paths maps and missions from the mission manager +all_maps_srv = rospy.ServiceProxy("/mission_manager/get_all_network_maps", GetAllNetworkMaps) +all_missions_srv = rospy.ServiceProxy("/mission_manager/get_all_network_missions", GetAllNetworkMissions) +maps = all_maps_srv() +missions = all_missions_srv() + +# Do a simple search for the map with the desired name +# You can replace the name, or search for any other attribute of the NetworkMap object +map = None +for m in maps: + if m.name == "My Map": + map = m + break + +# As above, but looking for the desired mission instead of the desired map +mission = None +for m in missions: + if m.name == "My Mission": + mission = m + break + + +# we have the map & the mission; we can run the mission +if map and mission: + # 1) create the actionlib client + mission_execution_client = actionlib.SimpleActionClient("/autonomy/network_mission", ExecuteNetworkMissionByUuidAction) + + # 2) create the goal + goal = ExecuteNetworkMissionByUuidGoal(mission.uuid, map.uuid) + + # 3) send the goal to the server + mission_execution_client.send_goal(goal) + + # 4) Wait for the mission to finish executing + mission_execution_client.wait_for_result() +``` diff --git a/docs_outdoornav_user_manual/faq.mdx b/docs_outdoornav_user_manual/faq.mdx index a086c447..374e05b3 100644 --- a/docs_outdoornav_user_manual/faq.mdx +++ b/docs_outdoornav_user_manual/faq.mdx @@ -10,7 +10,7 @@ toc_max_heading_level: 4 1. **How do I start, pause or stop a mission?** - A mission can be started in a few different ways, i) through the web user interface (See [Mission Execution](./web_user_interface/ui_autonomous_mode.mdx#mission-execution)) or, + A mission can be started in a few different ways, i) through the web user interface (See [Mission Execution](./web_user_interface/ui_waypoint_mode.mdx#mission-execution)) or, ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). 2. **When I start a mission the UGV does not move. What could be the @@ -101,7 +101,7 @@ ping 192.168.131.30 These types of warnings appear on the UI under two conditions: i) If the robot indicator (blue arrow on the UI) is not within 3.0 meters of the first Waypoint (the Green one on the UI). ii) If the robot is outside of the allowable navigable space (defined by the path contraint, default: 3.0 meters around the reference path). - Enable the visualization of the [path contraint](./web_user_interface/ui_autonomous_mode.mdx#constrained_path) and Teleop the robot back into the + Enable the visualization of the [path contraint](./web_user_interface/ui_waypoint_mode.mdx#constrained_path) and Teleop the robot back into the navigable space. 6. **How can I remove certain sensors from the collision avoidance pipeline?** @@ -127,7 +127,7 @@ ping 192.168.131.30 2. **How do I add a Task to a Waypoint on the UI?** - See [Add Task to Waypoint](./web_user_interface/ui_autonomous_mode.mdx#add-task) for information on how + See [Add Task to Waypoint](./web_user_interface/ui_waypoint_mode.mdx#add-task) for information on how to add a Task to a Waypoint. 3. **Why is the "Save Image" Task failing?** @@ -145,7 +145,7 @@ ping 192.168.131.30 5. **What to do if my custom task is not working?** Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) instructions. When adding the - custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_autonomous_mode.mdx#add-task) + custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_waypoint_mode.mdx#add-task) for your custom task are correct. 6. **Why are either of the GNSS Status indicator (POS and/or DIR) on the UI not Green?** diff --git a/docs_outdoornav_user_manual/features/assisted_teleoperation.mdx b/docs_outdoornav_user_manual/features/assisted_teleoperation.mdx new file mode 100644 index 00000000..74f5e010 --- /dev/null +++ b/docs_outdoornav_user_manual/features/assisted_teleoperation.mdx @@ -0,0 +1,105 @@ +--- +title: Assisted Teleoperation +sidebar_label: Assisted Teleoperation +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::danger SAFETY WARNING + +Making changes to any of the following variables will decrease system safety. It is recommended that users +only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + + +As of version 0.12.0, the OutdoorNav software contains an assisted teleoperation feature that will help users +teleoperate their UGV safely, without worry of colliding into obstacles. + +
+
+ +
Block Diagram of Assisted Teleoperation Twist Mux
+
+
+ + +The assisted teleoperation feature is intended to work with the following sources of velocity input: + +| Input source | Topic | +|--------------|--------| +| UI Joystick | `/ui_teleop/cmd_vel` | +| PS4 Controlller | `/bluetooth_teleop/cmd_vel` or `/joy_teleop/cmd_vel`| +| Logitech Controller | `/joy_teleop/cmd_vel` | + + +The Assisted teleop feature will **NOT** work on the following sources of velocity input: + +| Input source | Topic | +|--------------|-------| +| External Command | `/cmd_vel` | +| Keyboard Command | `/kb_teleop/cmd_vel` | +| Interactive Marker | `/twist_marker_server/cmd_vel` | + +The Assisted Teleoperation feature can be activated/deactivated according to your required application requirements. +This can be done by setting the **ENABLE_ASSISTED_TELEOP** environment variable in the +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. + +## Functionality + +The intended purpose for the assisted teleoperation feature is to provide some software level safety for users while they are teleoperating the UGV. +This feature is intended to solely provide software level safety and does not use any hardware level PLCs to trigger a motor disconnect. It is to be +treated as a tool that provides a sense of security to the user, such that they will not accidentally crash the UGV any obstacles. The feature +constantly monitors the 2D/3D LiDAR sensor data that it is provided and uses this information to control the velocity of the UGV. As the UGV +approaches obstacles, it will decrease the velocity of the UGV and will bring the UGV to a complete stop if the user continues to drive +towards the oncoming obstacle. + +For visualization details of the assisted teleoperation feature, please consult the [UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) page. + +### Enable/Disable from the UI + +From the OutdoorNav UI you are able to enable/disable the "Teleop Assist" by using the toggle that is located by the UI joystick. + +### Enable/Disable using Joystick + +To disable the "Teleop Assist" when driving the UGV with the PS4 or Logitech controllers, you will need to press and hold the following button: + +| Controller Type | Button | +|--------------|-------| +| PS4 controller | **O** | +| Logitech controller | **B** | + +### Error/Warnings + +OutdoorNav will throw warnings and display them on the UI related to the status of the assisted teleoperation feature. +Below are the errors/warnings you may see: + +| Error/Warning | Reason | +|---------------|--------| +| **"Error: Failed to communicate with the Assisted Teleop node"** | The assisted teleoperation node is not running or has crashed | +| **"Error: No sensors configured"** | The assisted teleoperation node is running but no sensors have been configured to be used as obstacle detection sources | +| **"Error: Invalid twist_mux configuration"** | The twists mux configuration has been modified and does not satisfy the requirements for safe operation under the requirements of assisted teleoperation | +| **"Error: Unknown platform type"** | The assisted teleoperation node cannot determine the type of platform you are on | +| **"WARNING: Assisted teleoperation OFF due to service"** | The UI toggle switch or the `/assisted_teleop/enable` service has disabled assisted teloperation | +| **"WARNING: Assisted teleoperation OFF due to joystick override"** | The enable/disable button on the UGV remote joystick has been pressed | +| **"WARNING: Assisted teleoperation OFF due to sensor timeout"** | Communication has been lost between the assisted teloperation node and one of the configured 2D/3D detection sensors. | +| **"Warning: Robot is in a collision state and cannot be driven while assisted teleop is enabled. Please disable assisted teleop to recover."** | The robot is is a state where is is too close to an obstacle. This will mostly occur when you are at a charge dock but may also occur if you are driving/rotating in a tight space. You may need to disable the Teleop Assist to continue remote operation | + + +## Limitations + +The assisted teleoperation features has similar limitations to those of our collision avoidance features. +Performance degradation will be experiences in rain and/or snow conditions, as well as in tall grass environments. +The assisted teleoperation feature also only work if obstacles are detected by the 3D sensors. If obstacles appear +in any of the UGVs blind spots, the assisted teleoperation feature will not prevent collision with these obstacles. diff --git a/docs_outdoornav_user_manual/features/collision_avoidance.mdx b/docs_outdoornav_user_manual/features/collision_avoidance.mdx index e9a983d6..bec48f5f 100644 --- a/docs_outdoornav_user_manual/features/collision_avoidance.mdx +++ b/docs_outdoornav_user_manual/features/collision_avoidance.mdx @@ -9,7 +9,7 @@ toc_max_heading_level: 4 :::danger SAFETY WARNING Making changes to any of the following variables may decrease system safety. It is recommended that users -only modify these parameters in consultation with Clearpath Robotics Support. +only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). ::: diff --git a/docs_outdoornav_user_manual/features/mission_scheduler.mdx b/docs_outdoornav_user_manual/features/mission_scheduler.mdx index 95c87061..aef2ea67 100644 --- a/docs_outdoornav_user_manual/features/mission_scheduler.mdx +++ b/docs_outdoornav_user_manual/features/mission_scheduler.mdx @@ -13,6 +13,13 @@ allows users to schedule groups of missions to run at a later time. These schedu For example, a user could create a schedule that will run 3 missions starting at 9 AM and run every hour 8 times. Once the last iteration is run, the schedule will disable itself and can be re-enabled to run again later. The view itself can be found in the image below and is elaborated further afterwards. +:::note + +Presently only Waypoint Missions can be scheduled with the scheduler. A future update will allow users to schedule both Map and +Waypoint Missions together in a single schedule. + +::: +
diff --git a/docs_outdoornav_user_manual/features/navigation.mdx b/docs_outdoornav_user_manual/features/navigation.mdx index 852097a0..d2e0284d 100644 --- a/docs_outdoornav_user_manual/features/navigation.mdx +++ b/docs_outdoornav_user_manual/features/navigation.mdx @@ -31,7 +31,7 @@ that we expose that may also be included to tune the feature. | Feature | Description | |-----------------------------|----------------------------------------| | **Collision Avoidance** | Collision avoidance is the UGV's ability to detect obstacles and stop/maneuver around the obstacle without any collisions. If `true`, the UGV will detect obstacles and if `false` no obstacles will be detected. Setting to `false` is not recommended and may cause harm to property or to individuals.

Environment Variable: `ENABLE_COLLISION_AVOIDANCE` (Default: `true`). | -| **Constrained Planning** | The constrained replanning feature, which is always enabled, restricts the area in which the UGV can plan paths. For example, if the default `PATH_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to 1) produce paths that drives it more than 3.0 meters from the initial path, and 2) fail to compute paths if the UGV is further than 3.0 meters from the any of the Waypoints. This allowable planning/navigation area can be shown on the map over the connecting lines between Waypoints. See [Constrained Replanning](../web_user_interface/ui_autonomous_mode.mdx#constrained_path) for further details.

Use the `PATH_CONSTRAINT` environment variable to modify the path constraint (in meters). | +| **Constrained Planning** | The constrained replanning feature, which is always enabled, restricts the area in which the UGV can plan paths. For example, if the default `PATH_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to 1) produce paths that drive it more than 3.0 meters from the initial path, and 2) fail to compute paths if the UGV is further than 3.0 meters from the any of the Waypoints. This allowable planning/navigation area can be shown on the map over the connecting lines between Waypoints. See [Constrained Replanning](../web_user_interface/ui_waypoint_mode.mdx#constrained_path) for further details.

Use the `PATH_CONSTRAINT` environment variable to modify the path constraint (in meters). | | **Path Smoothing** | Generate paths according to a specified turning radius.

Environment Variable: `ENABLE_DUBINS_PATH_SMOOTHER` (Default: `false`).

Use the `TURN_RADIUS` environment variable to modify the radius of the planned paths (in meters). | | **Stop Distance** | The stop distance feature allows the UGV to stop a predefined distance away from obstacles. This is useful if a UGV cannot drive in reverse and needs the required room in front of it to replan around an obstacle.

Environment Variable: `ENABLE_STOP_DISTANCE` (Default: `false`)

Use the `STOP_DISTANCE` environment variable to modify the stop distance (in meters). Note that if the stop distance is larger than 4.5 meters for the Clearpath Robotics Jackal and Husky UGVs, or 10.0 meters for the Clearpath Robotics Warthog UGV, the computational load will increase and may cause a decrease in performance in the navigation. | | **Delay Compensation** | The delay compensation feature is able to compensate for mechanical delay on UGVs where either the accelerator introduces delay into the linear velocity or the steering introduces delay in the angular velocity. This feature is not required for Clearpath Robotics UGVs as negligible delay is present in our system.

Environment Variable: `ENABLE_DELAY_COMPENSATION` (Default: `false`)

Use the `CONTROLLER_DELAY` environment variable to modify the amount of delay to be compensated (in milliseconds). | diff --git a/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx b/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx index c4d9dece..e7298e8a 100644 --- a/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx +++ b/docs_outdoornav_user_manual/getting_started/first_time_checklist.mdx @@ -97,11 +97,11 @@ related to this. Select the mission list and then click on `Add Mission` to create a new mission. To add new waypoints for the mission refer to -[Mission Creation](../web_user_interface/ui_autonomous_mode.mdx#mission-creation). +[Mission Creation](../web_user_interface/ui_waypoint_mode.mdx#mission-creation). ### ☐ After creating a new mission, can you execute the mission? -To execute a mission refer to [Mission Execution](../web_user_interface/ui_autonomous_mode.mdx#mission-execution). +To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#mission-execution). ### ☐ Are the cameras (if present) active in the view bar section when running the mission? diff --git a/docs_outdoornav_user_manual/getting_started/system_setup.mdx b/docs_outdoornav_user_manual/getting_started/system_setup.mdx index ed52d725..c8060f35 100644 --- a/docs_outdoornav_user_manual/getting_started/system_setup.mdx +++ b/docs_outdoornav_user_manual/getting_started/system_setup.mdx @@ -217,19 +217,10 @@ different tasks that can be accomplished while operating the UGV. - Overview of the buttons required to operate the UGV in Manual Mode (teleoperation). - - Instructions to send the UGV on autonomous navigation missions, - including: - - > - Adding Waypoints to the map - > - Creating missions - > - Viewing and updating missions - > - Adding task to missions, such as **Move PTZ** camera, - > **Save Image**, **Dock/Undock** UGV, **Wait**, etc.... - > - Start/Stop/Pause missions - - - Description of the docking procedures allowing the user to dock - and undock the UGV autonomously. Recovery instructions are also - described. + - Overview of how to send missions using the Map mode. + + - Overview of how to send missions using the Waypoint mode. + 2. **Application Programming Interface:** Details on how to control the UGV programmatically. 3. **OutdoorNav Features** Details on the features available as part of the diff --git a/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx index 8afafb7c..aeedd85f 100644 --- a/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx +++ b/docs_outdoornav_user_manual/getting_started/terminal_interface.mdx @@ -213,22 +213,17 @@ onav start ## Upgrading the OutdoorNav Software After receiving a notice that a new version of the OutdoorNav Software is -available, use the `onav install` command with the appropriate version. -Note that `onav install` runs the following commands in sequence: - -- `onav download` -- `onav configure` -- `onav upgrade` - -For example, to upgrade from 0.11.0 to 0.12.0, run the following command: +available, use the `onav upgrade` command with the appropriate version. +For example, to upgrade to the newest avialbel version that you are eligible +to receive, run the following command: ``` -onav install 0.12.0 +onav upgrade ``` :::note -The `download` step requires internet access to download the new software. +The upgrade requires internet access to download the new software. Confirm that the OutdoorNav Computer has internet access by running a command such as: diff --git a/docs_outdoornav_user_manual/release_notes.mdx b/docs_outdoornav_user_manual/release_notes.mdx index 8638b24a..18d52693 100644 --- a/docs_outdoornav_user_manual/release_notes.mdx +++ b/docs_outdoornav_user_manual/release_notes.mdx @@ -6,6 +6,43 @@ toc_min_heading_level: 2 toc_max_heading_level: 4 --- +## 0.12.0 + +### New Features +- Modified mission planning modes. Now includes: + - Map mode (which allows the user to create maps of an environment + and send mission using said map) + - Waypoint mode (which allows the user to create more direct mission + by placing waypoints directly on the Aerial overlay) +- Added an Assisted teleoperation feature to prevent robot collisions with + obstacles when it is being teleoperated. +- Added the upgrade command to the CLI tool. Customers can now upgrade their + software as long as they are eligible to be upgraded to the newest version. + Please contact [Support](./support.mdx) for more information. +- New visualization of status command in CLI tool +- Added a filebrowser extension to access/view the robot filesystem for easier + media access + +### API Features + +- Added new message definitions and service calls for the storage/editing of Maps + +### Bug Fixes + +- 1973: Fixed python “machineid” error during installation +- 2089: Fixed the no serial number on /platform/id topic +- 2169: Fixed the mission manager/scheduler still requesting during Teleop only mode + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect +- 2332: upgrading from 0.11 to 0.12.0 in teleoperation only configuration and Q62 + installed causes duplication of axis driver. Please contact [Support](./support.mdx) + if you run into this issue. +- 2344: Autonomy not going down during low-power mode +- 2360: Waypoint/Map modes use different mouse click to open context menus + ## 0.11.0 ### New Features @@ -44,7 +81,7 @@ toc_max_heading_level: 4 ### API Features -- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api)) +- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx)) - Mission.action added from_start and *start_waypoint_uuid* fields - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields - Message Definition changes @@ -136,7 +173,7 @@ toc_max_heading_level: 4 ### New Features - Goal terminology has been removed from the mission generation nomenclature (see - [Definitions](./web_user_interface/ui_autonomous_mode.mdx#definitions)) + [Definitions](./web_user_interface/ui_waypoint_mode.mdx#definitions)) Users can now add tasks, apply final headings, and set navigation tolerances to any Waypoint in a Mission. - Drag and Drop of Waypoints now available in Edit Mode. diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx index 05588284..1447f480 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_manual_mode.mdx @@ -18,25 +18,31 @@ methods that can be used to stop the moving UGV.
- +
Teleoperation Components
-1. **Speedometer:** An indicator of the UGV's current forward speed. +1. **Error/Warning Bar:** A bar along the top of the page reporting + the error or warning status of the Assisted Teleoperation feature. 2. **Joystick:** The joystick will allow the user to move the UGV manually from the UI. Motion can be sent to the UGV in 360° directions and the speed can be controlled by the distance of the - joystick from its neutral position. -3. **Sensitivity Scale:** A UGV-specific scale that controls the - maximum allowable UGV velocities at each level. The maximum linear - velocity is 1.0 meters per second and the maximum angular velocity - is 0.5 radians per second. The scale levels are 100%, 80%, 50% and - 20%, with the default set to 80%. -4. **Local Docking Buttons:** The local docking/undocking buttons used - to dock/undock the UGV through the teleop view. To dock, the UGV - must be within the predock distance and facing the dock before the - button is selected. + joystick from its neutral position. Four fixed direction buttons are + now present to move the UGV in purely forward/reverse directions or + clockwise/counter-clockwise. Finally, we overlay an obstacle map + on top of the joystick, representing obstacle distances from the + UGV. +3. **Speedometer:** An indicator of the UGV's current linear speed. +4. **Sensitivity Scale:** A UGV-specific scale that controls the + maximum allowable UGV velocities at each level. The default maximum + linear velocity is 1.0 meters per second and the maximum angular + velocity is 0.5 radians per second. These can be changed in the + [General Settings](./ui_overview.mdx#config-general-settings) page. + The scale levels are 100%, 80%, 50% and 20%, with the default set + to 80%. +5. **Teleop Assist Toggle:** The "Teleop Assist" toggle can be used to + enable/disable the Assisted Teleoperation feature. ## Monitor Wireless Strength diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_map_mode.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_map_mode.mdx new file mode 100644 index 00000000..b579ef50 --- /dev/null +++ b/docs_outdoornav_user_manual/web_user_interface/ui_map_mode.mdx @@ -0,0 +1,377 @@ +--- +title: Web UI Map Mode +sidebar_label: Web UI Map Mode +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +![](/img/outdoornav_images/gps_danger.png) + +Ensure that the [Safety](../safety.mdx) document has been +read and the Operator is aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +The Map Mode of OutdoorNav Software uses a set of robotic +navigation modules that allows the Operator(s) to define driveable paths and +then execute missions using these maps. The UGV leverages these paths +along with specified goal points to calculate a route. Operators can +define one-way or two-way paths, speed limits for paths, allowable +deviation distances from the paths and cost factors for each path. + +## Definitions {#definitions} + +The list below defines what a "Map" and "Mission" are in relation to the Map mode view. The list also includes +their relevant components. These terms are referred to throughout this page. + +- **Mission** A Mission is a set of one or more Goalpoints. +- **Map** A Operator created map that goes over the aerial view and is used to define valid driveable + areas for a mission. +- **Point** A map point used to help define a path. +- **Path** A connection between two points that the UGV can travel along for missions. Can be defined as + one way or two way. +- **Goalpoint** A Goalpoint is a mission relevant geographical point referenced by its + position relative to the datum in meters. These points are travelled to as part of the Mission. +- **Task** A Task is an automated activity or wait time implemented as + a ROS action at a specific event or Goalpoint. +- **GoToPoint** A Goalpoint that is independant of a mission. This point is meant to be a one off + position to send the UGV to. +- **Ghost point** A transparent point that is not part of the map. This + point appears between two other points when in map edit mode. The Operator can + drag and drop this ghost point to split a path. The newly created paths will + keep the same properties as the path that was split (speed limit, cost factor, etc. ) + +## Map Mode Bottom Bar + +
+
+ +
Map Mode Bottom Bar
+
+
+ +1. **Map List:** Contains the list of Maps that Operator(s) have + created. The system also performs a health check of the map + to ensure that the UGV can't get into a stuck state. This is + shown with various icons by the map's name. + + - Valid Map: Every path is + reachable within the map and the UGV should not become trapped. + + - Disconnected Points: + The map contains points that will trap the UGV if it navigates to it. The best example of these are one-way paths that + lead to dead ends. + + - Disconnected Maps: + There are groups of paths that are not connected and are treated as separate maps. This may be desired by the Operator but + it can lead to situations where the UGV has sections that aren't navigable. + +2. **Edit Map Toggle:** This toggle allows the Operator to start + creating Points and Paths for the current Map. The Operator will also be able to + drag and drop Points in this mode. Once this button is enabled, + the Path Type Button and Point Drop Button will be visible and useable. + + :::note + + If the toggle is enabled while an autonomous Mission is running, it + will cancel the current Mission. + + ::: + +3. **Map Panel Toggle:** View/Edit details of the current Map including number or points, paths, and default settings. + +4. **Path Type Button:** The Path connection button that is used to set the type of path being connected between + points (one-way/two-way). When in connection mode the button will be highlighted. + +5. **Point Drop Button:** Drops a point at the UGV's current location. This action can also be accomplished by pressing Shift + P. + +6. **Mission List** Contains the list of Missions that Operator(s) have created. + +7. **Edit Mission Toggle** This toggle allows the Operator to start creating Goalpoints and editing currently existing Goalpoints. Once this button + is enabled the Goalpoint Drop button will become visible and useable. + + :::note + + Only one mode at a time can be enabled. If Edit Mission is toggled the Edit Map Toggle will be set to false. + + ::: + +8. **Mission Panel Toggle:** View/Edit details of the current Mission including a list of the Goalpoints, Mission tasks, and Return to dock functionality. + +9. **Goalpoint Drop Button:** The Goalpoint indicator marker on the + bottom bar allows the Operator to place a Goalpoint at the location of the UGV. + This action can also be triggered by using the shortcut key combination Shift + X. + +## Map Creation {#mapCreation} + +Before creating a mission the Operator will need to first create a map that the UGV can use +to generate paths. First ensure that the UI is in "Map Edit Mode" (select the pencil icon in the bottom bar next to +the map selection drop down). Open the drop down menu and select the "Add Map" option. From here the Operator can create +a new map from scratch, clone the current map that is open or import a previously exported map. Once created the Operator can +start placing points and building paths. + +### Map Points + +To add points to the map, ensure that the UI is still in "Map Edit Mode" and click on the map. This will +add a point to the map and also trigger the "Connection Mode". The path type button (one-way/two-way) will +turn blue to indicate that the next point that is added will be connected to the previously created point. +A Operator may cancel this connection by pressing the ESC key or by clicking the path type button. Points can be +dragged and dropped to adjust their positions. To delete a point, right click the point and select Delete. + +While in edit mode, Ghost points will appear in the center of each path that can be dragged and dropped to split the +path. + +### Map Paths + +Paths are generally added as part of the Point placement process as mentioned above. However, there may be +cases where a Operator would like to connect existing points. To accomplish this, simply exit out of connection mode +then click on the existing points. Once the first point is clicked on, connection mode will be re-established with +the previously clicked point as the starting location. + +As paths are added they will be visible in the Map properties table, along with their relevant details. To edit a +path's details a Operator can simply right click on the path or select the gear icon for the specific path in the table. +This will open an overlay on the map that will allow the Operator to edit both one-way paths and two-way paths. In the +case of two-way paths users can keep both ways in sync with each other or vary the properties depending on the +direction. + +
+
+ +
Editing a two-way path that's in sync
+
+
+ +### Map Panel + +
+
+ +
Map Panel
+
+
+ +Enable the "Map Panel" toggle to open the details of the current map. This table will +show the maps current default settings, the "Network Path Recorder" and the general +map details. The Operator can modify the maps name, default path properties and edit path's through this +view. + +### Rename Map + +To rename the Map click the Map name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Map Defaults + +When adding paths the map uses defined default values to set the maximum driving radius +and speed limit. If a Operator wishes to adjust these defaults this can be done here. This will +only affect paths created after the changes have been made. + +### Network Path Recorder + +An Operator can start a path recorder to place map points based on the UGV's position as it drives. +As the UGV drives a preview path will be generated to show generally where the path will be placed. +The Operator can then choose to save the path which will generate the relevant points and paths or cancel +the recording which will remove the preview. + +### Map Details + +The general map details includes the total number of points as well as a table that highlights each +path within the map. Operators can delete paths or edit paths through this table as needed. If a path is +one-way it will show a directional arrow next to it. Two-way paths are shown as a single row unless they +are out of sync regarding their cost factor, speed limit or maximum driving radius. + +## Mission Creation + +To create a new Mission first ensure that the UI is in "Mission Edit Mode" ( +select the rightmost pencil icon in the bottom bar). Then open the drop down menu in the bottom +bar and select the "Add Mission" option. This will allow the Operator to create a new Mission +which can then be defined with Goalpoints. + +### Goalpoint Mode + +To add new Goalpoints to a Mission while edit mode is enabled select the +"Goalpoint Mode" button. This will allow the Operator to place Goalpoints at +locations where the Operator clicks on the map. These will appear as a circle +with an arrow pointing in the direction the UGV will face upon arriving +at the Goalpoint. The arrow can be rotated by holding the CTRL key and dragging +the Goalpoint to the new direction. It can also be modified through the Mission Panel's Goalpoint Advanced Settings. +When not holding the CTRL key the Goal point can be dragged and dropped +to new locations in the same way as map Points. + +### Preview Path + +
+
+ +
Mission Path Preview
+
+
+ +As Goalpoints are placed on the map the system will generate a path preview based on the UGV's +location and the order the Goalpoints are placed in. This can be used to help determine the +general route the UGV will attempt to take. + +:::note + +** In order for the UGV to reach the Goalpoint it must be on a reachable path. The preview path will look like a segmented red line for any points that +the UGV cannot reach.** + +::: + +### Goalpoint Panel + +
+
+ +
Goalpoint Panel
+
+
+ +Enable the "Goalpoint Panel" toggle to open the list of available Goalpoints +within the selected Mission as shown in the figure above. The Operator can +now rearrange the list, add Tasks to the Goalpoints, and modify the final heading +and/or tolerance of each Goalpoint. The Operator can also modify mission properties such +as the mission name, a return to dock threshold, and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Return to Dock + +A Operator may wish to add a flag to the mission to indicate when and if the UGV should +return to the dock while executing the mission. When enabled, the Operator can input a +battery percentage that once reached the UGV will begin navigating back to the specified +dock or to the closest dock. They can then set the minimum battery life before the UGV +is expected to resume the mission. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### Rearrange List of Goalpoints + +Goalpoints can be rearranged in order of operation in the list. To do this, +enable the "Goalpoints Panel" toggle to access the list of Goalpoints. Here, the +Operator will be able to drag and drop the Goalpoints to reorder them. + +### Add Tasks to Goalpoint {#add-task} + +
+
+ +
Add Task to Goalpoint
+
+
+ +To add a Task to a Goalpoint: + +1. Click the "+" icon (beside the Gear icon) in the Goalpoint row the Task is + to be added to. + +2. Click the "Add Task" button that has appeared. + +3. Select the Task from the dropdown list. Standard Goalpoint icons will be + decorated accordingly depending on the task selected. Goalpoints in the + table will also have a small icon to indicate if tasks are assigned to the + Goalpoint accordingly. + +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Goalpoint. + If its not checked, the Mission will become cancelled upon the Task's failure. + +5. Click the Gear icon next to the selected Task to modify or add required Task testings. + +### Advanced Settings + +#### Goalpoint Heading + +When creating a Goalpoint, the Operator has the option of setting a final heading +for the Goalpoint. For example, when creating a Goalpoint at an inspection point, +the Operator may want the UGV to navigate and stop facing a certain +direction. In [Goalpoint Panel](#goalpoint-panel), the list of +Goalpoints can be seen and the advanced settings of each Goalpoint can be accessed +by clicking the "Gear" icon. + +To set the Goalpoint's final heading, the Operator will need to check the +"Final Heading Enabled" checkbox and enter the heading value in +degrees. The heading indicator on the top bar can be used to help set +this value. See the figure below showing the advanced settings. + +:::note + +Goalpoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
Goalpoint Advanced Settings
+
+
+ +This heading is the same heading that is applied to the Goalpoint icon's arrow direction. + +#### Goalpoint Tolerance + +When creating a Mission, the Operator has the option of setting a specific +tolerance for each Goalpoint. By default, the Goalpoint position and orientation +tolerances are 0.3 meters and 180°, respectively. If a specific Goalpoint +requires that the tolerances be either increased or decreased, these +values can be modified in the advanced settings. For example, if it's +required that the position and/or orientation at a Goalpoint be very accurate, +such as 0.1 meters position and 5° orientation, or looser at 1.0 meter +position, this can be done within these settings. + +In [Goalpoint Panel](#goalpoint-panel), the list of Goalpoints can be +seen and the advanced settings of each Goalpoint can be accessed by clicking +the "Gear" icon. To set the Goalpoint's tolerance, the Operator will need to +check the "Goalpoint Tolerance Enabled" checkbox and enter the position and +orientation values, in meters and degrees, respectively. + +## Mission Execution + +### Start Mission + +In the bottom bar of the UI, the Operator has the ability to start the currently selected Mission by +clicking the "Play" button . + +When a Mission has been started the Play button will turn green. + +### Pause Mission + +At the bottom of the UI, the Operator has the ability to pause the currently +running mission by clicking the "Pause" button . When the +mission has been paused this button will turn yellow. Pausing a mission +allows the Operator to take time to look around with the camera or to +teleoperate the UGV to a nearby location to perform an inspection. For +ease of operation, the Operator must PAUSE the active mission if the Operator +wants to teleoperate the UGV. + +### Cancel Mission/Task + +At the bottom of the UI, the Operator has the ability to stop the currently +running mission or task by clicking the "Stop" button . When the +mission/task has been cancelled this button will turn red. The name of +the mission/task will be shown to be cancelled in the feedback bar. + +### Navigate to GoToPoint + +
+
+ +
GoToPoint with preview path
+
+
+ +When a Map has been created a user can right click on a path or a path's driveable area to place a GoToPoint. This +point will be a single point that will also create a small overlay to allow users to start or cancel the "Go To" +execution. Before starting the execution the GoToPoint can be dragged to any driveable area or rotated using the CTRL +key just like with Goalpoints. diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx index 8919c358..132e5b41 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_overview.mdx @@ -22,7 +22,7 @@ mode.
1. **Menu:** A dropdown menu allowing the user to access the Dashboard - (ie. Home), Settings, Status, Scheduler and Help pages. The Operator + (ie. Home), Settings, Status, Scheduler, Help, and File pages. The User can also run the UI Virtual Tour from this menu. 2. **Feedback Bar:** The feedback bar will display information @@ -67,44 +67,26 @@ mode. cellular connections a cellular indicator will appear next to the wifi icon with the currently active connection being highlighted in green. -10. **Views List:** A dropdown list of available views, detailed later +10. **Stack Light:** If a Stack Light is configured for the UGV its current status + will show here. + +11. **Views List:** A dropdown list of available views, detailed later in this section. Some of the available views are Map, Camera and 3D views, etc. -11. **Record Audio:** If the UGV is equipped with a microphone the user - can start/stop recording manually by clicking this icon. - -12. **Mission List:** View the list of Missions that Operator(s) have - created. +12. **Local Docking/Undocking:** The local docking/undocking buttons used + to dock/undock the UGV. The UGV must have it's charging adaptor facing the dock + when performing the local dock action. -13. **Edit Mission Toggle:** This toggle allows the Operator to start - creating Waypoints for the current Mission. The Operator will also be able to - drag and drop Waypoints in this mode. Once this button is enabled, - the Waypoint Mode will be available for selection. When a Mission is - started this toggle will be disabled (ie. the Operator will not be able - to modify/add Waypoints). +13. **Lights Control:** If the UGV is equipped with software controllable lights they can be + controlled through a simple drop down button as well as relevant hotkeys, + depending on the configuration. - :::note - - If the toggle is enabled while an autonomous Mission is running, it - will cancel the current Mission. - - ::: - -14. **Waypoint Panel Toggle:** View list of Waypoints in the current Mission. - -15. **Waypoint Drop Button:** The Waypoint indicator marker on the - bottom bar allows the Operator to place a Waypoint at the location of the UGV. - This action can also be triggered by using the shortcut key combination Shift + X. - -16. **Start Button:** Start the current Mission. - -17. **Pause Button:** Pause the current Mission. Pressing the start button - while paused will continue the current Mission. +14. **Record Audio:** If the UGV is equipped with a microphone the user + can start/stop recording manually by clicking this icon. -18. **Stop Button:** Cancel the Mission or Task that is currently being - executed. Pressing the start button while when stopped will restart - the list of steps in the current Mission. +15. **Mission Execution Buttons:** These buttons allow users to Start, Pause and Stop an + autonomous mission. By opening the dropdown list "Views", on the right side of the UI, the @@ -113,7 +95,6 @@ Operator can access the following views: - Map View - PTZ Camera View (if available) - Front/Back Camera View (if available) -- 3D View ## Map View @@ -127,28 +108,22 @@ Operator can access the following views: 1. **Zoom Buttons:** These buttons allow the user to zoom in/out of the map levels. 2. **Zoom-to-Fit Button:** This button will zoom the map to where there - is activity (ie. where the datum is set or where Waypoints have been + is activity (ie. where the datum is set or where features have been set on the map. -3. **Pointer Mode Button:** This button allows the user to move the map - and select point on the map to see their coordinate (lat/lon or - x/y). -4. **Waypoint Mode Button:** This button allows the user to place - Waypoints on the map. Users can also select existing Waypoints to - modify/delete them. -5. **UGV:** The blue arrow represents the UGV. Its location is its +3. **UGV:** The blue arrow represents the UGV. Its location is its position in the world frame and its orientation is the heading in the world frame. -6. **Base Station:** The yellow antenna icon is the last known location of +4. **Base Station:** The yellow antenna icon is the last known location of the base station based on the last survey performed. By clicking it the user will be presented with the base station's coordinates, when it was surveyed, and how many samples were taken during the survey. - -7. **Datum:** The blue Waypoint marker on the map view represents the +5. **Dock:** If a dock is configured for the UGV it will appear on the map in + this format. When in Waypoint mode the Docks pre-dock radius will appear as + a circle around the dock when in Edit Mission mode. +6. **Datum:** The blue Waypoint marker on the map view represents the location of the reference point (ie. (x,y)=(0,0)) of the world coordinate system. The world (ie. map) coordinate system is in the ENU convention. -8. **Scale:** The scale representing the ratio of a distance on the map - to the corresponding distance on the ground. ## Camera Views @@ -229,7 +204,7 @@ acquired by the VLP-16 LiDAR. ## System Configuration -### General Settings +### General Settings {#config-general-settings} The General settings section can be found in through the upper left hand menu and allows the Operator to modify general features of the UGV. @@ -266,6 +241,31 @@ toggle does not disable the path deviation distance feature. If the UGV is equipped with a Low Power Module this toggle allows the user to switch the UGV into a low power state that will drastically limit functionality but help conserve power. This mode is best used to help better facilitate charging while the UGV is not in use. +#### Joystick Max Speeds + +The Operator can choose to set the Maximum Linear Speed and the Maximum Angular Speed that the teleoperation will use. These are limited to the +maximum speeds of the UGV itself. + +### Aerial Overlay Settings + +
+
+ +
Aerial Overlay settings
+
+
+ +To access the Aerial Overlay Settings: Menu → Settings → Aerial Overlay: + +1. **Offset:** The map tiles used in this software are not + perfectly aligned with the real world. Therefore, the user may need + to apply an offset to the map so that the UGV's position in the + real world matches its position on the map. +2. **Change Datum:** The datum is represented by a blue marker on the + map and should be set to a location within 10km of the test site. + The user can change this value in the Map Settings page. Enter the + new values and click the "Set Datum" button. + ### Map Source Configuration The Web UI ships with access to free @@ -421,3 +421,203 @@ below. Once your map tiles are available on the network, you can follow the steps in [Using Custom Maps](#using_custom_maps) to have the Web UI use your custom tiles. + +## Autonomous Features + +There are presently 2 autonomous modes that the UGV can be used in, [Waypoint Mode](ui_waypoint_mode.mdx) and [Map Mode](ui_map_mode.mdx). +While each mode leverages different features, some are shared and are elaborated on here. + +:::note + +Some objects that appear on the overlay have context menus associated with them. However there is a known issue related to opening this context menu +between Autonomy modes. At present to open a context menu in the Waypoint Mode, left click the object, and when in Map Mode right click the object. +This issue will be reconciled in a future release. + +::: + +### Tasks + +When running a mission autonomously the user can assign tasks to various events. These tasks, along with their decoration icons, are found below: + +- Dock Robot: + Will dock the UGV to begin charging the UGV's + battery. There are 3 kinds of docking that can be used; Network, Radius and Local. + See [Autonomous Docking](#autonomous-docking) for more information on + the autonomous docking feature. + +- Move PTZ: + Will move the PTZ camera to the position selected + in the task settings. + + Settings: Select the camera position. See + [Pan-Tilt-Zoom (PTZ) View](ui_overview.mdx#ptz-view) for details on how to + save camera positions. + +- Save Image: + Will save an image using one of the UGV camera(s) + to the /opt/onav/saved_files/media/... directory and can be retrieved using a tool + such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which camera the image will be saved from. + +- / Start/Stop Video Recording: + Will start/stop recording video using one of the + UGV camera(s) to the /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which camera the recording will come from. + +- Start/Stop Audio Recording: + Will start/stop recording audio using one of the + UGV microphone(s) to the /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which microphone the recording will come from. + +- Undock UGV: + Will undock the UGV from the autocharge dock. Once + completed, the UGV can be sent on autonomous missions. It is + often recommended to place the undock task first in the list of Waypoints or as a start Mission Task; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + :::note + + If the users places the Undock Task in the start Mission event for a Waypoint Mission the first Waypoint should be + approximately 2-3 meters behind the UGV's docked position. + + ::: + +- Wait: + Will pause and wait for the specified number of + seconds at the end of the Waypoint. + + Settings: Enter the amount of time to wait, in seconds. + +- New Custom Task: + Creates a new custom task that is defined by the user. +
+
+ +
Custom Task Settings Dialog
+
+
+ + - Task Name: Task name that will show up in the list of available tasks on the UI. + - Action Server Name: The namespace of the custom task action server. + - Float CSV: A list of comma seperated float values that consist of the numerical inputs to the custom task. + - String CSV: A list of comma seperated string values that consist of the semantic inputs to the custom task. + + See the [Custom Tasks](../features/custom_tasks.mdx) section + for details on how to develop custom tasks for your application. + + +:::note + +If a Waypoint/Goalpoint has more than one task assigned to it, the icon will +be replaced with a sheet of paper icon like so: + +::: + +### Autonomous Docking + +
+
+ +
Dock Icon
+
+
+ +### Docking The UGV + +To dock the UGV autonomously the user can use the following methods: + +#### Dock (Local) + +If there is a valid dock within its driveable range the UGV will attempt to dock. +This docking method can be done by selecting the Dock button in the bottom bar or by adding a +"Dock Robot (Local)" task to either an event or a mission point. + +#### Dock (Radius) + +If the UGV is within the specified docks radius the UGV will first navigate to a predock location +and then attempt to dock. When in Waypoint Mode a user can dock via this method as follows: + +- Enable the "Edit Mission" toggle. +- Maneuver the UGV so that is somewhere within the dock's radius. +- Click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Radius)" task to either +an event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +#### Dock (Network) + +:::note + +This mode is only available in [Map mode](ui_map_mode.mdx). Please see the Map mode page for further +details on map generation. + +::: + +If the UGV and the dock are within a map's driveable area the UGV will first navigate to a +predock location based on the map paths available. A user can dock manually using this method as follows: + +- Enable the "Edit Map" toggle. +- Maneuver the UGV so that is within the driveable range of the map. +- Ensure the dock is within the driveable range of the map. +- Right click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Network)" task to either an +event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +### Undocking The UGV + +To undock the UGV autonomously, the user can apply a "Undock Robot" task to a mission event or +point. The user can also click the Undock button in the bottom bar's left hand corner. + +### Compatibility with a Doghouse + +In order for the autonomous docking feature to be compatible with a doghouse, the +doghouse must conform to a few specifications: + +- Must be installed on a flat surface, and have no elevation change between the + charge-dock and the outdoor surface (ie. no ramp into the doghouse). +- Must be greater than 1.2 m wide. +- Must be between 1.5 and 2.5 m long. +- Dock target should be installed centered along the back of the doghouse. + +### Recover from Failed Docking or Undocking + +If for any reason, the docking or undocking tasks fail, the user can: + +- Manually drive the UGV towards the dock target, aligning the + charging unit with the receiver on the UGV. +- Manually drive the UGV in reverse away from the dock target. It is + suggested that the user reverse roughly 2-3 meters away from the target, + then wait 1-2 minutes before starting any autonomous navigation + missions. + +## Switching to IndoorNav + +If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. +To switch between the modes in OutdoorNav select the 'Navigation Mode' option found +in the hamburger menu. This will navigate to a page that shows the current mode and +provides an option to switch. When in IndoorNav mode the user may navigate to +the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen +below. + +
+
+ +
+
+ +:::note + +When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will +disable OutdoorNav UI features related to Autonomy but will still allow users the +option to view camera streams. + +::: \ No newline at end of file diff --git a/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx b/docs_outdoornav_user_manual/web_user_interface/ui_waypoint_mode.mdx similarity index 59% rename from docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx rename to docs_outdoornav_user_manual/web_user_interface/ui_waypoint_mode.mdx index 61acab87..daf67ed9 100644 --- a/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode.mdx +++ b/docs_outdoornav_user_manual/web_user_interface/ui_waypoint_mode.mdx @@ -1,6 +1,6 @@ --- -title: Web UI Autonomous Mode -sidebar_label: Web UI Autonomous Mode +title: Web UI Waypoint Mode +sidebar_label: Web UI Waypoint Mode sidebar_position: 3 toc_min_heading_level: 2 toc_max_heading_level: 4 @@ -39,26 +39,6 @@ These components are referred to throughout this manual. drag and drop this ghost waypoint to add a new waypoint to the mission between the other two waypoints. -## Map Settings - -
-
- -
Map settings
-
-
- -To access the Map Settings: Menu → Settings → Map: - -1. **Map Offset:** The map tiles used in this software are not - perfectly aligned with the real world. Therefore, the user may need - to apply an offset to the map so that the UGV's position in the - real world matches its position on the map. -2. **Change Datum:** The datum is represented by a blue marker on the - map and should be set to a location within 10km of the test site. - The user can change this value in the Map Settings page. Enter the - new values and click the "Set Datum" button. - ## Mission Creation To create a new Mission first ensure that the UI is in "Edit Mode" ( @@ -153,69 +133,6 @@ To add a Task to the end of a Mission: assigned to them based on placement). Waypoints in the table will also have a small icon to indicate if tasks are assigned to the Waypoint accordingly. - - Dock UGV: - Will dock the UGV to begin charging the UGV's - battery. See [Autonomous Docking](#autonomous-docking) - for more information on the autonomous docking feature. - - - Move PTZ: - Will move the PTZ camera to the position selected - in the task settings. - - Settings: Select the camera position. See - [Pan-Tilt-Zoom (PTZ) View](ui_overview.mdx#ptz-view) for details on how to - save camera positions. - - - Save Image: - Will save an image using one of the UGV camera(s) - to the **/opt/onav/saved_files/media/...** directory and can be retrieved using a tool - such as Filezilla. - - Settings: Select which camera the image will be saved from. - - - Start/Stop Video Recording: - Will start/stop recording video using one of the - UGV camera(s) to the **/opt/onav/saved_files/media/...** folder and can be retrieved - using a tool such as Filezilla. - - Settings: Select which camera the recording will come from. - - - Undock UGV: - Will undock the UGV from the autocharge dock. Once - completed, the UGV can be sent on autonomous missions. It is - often recommended to place the undock task first in the list of Waypoints or as a start Mission Task; - that way, the UGV will automatically continue towards its next - Waypoint once undocked. - - :::note - - If the users places the Undock Task in the start Mission event the first Waypoint should be - approximately 2-3 meters behind the UGVs docked position. - - ::: - - - Wait: - Will pause and wait for the specified number of - seconds at the end of the Waypoint. - - Settings: Enter the amount of time to wait, in seconds. - - - New Custom Task: - Creates a new custom task that is defined by the user. -
-
- -
Custom Task Settings Dialog
-
-
- - - Task Name: Task name that will show up in the list of available tasks on the UI. - - Action Server Name: The namespace of the custom task action server. - - Float CSV: A list of comma seperated float values that consist of the numerical inputs to the custom task. - - String CSV: A list of comma seperated string values that consist of the semantic inputs to the custom task. - - See the [Custom Tasks](../features/custom_tasks.mdx) section - for details on how to develop custom tasks for your application. 4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. If its not checked, the Mission will become cancelled upon the Task's failure. @@ -320,7 +237,7 @@ UGV is returned within the navigable area defined by the path contraint. ### Start Mission There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently -selected Mission by clicking the "Play" button . +selected Mission by clicking the "Play" button . Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on @@ -352,83 +269,3 @@ running mission or task by clicking the "Stop" button -
Dock Icon
- - - -### Docking The UGV - -To dock the UGV autonomously, the user should follow these steps: - -- Enable the "Edit Mission" toggle. -- Create a Mission whose Waypoints approach the dock from the front and - whose final Waypoint is within the maximum predock distance which is shown as a circle around the dock. -- Enable the Waypoints Panel toggle to view the list of Waypoints, rename the last - Waypoint to "Dock Waypoint" or something descriptive and add the "Dock - UGV" Task to this Waypoint. If there is more than one dock in the system the user will - have to open the task options and select the dock name from the list. -- Run the Mission. - -### Undocking The UGV - -To undock the UGV autonomously, the user should follow these steps: - -- Enable the "Edit Mission" toggle. Select the "Waypoint Mode" - button. -- Select the Waypoint icon on the bottom bar to create a Waypoint at the - current location of the UGV. This step should either be it's own mission - or it should be the starting point of a mission. -- Enable the Waypoints Panel toggle to view the list of Waypoints, rename this - Waypoint to "Undock Waypoint" or something descriptive and add the - "Undock UGV" task to the Waypoint that was just created. -- Run the Mission. - -### Compatibility with a Doghouse - -In order for the autonomous docking feature to be compatible with a doghouse, the -doghouse must conform to a few specifications: - -- Must be installed on a flat surface, and have no elevation change between the - charge-deck and the outdoor surface (ie. no ramp into the doghouse). -- Must be greater than 1.2 m wide. -- Must be between 1.5 and 2.5 m long. -- Dock target should be installed centered along the back of the doghouse. - -### Recover from Failed Docking or Undocking - -If for any reason, the docking or undocking tasks fail, the user can: - -- Manually drive the UGV towards the dock target, aligning the - charging unit with the receiver on the UGV. -- Manually drive the UGV in reverse away from the dock target. It is - suggested that the user reverse roughly 2-3 meters away from the target, - then wait 1-2 minutes before starting any autonomous navigation - missions. - -## Switching to IndoorNav - -If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. -To switch between the modes in OutdoorNav select the 'Navigation Mode' option found -in the hamburger menu. This will navigate to a page that shows the current mode and -provides an option to switch. When in IndoorNav mode the user may navigate to -the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen -below. - -
-
- -
-
- -:::note - -When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will -disable OutdoorNav UI features related to Autonomy but will still allow users the -option to view camera streams. - -::: \ No newline at end of file diff --git a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx index 3c9a1de4..9a5ff284 100644 --- a/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx +++ b/docs_versioned_docs/version-ros1noetic/robots/solutions/husky_observer/user_manual_husky_observer.mdx @@ -1331,8 +1331,8 @@ during the execution of the mission. #### Autonomous Missions {#autonomous-missions} Refer to the Outdoor Nav User Manual for details on the -[Autonomous Mode](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode), -including details on [Autonomous Docking](/docs_outdoornav_user_manual/web_user_interface/ui_autonomous_mode#autonomous-docking). +[Autonomous Mode](/docs_outdoornav_user_manual/web_user_interface/ui_overview#autonomous-features), +including details on [Autonomous Docking](/docs_outdoornav_user_manual/web_user_interface/ui_overview#autonomous-docking). #### Retrieving Results from Autonomous Missions diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json new file mode 100644 index 00000000..c123e1bc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "OutdoorNav User Manual", + "position": 1 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json new file mode 100644 index 00000000..a6e53920 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Application Programming Interface", + "position": 7 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/_category_.json new file mode 100644 index 00000000..21746ac4 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "API Endpoints", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx new file mode 100644 index 00000000..c65c4150 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/api_endpoints.mdx @@ -0,0 +1,16 @@ +--- +title: API Endpoints +sidebar_label: API Endpoints +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The ROS 1 Noetic API can be used to monitor and manage OutdoorNav Software. Details +are available through the child pages. + +- [Platform API](platform_api.mdx) +- [Autonomy API](autonomy_api.mdx) +- [Mission Manager API](mission_manager_api.mdx) +- [Definitions](definitions.mdx) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/autonomy_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/autonomy_api.mdx new file mode 100644 index 00000000..43eb0e51 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/autonomy_api.mdx @@ -0,0 +1,536 @@ +--- +title: Autonomy API +sidebar_label: Autonomy API +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Autonomy provides some relevant topics and services suitable for +controlling and monitoring the robot as it is performing autonomous +navigation. + +### Topics Published by Autonomy + +The OutdoorNav software publishes to the topics in this section either +all the time or while an autonomous navigation missions is running. They +can be used to monitor the behaviour of OutdoorNav. + + +#### /assisted_teleop/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** The safe output velocity from the assisted teleop node +computes. If assisted teleop is enabled the UGV will use this velocity. + +#### /assisted_teleop/footprint + +  **Message Type:** geometry_msgs/Polygon + +  **Description:** The footprint that the assisted teleop node uses to compute +if it is in a collision state. + +#### /assisted_teleop/obstacle_map + +  **Message Type:** [clearpath_safety_msgs/ObstacleMap](definitions.mdx#msg-obstacle-map) + +  **Description:** The radial mapping of detected obstacles used to populate the joystick +on the OutdoorNav UI. + +#### /assisted_teleop/safe_path + +  **Message Type:** nav_msgs/Path + +  **Description:** The path used by assisted teleop to lookahead for collisions. + +#### /assisted_teleop/safety_footprints + +  **Message Type:** nav_msgs/Path + +  **Description:** Footprint sets used for detecting obstacles and slowing +down the robot to a standstill. The footprints are modular in size +according to the current velocity of the robot. + +#### /assisted_teleop/state + +  **Message Type:** [clearpath_safety_msgs/AssistedTeleopState](definitions.mdx#msg-assisted-teleop-state) + +  **Description:** The current state of the assisted teleop node including +any error conditions that may occur. + +#### /control_selection/control_state + +  **Message Type:** [clearpath_control_msgs/ControlSelectionState](definitions.mdx#msg-control-selection-state) + +  **Description:** Indicates the complete state of control selection +including autonomy state and mode. + +#### /control_selection/current_mode + +  **Message Type:** [clearpath_control_msgs/ControlMode](definitions.mdx#msg-control-mode) + +  **Description:** Current control mode (NEUTRAL, MANUAL, AUTONOMY). + +#### /dock/feedback + +  **Message Type:** [clearpath_dock_msgs/DockActionFeedback](definitions.mdx#action-dock) + +  **Description:** Feedback topic from the dock action. + +#### /dock/result + +  **Message Type:** [clearpath_dock_msgs/DockActionResult](definitions.mdx#action-dock) + +  **Description:** Result topic from the dock action. + +#### /dock/properties + +  **Message Type:** [clearpath_dock_msgs/DockProperties](definitions.mdx#msg-dock-properties) + +  **Description:** A list of docks, in which each dock includes information related to +the location, id, etc... + +#### /dock/state + +  **Message Type:** [clearpath_dock_msgs/DockState](definitions.mdx#msg-dock-state) + +  **Description:** The current state of the docking process. + +#### /localization/odom + +  **Message Type:** nav_msgs/Odometry + +  **Description:** The robot's current pose and velocity. + +#### /localization/status + +  **Message Type:** [clearpath_localization_msgs/LocalizationStatus](definitions.mdx#msg-localization-status) + +  **Description:** Current localization status. Includes accuracy, GNSS +status, and whether the robot is dead reckoning. + +#### /mission/feedback + +  **Message Type:** clearpath_navigation_msgs/MissionActionFeedback + +  **Description:** Feedback topic from the mission action. + +#### /mission/result + +  **Message Type:** clearpath_navigation_msgs/MissionActionResult + +  **Description:** Result topic from the mission action. + +#### /navigation/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** This output commanded velocity from the autonomy +software (OutdoorNav) to control the velocity of the platform. It is +commonly relayed directly into the UGV's velocity controller. + +#### /navigation/distance_to_goal + +  **Message Type:** [clearpath_navigation_msgs/DistanceToGoal](definitions.mdx#msg-distance-to-goal) + +  **Description:** The current Euclidean distance and the path distance, +in meters, from the robot to its current goal. + +#### /navigation/footprint + +  **Message Type:** geometry_msgs/Polygon + +  **Description:** The footprint of the robot. + +#### /navigation/global_costmap + +  **Message Type:** nav_msgs/OccupancyGrid + +  **Description:** An occupancy grid consisting of the Free, Occupied or +Unknown space that the robot uses to plan paths in the environment. + +#### /navigation/local_costmap + +  **Message Type:** nav_msgs/OccupancyGrid + +  **Description:** An occupancy grid consisting of the Free, Occupied or +Unknown space that the robot uses to detect obstacles. + +#### /navigation/local_plan + +  **Message Type:** nav_msgs/Path + +  **Description:** The MPC local plan that the navigation uses to control +the robot along the reference path. + +#### /navigation/metrics + +  **Message Type:** [clearpath_navigation_msgs/Metrics](definitions.mdx#msg-metrics) + +  **Description:** This topic provides metric information regarding the lifetime of +the navigation. This includes the total distance travelled, duration run, as well as mission +information such as how many missions have been sent, how many have been completed and the number +of replanning maneuvers, recoveries and number of tasks executed. + +#### /navigation/motion_state + +  **Message Type:** [clearpath_navigation_msgs/MotionState](definitions.mdx#msg-motion-state) + +  **Description:** This topic provides information about the motion state +of the robot. This includes information about whether the robot is +moving or stopped. Whether it is about to make a turn and the direction +of the turn, and the direction of travel of the robot in regards to its +physical orientation. + +#### /navigation/odom_intent (IN DEVELOPMENT) + +  **Message Type:** [clearpath_navigation_msgs/OdomIntent](definitions.mdx#msg-odom-intent) + +  **Description:** The robot's current pose and velocity as well as an +intended pose and velocity in the immediate future. + +#### /navigation/path + +  **Message Type:** geometry_msgs/PoseArray + +  **Description:** The path that the robot is currently traversing. This +is initialized with the initial path and may be updated with paths +generated from replanning maneuvers. + +#### /navigation/progress (BETA) + +  **Message Type:** [clearpath_navigation_msgs/Progress](definitions.mdx#msg-navigation-progress) + +  **Description:** The completion percentage of the current path, the +current goal and the current mission. + +#### /navigation/safety_footprints + +  **Message Type:** geometry_msgs/PolygonStamped + +  **Description:** Footprint sets used for detecting obstacles and slowing +down the robot to a standstill. The footprints are modular in size +according to the current velocity of the robot. + +#### /navigation/scan_points (IN DEVELOPMENT) + +  **Message Type:** [clearpath_navigation_msgs/ScanPoints](definitions.mdx#msg-scan-points) + +  **Description:** Scans and pointclouds from the various ROS message +formats converted into a simple PointVector format that can be easily +consumed by the UI. + +#### /navigation/state (BETA) + +  **Message Type:** [clearpath_navigation_msgs/NavigationState](definitions.mdx#msg-navigation-state) + +  **Description:** The current navigation state. The available states are +COMPUTE PATH, EXECUTE, REPLAN, NAVIGATING AROUND OBSTACLE, RECOVERY, +IDLE, PAUSE, ESTOP, LOST. Multiple simultaneous states are possible. + +#### /navigation/track_error + +  **Message Type:** [clearpath_navigation_msgs/TrackError](definitions.mdx#msg-track-error) + +  **Description:** The current crosstrack error (ie. the off-path distance +between the robot and the reference path) and as well as the heading +error (ie. the difference between the current heading and the path +direction). + +#### /safety/safety_stop + +  **Message Type:** [clearpath_safety_msgs/Safety](definitions.mdx#msg-safety) + +  **Description:** Flag denoting if autonomy should be stopped due to any +of the following reasons: emergency stop active, one of the sensors has +triggered the safety monitor watchdog. + +#### /safety/watchdog_status (IN DEVELOPMENT) + +  **Message Type:** [clearpath_safety_msgs/WatchdogStatus](definitions.mdx#msg-safety-watchdog) + +  **Description:** Provides a list of status flags for each of the +possible sensors that may trigger a safety stop. The watchdog will +trigger if the sensor times out (ie. does not publish a relevant ROS +message for 1 second). + +#### /target_tracker/state + +  **Message Type:** [clearpath_dock_msgs/TargetTrackerState](definitions.mdx#msg-target-tracker-state) + +  **Description:** The state information for target tracker used as part of docking. + +#### /undock/feedback + +  **Message Type:** [clearpath_dock_msgs/UndockActionFeedback](definitions.mdx#action-undock) + +  **Description:** Feedback topic from the undock action. + +#### /undock/result + +  **Message Type:** [clearpath_dock_msgs/UndockActionResult](definitions.mdx#action-undock) + +  **Description:** Result topic from the undock action. + +------------------------------------------------------------------------ + +### Topics Subscribed to by Autonomy + +The OutdoorNav software subscribes to the topics in this section. They +can be used to control the behaviour of OutdoorNav. + +#### /platform/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** Platform-level commanded velocity. This should be the velocity tracked by the platforms velocity controller. + +#### /mission/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel all the missions that have +been sent to the OutdoorNav software. + +#### /mission/goal + +  **Message Type:** clearpath_navigation_msgs/msg/MissionActionGoal + +  **Description:** This topic is used to send a goal to the OutdoorNav +software. The goal can consist of a series of Waypoints and must include +a Goal point. + +#### /dock/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel the docking process that has been +initialized by a previously sent goal. + +#### /dock/goal + +  **Message Type:** [clearpath_dock_msgs/msg/DockActionGoal](definitions.mdx#action-dock) + +  **Description:** This topic is used to send a goal to the docking process. +The goal consists of the UUID of the dock to dock at as well as wether or not local docking +should be performed. + +#### /undock/cancel + +  **Message Type:** actionlib_msgs/GoalID + +  **Description:** This topic is used to cancel the undocking process that has been +initialized by a previously sent goal. + +#### /undock/goal + +  **Message Type:** [clearpath_dock_msgs/msg/UndockActionGoal](definitions.mdx#action-undock) + +  **Description:** This topic is used to send a goal to the undocking process. +The goal is empty since we always consider undocking to be a local undocking process. + +------------------------------------------------------------------------ + +### Services Exported by Autonomy + +#### /control_selection/set_mode + +  **Service Type:** [clearpath_control_msgs/srv/SetControlMode](definitions.mdx#srv-set-control-mode) + +  **Description:** Change the current control mode from NEUTRAL to MANUAL +or AUTONOMY. + +#### /control_selection/autonomy_pause + +  **Service Type:** std_srvs/SetBool + +  **Description:** Pause the autonomy when it is currently in AUTONOMY +mode. Will only pause when autonomy is active. + +#### /control_selection/autonomy_resume + +  **Service Type:** std_srvs/SetBool + +  **Description:** Resume the autonomy when it is current mode is in +AUTONOMY. Will only resume if the robot is in a paused state. + +#### /dock/add + +  **Service Type:** [clearpath_dock_msgs/srv/AddDock](definitions.mdx#srv-add-dock) + +  **Description:** Add a dock to the database of docks. Complete list of dock information is required as input. +The new dock will appear on the UI. + +#### /dock/remove + +  **Service Type:** [clearpath_dock_msgs/srv/RemoveDock](definitions.mdx#srv-remove-dock) + +  **Description:** Remove and existing dock from the database. Input to this service requires ether the UUID +or the semantic name of the dock. + +#### /dock/clear_data + +  **Service Type:** [std_srvs/srv/Trigger](definitions.mdx#srv-clear-dock-data) + +  **Description:** Remove all existing dock data from storage. + +#### /dock/set_location/by_id + +  **Service Type:** [clearpath_dock_msgs/srv/SetDockLocationByID](definitions.mdx#srv-set-dock-location-by-id) + +  **Description:** Can be used to either set up a new dock (empty string in the uuid field), or update +the location of an existing dock (where the `uuid` field is required). + +#### /dock/set_location/by_name + +  **Service Type:** [clearpath_dock_msgs/srv/SetDockLocationByName](definitions.mdx#srv-set-dock-location-by-name) + +  **Description:** Can be used to update the location of an existing dock. Requires the semantic name +of the dock to be input into the `name` field. + +#### /localization/set_datum + +  **Service Type:** [clearpath_localization_msgs/srv/SetDatum](definitions.mdx#srv-set-datum) + +  **Description:** This service is used to manually set the datum +parameters of OutdoorNav running on the UGV. After setting the datum +parameter, this service also reinitializes the states of the +localization according to the current sensor readings. If you are +sending a mission to the UGV without using the UI and through the API, +you must call this service before sending the mission. + +#### /localization/reset + +  **Service Type:** [clearpath_localization_msgs/srv/ResetLocalization](definitions.mdx#srv-reset-localization) + +  **Description:** This service can be used to trigger a reset of the UGVs localization. + +#### /navigation/set_collision_avoidance + +  **Service Type:** std_srvs/SetBool + +  **Description:** Modify the state of the collision avoidance feature. If +True, collision avoidance is ENABLED and the robot will use its lidar(s) +to detect and maneuver around obstacles. If False, collision avoidance +is DISABLED and the robot will NOT use its lidar(s) to detect and +maneuver around obstacles. Disabling this feature is not recommended and +should be used with caution. + +:::note + +1. This feature does not take effect immediately when the service is + called, but only takes effect at the next Goal. + +2. Disabling collision avoidance also disables the continuous planner, in such a case where the + continuous planner is enabled. When re-enabling the collision avoidance, + the continuous planner must also be re-enabled using the following API service. + +::: + +#### /navigation/set_continuous_planner + +  **Service Type:** std_srvs/SetBool + +  **Description:** Modify the state of the continuous planning feature. If +True, continuous planning is ENABLED and the robot will proactively +attempt to generate a path around detected obstacles. If False, +continuous planning is DISABLED and the robot will stop in front of +obstacles before generating a path around the obstacle. + +:::note + +1. This feature takes effect immediately once the service is called. +2. This service needs to be called if you are re-enabling the collision + avoidance and want the continuous planner to be active. Disabling + collision avoidance will have disabled the continous planner. + +::: + +#### /navigation/set_path_smoother + +  **Service Type:** [clearpath_navigation_msgs/srv/SetPathSmoother](definitions.mdx#srv-set-path-smoother) + +  **Description:** Modify the state of the path smoothing feature. If +True, path smoothing is ENABLED and curved paths will be generated +according to the specified turning radius. If False, path smoothing is +DISABLED and point-to-point paths will be generated. + +:::note + +This feature takes effect immediately once the service is called. + +::: + +#### /navigation/set_path shifter + +  **Service Type:** [clearpath_navigation_msgs/srv/SetPathShifter](definitions.mdx#srv-set-path-shifter) + +  **Description:** Modify the state of the path shifting feature. If True, +path shifting is ENABLED and the reference path will be automatically +shifted as it veers off the reference path (to prevent oscillations). If +False, path shifting is DISABLED and normal behaviour is active. + +:::note + +This feature takes effect immediately once the service is called. + +::: + +#### /navigation/set_stop_distance (IN DEVELOPMENT) + +  **Service Type:** [clearpath_navigation_msgs/srv/SetStopDistance](definitions.mdx#srv-set-stop-distance) + +  **Description:** Modify the state of the stop distance feature. If True, +the stop distance feature is ENABLED and the robot will stop the +specified distance from obstacles. If False, the stop distance feature +is DISABLED and the robot will stop the default distance from obstacles. + +#### /navigation/set_delay_compensation (IN DEVELOPMENT) + +  **Service Type:** [clearpath_navigation_msgs/srv/SetDelayCompensation](definitions.mdx#srv-set-delay-compensation) + +  **Description:** Modify the state of the delay compensation feature. If +True, delay compensation is ENABLED and the controller will compensate +for low-level mechanical delays. If False, delay compensation is +DISABLED and the normal behaviour is expected. + +------------------------------------------------------------------------ + +### Actions Exported by Autonomy + +#### /dock + +  **Action Type:** [clearpath_dock_msgs/action/Dock](definitions.mdx#action-dock) + +  **Description:** Send the robot to the charging dock, if the docking +package has been included. + +#### /localization/survey + +  **Action Type:** [clearpath_localization_msgs/action/SurveyBaseStation](definitions.mdx#action-survey-base-station) + +  **Description:** Start surveying the base station, if available. + +#### /mission + +  **Action Type:** [clearpath_navigation_msgs/action/Mission](definitions.mdx#action-mission) + +  **Description:** Send goals for execution by the robot. This will +include the goal, the waypoint(s), tasks, goal tolerances, goal +heading, a from_start flag, and an optional start_waypoint_uuid. + +#### /mission/by_id + +  **Action Type:** [clearpath_navigation_msgs/action/ExecuteMissionByUuid](definitions.mdx#action-execute-mission-by-uuid) + +  **Description:** Send goals for execution by the robot +according to the specific mission uuid. This will include the goal, the waypoint(s), tasks, +goal tolerances, goal heading, an optional start_waypoint_uuid, and a from_start flag. + +#### /undock + +  **Action Type:** [clearpath_dock_msgs/action/Dock](definitions.mdx#action-undock) + +  **Description:** Undock the robot to the charging dock, if the docking +package has been included. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/definitions.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/definitions.mdx new file mode 100644 index 00000000..76842af3 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/definitions.mdx @@ -0,0 +1,1729 @@ +--- +title: Definitions +sidebar_label: Definitions +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +### Message Definitions + +#### clearpath_control_msgs/ControlMode.msg {#msg-control-mode} + +``` +# Control mode message + +int8 NEUTRAL=0 +int8 MANUAL=1 +int8 AUTONOMY=2 + +int8 mode +``` + +#### clearpath_control_msgs/ControlSelectionState.msg {#msg-control-selection-state} + +``` +# The complete state of the control selection module. This message includes the autonomy state as well as the navigation mode. + +ControlState autonomy +ControlMode mode +``` + +#### clearpath_control_msgs/ControlState.msg {#msg-control-state} + +``` +# The autonomy state message, The autonomy can be either enabled/disabled and active/paused. + +bool enabled +bool paused +``` + +#### clearpath_dock_msgs/DockInfo.msg {#msg-dock-info} + +``` +# Message definition containing the information of a single dock. This includes identifiers, lat/lon and orientation of the location of a dock. + +string name +string uuid +string frame +string target_template + +# ISO 8601 date/time format of last successfull dock location setting +string last_location_set_time + +# maximum allowable distance to allow for predocking. (ie. the distance within which the dock waypoint must be located) +float32 max_predock_distance +# the distance from the dock that the robot will navigate to prior to start docking +float32 predock_distance + +# location of the dock +float64 latitude +float64 longitude +float64 heading +``` + +#### clearpath_dock_msgs/DockProperties.msg {#msg-dock-properties} + +``` +# Message definition containing the properties for each of the docks available. + +clearpath_dock_msgs/DockInfo[] docks +``` + +#### clearpath_dock_msgs/DockState.msg {#msg-dock-state} + +``` +# Message definition containing information on what state the docking process is in. + +uint8 UNDOCKED = 0 +uint8 DOCKED = 1 +uint8 IN_PROGRESS = 2 +uint8 FAILED = 3 +uint8 CANCELLED = 4 + +uint8 state +``` + +#### clearpath_dock_msgs/TargetTrackerState.msg {#msg-target-tracker-state} + +``` +# Message definition containing the state information of the target tracker. +# This includes whether or not the tracker is active, whether the target is visible/lost, and the target pose and score of that pose. + +bool active + +# flag indicates if the target is visible or not +bool target_locked + +geometry_msgs/PoseWithCovarianceStamped target_pose +float32 score + +# the distance of the sensor_link to the dock target +float64 distance_to_target +``` + +#### clearpath_localization_msgs/LocalizationStatus.msg {#msg-localization-status} + +``` +# Localization status message for all sources of localization + +std_msgs/Header header +float32 accuracy # IN DEVELOPMENT + +# status information related to the GPS receiver units +GNSSStatus position_gnss +GNSSStatus heading_gnss +GNSSStatus base_station_gnss + +bool dead_reckoning +``` + +#### clearpath_localization_msgs/GNSSStatus.msg {#msg-gnss-status} + +``` +# GNSS receiver status message + +uint8 POSITION_RECEIVER = 0 +uint8 HEADING_RECEIVER = 1 +uint8 BASE_STATION_RECEIVER = 2 +uint8 receiver_type + +uint8 POSITION_NO_FIX = 0 +uint8 POSITION_SPP = 1 +uint8 POSITION_SBAS = 2 +uint8 POSITION_RTK_FLOAT = 3 +uint8 POSITION_RTK_FIXED = 4 +uint8 position_fix_type + +uint8 HEADING_NOT_APPLICABLE = 0 +uint8 HEADING_NO_SOLUTION = 1 +uint8 HEADING_RTK_FLOAT = 2 +uint8 HEADING_RTK_FIXED = 3 +uint8 heading_fix_type + +uint8 num_connected_sats # Number of satellites connected to the antenna/receiver +uint8 num_sats_solution # Number of sats used in solution +float32[] cn0 # The carrier-to-noise ratio of each connected satellite +float64 correction_age # Age of RTK corrections. -1 indicates none received +``` + +#### clearpath_mission_manager_msgs/msg/NetworkEdgeReq.msg {#storage-networkedgereq} + +``` +string start_point_id +string end_point_id + +float32 speed_limit + +float32 radius +``` + +#### clearpath_mission_manager_msgs/msg/NetworkMapState.msg {#storage-networkmapstate} + +``` +# The UUID of the map +string uuid + +# True if the map actually exists and was found +bool exists + +# The number of disconnected sub-graphs of the map +# Normally this will be 1 (i.e. the map is a single graph that is connected) +# but there are circumstances where the user may intentionally want 2+ disconnected graphs +# (e.g. a separate graph for each side of a fence, where the only connection between the two +# sides is an out-of-bounds, teleop-only road) +int32 num_subgraphs + +# If the map has any disconnected vertices, we enumerate them here by their ID +# If size_exceeded is true, this list may be empty or incomplete (see below) +string[] disconnected_point_ids + +# True if the map is too big for the validation to run on it +# Maps with more than 1000 vertices or 8000 edges will not be fully tests +bool size_exceeded +``` + +#### clearpath_mission_manager_msgs/msg/NetworkMapValidityState.msg {#storage-networkmapvaliditystate} + +``` +# Reports the validity of all network of paths maps registered with the mission manager +clearpath_mission_manager_msgs/NetworkMapState[] map_states +``` + +#### clearpath_mission_manager_msgs/msg/StorageState.msg {#storage-storagestate} + +``` +# The entire contents of the Mission database +# Note that all of the following cases are valid: +# - a Task can be referenced in multiple Waypoints +# - a Waypoint can be referenced in multiple Missions +# - a Waypoint can be orphaned (i.e. not included in any Missions) +# - a Task can be orphaned (i.e. not included in any Waypoints) + +# All missions defined in the database +clearpath_navigation_msgs/Mission[] missions + +# All waypoints defined in the database +clearpath_navigation_msgs/Waypoint[] waypoints + +# All tasks defined in the database +clearpath_navigation_msgs/Task[] tasks + +# All network of paths missions in the database +clearpath_navigation_msgs/NetworkMission[] network_missions + +# All network of paths maps in the database +clearpath_navigation_msgs/NetworkMap[] network_maps +``` + +#### clearpath_mission_scheduler_msgs/msg/NextSchedule.msg + +``` +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start +``` + +#### clearpath_mission_scheduler_msgs/msg/Schedule {#scheduler-schedule} + +``` +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 + +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 + +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid + +# The time that this mission starts every day +clearpath_mission_scheduler_msgs/UtcTime start_time + +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled +``` + +#### clearpath_mission_scheduler_msgs/msg/StorageState.msg {#scheduler-state} + +``` +# Single-execution mode; the schedule starts at the designated time and runs once +uint8 MODE_ONCE=0 + +# Looping mode; the schedule starts at the designated time, and every loop_interval seconds after +# for the designated number of repeats +uint8 MODE_LOOP=1 + +# Single-shot execution, but does NOT get added to the persistent storage +# Equivalent to MODE_ONCE, but for one-off, throw-away schedules (e.g. "Run X in 5 minutes") +uint8 MODE_TRANSIENT=2 + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The unique ID of this schedule +# A string of the form "12345678-90ab-cdef-1234-567890abcdef" +string uuid + +# The time that this mission starts every day +clearpath_mission_scheduler_msgs/UtcTime start_time + +# Either MODE_ONCE or MODE_LOOP to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled +``` + +#### clearpath_mission_scheduler_msgs/msg/UtcTime.msg {#scheduler-time} + +``` +# Represents a moment in time on a 24-hour clock + +# The hour, 0-23 +uint8 hour + +# The minute, 0-59 +uint8 minute + +# The second, 0-59 +uint8 second + +# Milliseconds, 0-999 (not typically needed) +uint16 millisecond +``` + +#### clearpath_navigation_msgs/Mission.msg {#msg-navigation-mission} + +``` +# Message definition for an OutdoorNav mission + +std_msgs/Header header + +# The human-readable name of this mission +string name + +# A UUID string used to uniquely identify this mission +string uuid + +# The ordered list of Waypoints that make up the mission +clearpath_navigation_msgs/Waypoint[] waypoints + +# Configuration parameters for the mission +# Additional details TBD +string onav_config +``` + +#### clearpath_navigation_msgs/DistanceToGoal.msg {#msg-distance-to-goal} + +``` +# Message includes Euclidean and Path distance to goal + +float32 euclidean +float32 path +``` + +#### clearpath_navigation_msgs/Metrics.msg {#msg-metrics} + +``` +# Message containing some metric information related to the autonomy metrics. + +float64 total_distance_travelled # [m] +float64 total_duration # [s] + +uint64 num_missions_sent +uint64 num_missions_completed +uint64 num_replans +uint64 num_recoveries +uint64 num_tasks_executed +``` + +#### clearpath_navigation_msgs/MotionState.msg {#msg-motion-state} + +``` +# Motion state message to indicate the current motion, expected motion and the direction of travel of the robot. + +# State pertaining to current motion of the robot. +uint8 MOTION_NORMAL=10 +uint8 MOTION_STOPPED=11 +uint8 MOTION_REVERSE=12 +uint8 MOTION_SLOWING=13 # Currently unused +uint8 motion + +# State pertaining to the robot's movement along the path. Predictive, ie state +# will be INDICATOR_LEFT_TURN if in or approaching a left turn. +uint8 INDICATOR_NORMAL=20 +uint8 INDICATOR_LEFT_TURN=21 +uint8 INDICATOR_RIGHT_TURN=22 +uint8 INDICATOR_CLOCKWISE=23 +uint8 INDICATOR_COUNTERCLOCKWISE=24 +uint8 INDICATOR_HAZARD=25 # Currently unused +uint8 indicator + +# Direction of travel of the robot relative to its physical forward direction. +uint8 DIRECTION_FORWARD=30 +uint8 DIRECTION_REVERSE=31 +uint8 direction +``` + +#### clearpath_navigation_msgs/NavigationState.msg {#msg-navigation-state} + +``` +# Message containing the current navigation state(s). Navigation may be in multiple states. + +uint8 STATE_IDLE = 0 +uint8 STATE_COMPUTE_PATH = 1 +uint8 STATE_EXECUTE_PATH = 2 +uint8 STATE_REPLAN = 3 +uint8 STATE_NAVIGATING_AROUND_OBSTACLE = 4 +uint8 STATE_RECOVERY = 5 +uint8 STATE_LOST = 6 +uint8 STATE_DONE = 7 +uint8 STATE_SAFETY_STOP = 8 +uint8 STATE_PAUSE = 9 +uint8 STATE_DISABLE = 10 + +uint8[] states +``` + +#### clearpath_navigation_msgs/OdomIntent.msg {#msg-odom-intent} + +``` +# Message containing current and predicted odom related information + +std_msgs/Header header + +# Current and predicted odom +perception_navigation_msgs/Odom2DLean odom +perception_navigation_msgs/Odom2DLean predicted_odom + +# Time offset corresponding to prediction +float32 dt +``` + +#### clearpath_navigation_msgs/PointVector.msg {#msg-point-vector} + +``` +# Vector of point vectors (for GUI) +std_msgs/Header header + +clearpath_navigation_msgs/Vector2D[] cloud +``` + +#### clearpath_navigation_msgs/Progress.msg (BETA) {#msg-navigation-progress} + +``` +# Message containing the completion percentage of the currently executed path and the current goal. + +float32 path_progress +float32 goal_progress +float32 mission_progress +``` + +#### clearpath_navigation_msgs/ScanPoints.msg {#msg-scan-points} + +``` +# Message definition for the detection points used by the navigation that relate to the detected obstacles. + +std_msgs/Header header + +string[] frames_vector +clearpath_navigation_msgs/PointVector[] cloud_vector +``` + +#### clearpath_navigation_msgs/Task.msg {#msg-navigation-task} + +``` +# A single task that can be executed at a Waypoint + +# The human-readable name of this task +string name + +# A UUID string to uniquely identify this Task +string uuid + +# The ROS action that this task executes +string action_server_name + +# The version of this task +string version + +# Numerical/boolean data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service +float64[] floats + +# String data to be passed to the action_server_name +# The exact meaning of these values is dependent on the underlying service +string[] strings + +# Boolean value which determines whether a mission using this task can continue +# if this task fails to execute +bool allow_failure +``` + +#### clearpath_navigation_msgs/TrackError.msg {#msg-track-error} + +``` +# The path error message containing the off-path cross track error and the relative heading error to the path direction + +std_msgs/Header header +float32 cross_track_error +float32 heading_error +``` + +#### clearpath_navigation_msgs/Vector2D.msg {#msg-vector-2d} + +``` +# 2D Vector of floats (used for GUI) + +float32[2] point +``` + +#### clearpath_navigation_msgs/Waypoints.msg {#msg-navigation-waypoints} + +``` +# A single Waypoint along a Mission + +# A UUID string to uniquely identify this Waypoint +string uuid + +# The human-readable name of this Waypoint +string name + +# The latitude (in degrees) of this Waypoint +float64 latitude + +# The longitude (in degrees) of this Waypoint +float64 longitude + +# The compass heading (in degrees) of this Waypoint +float64 heading + +# A radius in meters indicating the acceptable radius from the target location +# Posititon tolerance is disabled if this value is negative +float64 position_tolerance + +# A tolerance in degrees indicating the acceptable deviation from the heading +# Heading tolerance is disabled if this value is negative +float64 yaw_tolerance + +# The ordered set of Tasks to execute once the goal position & orientation are reached +clearpath_navigation_msgs/Task[] tasks +``` + +#### clearpath_platform_msgs/PlatformID.msg {#msg-platform-id} + +``` +# Platform ID message containing the model, serial #, hardware and firmware versions + +string model +string serial_id +string hardware_revision +string firmware_revision +``` + +#### clearpath_safety_msgs/Safety.msg {#msg-safety} + +``` +# Safety monitor message telling us if the safety monitor has been triggered and a message +# indicating what caused the trigger + +uint8 SAFETY_ESTOP = 0 +uint8 SAFETY_SENSOR_TIMEOUT = 1 + +bool safety_monitor_triggered +uint8 trigger_type +string message +``` + +#### clearpath_safety_msgs/AssistedTeleopState.msg {#msg-assisted-teleop-state} + +``` +# Assisted teleoperation message indicating the current state of the protection + +uint8 STATE_ACTIVE = 0 +uint8 STATE_DISABLED = 1 +uint8 STATE_COLLISION_IMMINENT = 2 +uint8 STATE_STOPPED = 3 +uint8 STATE_COLLISION = 4 +uint8 STATE_ERROR = 5 +uint8 state + +uint8 ASSIST_ON = 100 +uint8 ASSIST_OFF_SERVICE = 101 +uint8 ASSIST_OFF_JOYSTICK_OVERRIDE = 102 +uint8 ASSIST_OFF_SENSOR_TIMEOUT = 103 +uint8 assist_off_trigger + +string error_message +``` + +#### clearpath_safety_msgs/ObstacleMap.msg {#msg-obstacle-map} + +``` +# Assisted teleoperation message indicating the threat level of obstacles surrounding the platform + +float32[] threat_level +``` + +#### clearpath_safety_msgs/WatchdogStatus.msg {#msg-safety-watchdog} + +``` +# Watchdog status message containing information related to sensor monitoring, emergency stop and safety stops + +bool[] gps_watchdog_triggered +bool[] lidar_watchdog_triggered +bool[] camera_watchdog_triggered +``` + +#### Standard ROS Messages {#std-ros-msgs} + +- [actionlib_msgs/GoalID](http://docs.ros.org/en/noetic/api/actionlib_msgs/html/msg/GoalID.html) +- [diagnostic_msgs/DiagnosticArray](http://docs.ros.org/en/noetic/api/diagnostic_msgs/html/msg/DiagnosticArray.html) +- [geometry_msgs/PolygonStamped](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PolygonStamped.html) +- [geometry_msgs/Polygon](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Polygon.html) +- [geometry_msgs/PoseArray](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/PoseArray.html) +- [geometry_msgs/Twist](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +- [nav_msgs/OccupancyGrid](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/OccupancyGrid.html) +- [nav_msgs/Odometry](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) +- [nav_msgs/Path](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Path.html) +- [sensor_msgs/Imu](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/Imu.html) +- [sensor_msgs/LaserScan](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/LaserScan.html) +- [sensor_msgs/NavSatFix](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/NavSatFix.html) +- [sensor_msgs/PointCloud2](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/PointCloud2.html) +- [std_msgs/Bool](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Bool.html) +- [std_msgs/Empty](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Empty.html) +- [std_msgs/String](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/String.html) +- [tf2_msgs/TFMessage](http://docs.ros.org/en/noetic/api/tf2_msgs/html/msg/TFMessage.html) +- [wireless_msgs/Connection](http://docs.ros.org/en/noetic/api/wireless_msgs/html/msg/Connection.html) + +------------------------------------------------------------------------ + +### Service Definitions + +#### clearpath_control_msgs/srv/SetControlMode.srv {#srv-set-control-mode} + +``` +# Service definition to set the control mode + +clearpath_control_msgs/ControlMode mode +--- +``` + +#### clearpath_dock_msgs/srv/AddDock.srv {#srv-add-dock} + +``` +# A dock information message that will be added to the docks list +clearpath_dock_msgs/DockInfo dock +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/RemoveDock.srv {#srv-remove-dock} + +``` +# A dock information message that will remove a dock from the docks list +string uuid +string name +--- +# True if the dock was removed successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/SetDockLocationById.srv {#srv-set-dock-location-by-id} + +``` +# The UUID of the dock we're setting a location for +# If empty, a new dock is to be added with the location +string uuid +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_dock_msgs/srv/SetDockLocationByName.srv {#srv-set-dock-location-by-name} + +``` +# The UUID of the dock we're setting a location for +# If empty, a new dock is to be added with the location +string name +--- +# True if the location was updated/added successfully, otherwise False +bool success +``` + +#### clearpath_localization_msgs/srv/SetDatum.srv {#srv-set-datum} + +``` +# Service definition to set the datum with a latitude (lat) and longitude (lon) + +float32 lat +float32 lon +--- +bool success +``` + +#### clearpath_localization_msgs/srv/ResetLocalization.srv {#srv-reset-localization} + +``` +# Service definition to reset the localization + +bool require_gnss +uint32 gnss_samples +--- +bool success +``` +#### clearpath_mission_manager_msgs/srv/AddNetworkEdge.srv {#storage-addnetworkedge} + +``` +# The UUID of the map we're operating on +string map_id + +# The UUIDs of the start and end points for this edge +string start_point_id +string end_point_id + +# The operational radius around the edge +float32 radius + +# The speed limit when driving along this edge +float32 speed_limit + +# An additional cost factor to prioritize certain edges over others in the planner +# Higher costs -> edge is less likely to be included in the planned route +# Expected range is (0.0, 100.0) (exclusive range). +# Values outside the expected range will be treated as the default 1.0 +float32 cost_factor + +# If true, we add 2 edges, with the second one having inverted start and end points +bool symmetrical + +--- + +# The generated edge(s) +clearpath_navigation_msgs/NetworkEdge[] edges +``` + +#### clearpath_mission_manager_msgs/srv/AddNetworkPath.srv {#storage-addnetworkpath} + +``` +# The lat-lon locations of the points to add +float64[] latitudes +float64[] longitudes + +# The UUID of the map we're adding points to +string map_id + +# If true, bidirectional edges are added between the points +bool symmetrical + +--- +bool success +string message +``` + +#### clearpath_mission_manager_msgs/srv/AddNetworkPoint.srv {#storage-addnetworkpoint} + +``` +# The location of this point on the map +float64 latitude +float64 longitude + +# The UUID of the map we're adding this point to +string map_id + +# Optional list of node IDs in the map we want to connect to the new node +# This specifies edges originating in the given nodes, pointing to the new node +string[] connect_from + +# Optional list of node IDs in the map we want to connect to the new node +# This specifies edges originating at the new node, pointing to the nodes with the given UUIDs +string[] connect_to + +# If true, bidirectional edge are added between the nodes specified in connect_from and connect_to +bool symmetrical + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint point +``` + +#### clearpath_mission_manager_msgs/srv/AddRemoveById.srv {#storage-addremovebyid} + +``` +# The UUID of the object we're inserting/removing +# When removing, all instances with this UUID are deleted from the parent +string uuid + +# The UUID of the parent object +string parent_uuid + +# The zero-based index to insert the object into +# Ignored when removing +int32 position +--- +# True if the object was added/removed successfully, otherwise False +bool ok +``` + +#### clearpath_mission_manager_msgs/srv/CloneMission.srv {#storage-clonemission} +``` +# The UUID of the mission to clone +string uuid + +# The new name for the mission +# If blank, the old mission name will be re-used with -copy appended to the end +string new_name + +# If true, the order of the waypoints within the cloned mission are reversed +bool reverse +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/Mission mission +``` + +:::note + +The `reverse` parameter was added in 0.9.0 + +::: + +#### clearpath_mission_manager_msgs/srv/CloneNetworkMap.srv {#storage-clonenetworkmap} + +``` +# The UUID of the map to clone +string uuid + +# The new name for the map +# If blank, the old map name will be re-used with -copy appended to the end +string new_name + +--- +# The newly-created copy of the original map, with a new name and new UUID +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/CloneNetworkMission.srv {#storage-clonenetworkmission} + +``` +# The UUID of the mission to clone +string uuid + +# The new name for the mission +# If blank, the old mission name will be re-used with -copy appended to the end +string new_name + +# If true, the order of the waypoints within the cloned mission are reversed +bool reverse +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/NetworkMission mission +``` + +#### clearpath_mission_manager_msgs/srv/CreateMission.srv {#storage-createmission} + +``` +# The desired name for the new mission +string name + +# The additional configuration options +# see clearpath_mission_manager_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids +--- +# The resulting Mission, with an auto-generated UUID is returned +clearpath_navigation_msgs/Mission result +``` + +#### clearpath_mission_manager_msgs/srv/CreateTask.srv {#storage-createtask} + +``` +# The desired name for the Task +string name + +# The ROS Action to invoke to execute the task +string service_call + +# The version of the task +string version + +# The numerical arguments to pass to the service_call +float64[] floats + +# The string arguments to pass to the service_call +string[] strings + +# Optional list of Waypoint UUIDs to assign this task to automatically +# The new task will be appended to the end of the existing Waypoints +string[] assign_to +--- +# The resulting Task with an auto-generated UUID is returned +clearpath_navigation_msgs/Task result +``` + +#### clearpath_mission_manager_msgs/srv/CreateWaypoint.srv {#storage-createwaypoint} + +``` +# The desired name for the Waypoint +string name + +# The latitude for the Waypoint in degrees +float64 latitude + +# The longitude for the Waypoint in degrees +float64 longitude + +# The compass heading in degrees for the Waypoint +float64 heading + +# The position tolerance for the Waypoint in meters +float64 position_tolerance + +# The orientation tolerance for the Waypoint in degrees +float64 yaw_tolerance + +# Optional ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids + +# Optional list of Mission UUIDs to assign the new Waypoint to +# The new Waypoint is appended to the end of the existing Missions +string[] assign_to +--- +# The resulting Waypoint with an auto-generated UUID is returned +clearpath_navigation_msgs/Waypoint result +``` + +#### clearpath_mission_manager_msgs/srv/DeleteById.srv {#storage-deletebyid} + +``` +# The UUID of the object we want to delete +string uuid +--- +# True if the item was successfully deleted, otherwise False +bool ok +``` + +#### clearpath_mission_manager_msgs/srv/DeleteEverything.srv {#storage-deleteeverything} + +``` +# Used to permanently delete everything from the database. +# Use this service at your own risk + +# This must be set to true to confirm you really want to delete everything +bool yes_i_am_absolutely_sure_i_want_to_do_this +--- +# True if the database was cleared, otherwise False +bool ok +``` + +#### clearpth_mission_manager_msgs/srv/DeleteMultiple.srv {#storage-deletemultiple} + +``` +# A list of UUIDs of items we want to delete +string[] uuids + +# An optional ID of the parent object we're deleting from +string parent_id +--- +# A list of UUIDs that we were asked to delete, but failed to +string[] failed_uuids +``` + +#### clearpath_mission_manager_msgs/srv/ExportData.srv {#storage-exportdata} + +``` +--- +# A JSON string representing the database contents. +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### clearpath_mission_manager_msgs/srv/GetAllMissions.srv {#storage-getallmissions} + +``` +--- +# An array of all Missions defined in the database +clearpath_navigation_msgs/Mission[] missions +``` + +#### clearpath_mission_manager_msgs/srv/GetAllNetworkMaps.srv {#storage-getallnetworkmaps} + +``` +--- +clearpath_navigation_msgs/NetworkMap[] maps +``` + +#### clearpath_mission_manager_msgs/srv/GetAllNetworkMissions.srv {#storage-getallnetworkmissions} + +``` +--- +# An array of all Missions defined in the database +clearpath_navigation_msgs/NetworkMission[] missions +``` + +#### clearpath_mission_manager_msgs/srv/GetAllTasks.srv {#storage-getalltasks} + +``` +--- +# The array of all Tasks defined in the database +clearpath_navigation_msgs/Task[] tasks +``` + +#### clearpath_mission_manager_msgs/srv/GetAllWaypoints.srv {#storage-getallwaypoints} + +``` +--- +# The array of all Waypoints defined in the database +clearpath_navigation_msgs/Waypoint[] waypoints +``` + +#### clearpath_mission_manager_msgs/srv/GetEverything.srv {#storage-geteverything} + +``` +--- +# All Missions, Waypoints, and Tasks defined in the database +clearpath_mission_manager_msgs/StorageState state +``` + +#### clearpath_mission_manager_msgs/srv/GetMission.srv {#storage-getmission} + +``` +# The UUID of the Mission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/Mission mission +``` + +#### clearpath_mission_manager_msgs/srv/GetnetworkMap.srv {#storage-getnetworkmap} + +``` +# The UUID of the NetworkMap we want to retrieve +string uuid +--- +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/GetNetworkMission.srv {#storage-getnetworkmission} + +``` +# The UUID of the NetworkMission we want to retrieve +string uuid +--- +# The Mission with the given ID, or null if no Mission with that ID exists +clearpath_navigation_msgs/NetworkMission mission +``` + +#### clearpath_mission_manager_msgs/srv/GetTask.srv {#storage-gettask} + +``` +# The UUID of the Task we want to retrieve +string uuid +--- +# The Task with the given ID, or null if no Task with that ID exists +clearpath_navigation_msgs/Task task +``` + +#### clearpath_mission_manager_msgs/srv/GetWaypoint.srv {#storage-getwaypoint} + +``` +# The UUID of the Waypoint we want to retrieve +string uuid +--- +# The Waypoint with the given ID, or null if no Waypoint with that ID exists +clearpath_navigation_msgs/Waypoint waypoint +``` + +#### clearpath_mission_manager_msgs/srv/ImportData.srv {#storage-importdata} + +``` +# A JSON string representing the database contents. +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +clearpath_mission_manager_msgs/StorageState state +``` + +#### clearpath_mission_manager_msgs/srv/ImportMission.srv {#storage-importmission} + +``` +# The Mission to import. All UUIDs will be re-generated +clearpath_navigation_msgs/Mission mission +--- +# The generated mission with new UUIDs +clearpath_navigation_msgs/Mission mission +``` + +#### clearpath_mission_manager_msgs/srv/ImportNetworkMap.srv {#storage-importnetworkmap} + +``` +# The map to import. UUIDs that do not already exist are added, but objects with existing UUIDs +# are re-used +clearpath_navigation_msgs/NetworkMap map +--- +# The imported map +clearpath_navigation_msgs/NetworkMap map +``` + +#### clearpath_mission_manager_msgs/srv/ImportNetworkMission.srv {#storage-importnetworkmission} + +``` +# The mission to import. UUIDs that do not already exist are added, but objects with existing UUIDs +# are re-used +clearpath_navigation_msgs/NetworkMission mission +--- +# The imported mission +clearpath_navigation_msgs/NetworkMission mission +``` + +#### clearpath_mission_manager_msgs/srv/SplitNetworkEdge.srv {#storage-splitnetworkedge} + +``` +# Splits an edge on a NetworkMap to connect to a new point + +# The UUID of the map to edit +string map_id + +# The UUID of the edge we want to split +string edge_id + +# The position of the new point to create +float64 new_point_latitude +float64 new_point_longitude + +# If true, we also split the reverse edge (if it exists) +bool symmetrical +--- +# The map in its new state +clearpath_navigation_msgs/NetworkMap result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateMission.srv {#storage-updatemission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The human-readable name for the Mission +string name + +# The configuration parameters for the Mission +string onav_config + +# The ordered list of Waypoint UUIDs to include in the Mission +string[] waypoint_ids +--- +# The edited Mission, or null if no mission with the given ID exists +clearpath_navigation_msgs/Mission result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkEdge.srv {#storage-updatenetworkedge} + +``` +# The UUID of the map we're operating on +string map_id + +# The UUID of the edge to edit +string uuid + +# The UUIDs of the start & end points of the edge we're editing +# Ignored if null/empty +string start_point_id +string end_point_id + +# The operational radius around the edge +float32 radius + +# The speed limit when driving along this edge +float32 speed_limit + +# An additional cost factor to prioritize certain edges over others in the planner +# Higher costs -> edge is less likely to be included in the planned route +# Expected range is (0.0, 100.0) (exclusive range). +# Values outside the expected range will be treated as the default 1.0 +float32 cost_factor + +--- + +# The updated edge +clearpath_navigation_msgs/NetworkEdge result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkEdges.srv {#storage-updatenetworkedges} + +``` +# Update multiple edges in a single map + +# The UUID of the map we're operating on +string map_id + +# The UUIDs of edges to edit +string[] uuids + +# The operational radii around the edges +# Ignored if negative +float32[] radii + +# The speed limit when driving along the edges +# Ignored if negative +float32[] speed_limits + +# The cost factors of the edges +float32[] cost_factors + +--- + +# The updated edge +clearpath_navigation_msgs/NetworkEdge[] result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkMap.srv {#storage-updatenetworkmap} + +``` +string uuid + +string name +float32 default_radius +float32 default_speed_limit +--- +clearpath_navigation_msgs/NetworkMap result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkMission.srv {#storage-updatenetworkmission} + +``` +# The UUID of the mission we want to edit +string uuid + +# The desired name for the new mission +string name + +# The additional configuration options +# see clearpath_navigation_msgs/msg/Mission for details +string onav_config + +# The ordered list of Waypoint UUIDs to include in this mission +string[] waypoint_ids + +# The ordered list of Task UUIDs to include in the on_start Task Array +string[] on_start_ids + +# The ordered list of Task UUIDs to include in the on_stop Task Array +string[] on_stop_ids + +# Boolean value indicating whether robot should attempt 'return to dock' behavior +# when battery level drops below return_to_dock_battery_level +bool return_to_dock_enabled + +# Dock UUID that the robot should return to for 'return to dock' behavior +string return_to_dock_id + +# Value from 0 to 1 indicating what charge level the robot will return to dock at +float32 return_to_dock_battery_level + +# Value from 0 to 1 indicating what charge level the robot should resume this mission at +# after returning to dock for recharging +float32 resume_mission_battery_level + +# Boolean value indicating whether 'network' level replanning should be performed +# in the event that a network edge is deemed un-traversable (e.g., due to obstacles) +bool network_replan_enabled + +--- +# The resulting Mission, with an auto-generated UUID is returned +clearpath_navigation_msgs/NetworkMission result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkPoint.srv {#storage-updatenetworkpoint} + +``` +# The UUID of the map we're working on +string map_id + +# The UUID of the point to edit +string uuid + +# The location of this point on the map +float64 latitude +float64 longitude + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateNetworkPoints.srv {#storage-updatenetworkpoints} + +``` +# The UUID of the map we're working on +string map_id + +# The UUID of the points to edit +string[] uuids + +# The location of the points on the map, in the same order as uuids +float64[] latitudes +float64[] longitudes + +--- + +# The added point, with generated UUID +clearpath_navigation_msgs/NetworkPoint[] result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateTask.srv {#storage-updatetask} + +``` +# The UUID of the Task to edit +string uuid + +# The human-readable name for the Task +string name + +# The ROS Action that the Task executes +string service_call + +# The version of the Task +string version + +# The numerical data to pass to the service_call +float64[] floats + +# The string data to pass to the service_call +string[] strings +--- +# The edited Task, or null if no Task with the given ID exists +clearpath_navigation_msgs/Task result +``` + +#### clearpath_mission_manager_msgs/srv/UpdateWaypoint.srv {#storage-updatewaypoint} + +``` +# The UUID of the Waypoint to edit +string uuid + +# The human-readable name for the Waypoint +string name + +# The latitude of the Waypoint in degrees +float64 latitude + +# The longitude of the Waypoint in degrees +float64 longitude + +# The compass heading of the Waypoint in degrees +float64 heading + +# The Waypoint's position tolerance in meters +float64 position_tolerance + +# The Waypoint's orientation tolerance in degrees +float64 yaw_tolerance + +# The ordered list of Task UUIDs to execute at this Waypoint +string[] task_ids +--- +# The edited Waypoint, or null if no Waypoint with the given ID exists +clearpath_navigation_msgs/Waypoint result +``` + +#### clearpath_mission_manager_msgs/srv/ValidateNetworkMap.srv {#storage-validatenetworkmap} + +``` +# Checks that a Network of Paths map is valid and error/warning-free + +# The UUID of the map to check +string uuid +--- +clearpath_mission_manager_msgs/NetworkMapState state +``` + +#### clearpath_mission_scheduler_msgs/srv/CloneSchedule.srv {#scheduler-cloneschedule} + +``` +# The UUID of the schedule to clone +string uuid + +# The name for the new copy of the schedule +string new_name +--- +# The cloned schedule +# This should be identical to the original, but with a new name and new UUID +clearpath_mission_scheduler_msgs/Schedule schedule +``` + +#### clearpath_mission_scheduler_msgs/srv/CreateSchedule.srv {#scheduler-createschedule} + +``` +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +clearpath_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The created mission, as-saved on disk +clearpath_mission_scheduler_msgs/Schedule result +``` + +#### clearpath_mission_scheduler_msgs/srv/EnableSchedule.srv {#scheduler-enableschedule} + +``` +# The ID of the schedule to enable/disable +string uuid + +# Should this schedule be enabled or disabled? +bool enable + +--- + +# True if we successfully enabled/disabled the schedule +# False if there was an error or the schedule wasn't found +bool ok +``` + +#### clearpath_mission_scheduler_msgs/srv/ExportData.srv {#scheduler-exportdata} + +``` +--- +# A JSON string representing the database contents. +# This can be written to a file or used with the ImportData.srv +# to back-up/restore the database contents +string data +``` + +#### clearpath_mission_scheduler_msgs/srv/GetAllSchedules.srv {#scheduler-getallschedules} + +``` +--- +clearpath_mission_scheduler_msgs/Schedule[] schedules +``` + +#### clearpath_mission_scheduler_msgs/srv/GetNextSchedule.srv {#scheduler-getnextschedule} + +``` +--- +# The ID of the next schedule to start +# Empty if nothing is scheduled +string uuid + +# The time until the schedule starts (rounded to the nearest second) +duration time_to_start +``` + +#### clearpath_mission_scheduler_msgs/srv/GetSchedule.srv {#scheduler-getschedule} + +``` +string uuid +--- +clearpath_mission_scheduler_msgs/Schedule schedule +``` + +#### clearpath_mission_scheduler_msgs/srv/ImportData.srv {#scheduler-importdata} + +``` +# A JSON string representing the database contents. +# This is the same as the data output by the ExportData service, and is intended +# to be used to restore the database to a previous state +string data +--- +# The state of the database after importing the data +clearpath_mission_scheduler_msgs/StorageState state +``` + +#### clearpath_mission_scheduler_msgs/srv/UpdateSchedule.srv {#scheduler-updateschedule} + +``` +# The ID of the mission to edit +string uuid + +# The human-readable name for this schedule +# Should be unique, but there's no hard requirement for it to be so +string name + +# The time that this mission starts every day +clearpath_mission_scheduler_msgs/UtcTime start_time + +# Either Schedule.MODE_ONCE, Schedule.MODE_LOOP, OR Schedule.MODE_TRANSIENT to indicate the execution mode +uint8 mode + +# In MODE_LOOP, how many times do we repeat the missions? +uint8 loop_repeats + +# In MODE_LOOP, how long do we wait between executions? +duration loop_interval + +# The ordered list of Mission UUIDs to execute +string[] mission_ids + +# The minimum battery charge needed before we execute the missions +# Must be in the range 0-1 +float32 min_battery + +# If the missions take longer than this to execute, assume the schedule has failed and alert the user +# Set to zero to disable the timeout +duration timeout + +# Is this schedule enabled? +# Only enabled schedules will execute +bool enabled + +--- + +# The modified mission, as-saved on disk +clearpath_mission_scheduler_msgs/Schedule result +``` + +#### clearpath_navigation_msgs/srv/SetDelayCompensation.srv {#srv-set-delay-compensation} + +``` +# Service definition to enable/disable the delay compensation feature. If enabling, the delay to compensate for must be specified in the request. + +bool enable_delay_compensation +uint16 delay # units: milliseconds +--- +bool success +string message +``` + +#### clearpath_navigation_msgs/srv/SetPathSmoother.srv {#srv-set-path-smoother} + +``` +# Service definition to enable/disable the path smoothing feature. If enabling, minimum turning radius must be specified in the request. + +bool enable_path_smoother +float32 turn_radius # units: meters +float32 step_size +--- +bool success +string message +``` + +#### clearpath_navigation_msgs/srv/SetStopDistance.srv {#srv-set-stop-distance} + +``` +# Service definition to enable/disable the stop distance. If enabling, the stop distance must be specified in the request. + +bool enable_stop_distance +float32 stop_distance # units: meters +--- +bool success +string message +``` + +#### Standard ROS Services + +- [std_srvs/Empty](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/Empty.html) +- [std_srvs/SetBool](http://docs.ros.org/en/noetic/api/std_srvs/html/srv/SetBool.html) + +------------------------------------------------------------------------ + +### Action Definitions + +#### clearpath_dock_msgs/action/Dock.action {#action-dock} + +``` +# Action definition for sending a Clearpath UGV to one of its charging dock. + +# goal +string uuid +bool local_mode +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_dock_msgs/action/Undock.action {#action-undock} + +``` +# Action definition for undocking a Clearpath UGV from one of its charging docks. + +# goal +string uuid +--- +# result +bool success +--- +# feedback +string state + +# the distance of the charger_link to the dock target +float64 distance_to_dock +``` + +#### clearpath_localization_msgs/action/SurveyBaseStation.action {#action-survey-base-station} + +``` +# Action definition for surveying the base station + +# goal +# the number of GPS fixes that will be used to compute to surveyed position +uint32 number_of_desired_fixes +--- +# result +bool success +--- +# feedback +# current progress, as a percentage, of the surveying +float32 percent_complete +``` + + +#### clearpath_mission_scheduler_msgs/action/RunScheduleByUuid.action {#scheduler-runschedulebyuuid} + +``` +# Action definition for executing a schedule on-demand +# Potentially only useful for debugging + +# The UUID of the schedule to execute +string uuid + +# Wait this long before starting the schedule (ros:Duration msg, so the units are secs/nsecs) +duration delay +--- +# Did the schedule terminate successfully? +bool success +--- +# The ID of the mission we're executing right now +string current_mission_uuid + +# One of "waiting" or "executing" indicating what the schedule is doing +string state +``` + +#### clearpath_navigation_msgs/action/ExecuteMissionByUuid.action {#action-execute-mission-by-uuid} + +``` +# Action definition for executing a mission by uuid + +# goal +string uuid # UUID of The mission being executed + +# from_start = True -> Forces the mission to execute from the beginning +bool from_start + +# If from_start = False, mission will be executed from the waypoint with UUID specified. +# If from_start = False and no start_waypoint_uuid is specified then autonomy will pick the closest waypoint +string start_waypoint_uuid +--- +# result +bool success +--- +# feedback +string state + +``` + +#### clearpath_navigation_msgs/action/Mission.action {#action-mission} + +``` +# Action definition for sending a mission to the Clearpath OutdoorNav software + +# goal +clearpath_navigation_msgs/Mission mission + +# from_start = True -> Forces the mission to execute from the beginning +bool from_start + +# If from_start = False, mission will be executed from the start_waypoint specified. +# If from_start = False and no start_waypoint is specified then autonomy will pick the closest waypoint +clearpath_navigation_msgs/Waypoint start_waypoint +--- +# result +bool success +--- +# feedback +string state +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_manager_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_manager_api.mdx new file mode 100644 index 00000000..406e009f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_manager_api.mdx @@ -0,0 +1,463 @@ +--- +title: Mission Manager API +sidebar_label: Mission Manager API +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Mission Manager API allows creation, deletion, and modification of OutdoorNav missions. Mission data is stored +in a databse-like structure on-disk. The web UI is the primary method of managing missions, but this service +API provides the ability to write your own UI if desired. + +### Topics Exported by Mission Manager + +#### mission_manager/network_maps_validity + +**Message Type:** [clearpath_mission_manager_msgs/msg/NetworkMapValidityState](definitions.mdx#storage-networkmapvaliditystate) + +**Description:** Latched topic that publishes the validity state of all network of paths maps defined on the robot. + +#### mission_manager/state + +**Message Type:** [clearpath_mission_manager_msgs/msg/StorageState](definitions.mdx#storage-storagestate) + +**Description:** Latched topic that publishes the current database contents every time a change is made. + +### Services Exported by Mission Manager + +#### mission_manager/add_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkEdge](definitions.mdx#storage-addnetworkedge) + +**Description:** Adds an edge between two vertices in a network of paths map. Edges are unidirectional, but symmetrical +edges can be added by setting `symmetrical` to `true`. + +#### mission_manager/add_network_path + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkEdge](definitions.mdx#storage-addnetworkpath) + +**Description:** Adds multiple points and edges to an existing network of paths map. Vertices are supplied in-order, +with edges automatically added between adjacent vertices. + +#### mission_manager/add_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddNetworkPoint](definitions.mdx#storage-addnetworkpoint) + +**Description:** Adds a single vertex to a network of paths map. The new vertex can optionally be connected to +existing vertices by specifying the connecting points' UUIDs. + +#### mission_manager/add_task_to_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Add an existing Task to an existing Waypoint. If the `position` parameter is negative the Task +is added to the end of the Waypoint's `tasks` list. + +#### mission_manager/add_waypoint_to_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Add an existing Waypoint to an existing Mission. If the `position` parameter is negative the Waypoint +is added to the end of the Task's `waypoints` list. + +#### mission_manager/clone_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneMission](definitions.mdx#storage-clonemission) + +**Description:** Create a deep-copy of a Mission. The new Mission will be given the provided name, or reuse the original +mission's name wth `-copy` appended to the end if no name is provided. All Waypoints and their associated Tasks are also +deep-copied. If the `reverse` parameter is set to `true` the order of waypoints is reversed in the new mission. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. If the specified name is not unique the cloning will +fail. Cloning a mission multiple times without specifying a unique name will add incrementing numbers to the suffix: +`-copy` for the first, `-copy1` for the second, `-copy2` for the third, and so on. + +::: + +:::note + +The `reverse` parameter was added in 0.9.0 and is not available in older versions. + +::: + +#### mission_manager/clone_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneNetworkMap](definitions.mdx#storage-clonenetworkmap) + +**Description:** Create a deep-copy of a network of paths map + +#### mission_manager/clone_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CloneNetworkMission](definitions.mdx#storage-clonenetworkmission) + +**Description:** Create a deep-copy of a network of paths mission + +#### mission_manager/clone_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions.mdx#storage-gettask) + +**Description:** Create a deep-copy of a Task. + +#### mission_manager/clone_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions.mdx#storage-getwaypoint) + +**Description:** Create a deep-copy of a Waypoint. The new Waypoint will be renamed to have `-copy` at the end. All +Tasks in the original Waypoint are also duplicated. + +#### mission_manager/create_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateMission](definitions.mdx#storage-createmission) + +**Description:** Create a new Mission. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. Creating a mission with a duplicate mission will fail. + +::: + +#### mission_manager/create_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateNetworkMap](definitions.mdx#storage-createnetworkmap) + +**Description:** Create a new network of paths map + +#### mission_manager/create_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateNetworkMission](definitions.mdx#storage-createnetworkmission) + +**Description:** Create a new network of paths mission + +#### mission_manager/create_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateTask](definitions.mdx#storage-createtask) + +**Description:** Create a new Task. + +#### mission_manager/create_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/CreateWaypoint](definitions.mdx#storage-createwaypoint) + +**Description:** Create a new Waypoint. + +#### mission_manager/delete_all + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions.mdx#storage-deleteeverything) + +**Description:** Delete everything in the database. + +:::note + +Use with extreme caution; this procedure cannot be undone. + +::: + +#### mission_manager/delete_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete the Mission with the given ID. Waypoints that are included in this mission are not +deleted, as they may be referenced by other Missions. + +#### mission_manager/delete_missions + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete the missions with the given IDs. Waypoints that are part of these missions are not deleted, +as they may be referenced by other Missions. + +#### mission_manager/delete_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Delete an edge from a network of paths map + +#### mission_manager/delete_network_edges + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete multiple edges from a network of paths map + +#### mission_manager/delete_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete a network of paths map. All vertices and edges contained within the map are also deleted. + +#### mission_manager/delete_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete a network of paths mission + +#### mission_manager/delete_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Delete a vertex from a network of paths map. All edges that connect to this vertex at either end +are also deleted. + +#### mission_manager/delete_network_points + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete multiple vertices from a network of paths map. All edges that connect to the deleted vertices +are also deleted. + +#### mission_manager/delete_orphan_objects + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions.mdx#storage-deleteeverything) + +**Description:** Delete all Waypoints that are not referenced by any Missions and all Tasks that are not referenced +by any Waypoints. + +:::note + +Use with caution; deleted items cannot be recovered. + +::: + +#### mission_manager/delete_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete the Task with the given ID. Any Waypoints that reference the deleted Task will be modified +to omit this Task once it is deleted. + +#### mission_manager/delete_tasks + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete the tasks with the given IDs. + +#### mission_manager/delete_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete the Waypoint with the given ID. Tasks that are included in this mission are not +deleted, as they may be referenced by other Waypoints. Any Missions that reference the deleted Waypoint will be +modified to omit this Waypoint once it is deleted. + +#### mission_manager/delete_waypoints + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteMultiple](definitions.mdx#storage-deletemultiple) + +**Description:** Delete the Waypoints with the given IDs. Tasks that are part of these Waypoints are not deleted, +as they may be referenced by other Waypoints. + +#### mission_manager/export + +**Service Type:** [clearpath_mission_manager_msgs/srv/ExportData](definitions.mdx#storage-exportdata) + +**Description:** Export the database so its contents can be restored later using the `mission_manager/restore` service +or merged with other data using the `mission_manager/import` service. + +:::note + +The data returned in a JSON string representing the underlying storage file's contents. + +::: + +#### mission_manager/get_all + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetEverything](definitions.mdx#storage-geteverything) + +**Description:** Get the entire contents of the database, including all Missions, Tasks, and Waypoints. + +:::note + +If you need to maintain an up-to-date copy of the database state, rather than calling this service repeatedly you +should subscribe to the `mission_manager/state` topic. + +::: + +#### mission_manager/get_all_missions + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllMissions](definitions.mdx#storage-getallmissions) + +**Description:** Get all Missions defined in the database. + +#### mission_manager/get_all_network_maps + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllNetworkMaps](definitions.mdx#storage-getallnetworkmaps) + +**Description:** Get all network of paths maps defined in the database. + +#### mission_manager/get_all_network_missions + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllNetworkMissions](definitions.mdx#storage-getallnetworkmissions) + +**Description:** Get all network of paths missions defined in the database. + +#### mission_manager/get_all_tasks + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllTasks](definitions.mdx#storage-getalltasks) + +**Description:** Get all Tasks defined in the database. + +#### mission_manager/get_all_waypoints + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetAllWaypoints](definitions.mdx#storage-getallwaypoints) + +**Description:** Get all Waypoints defined in the database. + +#### mission_manager/get_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetMission](definitions.mdx#storage-getmission) + +**Description:** Get the Mission with the specified ID. + +#### mission_manager/get_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetNetworkMap](definitions.mdx#storage-getnetworkmap) + +**Description:** Get the network of paths map with the specified ID. + +#### mission_manager/get_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetNetworkMission](definitions.mdx#storage-getnetworkmission) + +**Description:** Get the network of paths mission with the specified ID. + +#### mission_manager/get_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetTask](definitions.mdx#storage-gettask) + +**Description:** Get the Task with the specified ID. + +#### mission_manager/get_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/GetWaypoint](definitions.mdx#storage-getwaypoint) + +**Description:** Get the Waypoint with the specified ID. + +#### mission_manager/import + +**Service Type:** [clearpath_mission_manager_msgs/srv/ImportData](definitions.mdx#storage-importdata) + +**Description:** Add existing Missions, Tasks, and Waypoints to the database. + +:::note + +All imported Missions, Tasks, and Waypoints are added to the existing database. Items whose UUIDs already exist will +be skipped & the existing copies re-used. This allows you to copy all mission objects from one robot to another. + +To delete all data and restore a backup, instead of merging with existing data, use the `/mission_manager/restore` +service instead. + +::: + +#### mission_manager/import_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/ImportMission](definitions.mdx#storage-importmission) + +**Description:** Add existing Mission to the database. All UUIDs will be regenerated. + + +#### mission_manager/remove_task_from_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Remove a Task from a Waypoint. All instances of the Task are removed from the given Waypoint. + +#### mission_manager/remove_waypoint_from_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Remove a Waypoint from a Mission. All instances of the Waypoint are removed from the given Mission. + +#### mission_manager/restore + +**Service Type:** [clearpath_mission_manager_msgs/srv/ImportData](definitions.mdx#storage-importdata) + +**Description:** Overwite the database contents with data generated by the `mission_manager/export` service. This is +intended to be used to restore a backup of the missions and roll the database back to an earlier state. + +:::note + +All existing Missions, Tasks and Waypoints are deleted permanently and the entire database contents are replaced +with the imported data. + +To merge the data with the existing database, without deleting existing data, use the `/mission_manager/import` +service instead. + +::: + +#### mission_manager/split_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/SplitNetworkEdge](definitions.mdx#storage-splitnetworkedge) + +**Description:** Split an edge of network of paths map to create 2 edges connected to a new vertex between them. If +`symmetrical` is set to `true` the new edges will be bidirectional, otherwise only the edge going in one direction is +split. + +#### mission_manager/update_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateMission](definitions.mdx#storage-updatemission) + +**Description:** Modify a Mission. All attributes of the Mission are replaced with the provided values. + +:::note + +In 0.8.0 onward, all missions are required to have unique names. Assigning a name that is already in-use will result +in an error. + +::: + +#### mission_manager/update_network_edge + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdge](definitions.mdx#storage-updatenetworkedge) + +**Description:** Modify a network of paths edge + +#### mission_manager/update_network_edges + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdges](definitions.mdx#storage-updatenetworkedges) + +**Description:** Modify multiple network of paths edges + +#### mission_manager/update_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkEdge](definitions.mdx#storage-updatenetworkmap) + +**Description:** Modify a network of paths map + +#### mission_manager/update_network_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkMission](definitions.mdx#storage-updatenetworkmission) + +**Description:** Modify a network of paths map + +#### mission_manager/update_network_point + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkPoint](definitions.mdx#storage-updatenetworkpoint) + +**Description:** Modify a network of paths vertex + +#### mission_manager/update_network_points + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateNetworkPoints](definitions.mdx#storage-updatenetworkpoints) + +**Description:** Modify multiple network of paths vertices + +#### mission_manager/update_task + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateTask](definitions.mdx#storage-updatetask) + +**Description:** Modify a Task. All attributes of the Task are replaced with the provided values. + +#### mission_manager/update_waypoint + +**Service Type:** [clearpath_mission_manager_msgs/srv/UpdateWaypoint](definitions.mdx#storage-updatewaypoint) + +**Description:** Modify a Waypoint. All attributes of the Waypoint are replaced with the provided values. + +#### mission_manager/validate_network_map + +**Service Type:** [clearpath_mission_manager_msgs/srv/ValidateNetworkMap](definitions.mdx#storage-validatenetworkmap) + +**Description:** Manually run the network of paths validation on a specific map. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_scheduler_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_scheduler_api.mdx new file mode 100644 index 00000000..80a30da1 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/mission_scheduler_api.mdx @@ -0,0 +1,213 @@ +--- +title: Mission Scheduler API +sidebar_label: Mission Scheduler API +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Mission Scheduler API provides a ROS interface for creating, deleting, editing, and executing missions on a daily +schedule. Schedules are stored in a database-like structure on-disk, and can be executed manually or automatically. + +The web UI is the primary method of creating and modifying schedules, though the ROS API is available should you wish +to write your own interface or create automation tools to interact with the scheduler. + +## The Schedule Object + +A schedule consists of one or more missions to be executed in the specified order at a particular start time. For +consistency the start time is expressed as a 24-hour time in UTC. + +The schedule must be in one of 3 modes: +- `MODE_ONCE` -- the mission is executed exactly once per day, at the indicted UTC time +- `MODE_LOOP` -- the mission is executed a set number of times per day, starting at the indicated UTC time and repeating + at fixed intervals until the desired number of repetitions is reached +- `MODE_TRANSIENT` -- the mission is run exactly once, and is not saved to the persistent storage. This is intended to + be used for deferred execution of a mission (e.g. `execute mission X in 5 minutes` would use a transient schedule) + +Deleting a mission from the Mission Manager will result in that mission being automatically removed from any schedules +it was part of. If a schedule has no missions it is automatically disabled, and cannot be re-enabled until it contains +at least one mission. + +### A Note on Schedule Timing + +Automatically-scheduled missions are executed at the provided time +/- 10 seconds. The duration provided by the +`next_schedule` topic and `get_next_schedule` service is therefore approximate. We recommend rounding the time to the +nearest minute when displaying the countdown information to the user in any sort of GUI. + +## Topics Exported by Mission Scheduler + +### mission_scheduler/next_schedule + +**Message Type:** [clearpath_mission_scheduler_msgs/msg/NextSchedule](definitions.mdx#scheduler-nextschedule) + +**Description:** Publishes the UUID and duration to the next scheduled mission. If no missions are scheduled the UUID +will be blank. + +**Update Rate:** 1Hz + +### mission_scheduler/state + +**Message Type:** [clearpath_mission_scheduler_msgs/msg/StorageState](definitions.mdx#scheduler-state) + +**Description:** Publishes the current state of the database. Anything that needs to display the current set of +schedules should subscribe to this topic + +**Update Rate:** Latched, publishes on state-change only + +## Services Exported by Mission Scheduler + +### mission_scheduler/add_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Add a mission to an existing schedule. + +### mission_scheduler/clone_schedule + +**Service Type:** [clearpath_mission_scheduler_msgs/srv/CloneSchedule](definitions.mdx#scheduler-cloneschedule) + +**Description:** Perform a deep-copy of an existing schedule + +### mission_scheduler/create_schedule + +**Service Type:** [clearpath_mission_scheduler_msgs/srv/CreateSchedule](definitions.mdx#scheduler-createschedule) + +**Description:** Create a new schedule + +### mission_scheduler/delete_all_schedules + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteEverything](definitions.mdx#storage-deleteeverything) + +**Description:** Delete all schedules. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/delete_schedule + +**Service Type:** [clearpath_mission_manager_msgs/srv/DeleteById](definitions.mdx#storage-deletebyid) + +**Description:** Delete a single schedule. + +:::note + +This action is permanent and cannot be undone. Use with caution. + +::: + +### mission_scheduler/enable_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions.mdx#scheduler-enablechedule) + +**Description:** Enable or disable a schedule. + +:::note + +Disabled schedules can still be run manually with the `run_now` action (see below). Disabled schedules will never +be run automatically. + +::: + +### mission_scheduler/export + +**Service Type:** [clearpath_mission_scheduler_msgs/srv/ExportData](definitions.mdx#scheduler-exportdata) + +**Description:** Export all schedule data to a JSON string so it can be backed-up or copied to another robot. + +:::note + +This service is intended to be used in combination with the `import_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/get_all_schedules + +**Service Type:** [mission_scheduler/srv/GetAllSchedules](definitions.mdx#scheduler-getallschedules) + +**Description:** Get the list of all schedules. The list will include enabled, disabled, and transient schedules. + +### mission_scheduler/get_next_schedule + +**Service Type:** [mission_scheduler/srv/GetNextSchedule](definitions.mdx#scheduler-getnextschedule) + +**Description:** Get the UUID of the next schedule that will be run automatically. If nothing is scheduled (e.g. because +there are no enabled schedules) the UUID will be blank. + +:::note + +The duration is the approximate time left before the schedule will be started automatically. Schedules will start at +their designated start time +/- 10 seconds. + +::: + +### mission_scheduler/get_schedule + +**Service Type:** [mission_scheduler/srv/GetSchedule](definitions.mdx#scheduler-getschedule) + +**Description:** Get the schedule with the provided UUID. If an error occurred, or no schedule with the provided UUID +exists, the returned object will have a blank UUID. + +### mission_scheduler/import + +**Service Type:** [clearpath_mission_scheduler_msgs/srv/ImportData](definitions.mdx#scheduler-importdata) + +**Description:** Import data exported by the `export_data` service. This will add new schedules to the database +but will not modify or delete any existing schedules. + +:::note + +This service is intended to be used in combination with the `export_data` service to facilitate deploying new +schedules across multiple robots. + +::: + +### mission_scheduler/remove_mission + +**Service Type:** [clearpath_mission_manager_msgs/srv/AddRemoveById](definitions.mdx#storage-addremovebyid) + +**Description:** Remove the mission at a given position from a schedule, or remove all copies of a mission from a +schedule + +### mission_scheduler/restore + +**Service Type:** [cpr_mission_scheduler_msgs/srv/ImportData](definitions.mdx#scheduler-importdata) + +**Description:** Restore data exported by the `export_data` service. This will delete all schedules and replace the +database contents with the imported data. + +:::note + +This service is intended to be used in combination with the `export_data` service to facilitate backups or +synchronizing schedules across multiple robots. + +::: + +### mission_scheduler/update_schedule + +**Service Type:** [mission_scheduler/srv/UpdateSchedule](definitions.mdx#scheduler-updateschedule) + +**Description:** Modify an existing schedule. All of the schedule's properties are overwritten with the new values +provided in the service call. + +:::note + +Before modifying a schedule it is recommended to call the `get_schedule` service to get the schedule's current state, +copy all values to the service request object, and then change the fields you want to overwrite. + +::: + +## Actions Exported by Mission Scheduler + +### mission_scheduler/run_now + +**Action Type:** [clearpath_mission_scheduler_msgs/action/RunScheduleByUuid](definitions.mdx#scheduler-runschedulebyuuid) + +**Description:** Execute the schedule with the given UUID. The `delay` parameter will defer the execution by the +specified time. This action can be used to run a disabled schedule, or run a schedule at a time other than its +scheduled start time. + +**Feedback Rate:** 1Hz diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/platform_api.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/platform_api.mdx new file mode 100644 index 00000000..c2ce5b11 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_endpoints/platform_api.mdx @@ -0,0 +1,203 @@ +--- +title: Platform API +sidebar_label: Platform API +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Platform API provides topics to communicate with the hardware +platform (eg. sensor data, command velocity, tfs, etc\...). This API can +be used by autonomy software packages to interface with the hardware +platform. + +### Topics Published by UGV {#topics-published-by-platform} + +The topics in this section are published by the UGV. If available, they +are used by the OutdoorNav software. + +#### /tf + +  **Message Type:** tf2_msgs/TFMessage + +  **Description:** Transform tree describing the 3D links/frames of the +robot. + +#### /tf_static + +  **Message Type:** tf2_msgs/TFMessage + +  **Description:** Static links/frames of robot transform tree. + +#### /platform/cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** Platform-level velocity used to drive the robot. + +#### /platform/description + +  **Message Type:** std_msgs/String + +  **Description:** String containing robot URDF description. + +#### /platform/diagnostics_agg + +  **Message Type:** diagnostic_msgs/DiagnosticArray + +  **Description:** Provides a list of human-readable diagnostic messages +from various subsystems (sensors, onboard systems, localization, +navigation, mapping etc.) + +#### /platform/emergency_stop + + **Message Type:** std_msgs/Bool + + **Description:** True, if robot is emergency stopped, False, otherwise. + +#### /platform/id + +  **Message Type:** [clearpath_platform_msgs/PlatformID](definitions.mdx#msg-platform-id) + +  **Description:** Contains model, serial number, and hardware revision of +the platform + +#### /platform/joint_states + +  **Message Type:** sensor_msgs/JointState + +  **Description:** Position and velocity of robot's joints. + +#### /platform/odom + +  **Message Type:** nav_msgs/Odometry + +  **Description:** Platform-level wheel odometry. + +#### /platform/odom_filtered + +  **Message Type:** nav_msgs/Odometry + +  **Description:** EKF fused odometry from available sources on the +platform. This may include the wheel odometry, imu data, etc.. + +------------------------------------------------------------------------ + +The following table contains the types of sensors that could be +integrated onto our robot platforms. + +| Type | Test | +| ---- | ---------- | +| **gps** | A singular GPS (Global Positioning System) antenna/receiver pair. These may also be referred to as GNSS receivers. | +| **ins** | An inertial navigation system (INS) that consists of an IMU and a GPS unit. | +| **imu** | An inertial measurement unit consisting of an accelerometer, gyroscope and potentially a magnetometer. | +| **lidar** | A light emitting sensor that uses this light to determine the distance to obstacles. This includes 1D, 2D and 3D range detection sensors. | +| **radar** | A radio emitting sensor used to compute distance/velocity of obstacles. | +| **camera** | A singular lens (ie. mono) camera that produces an ROS image stream. This can therefore include regular mono cameras as well as single lens thermal imagers, etc\... | +| **stereo** | A type of camera with two or more image sensors. | + +#### /sensors/imu_\[0,1,\...\]/data + +  **Message Type:** sensor_msgs/Imu + +  **Description:** Raw data from IMU (gyro / acceleration) + +#### /sensors/imu_\[0,1,\...\]/magnetic_field + +  **Message Type:** sensor_msgs/MagneticField + +  **Description:** Reports the MPU 9250 Magnetometer sensor information. + +#### /sensors/_\[0,1,\...\]/fix + +  **Message Type:** sensor_msgs/NavSatFix + +  **Type:** gps, ins + +  **Description:** GPS latitude and longitude data. This data can either +be RTK corrected or regular GPS data. + +#### /sensors/_[0,1,\...\]/heading + +  **Message Type:** sensor_msgs/Imu + +  **Type:** gps, ins, imu + +  **Description:** RTK heading data computed from a dual GPS receiver +setup. + +#### /sensors/_\[0,1,\...\]/pointcloud + +  **Message Type:** Type: sensor_msgs/PointCloud2 + +  **Type:** lidar, radar, stereo, camera + +  **Description:** Raw pointcloud data generated from the specific sensor. + +#### /sensors/_\[0,1,\...\]/scan + +  **Message Type:** sensor_msgs/LaserScan + +  **Type:** lidar, radar, stereo, camera + +  **Description:** Raw scan data generated from the specific sensor. + +#### /sensors/_\[0,1,\...\]/camera_info + +  **Message Type:** sensor_msgs/CameraInfo + +  **Type:** camera, stereo + +  **Description:** Camera information including image dimensions, +distortion parameters, calibration parameters, etc\... + +#### /sensors/_\[0,1,\...\]/image + +  **Message Type:** sensor_msgs/Image + +  **Type:** camera, stereo + +  **Description:** Image data from the specific sensor. + +#### /sensors/_\[0,1,\...\]/depth/camera_info + +  **Message Type:** sensor_msgs/CameraInfo + +  **Type:** camera, stereo + +  **Description:** Camera information for the depth image including image dimensions, +distortion parameters, calibration parameters, etc\... + +#### /sensors/_\[0,1,\...\]/depth/image_rect_raw + +  **Message Type:** sensor_msgs/Image + +  **Type:** camera, stereo + +  **Description:** Raw depth image from the specific sensor. + +#### /onboard_systems/wireless/connection + +  **Message Type:** wireless_msgs/Connection + +  **Description:** Information about the robot's wireless connection +including ssid, frequency, bitrate, and signal and noise levels. + +#### /onboard_systems/bms/state + +  **Message Type:** sensor_msgs/BatteryState + +  **Description:** State data for each battery module installed. + +------------------------------------------------------------------------ + +### Topics Subscribed to by UGV {#topics-subscribed-by-platform} + +The UGV subscribes to the topics in this section. + +#### /cmd_vel + +  **Message Type:** geometry_msgs/Twist + +  **Description:** The command velocity to the platform layer effectively +commanding the wheels to spin. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx new file mode 100644 index 00000000..333bd135 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/api_examples.mdx @@ -0,0 +1,21 @@ +--- +title: API Examples +sidebar_label: API Examples +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav API examples are now available and accesible to everyone. A +[Python API library](https://github.com/cpr-application/clearpath_onav_examples) along +with some example scripts are available to build and use for our application. + +A few examples scripts follow with detailed explanations: + +- [Execute Mission from File](./mission_from_file.mdx) +- [Execute Mission with Custom Task](./mission_with_custom_tasks.mdx) +- [Status Monitoring](./monitor_status.mdx) +- [Network of Paths](./network_of_paths.mdx) + +The documentation for the Python API library can be built following the +instructions in the above linked GitHub repository. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx new file mode 100644 index 00000000..eff0f768 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_from_file.mdx @@ -0,0 +1,210 @@ +--- +title: Mission from YAML File +sidebar_label: Mission from YAML File +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## The Code + +``` python +#! /usr/bin/env python3 + +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +import time +import os + +# The file containing the mission configuration (adjust as needed) +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" + +class MissionFromYamlFile(RosNode): + """ + Create and run a mission loaded from a YAML configuration file. + Be sure that your robot is within 3 meters of your first Waypoint prior to starting the mission. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE) + + # NOTE: to save the configuration to file, uncomment the following lines: + # YamlConfig.missionToYamlFile('/tmp/test1.yaml', self.mission) + + def run(self): + """Execute the mission.""" + + if not self.mission.startMission(): + return False + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MissionFromYamlFile().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +Let's break down the code. + +``` python +#! /usr/bin/env python3 +``` + +Every Python ROS Node will have this declaration at the top. The first line makes sure your script is executed as a Python3 script. + + +``` python +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.yaml_config import YamlConfig +``` + +We provide a library of classes that can be used within your file for ease of use. In the above example, we import the RosNode and YamlConfig classes. +The RosNode class is used by all of our examples to initialize a ROS node that will execute the example mission. The YamlConfig class is used to import +a YAML file and convert it to a Mission object. + +``` python +MISSION_YAML_FILE = os.environ.get("HOME", "administrator") + "/example_ws/src/" + \ + "CPR-OutdoorNav/src/cpr_outdoornav_api_examples/config/sample_mission.yaml" +``` + +This defines the file path of the YAML file that contains the mission to be executed. See the [YAML file](#yaml-file) below for the example YAML file +that will be executed. + +``` python +class MissionFromYamlFile(RosNode): +``` + +Creates a class for your example, which inherits a RosNode object. All python mission files are requried to inherit the RosNode class. + +``` python + RosNode.__init__(self, 'mission_from_yaml_file') + self.mission = YamlConfig.yamlFileToMission(MISSION_YAML_FILE)``` +``` + +Initialize the ROS node with name `mission_from_yaml_file` and import the the mission from the yaml config file. The `YamlConfig.yamlFileToMission()` function +reads teh configuration you have created in the YAML file and converts it into a Mission object. + +``` python + if not self.mission.startMission(): + return False +``` + +Upon execution of the script, the `self.mission.startMission()` function creates the mission client if not yet created, connects to the mission action server +and sends the goal to the action server to begin the execution of the mission. + +``` python + while not self.mission.isMissionComplete(): + time.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +`self.mission.isMissionComplete()` monitors the mission status and only proceeds to terminating the mission has completed or been cancelled. + + +## YAML File {#yaml-file} + +The following YAML file is used in the above example mission. + +``` python +mission: + header: + seq: 0 + stamp: + secs: 0 + nsecs: 0 + frame_id: '' + name: "Sample Mission" + uuid: "8f57fd20-8a8c-4748-85ef-be1495b3ee06" + waypoints: + - + name: "Waypoint: 60" + uuid: "3edcedd7-ae0d-47cf-bd23-f7988d2779b7" + latitude: 50.10950820165676 + longitude: -97.31898507913323 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 61" + uuid: "ad23202e-7067-4f1c-8677-2dc07af1e729" + latitude: 50.1095698924641 + longitude: -97.31929487427445 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 62" + uuid: "fe452e77-4a26-41b0-b4ab-ee1859612a60" + latitude: 50.109437123117864 + longitude: -97.31946787675591 + heading: -1.0 + tasks: + - + name: "Wait" + uuid: "ec1121a8-7481-420f-b532-c47ea86afcd7" + service_call: "/wait" + version: "0.0.0" + floats: [3.0] + strings: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 63" + uuid: "5ed54c1f-1599-497a-9c16-93c7ca6c355e" + latitude: 50.109384820042074 + longitude: -97.3194477601883 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 64" + uuid: "2e021345-636b-4bd3-81ba-4f6901fdc016" + latitude: 50.10934056359333 + longitude: -97.31936192949982 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 65" + uuid: "00c041ee-2ca4-40ba-8e38-65ac900d5a1d" + latitude: 50.10946930962604 + longitude: -97.31921709021302 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 66" + uuid: "a5826fc5-b696-4b63-82aa-cc2e7a426640" + latitude: 50.10949344950718 + longitude: -97.31911382516594 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + - + name: "Waypoint: 67" + uuid: "7ff204b2-79a3-46da-a8c0-2c734b4c5314" + latitude: 50.10949613171619 + longitude: -97.31898910244675 + heading: -1.0 + tasks: [] + position_tolerance: -1.0 + yaw_tolerance: -1.0 + onav_config: "To be determined" +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx new file mode 100644 index 00000000..30ec477e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/mission_with_custom_tasks.mdx @@ -0,0 +1,233 @@ +--- +title: Mission with Custom Tasks +sidebar_label: Mission with Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Before being able to run the examples similar to the one explained below, it is required that you have written your own custom tasks. See the +[Custom Tasks](../../features/custom_tasks.mdx) section for information on how to develop tasks for your application. + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction + + +CUSTOM_ACTION_NAME = "/record_gnss" +UNSPECIFIED_HEADING = -1 + + +class MissionWithCustomTask(RosNode): + """Create and run a mission with 3 waypoints, each of which executes a custom task. + + Our goal is to set up 3 waypoints, then create a mission such that the robot drives + to each waypoint in order. In addition, at each of the waypoints, a custom task will be + called to record the timestamp, goal name, and GPS coordinates. Since this is a custom task, + it is necessary to create an actionlib server to implement the custom task. + + The main component of this example is the mission builder, which builds up the set of goals, + including information on the custom tasks, and runs the mission, to execute the custom task. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 43.50076203007681, -80.546296281104, UNSPECIFIED_HEADING), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 43.50073600330896, -80.54621215801687, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 43.50067256664828, -80.5462159469465, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) + + def getMission(self): + """Gets a reference to the mission. + + Returns + ------- + A reference to the mission. + """ + return self._mission + + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() + + + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + rospy.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() + + +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +## The Code Explained + +``` python +import rospy +import actionlib +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from clearpath_navigation_msgs.msg import Task, UITaskResult, UITaskAction +``` + +Import the `RosNode`, `Waypoint` and `Mission` classes which will be used to create the mission to be executed. +We also import the `Task` and `UITask` messages which are used to generate the action servers. + +``` python + class MissionBuilder: + """Creates and runs the mission, including custom tasks.""" + + def __init__(self): + """Creates the mission with 3 waypoints and custom tasks.""" + + # First waypoint, with custom task + waypoint_a_name = "A" + custom_task_a = Task() + custom_task_a.name = "my_custom_task_a" # choose any name here + custom_task_a.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_a.version = "1.0" # choose any version + custom_task_a.floats = [1000] # param: unique ID + custom_task_a.strings = [waypoint_a_name] # param: goal name + + # Second waypoint, with custom task + waypoint_b_name = "B" + custom_task_b = Task() + custom_task_b.name = "my_custom_task_b" # choose any name here + custom_task_b.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_b.version = "1.0" # choose any version + custom_task_b.floats = [1001] # param: unique ID + custom_task_b.strings = [waypoint_b_name] # param: goal name + + # Third waypoint, with custom task + waypoint_c_name = "C" + custom_task_c = Task() + custom_task_c.name = "my_custom_task_c" # choose any name here + custom_task_c.action_server_name = CUSTOM_ACTION_NAME # must match server name + custom_task_c.version = "1.0" # choose any version + custom_task_c.floats = [1002] # param: unique ID + custom_task_c.strings = [waypoint_c_name] # param: goal name + + + waypoints = [ + Waypoint(waypoint_a_name, "uuid-waypoint-01", 50.1095255, -97.3192484, UNSPECIFIED_HEADING, [custom_task_a]), + Waypoint(waypoint_b_name, "uuid-waypoint-02", 50.1094938, -97.3191085, UNSPECIFIED_HEADING, [custom_task_b]), + Waypoint(waypoint_c_name, "uuid-waypoint-03", 50.1094600, -97.3192100, UNSPECIFIED_HEADING, [custom_task_c]), + ] + + # Build mission from two waypoints with custom tasks + self._mission = Mission("Custom task mission", "uuid-mission-1", waypoints) +``` + +We create the `MissionBuilder` subclass that will create the mission to be executed. We initialize custom task objects +where we specify the `action_server_name` field with the specific action of the custom task. These are then added to the +Waypoints as a list of tasks and the Mission object is created. + +``` python + def __init__(self): + """Initializes ROS, the custom task server, GPS subscriber and mission.""" + + RosNode.__init__(self, 'mission_with_custom_task') + self._mission_builder = MissionWithCustomTask.MissionBuilder() +``` + +We initialize the example class by starting a ROS node and initialize the mission to be executed. + +``` python + def run(self): + """Execute the mission. + + This function blocks until the mission is complete. + + Returns + ------- + True on successful execution of the mission; else False on any error. + """ + + if not self._mission_builder.getMission().startMission(): + return False + while not self._mission_builder.getMission().isMissionComplete(): + time.sleep(1.0) + return self._mission_builder.getMission().getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MissionWithCustomTask().run(): + print("Mission completed successfully") + else: + print("Mission failed") + rospy.signal_shutdown('Done') +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. + + diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx new file mode 100644 index 00000000..077a9fcf --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/monitor_status.mdx @@ -0,0 +1,152 @@ +--- +title: Monitor Status +sidebar_label: Monitor Status +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## The Code + +``` python +#! /usr/bin/env python3 + +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor + + +class MonitorStatus(RosNode): + """Run a simple mission and report status throughout. + + The coordinates used in this example are based on the cpr_agriculture_gazebo + world and should be updated to match the location in which the user's + robot will be operating. + """ + + def __init__(self): + """Initialize the mission details and server connection.""" + + RosNode.__init__(self, 'monitor_status') + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() + + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() + + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() + + +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") + +``` + +## The Code Explained + +``` python +import rospy +from cpr_outdoornav_api_examples_lib.ros_node import RosNode +from cpr_outdoornav_api_examples_lib.waypoint import Waypoint +from cpr_outdoornav_api_examples_lib.mission import Mission +from cpr_outdoornav_api_examples_lib.platform_status import PlatformStatusMonitor +from cpr_outdoornav_api_examples_lib.control_status import ControlStatusMonitor +from cpr_outdoornav_api_examples_lib.localization_status import LocalizationStatusMonitor +from cpr_outdoornav_api_examples_lib.navigation_status import NavigationStatusMonitor +``` + +Import the `RosNode`, `Waypoint`, `Mission` classes which will be used to create the mission to be executed. We also import the +`PlatformStatusMonitor`, `ControlStatusMonitor`, `LocalizationStatusMonitor`, `NavigationStatusMonitor` classes which are set up to monitor the topics +relavant to the platform, localization, contrle selection an navigation modules respectively. + +``` python + waypoints = [ + Waypoint("A", "uuid-waypoint-1", 50.1094938, -97.3191085), + Waypoint("B", "uuid-waypoint-2", 50.1095100, -97.3192000), + Waypoint("C", "uuid-waypoint-3", 50.1095255, -97.3192484), + ] + self.mission = Mission("Monitor status mission", "uuid-mission-1", waypoints) +``` + +After initializing the ROS node, we create a mission manually by first creating a list of Waypoint objects and then adding then using the waypoint list +to construct the Mission object. + +``` python + self._platform_status = PlatformStatusMonitor() + self._control_status = ControlStatusMonitor() + self._localization_status = LocalizationStatusMonitor() + self._navigation_status = NavigationStatusMonitor() +``` + +We then initialize the platform, control, localization and navigation monitors, which subscribes to several API topics. + +``` python + def _reportStatus(self): + """Report the current status.""" + + rospy.loginfo("--------------------------------------------------------") + self._platform_status.report() + self._control_status.report() + self._localization_status.report() + self._navigation_status.report() +``` + +The `_reportStatus()` function outputs the results of the monitors to the ROS logs. This includes both the internal ROS logs as well as terminal output. + +``` python + def run(self): + """Execute the mission and report status.""" + + if not self.mission.startMission(): + rospy.logerr("Failed to start mission") + return False + while not self.mission.isMissionComplete(): + self._reportStatus() + rospy.sleep(1.0) + return self.mission.getMissionSuccess() +``` + +The `run()` function starts the mission and checks for completion. Every seconds we run the `reportStatus()` function to output the status information. +Once complete we terminate the example code. + +``` python +if __name__ == '__main__': + if MonitorStatus().run(): + print("Mission completed successfully") + else: + print("Mission failed") +``` + +The main python execution block. We first initialize the example class (runs the __init__ function) and then execute the run() function which +executes the mission and outputs the status information. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/network_of_paths.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/network_of_paths.mdx new file mode 100644 index 00000000..c5944070 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_examples/network_of_paths.mdx @@ -0,0 +1,764 @@ +--- +title: Network of Paths +sidebar_label: Network of Paths +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Overview + +Network of paths uses a directed graph to define the robot's valid driving area. When executing a mission the robot +plans its route to follow the edges of the graph to get from waypoint to waypoint. The exact route taken is dynamic +and may change depending on the robot's exact starting location, detected obstacles along some edges, and the geometry +of the graph itself. + +![](/img/outdoornav_images/parking_lot_map.png) + +:::note + +All services in the `mission_manager` namespace are provided by OutdoorNav's `misssion_manager` node. This node is part +of the `autonomy` docker service. + +::: + +## Creating a map + +To create a map, use the `/mission_manager/create_network_map` service: + +```python +#!/usr/bin/env python3 + +import rospy +from clearpath_mission_manager_msgs.srv import * + +rospy.init_node("map_maker_example") + +map_maker_service = rospy.ServiceProxy("/mission_manager/create_network_map", CreateNetworkMap) +map = map_maker_service("Example Map", 2.5, 1.0, [], []).result + +print(map) +``` + +This program produces an empty map with an automatically generated UUID: + +```yaml +name: "Example Map" +uuid: "c7c6bd2e-06dd-4f61-9ab0-f81fa896a915" +default_radius: 2.5 +default_speed_limit: 1.0 +points: [] +connections: [] +``` + +From here you can use the `/mission_manager/add_network_point` and `/mission_manager/add_network_edge` services to +add vertices and connect them. However, this can be very slow if your map is large. A faster way is to include the +vertices and edges in the request to create the map: + +```python +#!/usr/bin/env python3 + +import rospy + +from clearpath_mission_manager_msgs.msg import * +from clearpath_mission_manager_msgs.srv import * +from clearpath_navigation_msgs.msg import * + +# A tuple of (TAG, longitude, latitude, altitude), copied from a Google Earth KML file +# Tags are added manually to identify each coordinate +# The tag is used as a placeholder for the generated UUIDs to simplify defining the edges ourselves +COORDINATES = [ + ("A", -97.28322817327727,50.12300747122199,0), + ("B", -97.28217525643019,50.12171056479555,0), # the first intersection, connects to C and L + ("C", -97.28326793963477,50.11981930442499,0), # the second intersection, connects to D and H + ("D", -97.28483408203536,50.11926816962462,0), + ("E", -97.28486964915798,50.11761512315844,0), + ("F", -97.28166555083155,50.11758334859005,0), + ("G", -97.28229122963415,50.11952637327663,0), + ("H", -97.28167846932446,50.11913714171172,0), # the third intersection, connects to I and C + + # A dead-end side-branch + ("I", -97.28219097560832,50.11973533270263,0), # forks from H + ("J", -97.28249905504131,50.1199092365631,0), + ("K", -97.28242834054022,50.12013941719884,0), + + # Another dead-end side-branch + ("L", -97.28242899160524,50.12209511863426,0), # forks from B + ("M", -97.28246941874356,50.12229616417419,0), + ("N", -97.28325139122391,50.12230651895854,0), +] + +DEFAULT_RADIUS = 2.5 +DEFAULT_SPEED_LIMIT = 1.0 + +rospy.init_node("map_maker_example_2") + +map_maker_service = rospy.ServiceProxy("/mission_manager/create_network_map", CreateNetworkMap) +map = map_maker_service( + "Example Map", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT, + + # The vertices + # This is just a simple array of NetworkPoint objects. Each must have a unique ID, a one-letter tag in this + # example + [ + NetworkPoint(c[1], c[0], c[2]) for c in COORDINATES # Note that NetworkPoint uses latitude first! + ], + + # The edges. This defines the geometry of the map + # Edges are unidirectional, so we must manually add edges going in both directions where necessary + [ + NetworkEdgeReq("A", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("B", "A", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("B", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("C", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("C", "D", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("D", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("D", "E", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("E", "D", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("E", "F", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("F", "E", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("F", "G", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("G", "F", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("G", "H", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("H", "G", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("H", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), # end of the main road & loop + NetworkEdgeReq("H", "C", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("H", "I", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("I", "H", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("I", "J", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("J", "I", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("J", "K", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("K", "J", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), # end of one fork + + NetworkEdgeReq("B", "L", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("L", "B", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("L", "M", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("M", "L", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + + NetworkEdgeReq("M", "N", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + NetworkEdgeReq("N", "M", DEFAULT_RADIUS, DEFAULT_SPEED_LIMIT), + ] +).result + +print(map) +``` + +The program's output looks like this: +```yaml +name: "Example Map" +uuid: "3b3bed4e-bcfb-40d4-bc2e-3d5e904890cf" +default_radius: 2.5 +default_speed_limit: 1.0 +points: + - + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + - + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + - + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + - + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + - + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + - + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + - + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + - + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + - + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + - + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + - + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + - + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + - + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + - + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 +connections: + - + uuid: "9152c6ee-6cb0-4a6a-a1a3-a156c137e10b" + start_point: + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "af77ee8c-9460-4c4a-bb23-d8eab4877bd8" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "1bef3d7d-3ead-49c7-9306-ede6c4030ebb" + latitude: 50.12300747122199 + longitude: -97.28322817327727 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "077e176e-531a-4afa-9c55-48496ddb19a3" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "8f605876-10d0-43bf-ade3-4acec11b90a4" + start_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "98cdf58f-76d1-4b00-8119-44850b20c006" + start_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + end_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "94f20e66-aea9-4ea8-8029-31eba37ba800" + start_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "356d56a0-1165-48ef-87ab-b3e289b6d275" + start_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + end_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "40438b94-fd92-4e95-bb31-1737d235c8ca" + start_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + end_point: + uuid: "7bd501a1-ef93-46b9-a440-213755522954" + latitude: 50.11926816962462 + longitude: -97.28483408203536 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "97e40361-123c-4f33-9dae-3bd293d5a001" + start_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + end_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "5ca07677-1ec9-4355-bfdb-f04801d18feb" + start_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + end_point: + uuid: "9e6c1b11-8430-4986-9091-da440b57df85" + latitude: 50.11761512315844 + longitude: -97.28486964915798 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "ac299ea0-18f0-42ed-ab82-01c4789c979d" + start_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + end_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "754ad065-c3e8-41de-b0c2-a32e7247db40" + start_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + end_point: + uuid: "7a0d3f02-85c3-4907-9bb8-0b2245736b9b" + latitude: 50.11758334859005 + longitude: -97.28166555083155 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "dcd5ca9f-5ad7-4404-a6a2-c5ab8b3bb0f5" + start_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + end_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "66884078-ab62-439b-be51-3446cf92809e" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "0b289f8f-86b8-413f-b35e-cadbd5c4ef31" + latitude: 50.11952637327663 + longitude: -97.28229122963415 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "948eca22-3bf2-443a-b117-a551c6503c2a" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "9e445547-0e42-4ba4-8411-6228288d3ae8" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "1efac02f-8dfc-4826-a4cc-894d2cac16f9" + latitude: 50.11981930442499 + longitude: -97.28326793963477 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "d15e27d7-e4aa-479c-b9bf-705c70ccbdfc" + start_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + end_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "1295c8da-65df-4b5b-a214-f7579ad7179d" + start_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + end_point: + uuid: "6db9a882-d40b-4050-ad60-3947c4a936d0" + latitude: 50.11913714171172 + longitude: -97.28167846932446 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "be0f8c9f-0f42-4f9a-9140-050ac617cd10" + start_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + end_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "6b1a04c8-e5d9-441d-b7d2-5426070d210f" + start_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + end_point: + uuid: "05b6fb7f-b071-4aa2-b253-1fdf942097c9" + latitude: 50.11973533270263 + longitude: -97.28219097560832 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "bee2318d-0e19-427b-aa15-a5aa195212be" + start_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + end_point: + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "159619a1-9a8e-41d0-b41b-918b187ac70c" + start_point: + uuid: "8a013830-fb3a-4225-84d3-946810dede60" + latitude: 50.12013941719884 + longitude: -97.28242834054022 + end_point: + uuid: "e77610aa-132d-45b1-83e2-0f8c9b5eafff" + latitude: 50.1199092365631 + longitude: -97.28249905504131 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "79e510bd-5f24-4251-9169-995f30212966" + start_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + end_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "720679a5-2eda-4f21-b430-9ea34be3076d" + start_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + end_point: + uuid: "a56eb1c5-3bee-4d4a-84e0-780651db67cd" + latitude: 50.12171056479555 + longitude: -97.2821752564302 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "40fdd435-c7da-4e91-895b-e3dd3c872dbd" + start_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + end_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "fff60db8-90ce-484b-ba44-a0637263f727" + start_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + end_point: + uuid: "d42dd9ce-dc49-4226-ab28-18ac644da0f6" + latitude: 50.12209511863426 + longitude: -97.28242899160524 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "995875bd-55dd-418b-81cc-72f3d957d119" + start_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + end_point: + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 + - + uuid: "9fc59ccd-75a7-4b0a-ab3e-d3c6e9bd9fb9" + start_point: + uuid: "4d6addba-73f4-4373-8e3c-0f7caf155283" + latitude: 50.12230651895854 + longitude: -97.28325139122391 + end_point: + uuid: "aa198f25-78b5-48e0-a9df-750ffb4080a5" + latitude: 50.12229616417419 + longitude: -97.28246941874356 + radius: 1.0 + speed_limit: 2.5 + cost_factor: 1.0 +``` + +Note that in the process of creating the map, all of the points' UUIDs have been regenerated. This is to ensure that +all points saved on the robot have unique identifiers. + +### Getting the coordinates for vertices + +The coordinates for the vertices in the example above were generated by drawing the desired paths using Google Earth's +path tool. The project was exported as a KML file, which can be opened in a text editor: + +```xml + + + + Untitled + + + + + + + + + normal + #__managed_style_1EF00888ED2FB5E604EF + + + highlight + #__managed_style_2832AC86D92FB5E604EF + + + + Main Path + + -97.28114320519418 + 50.1207190898435 + 255.3655780539208 + 1.174355479883316 + 0 + 35 + 1653.897493233089 + absolute + + #__managed_style_08F931B1C22FB5E604EF + + + -97.28322817327727,50.12300747122199,0 -97.28326793963477,50.11981930442499,0 -97.28483408203536,50.11926816962462,0 -97.28486964915798,50.11761512315844,0 -97.28166555083155,50.11758334859005,0 -97.28167846932446,50.11913714171172,0 -97.28229122963415,50.11952637327663,0 -97.28219097560832,50.11973533270263,0 -97.28249905504131,50.1199092365631,0 -97.28242834054022,50.12013941719884,0 + + + + + Side Path + + -97.28114320516248 + 50.1207190898435 + 255.3655780539208 + 1.174355479883316 + 0 + 35 + 1653.897493233089 + absolute + + #__managed_style_08F931B1C22FB5E604EF + + + -97.28217525643019,50.12171056479555,0 -97.28242899160524,50.12209511863426,0 -97.28246941874356,50.12229616417419,0 -97.28325139122391,50.12230651895854,0 + + + + + +``` + +![](/img/outdoornav_images/network-map-google-earth.png) + +The `` tags contain space-separated lists of the form `lon_0,lat_0,alt_0 lon_1,lat_1,alt_1 lon_2,lat_2,alt_2 ...`. +By copying these lists into Python and converting them to Lists or Tuples you can create the lists of coordinates: + +```python +# KML coordinates: +# +# -97.28217525643019,50.12171056479555,0 -97.28242899160524,50.12209511863426,0 -97.28246941874356,50.12229616417419,0 -97.28325139122391,50.12230651895854,0 +# + +lon_lat_alt = [ + (-97.28217525643019, 50.12171056479555, 0), + (-97.28242899160524, 50.12209511863426, 0), + (-97.28246941874356, 50.12229616417419, 0), + (-97.28325139122391, 50.12230651895854, 0) +] +``` + +## Executing a mission + +To execute a Network of Paths mission, you need to know the UUID of the mission to execute and the UUID of the map. The +UUIDs are generated when the objects are created, so you may need to search the available objects to determine the +appropriate mission & map if you have more than one. + +```python +from clearpath_mission_manager_msgs.msg import * +from clearpath_mission_manager_msgs.srv import * + +import actionlib +import rospy + +# 1) Get all of the Network of Paths maps and missions from the mission manager +all_maps_srv = rospy.ServiceProxy("/mission_manager/get_all_network_maps", GetAllNetworkMaps) +all_missions_srv = rospy.ServiceProxy("/mission_manager/get_all_network_missions", GetAllNetworkMissions) +maps = all_maps_srv() +missions = all_missions_srv() + +# Do a simple search for the map with the desired name +# You can replace the name, or search for any other attribute of the NetworkMap object +map = None +for m in maps: + if m.name == "My Map": + map = m + break + +# As above, but looking for the desired mission instead of the desired map +mission = None +for m in missions: + if m.name == "My Mission": + mission = m + break + + +# we have the map & the mission; we can run the mission +if map and mission: + # 1) create the actionlib client + mission_execution_client = actionlib.SimpleActionClient("/autonomy/network_mission", ExecuteNetworkMissionByUuidAction) + + # 2) create the goal + goal = ExecuteNetworkMissionByUuidGoal(mission.uuid, map.uuid) + + # 3) send the goal to the server + mission_execution_client.send_goal(goal) + + # 4) Wait for the mission to finish executing + mission_execution_client.wait_for_result() +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx new file mode 100644 index 00000000..d9c6d616 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/api/api_overview.mdx @@ -0,0 +1,63 @@ +--- +title: API Overview +sidebar_label: API Overview +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +While the Web User Interface provides a great way to get started quickly +with OutdoorNav Software, some users will want programmatic control or +may wish to develop their own graphical user interfaces \-- for those +users, the Application Programming Interface (API) provides the +flexibility to do so. This is illustrated in the figure below. + +
+
+ +
Interconnection between OutdoorNav Software and UGV Controller
+
+
+ +The API is, at present, a [ROS 1 Noetic](http://wiki.ros.org/noetic) API, +but will soon be extended to a ROS 2 API. The API is divided into two +sections, whose details are provided below: + +- [Platform API](api_endpoints/platform_api.mdx): The set of [ROS + Topics](http://wiki.ros.org/Topics) are used to comminucate with the + hardware platform (eg. sensor data, wireless, battery state, command + velocity). This API can be used by autonomy software packages to + interface with the hardware platform. + - [Topics Published by UGV](api_endpoints/platform_api.mdx#topics-published-by-platform): + The set of topics that are published by the hardware platform. + - [Topics Subscribed to by UGV](api_endpoints/platform_api.mdx#topics-subscribed-by-platform): + The set of topics that are subscribed to by the hardware + platform. +- [Autonomy API](api_endpoints/autonomy_api.mdx): The set of [ROS + Topics](http://wiki.ros.org/Topics) that are used for monitoring and + controlling the the hardware platform through the OutdoorNav + autonomy software. + - [Topics Published by Autonomy](api_endpoints/autonomy_api.mdx#topics-published-by-autonomy): + The set of [ROS Topics](http://wiki.ros.org/Topics) published by + OutdoorNav Software, to be subscribed to by the UGV. + - [Topics Subscribed to by Autonomy](api_endpoints/autonomy_api.mdx#topics-subscribed-to-by-autonomy): + The set of [ROS Topics](http://wiki.ros.org/Topics) + subscribed to by OutdoorNav Software, typically published by the + client for directing OutdoorNav operation. + - [Services Exported by Autonomy](api_endpoints/autonomy_api.mdx#services-exported-by-autonomy): + The set of [ROS Services](http://wiki.ros.org/Services) provided + by OutdoorNav Software, for use by the client to modify/control + the behaviour of the Autonomy. + - [Actions Exported by Autonomy](api_endpoints/autonomy_api.mdx#actions-exported-by-autonomy): + The set of [ROS Actions](http://wiki.ros.org/actionlib) provided + by OutdoorNav Software, for use by the client to modify/control + the behaviour of the Autonomy. +- [Mission Manager API](api_endpoints/mission_manager_api.mdx): The set of [ROS + Services](http://wiki.ros.org/Services) that are used for creating, deleting, and modifying OutdoorNav Missions +- [Mission Scheduler API](api_endpoints/mission_scheduler_api.mdx): The set of [ROS Services](http://wiki.ros.org/Services) + that are used for creating, deleting, and modifying OutdoorNav Mission Schedules +- [Definitions](api_endpoints/definitions.mdx): The set of custom + [ROS Message](http://wiki.ros.org/Messages), [ROS + Service](http://wiki.ros.org/Services), and [ROS + Action](http://wiki.ros.org/actionlib) definitions. +- API Examples: Example code to come. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx new file mode 100644 index 00000000..f60527ff --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/cpr_hardware.mdx @@ -0,0 +1,405 @@ +--- +title: "Appendix B: CPR Hardware" +sidebar_label: "Appendix B: CPR Hardware" +sidebar_position: 13 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +When using a Clearpath Robotics UGV and Base Station, the following +hardware setup may be required. + +## Calibrating the IMU + +Although IMU magnetometers are calibrated at the factory to remove any +internal magnetic influences in the device, measurements are still +subject to influence from external magnetic anomalies when the sensor is +installed. These anomalies are divided into two classes: hard iron +offsets and soft iron distortions. Hard iron offsets are created by +objects that produce a magnetic field. Soft iron distortions are +considered deflections or alterations in the existing magnetic field. +Ideally, these influences are mitigated by installing the sensor away +from magnetic sources, such as coils, magnets, and ferrous metal +structures and mounting hardware. However, often these sources are hard +to avoid or are hidden. To mitigate this effect when using the IMU +magnetometer to aid in heading estimations, a field calibration of the +magnetometer after final installation is highly recommended. This means +that the IMU must be calibrated in the same environment that you use +your UGV for autonomous navigation. + +### Microstrain IMU + +If your UGV has a 3DM-GX5-25 Microstrain IMU, the complete instruction +on calibration of your IMU can be found in section 5.4 of the +[datasheet](https://www.microstrain.com/sites/default/files/3dm-gx5-25_user_manual_8500-0012.pdf). +Note that you need a computer with Windows system and the LORD Sensing +MIP Hard and Soft Iron Calibration software installed which can be found +at the Microstrain website. + +### UM6/7 IMU + +If you are using UM6 or UM7 IMUs, you will need the magnetometer display +package which is located at the following address on your UGV: +`~/catkin_ws/Drivers/src/imu_tools/magnetometer_display`. + +Follow these steps to calibrate the IMU on your machine: + +1. Create a catkin workspace on your local machine and copy the package + `magnetometer_display` into your src folder. Build this package with + the `catkin_make` command. + +2. Perform the following command to make the calibration script + executable: + + ``` bash + $ sudo chmod +x calibration.py + ``` + +3. Connect the IMU to your computer and launch the driver. Or if you + are on the same network as your UGV, make your UGV the ROS master + and ensure that you can echo the IMU topic on your computer. + +4. Open the `magnetometer.launch` file in the `magnetometer_display` + package and change the sections shown in the figure below. + Specifically, set `use_mag_field` to true when the IMU is outputting + magnetometer measurements with a `sensor_msgs/MagneticField` + message, otherwise set to false. Microstrain is the only IMU which + uses the MagneticField message type. + +
+
+ +
Magnetometer calibration, general launch settings
+
+
+ +5. Launch the calibration using the following command: + + ``` bash + $ roslaunch magnetometer_display magnetometer.launch + ``` + +6. Move the IMU around to get good coverage. RViz will display + magnetometer points (red) and will plot current ellipsoid fit + (green) as shown in the figure below. + +
+
+ +
Magnetometer calibration, ellipsoid fit plot
+
+
+ +7. Ellipsoid fit parameters are displayed in terminal as shown in the + figure below. + +
+
+ +
Magnetometer calibration, ellipsoid fit + parameters
+
+
+ +8. Once there are enough red points on your fitted ellipsoid, enter the + above calibrations in the IMU driver launch file. Open the + `sensor.launch` file in the `cpr_gps_localization` package and go to + the UM7 (or UM6) section of the launch file. The figure below shows + this section for the UM7. + +
+
+ +
Magnetometer calibration, ellipsoid fit settings in launch file
+
+
+ + You should enter the parameters generated in the Ellipsoid fit step + as follows (to account for the NED to ENU transform the driver + applies): + + - Launch file X = Terminal Y + - Launch file Y = Terminal X + - Launch file Z = -Terminal Z + +## RTK Positioning GPS Setup + +:::note + +Please skip this section if your robot does not have RTK GPS. + +::: + +The following configuration is for establishing communications between +the Base Station and the UGV using TCP/IP for the purpose of +transmitting RTK corrections. Before starting this procedure, make sure +that you have installed the [SwiftNav +console](https://support.swiftnav.com/support/solutions/articles/44001903699-installing-swift-console). + +### Base Station GPS Configuration + +- Connect the Swift Navigation device to a computer via USB or the USB + to Serial Adapter cable. + +- Open Swift Console and connect to the device. + +- Set the following options in the **ethernet** section as shown in + the figure below. + + 1. ip_config_mode: `Static` + 2. ip_address: `192.168.131.30` + 3. netmask: `255.255.255.0` + +
+
+ +
Base Station Ethernet settings
+
+
+ +- Set the following options in the **tcp_server1** section as show in + the figure below. + + 1. mode: `SBP` + 2. port: `55556` + 3. enabled_sbp_messages: `72,74,117,65535` + +
+
+ +
Base Station TCP1 Server settings
+
+
+ +- Set the following options in the **solution** section as shown in + the figure below. + + 1. soln_freq: `10` + 2. correction_age_max: `30` + 3. output_every_n_obs: `10` + 4. dgnss_solution_mode: `Low Latency` + +
+
+ +
Base Station Solution settings
+
+
+ +- Next the Base Station has to be surveyed. There are two ways of + doing this which are explained in [RTK Survey Positioning](#base-station-survey). +- Click Save to Flash. +- Close Swift Console. +- Disconnect the device from the computer. + +### UGV Position GPS Configuration {#ugv-position-gps-config} + +- Connect the Swift Navigation device to a computer via USB or the USB + to Serial Adapter cable. + +- Open Swift Console and connect to the device. + +- Set the following options in the **ethernet** section as shown in + the figure below. + + 1. ip_config_mode: `Static` + 2. ip_address: `192.168.131.31` + 3. netmask: `255.255.255.0` + +
+
+ +
UGV GPS Ethernet settings
+
+
+ +- Set the following options in the **tcp_client0** section as show in + the figure below. + + 1. mode: `SBP` + 2. port: `192.168.131.30:55556` + 3. enabled_sbp_messages: `0` + +
+
+ +
UGV GPS TCP Client0 settings
+
+
+ +- Set the following options in the **solution** section as show in the + figure below. + + 1. soln_freq: `10` + 2. correction_age_max: `30` + 3. output_every_n_obs: `10` + 4. dgnss_solution_mode: `Low Latency` + +
+
+ +
UGV GPS Solution settings
+
+
+ +- Click Save to Flash. + +- Close Swift Console. + +- Disconnect the device from the computer. + +Once you have entered these settings. Connect your computer to the Wi-Fi +network of the Base Station. Also make sure that the UGC (which is +connected to the UGV GPS unit) is also connected to the Base Station +Wifi. The you should be able to verify connectivity across the devices. +To check the Base Station, complete the following steps. + +- Open Swift Console on you computer +- Select **TCP/IP** +- For IP Address enter `192.168.131.30` +- For IP Port enter `55555` +- Click **OK** +- Select the **Observations** tab +- In the **Remote** section you should see observation data from your + UGV. + +To check the UGV, complete the following steps. + +- Open Swift Console +- Select **TCP/IP** +- For IP Address enter `192.168.131.31` +- For IP Port enter `55555` +- Click **OK** +- Select the **Observations** tab +- In the **Remote** section you should see observation data from your + Base Station. + +Further information on [RTK setup](https://swiftnav.freshdesk.com/support/solutions/articles/44001904334-piksi-multi-gnss-rtk-position-with-stationary-base%7D%7Bhttps://swiftnav.freshdesk.com/support/solutions/articles/44001904334-piksi-multi-gnss-rtk-position-with-stationary-base) +is available from SwiftNav. + +## RTK Survey Positioning {#base-station-survey} + +:::note + +Please skip this section if your UGV does not have RTK GPS. + +::: + +:::warning + +Once you have surveyed the location of the Base Station, you **cannot** +relocate the Base Station throughout your tests. Otherwise, this step +has to be repeated. + +::: + +There are three ways to survey the Base Station location: + +1. OutdoorNav Web User Interface (easiest/accurate), +2. Swiftnav console autosurvey (fastest/least accurate), +3. ROS launch file geodetic survey (for debug output display). + +Using the OutdoorNav Web UI is the easiest and most accurate way to do +this since it runs the ROS geodetic survey tool which uses more samples +to compute the final position of the Base Station than the Swiftnav +console. Using the geodetic ROS survey launch file directly would allow +the user to visualize the output log directly but requires preliminary +knowledge in ROS. + +### Base Station Survey: Web UI + +Using the OutdoorNav Web UI to survey the Base Station is very simple. +See [Survey Base Station](getting_started/system_setup.mdx#survey_base_station) for details. + +### Base Station Survey: Piksi Console + +Use the Piksi console connect the base station GPS. Go to "Settings -\> +surveyed position", click to any field in this section and then click +the button on the top right corner "Auto Survey". The figure below +shows these steps. The last 1000 GPS points will be used to compute the +position of the Base Station. + +
+
+ +
Auto Survey
+
+
+ +After that, make sure the four fields in "surveyed position" +(broadcast, surveyed lat, surveyed lon, surveyed alt) are consistent +with your location. + +### Base Station Survey: ROS Geodetic Survey + +The `ethz_piksi_ros` repository should be installed in the UGV's +`catkin_ws`. To run the surveying process simply connect your PC to the +Base Station network, `ssh` into the UGV's computer and run the +following: + +``` bash +roslaunch {robot_name}_gps_navigation geodetic_survey.launch +``` + +where `robot_name` is either `jackal`, `husky`, or `warthog` depending +on your UGV. The surveying will begin and you will see a running tally +of the collected data. + +## RTK Heading Setup + +For the rest of this section, it is assumed that a third Swiftnav Duro +device is available with IP address of 192.168.131.32. Note that in +order to change the IP address of a Swiftnav Duro, you need to use the +Swiftnav console and connect to the device with the serial port. + +:::note + +The instructions in this section will overwrite some of the settings set +in [UGV Position GPS Configuration](#ugv-position-gps-config) on the +Position/Reference Duro receiver. This is normal since the configuration +in [UGV Position GPS Configuration](#ugv-position-gps-config) is for a UGV +with only the position Duro receiver. If the heading receiver is +connected as well, please continue with the instructions below. + +::: + +The two Swiftnav Duro GPS device on the UGV are connected via serial +cable. They are also both connected via Ethernet cable to the computer +on the UGV. For computing the heading, on Duro (the one on the rear with +IP address 192.168.131.31) operates only to provide GNSS Observations to +the other Duro that computes an RTK derived heading (the Duro on the +front with IP address 192.168.131.32). For the purposes of this +document, we will call the Duro/Piksi that operates to provide the raw +GNSS observations only the "Reference Receiver" and the Duro/Piksi +producing heading measurements the "Attitude Receiver." + +Use the Swiftnav console to connect to the Reference Receiver (with IP +address of 192.168.131.31) and insert the settings shown in the figure +below. + +
+
+ +
Reference Receiver settings
+
+
+ +Next, connect to the Attitude Receiver (with IP address of +192.168.131.32) and change the configuration as shown in the figure +below. + +
+
+ +
Attitude Receiver settings
+
+
+ +For further information please refer to [these instructions](https://swiftnav.freshdesk.com/support/solutions/articles/44001907898-rtk-heading-gnss-compass-configuration%7D%7Bhttps://swiftnav.freshdesk.com/support/solutions/articles/44001907898-rtk-heading-gnss-compass-configuration). + +## Wireless Motion Stop + +Please refer to the hardware user manual of the motion stop device for proper +usage. A trained operator should be used to supervise navigation of the +UGV under autonomous control at all times. The Operator should be +familiar with the use of the wireless motion stop device. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json new file mode 100644 index 00000000..4c27a4d9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Appendix C: Tuning & Customization", + "position": 14 +} \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx new file mode 100644 index 00000000..3839162f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/sensor_customization.mdx @@ -0,0 +1,9 @@ +--- +title: "Sensor Customization" +sidebar_label: "Sensor Customization" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Information incoming in a future release. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json new file mode 100644 index 00000000..d62e291a --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tuning Instructions", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx new file mode 100644 index 00000000..51639337 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/ackermann_drive_dynamics.mdx @@ -0,0 +1,9 @@ +--- +title: "Ackermann Drive" +sidebar_label: "Ackermann Drive" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +Information incoming in release 0.10.0. Please contact Clearpath customer support at support@clearpathrobotics.com to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx new file mode 100644 index 00000000..ba6ee960 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/differential_drive_dynamics.mdx @@ -0,0 +1,570 @@ +--- +title: "Differential Drive" +sidebar_label: "Differential Drive" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +:::note + +**When tuning controllers, it is advised to always only modify one single parameter prior to each +test. This allows the user to analyze the effect of this single parameter on the controller performance.** + +::: + +# Tuning Flowchart + +When attempting to tune the navigation controller, it is recommended to follow the following +flowchart. Begin with setting up [Initial Parameters](#initialize_parameters) for your UGV. + +
+
+ +
Differential Drive Tuning Flowchart
+
+
+ +**Condition Blocks**: The condition blocks can be seen in the flowchart as **RED** decision +blocks and either contain tests needed to be run or features of the software that are +enabled/disabled. + +**Tuning Blocks**: The tuning blocks can be seen in the flowchart as **YELLOW** blocks where it +is expected that the user modifies a parameter prior to re-testing the controller. + +## Conditions Blocks {#condition_blocks} + +#### Velocity Deadband Tests {#velocity_deadband_tests} + +The "**Velocity Deadband?**" condition block asks the user to verify if there is a velocity deadband that the UGV +motors must overcome in order to move the UGV. (ie. what is the minimum velocity that the UGV +is required to receive, in order for it to move). + +To verify this, the user should set up two missions: + +1. A two Waypoint mission where the first Waypoint is located on the robot, and second Waypoint about 10-20 meters +directly in front of the UGV. This will verify the requried linear motion of the UGV. +2. A two Waypoint mission where the first Waypoint is located on the robot, and second Waypoint about 10-20 meters +directly behind the UGV. The first part of the navigation to this point (ie. the rotation to face the Waypoint) will +verify the required angular motion of the UGV. + +If the above tests demonstrate that the UGV **is stuck** in a velocity deadband and is not moving, +then proceed to [Tune Deadband](#tune_deadband). + +If the above tests demonstrate that the UGV **is NOT stuck** in a velocity deadband (ie. it can +smoothly start navigating the mission), proceed to the following condition block: [Oscillation Tests](#oscillation_tests). + +#### Oscillation Tests (Straights) {#oscillation_tests} + +The "**Oscillations on Straights?**" conditions block asks if there are any oscillations present during +normal navigation along a straight path. + +##### Tests + +To verify the amount of oscilations around the reference path, the user should set up four +missions, each of which should pass (or fall within the users requirements) prior to moving on from this section of the tuning. The start +and end points of each of the tests should be identical and the start position (XY) should +be noted/marked on the testing area. The first Waypoint should be placed on the robots current location and the second Waypoint should be +placed 20-30m away from the start position. The four UGV orientations for each test are as follows: + +1. Align the UGV with a 0° offset from the Waypoint. +2. Align the UGV with a 90° offset from the Waypoint. +3. Align the UGV with a -90° offset from the Waypoint. +4. Align the UGV with a 180° offset from the Waypoint. + +See the image below to determine the placement of the UGV. The red arrow indicates the +orientation of the UGV with respect to the Waypoint. + +
+
+ +
Oscillation Test Start Orientations
+
+
+ +It is not necessary to run all of the offset tests after every parameter change. It is enough +to progress systematically through the tests as they succeed. That is, if +there are no oscillations during a 0° offset test, proceed to run the 45° test and so on +and so forth. If the 0° offset test fails, then there is no need to run the other three tests before updating a parameter. +The condition has been satisfied when all of the test results in minimal to no +oscillations (or as is deemed acceptable). + +##### Causes + +Oscillations during navigation along straight paths can be caused by one or several of the following +reasons. They are listed here in order of likelihood of occurence: + +| | Cause | Description | +|-|-------|-------------| +| **1** | Untuned MPC parameters | The default MPC controller parameters have been tuned for CPR UGVs, and may not be the same for third-party OEM UGVs. | +| **2** | Controller delay | There may be delay present in your UGV between the time the navigation computes a command velocity and when the velocity is actually executed. This could appear as mechanical delay in your motors or even mechanical delay in the rotational components of UGVs control mechanisms . It is rarely noticed when electrical motors are used. The effect of controller delay is most commonly noticed when when entering a straight from a curve or after a pure rotation.| +| **3** | Deformable Tires | If your tires are deformable, then after coming out of a pure rotation, while the UGV may be facing the required direction of travel, a purely linear command velocity would cause the UGV to veer off to the left/right. This in turn would cause the controller to correct itself, and place it into an oscillatory motion. | +| **4** | Uneven weight distribution | If your UGV is carrying more weight on one side it may bias the UGVs motion when being command straight and veer the UGV off to one side. The controller would then consistently try to correct this bias by pulling it back towards the reference path, thus causing oscillations. | + +To determine if causes 3 and 4 may apply to you, it is a good idea to run the following test: + +1. send the following command to rotate your UGV for one full rotation, +``` bash +rostopic pub /cmd_vel geometry_msgs/Twist "linear: + x: 0.0 + y: 0.0 + z: 0.0 +angular: + x: 0.0 + y: 0.0 + z: 0.3" -r 10 +``` +2. stop the rotation by stopping the command. +3. send the following command to move the UGV purely forward, +``` bash +rostopic pub /cmd_vel geometry_msgs/Twist "linear: + x: 0.5 + y: 0.0 + z: 0.0 +angular: + x: 0.0 + y: 0.0 + z: 0.0" -r 10 +``` +4. Analyse the motion and then stop the linear motion. If the UGV drifts left/right +during step 3, then your UGV is likely to suffer from the effect of uneven weight +distribution or deformable tires. (If not, there may be bigger issues). Further +investigation/discussion with Clearpath would be required. + +If the above tests demonstrate that the UGV **is oscillating** around the reference path, +then proceed to [Reduce Oscillations](#reduce_oscillations_on_straights). + +If the above tests demonstrate that the UGV **is NOT oscillating** or **within an acceptable +range of oscillation**, proceed to onto the following condition block: [Velocity Increase](#linear_velocity_condition). + + +#### Linear Velocity Condition/Test {#linear_velocity_condition} + +The "Increase Linear Velocity?" condition block asks if the user wants to increase the linear +velocity that the UGV will travel along long straight paths. This does not mean that it will +always drive at this velocity, but it is the velocity that it will accelerate to on straights, +when starting a mission and/or when coming out of a curve. + +To test this we want to create a mission that sends the UGV to a Waypoint +directly in front of the UGVs current position. This requires two Waypoints: the first one located at the robots +current position and the second Waypoint at least 20 meters away from the start position and will depend on the +linear velocity you wish to acheive. + +If during the above test, the velocity **does not** reach the desired velocity, proceed to +[Increase Linear Velocity](#increase_linear_velocity) and repeat the above test until the +desired has been achieved. + +If the above test results in the UGVs maximum velocity reaching the desired velocity, +then proceed to checking the two subconditions: [Goal Behavior](#goal_overshoot_tests) and +[Cornering Behavior](#cornering_tests). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions are +also satisfied. Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Goal State Tests {#goal_overshoot_tests} + +The "Goalpoint Overshoot?" condition block asks the user to check if, at the end of a mission, +the UGV overshoots the goalpoint. This condition should always be checked every time the +velocity is increased. A similar test can be used as in the [Velocity Increase](#linear_velocity_condition) section. + +If the test results in the UGV **overshooting the goal point**, then proceed to +[Tune Goal Behavior](#tune_goal_state). + +If the test results in a **smooth deceleration to the goal point, with the UGV completing its +mission within the required tolerance, and NO overshoot**, then proceed to re-verifying that your +changes have not caused any oscillations by returning to the [Oscillation Tests](#oscillation_tests). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions also +are also satisfied. Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Corner State Tests {#cornering_tests} + +The "Overshoot/Oscillations in Corners?" condition block asks the user to check if the UGV +overshoots the entry to corners, and/or if the UGV oscillates during the cornering. This +condition should always be checked every time the velocity is increased. + +A test should be designed so that the UGV will navigate a curve/corner. This type of mission +can be set up regardless of whether or not you have set a specified turn radius for the path planner. + +The Waypoints for the test mission should be placed such that there is sufficient change in +orientation of the reference path that the controller will switch into its CORNER state. An example mission +is provided below which demonstrates said Waypoint placement (although an extreme case with lots of Waypoints +for vehicle with a large turn radius). + +
+
+ +
Example test mission (complex) for cornering tests
+
+
+ +For the current case of differential drive UGVs who are able to turn on the spot, simpler +test missions can be used that change the heading of the UGV more than 45°, at each +Waypoint. + +If the test results in the UGV **overshooting the entrance to the corner/curve**, then proceed to +the first issue listed in [Tune Corner State](#tune_cornering_state). + +If the test results in the UGV **oscillating during the corner/curve**, then proceed to +the second issue listed in [Tune Corner State](#tune_cornering_state). + +If the test results in the UGV **navigating smoothly through all curves/corners, with no +minimal oscillations and no overshoot**, then proceed to re-verifying that your +changes have not caused any oscillations during straights ([Oscillation Tests](#oscillation_tests)). + +:::note + +Only advance to the following condition block: [Collision Avoidance](#collision_avoidance_condition) +if the UGVs maximum velocity has reached the desired velocity and all subconditions are also satisfied. +Ie. you have tuned the corner and goal behavior to within your allowable limits. + +::: + +#### Collision Avoidance Condition {#collision_avoidance_condition} + +The final condition block asks the user if collision avoidance is enabled or disabled on the +UGV. + +If collision avoidance is DISABLED, then you have completed tuning your UGV. +**Congratulations!** + +When collision avoidance is ENABLED, it is recommended to begin with a straight line test as in [Velocity Increase](#linear_velocity_condition) +but with an obstacle placed roughly in the center of the predicted path (ie. at the midpoint +between the start and goal locations). This obstacle should be at least 30 cm tall +and at least 10 cm wide. The user should be ready to emergency stop the UGV if they +notice it approaching the obstacle too fast or too closely. + +If the test results in any unexpected behaviour, such as: + +1) not stopping in front of the obstacle, + +2) not navigating after stopping in front of the obstacle, + +3) jittery motion navigating around the obstacle, + +then proceed to the respective issue listed in +[Tune Collision Avoidance Behavior](#tune_collision_avoidance). + + +## Tuning Blocks {#tuning_blocks} + +#### Initialize Parameters {#initialize_parameters} + +1. Update the footprint offsets of the UGV in the `/opt/onav//config/autonomy.env` file, where *onav_version* +is the version of OutdoorNav that you are currently running. + +:::note + +This above file path is only valid for versions after and including version 0.11.0. + +:::note + +
+
+ +
Differential Drive Tuning Flowchart
+
+
+ +| Environment Variable | Description | Sign | +|----------------------|-------------|------| +| FOOTPRINT_OFFSET_POS_X | Distance from base_link to the furthest edge of any part/sensor at the front of the UGV. | **+** | +| FOOTPRINT_OFFSET_NEG_X | Distance from base_link to the furthest edge of any part/sensor at the left of the UGV. | **-** | +| FOOTPRINT_OFFSET_POS_Y | Distance from base_link to the furthest edge of any part/sensor at the rear of the UGV. | **+** | +| FOOTPRINT_OFFSET_NEG_Y | Distance from base_link to the furthest edge of any part/sensor at the right of the UGV. | **-** | + +2. Update the [`vehicle_length`](../tuning_parameters/navigation_parameters.mdx#default_state_params) +parameter to be the longitudinal length (ie. along the x-axis) of your UGV. This is not +the sum of the above footprint x-axis magnitudes, but only the length of the UGV body. + +3. Update the following parameters with your UGV specific maximums and minimums: + + * [`max_fwd_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`min_fwd_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_rev_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_ang_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_accel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_decel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_ang_accel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + * [`max_lateral_accel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + +4. Update the [`stiction_compensator_fwd`](../tuning_parameters/navigation_parameters.mdx#default_state_params) +and [`stiction_compensator_yaw`](../tuning_parameters/navigation_parameters.mdx#default_state_params) to +be equivalent to the minimum linear and angular velocities that the UGV requires it to move +(eg. `stiction_compensator_fwd` would be equal to `min_fwd_velocity`). + + +#### Tune Velocity Deadband {#tune_deadband} + +To tune the velocity deadband, the user should at least start off by knowing the minimum +linear and angular velocities that the UGV motors can generate. + +If not already set from the [Initial Parameters](#initialize_parameters) section, you should set +the [`min_fwd_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) to the minimum +forward linear velocity that the UGV can handle. + +For each iteration of the linear deadband tuning, increment the following parameters by **0.05 m/s** +, until smooth linear motion is acheived from standstill: + +- [`min_fwd_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) +- [`stiction_compensator_fwd`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + +For each iteration of the angular deadband tuning, increment the following parameters by **0.02 rad/s** +, until smooth angular motion is acheived from standstill: + +- [`stiction_compensator_yaw`](../tuning_parameters/navigation_parameters.mdx#default_state_params) + + +#### Reducing Oscillation (Straights) {#reduce_oscillations_on_straights} + +To tune the UGV behavior on straights when dealing with the simple cause of untuned MPC +controller parameters, we list the following parameters along with likely ranges and their initial +default values. The are listed in order of which parameter will have the most effect of improving +the performance of the current tuning block. + +| Parameter | Likely Range* | Default | +|-----------|---------------|---------| +| [`yaw_weight`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 90 - 120 | 18.0 | +| [`y_weight`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 12 - 18 | 14.0 | +| [`endpoint_multiplier`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 10 - 20 | 10 | +| [`max_lookahead`](../tuning_parameters/navigation_parameters.mdx#default_state_params) |2.5 - 3.5 | 2.5 | +| [`x_weight`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 14 - 16 | 14.0 +| [`lookahead_factor`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 1.4 - 1.6 | 1.45 | +| [`mpc_opt_maxiteration`](../tuning_parameters/navigation_parameters.mdx#default_state_params)* | 10 - 15 | 13 | +| [`discretization_steps`](../tuning_parameters/navigation_parameters.mdx#default_state_params)* | 6 - 10 | 8 | + +:::note + +\* These parameters should be changed with caution. + +::: + +When you are experiencing oscillations due to cause \#2 (controller delay) try the modifying the +following parameters: + +| Parameter | Likely Range* | Default | +|-----------|---------------|---------| +| [`enable_delay_compensation`](../tuning_parameters/navigation_parameters.mdx#delay_compensation_params) | true | false | +| [`controller_delay`](../tuning_parameters/navigation_parameters.mdx#delay_compensation_params) | depends on your delay in your system. (usually between 300 - 1000 will provide changes to the performance) | NA | + + +No available solutions yet to resolve oscillations due to causes \#3 and \#4. Please contact +Clearpath customer support at to discuss any related issue. + +#### Increase Linear Velocity {#increase_linear_velocity} + +** *The following instructions are only relevant if you are planning on +increasing the velocity of the UGV above 2.0 m/s.* ** + +To increase the UGVs maximum velocity, the following parameters should be modified. + +First, the [`mpc_horizon`](../tuning_parameters/navigation_parameters.mdx#default_state_params) parameter +should be set to: 1.0 + +The following parameters should then be modified to the desired velocity ($v_{des}$). Ie. if $v_{des}=4.0$ m/s, then you should modify both parameters to be 4.0. + +| Parameter | Value | +|-----------|-------| +| [`max_fwd_velocity`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | $v_{des}$ | +| [`max_lookahead`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | $v_{des}$ | + +Finally, if you are increasing the velocity to a value greater than or equal to 4.0 m/s or if you +are seeing that the velocity is being limited even after changing the above parameters, +it is possible to try and increase the size (width and height) of the local costmap in file: +`/opt/onav//app/autonomy/params/platform/navigation/costmap_local.yaml`, +where *onav_version* is the currently running version of OutdoorNav. The limit in the velocity +is due to the fact that the lookahead distance at higher speeds ends up exceeding the size of +the local costmap. By increasing it, we allow the controller to lookahead further and allow for +that velocity increase. + +#### Tune Goal State {#tune_goal_state} + +A few different issues may have occurred that led you to tuning the goal behavior. We list a +few of them and the possible parameters that can be modified to improve the performance in and +around the goal point. + +1) Overshooting the goal point can be caused by a few factors: + +* Not decelerating fast enough or soon enough as the UGV approaches the goal. + +To tune for this issue, some parameters are listed in order in which they will have the most effect of +improving the performance of the current tuning block: + +| Parameter | Default | +|-----------|---------| +| [`goal_horizon_threshold`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 2.0 | +| [`goal_slowdown_multiplier`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 1.5 | +| [`goal_horizon_threshold`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.8 | +| [`endpoint_multiplier_goal`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 20 | +| [`x_weight_goal`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 14.0 | +| [`fwd_v_weight_goal`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.01 | +| [`fwd_a_weight_goal`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 8.0 | + + +* The autonomy core not considering the goal complete because it has too high of a velocity as it +starts entering the goal tolerance. + +To to tune for this issue, modify the following parameter: + +| Parameter | Value | Default | +|-----------|-------|---------| +| [`max_speed_at_goal`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | *depends on the deceleration of your UGV* | 0.8 | + +2) Oscillations (or jittery behavior) around the goal point are typically caused by the the +tolerance at the goal point being set too small. If they are too small and the UGV is unable +to localize itself within the required position and yaw tolerances, then it will jitter and +rotate to attempt to be a precise as you are expecting it to be. To resolve this, it is advised +to slightly increase the goal tolerance parameters: + +| Parameter | Default | +|-----------|---------| +| [`goal_tolerance_xy_rtk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.1 | +| [`goal_tolerance_yaw_rtk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.25 | +| [`goal_tolerance_xy_nortk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.3 | +| [`goal_tolerance_yaw_nortk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) | 0.5 | + +:::note + +If your UGV has RTK corrections, then it is only required to modify [`goal_tolerance_xy_rtk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) +and [`goal_tolerance_yaw_rtk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params). Otherwise, +only modify [`goal_tolerance_xy_nortk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params) +and [`goal_tolerance_yaw_nortk`](../tuning_parameters/navigation_parameters.mdx#goal_state_params). + +::: + +A complete list of parameters that relate to the GOAL state can be found +[here](../tuning_parameters/navigation_parameters.mdx#goal_state_params), however, the above set of +parameters is likely to satisfy the users requirements. + +#### Tune Cornering State {#tune_cornering_state} + +A few different issues may have occured that led you to tuning the cornering behavior. We list a +few of them and the possible parameters that can be modified to improve the performance approaching +as well as in the corner. + +1) Overshooting the corner only to enter the turn late + +This issue occurs most often, when the controller is unable to slow the UGV down early and/or +fast enough, prior to entering the corner. A reduction in velocity earlier in the approach to +the corner will improve the cornering performance. Below some parameters are listed that will +allow the user to improve the behavior entering corners: + +| Parameter | Default | +|-----------|---------| +| [`corner_segment_slowdown`](../tuning_parameters/navigation_parameters.mdx#corner_state_params) | false | +| [`corner_lookahead`](../tuning_parameters/navigation_parameters.mdx#corner_state_params) | 5.0 | +| [`corner_detection_threshold`](../tuning_parameters/navigation_parameters.mdx#corner_state_params) | 0.15 | +| [`corner_slowdown_multiplier`](../tuning_parameters/navigation_parameters.mdx#corner_state_params) | 1.5 | + +2) Oscillations during the corner + +To reduce the oscillations in the corners, some parameters are listed in order in which they will have the most effect of +improving the performance: + +| Parameter | Default | +|-----------|---------| +| [`endpoint_multiplier_corner`](../tuning_parameters/navigation_parameters.mdx#corner_state_params) | 20.0 | +| [`curvature_slowdown`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 0.15 | +| [`controller_delay`](../tuning_parameters/navigation_parameters.mdx#delay_compensation_params) | 0 | +| [`y_weight`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 14.0 | +| [`x_weight`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 14.0 | + +The complete list of parameters that relate to the CORNER state can be found +[here](../tuning_parameters/navigation_parameters.mdx#corner_state_params), however, the above set of +parameters is likely to satisfy the users requirements. + + +#### Tune Collision Avoidance {#tune_collision_avoidance} + +A few different issues may have occured that led you to tuning the collision avoidance. We list a +few of them and the possible parameters that can be modified to improve the performance approaching +as well as navigating around detected obstacles. + +1) UGV not stopping in front of the obstacle + +This issue would either occur if the collision avoidance has been disabled, or if the detection sensors +are not populating the costmap with the obstacle(s). To enable/disable collision avoidance: + +| Parameter | Default | +|-----------|---------| +| [`ENABLE_COLLISION_AVOIDANCE`](../tuning_parameters/collision_avoidance_parameters.mdx#general_collision_avoidance_params) | true | + +For the case where the obstacle that you are using is not being detected by the detection sensors, +make sure that it is neither too short nor too thin. Use RViz to check that the local costmap is being populated with +the obstacle. + +2) UGV not navigating after stopping in front of an obstacle + +This issue is either due to the robot unable to replan around the obstacle, in which case the +following parameters may help: + +| Parameter | Default | +|-----------|---------| +| [`inflation radius`](../tuning_parameters/collision_avoidance_parameters.mdx#costmap_params) | 1.0 | +| [`cost_scaling_factor`](../tuning_parameters/collision_avoidance_parameters.mdx#costmap_params) | 0.5 | +| [`max_decel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 0.5 | +| [`max_accel`](../tuning_parameters/navigation_parameters.mdx#default_state_params) | 0.5 | + +or that the obstacle has gotten inside of the safety footprints causing the navigation to place the +UGV in a collision state: + +Consult the [Footprint Tuning](footprint_tuning.mdx) instructions to increase the safety footprint sets. +The user can also try increasing the stop distance from the UGV to an obstacle as it decelerates +to a stop. + +| Parameter | Default | +|-----------|---------| +| [`enable_stop_distance radius`](../tuning_parameters/navigation_parameters.mdx#stop_distance_params) | false | +| [`obstacle_stop_distance`](../tuning_parameters/navigation_parameters.mdx#stop_distance_params) | 3.0 | + +3) UGV has jittery motion navigating around the obstacle, + +This issue is typically a problem when the safety footprints collide with the obstacle as it is +trying to navigate the replanned path around the obstacle: + +Consult the [Footprint Tuning](footprint_tuning.mdx) instructions to modify the safety footprint sets. + +The user can also try increasing the stop distance of the UGV to an obstacle. + +| Parameter | Default | +|-----------|---------| +| [`enable_stop_distance radius`](../tuning_parameters/navigation_parameters.mdx#stop_distance_params) | false | +| [`obstacle_stop_distance`](../tuning_parameters/navigation_parameters.mdx#stop_distance_params) | 3.0 | + + +4) UGV suddenly reducing its velocity as it accelerates up to maximum + +This issue is due to the safety footprints exceeding the length of the local costmap. Since the +safety footprints increase in length as the velocity increases, the user must also increase the +size of the local costmap. This allows the safety footprints to extend to their entire length +without triggering a "false" obstacle detection due to the footprint exceeding the local +costmap size. Increase the costmap using these parameters: + +| Parameter | Default | +|-----------|---------| +| [`local_costmap/width`](../tuning_parameters/collision_avoidance_parameters.mdx#costmap_params) | $2 * l_{max\_footprint} + 0.5$ | +| [`local_costmap/height`](../tuning_parameters/collision_avoidance_parameters.mdx#costmap_params) | $2 * l_{max\_footprint} + 0.5$ | + +where l_{max\_footprint} is the length of the largest safety footprint. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx new file mode 100644 index 00000000..a36d1b85 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_instructions/footprint_tuning.mdx @@ -0,0 +1,9 @@ +--- +title: "Footprint Tuning" +sidebar_label: "Footprint Tuning" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +Information incoming in release 0.9.0. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx new file mode 100644 index 00000000..851df29b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_overview.mdx @@ -0,0 +1,25 @@ +--- +title: "Tuning Overview" +sidebar_label: "Tuning Overview" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The scope of Appendix C is to provide information on how to tune the various components of +OutdoorNav. + +Instructions for tuning specific platform types can be found here: + +- [Differential Drive (Skid-Steer) Dynamics](tuning_instructions/differential_drive_dynamics.mdx) +- [Ackermann Drive Dynamics](tuning_instructions/ackermann_drive_dynamics.mdx) + + +Lists of parameters related to each component of the autonomy can be found here: + +- [Localization Parameters](tuning_parameters/localization_parameters.mdx) +- [Navigation Parameters](tuning_parameters/navigation_parameters.mdx) +- [Collision Avoidance Parameters](tuning_parameters/collision_avoidance_parameters.mdx) + +In future releases, we will describe how the user can [Customize their UI](user_interface_customization.mdx) +as well as how to [Customize which Sensors](sensor_customization.mdx) are input into OutdoorNav. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json new file mode 100644 index 00000000..fb6592a9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Tuning Parameters", + "position": 3 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx new file mode 100644 index 00000000..fa4b1ce2 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/collision_avoidance_parameters.mdx @@ -0,0 +1,37 @@ +--- +title: "Collision Avoidance Parameters" +sidebar_label: "Collision Avoidance Parameters" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +## General Environment Variables {#general_collision_avoidance_params} + +| Parameter | Description | File | Default | +|-----------|-------------|------|---------| +| `ENABLE_COLLISION_AVOIDANCE` | Flag to enable/disable collision avoidance | `/opt/onav//config/autonomy.env` | false | + + +## Costmap {#costmap_params} + +### Determine the file location of the parameter {#file_location} + +The parameters related to the costmap, can be found here: + +``` bash +/opt/onav//app/autonomy/params//navigation/costmap_.yaml +``` + +If they are not listed in the above file, it is because they are using the default values and are not being overwritten. + + +The following parameters can be used to modify the costmap, specifically when trying to tune +collision avoidance. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `width` | The width of the costmap | [/navigation/*<global/local>*_costmap](#file_location) | **m** | +| `height` | The height of the costmap | [/navigation/*<global/local>*_costmap](#file_location) | **m** | +| `inflation_radius` | The radius to which the map inflates obstacle cost values | [/navigation/*<global/local>*_costmap/inflation](#file_location) | **m** | +| `cost_scaling_factor` | A scaling factor to apply to cost values during inflation. The cost function is computed as follows for all cells in the costmap further than the inscribed radius distance and closer than the inflation radius distance away from an actual obstacle | [/navigation/*<global/local>*_costmap/inflation](#file_location) | - | diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/localization_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/localization_parameters.mdx new file mode 100644 index 00000000..b8102c74 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/localization_parameters.mdx @@ -0,0 +1,9 @@ +--- +title: "Localization Parameters" +sidebar_label: "Localization Parameters" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +Information incoming in release 0.9. Please contact Clearpath customer support at to discuss the issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx new file mode 100644 index 00000000..fa47f224 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/tuning_parameters/navigation_parameters.mdx @@ -0,0 +1,169 @@ +--- +title: "Navigation Parameters" +sidebar_label: "Navigation Parameters" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 3 +--- + +import versions from "@site/static/versions.js" + +## Controllers {#controllers} + +### Determine the file location of the parameter {#file_location} + +The parameters related to the controller, can be found here: + +``` bash +/opt/onav//app/autonomy/params//navigation/controls_general.yaml +/opt/onav//app/autonomy/params//navigation/mpc_controller.yaml +/opt/onav//app/autonomy/params//navigation/mpc_dock_controller.yaml +``` + +If they are not listed in the above file, it is because they are using the default values and are not being overwritten. + +### MPC Controller {#controller} + +#### MBF Plugins + +Currently we have implemented a Move-Base Flex controller plugin named: **OnavMbfMpcController** + +Two instances of this plugin are loaded at runtime by our navigation node (as seen in the table below). The parameters are equivalent for each instance of the plugin but the values of certain of these parameters are different. + +| Controller name | Description | +|-----------------|-------------| +| **`mpc_controller`** | The controller used during normal navigation and applies to tracking the paths generated between all the mission waypoints. | +| **`mpc_dock_controller`** | The controller used during docking and applies only to tracking the dock and undock paths. | + +#### MPC State Machine + +The MPC controller operates as a state machine that contains the following states: + +| MPC State | Description | Condition | +|-----------|-------------|-----------| +| **`DEFAULT`** | Standard tracking behavior. | Will revert to this state if none of the other state conditions are met. | +| **`GOAL`** | Tracking behavior as the UGV approaches the goal. | Will enter GOAL mode when the `goal_horizon_threshold` parameter distance to the goal has been reached.| +| **`PRECISE`** | State when more precision is required in the tracking. | At the start of the path, we begin in Precise mode to ensure that we have a good start to tracking.| +| **`RESCUE`** | State to rescue the tracker when the UGV is stuck. | Will enter RESCUE mode when UGV is appraching a condition that make it stuck.| +| **`HYSTERESIS`** | State when you the UGV requires compensation for tire flexion. | Will enter HYSTERESIS mode when the UGV detects that it will begin oscillating due to tire deformation. | +| **`CORNER`** | State when there is a curve or a corner ahead. | Will enter CORNER mode when the UGV approaches, within a `corner_lookahead` parameter distance, to a corner with at least `corner_detection_threshold` of a curvature.| + +#### Default State Parameters {#default_state_params} + +The following list defines the default parameters that the MPC controller uses. +For the most part, they apply to all states of the MPC controller. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `vehicle_length` | The length (longitudinally) of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `mpc_horizon` | The prediction horizon of the MPC. | [/navigation/*<controller>*/path_tracker](#file_location) | **s** | +| `max_lookahead` | Maximum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `min_lookahead` | Minimum distance along the path we seek to follow. Affects how far we do collision checks as well as the maximum velocity of the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `lookahead_smoother` | Factor between 0 and 1 that determines the smoothness of the change in lookahead distance: 0 means only maximum velocity is used to determine the horizon (can be jumpy but speeds up the UGV faster); 1 means only averaged planned velocity is used to determine the horizon (smoother but speeds up the UGV slowly). | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `lookahead_factor` | How aggressively do we want to increase the lookahead from min_lookahead to max_lookahead | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `mpc_opt_maxiteration` | The maximum number of iterations that the solver will run. Increase this value for better performance, decrease for shorter computation time. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `discretization_steps` | Number of grid points along the MPC prediction; Lower: less accuracy, but faster | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `max_fwd_velocity` | The maximum allowable linear velocity that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `min_fwd_velocity` | The minimum allowable linear velocity, in any mode, that the MPC controller can compute. This can be used to overcome the different deadbands that different UGVs may have. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `max_rev_velocity` | The maximum allowable reverse linear velocity (ie. positive value), in any mode, that the MPC controller can compute. By default this is set to the `max_fwd_velocity`, so only needed if your maximum linear reverse velocity is different than the forward linear velocity.| [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `max_ang_velocity` | The maximum allowable angular velocity, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular velocities. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad/s** | +| `max_accel` | The maximum allowable linear acceleration, in normal navigation mode, that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `max_decel` | The maximum allowable linear deceleration (ie. negative value), in any mode, that the MPC controller can compute. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `max_ang_accel` | The maximum allowable angular acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative angular accelerations. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad/s/s** | +| `max_lateral_accel` | The maximum allowable lateral acceleration, in any mode, that the MPC controller can compute. This parameter bounds both positive and negative lateral accelerations. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s/s** | +| `stiction_compensator_fwd` | The minimum linear velocity for movement of the UGV. This should typically be the minimum linear velocity that the UGV requires for it to move. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `stiction_compensator_yaw` | The minimum angular velocity for movement of the UGV. This should typically be the minimum angular velocity that the UGV requires for it to move. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `x_weight` | Weight for state x in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `y_weight` | Weight for state y in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_weight` | Weight for state yaw in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `fwd_v_weight` | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_d_weight` | Weight for state (yaw velocity) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `fwd_a_weight` | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `yaw_a_weight` | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: DEFAULT. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `horizon_percent_change` | The percentage factor used when shortening the MPC horizon. This will affect how quickly we want to speed up after a curvature slowdown. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `error_slowdown_multiplier` | The amount by which to increase the MPC horizon based on the crosstrack and/or heading error. This should be greater than 1.0 since increasing the MPC horizon will decrease the maximum MPC velocity. ** Less than 1.0 will result in the opposite behaviour which is not the expected behaviour for this parameter. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `crosstrackerror_slowdown` | Threshold on the amount of crosstrack error, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `headingerror_slowdown` | Threshold on the amount of heading error, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `curvature_slowdown` | Threshold on the path curvature, above which to a slowdown the UGV. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `endpoint_multiplier` | Weight multiplier of the very last point along the local plan segment in MPC state: DEFAULT. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `shrinking_horizon_min` | The minimum horizon that will be used in the computation. This value will prevent the horizon from dropping below this value during all the horizon adjustments. | [/navigation/*<controller>*/path_tracker](#file_location) | **s** | +| `crosstrack_tolerance` | The amount of lateral error that the controller will handle before stopping the UGV and replanning a new path. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `reference_trajectory_factor` | A factor that will skew the path parameter. This value should be between 0 and 1. Values closer to 0.0 will skew the path param closer to the UGV, decreasing speed but increasing the accuracy of the path tracking, and vice versa as you approach 1.0. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | + +#### Goal State Parameters {#goal_state_params} + +The following parameters can be modified to tune the controller as it approaches +the goal point as well as its behavior around the goal point. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `goal_horizon_threshold` | The distance from the goal point which the MPC state will switch into state: GOAL , and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_slowdown_multiplier` | The multiplier by which to increase the MPC horizon during the MPCs GOAL state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `max_speed_at_goal` | The maximum allowable speed at the goal point for the controller to stop and consider the goal complete. On OEM UGVs, this value should be increased. | [/navigation/*<controller>*/path_tracker](#file_location) | **m/s** | +| `x_weight_goal` | Weight for state x in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `y_weight_goal` | Weight for state y in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_weight_goal` | Weight for state yaw in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `fwd_v_weight_goal` | Weight for state ẋ (forward velocity) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_d_weight_goal` | Weight for state (yaw velocity) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `fwd_a_weight_goal` | Weight for state ẍ (forward acceleration) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `yaw_a_weight_goal` | Weight for state (yaw acceleration) in MPC cost function, in the MPC state: GOAL. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `endpoint_multiplier_goal` | Weight multiplier of the very last point along the local plan segment in MPC state: GOAL. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location) | | +| `goal_tolerance_xy_rtk` | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_tolerance_yaw_rtk` | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is enabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad** | +| `goal_tolerance_xy_nortk` | The (x, y) tolerance value (ie. radius) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | +| `goal_tolerance_yaw_nortk` | The yaw tolerance value (ie. heading) assigned to a goal, when RTK is disabled, in order to determine whether or not to consider the goal complete. | [/navigation/*<controller>*/path_tracker](#file_location) | **rad** | + +#### Corner State Parameters {#corner_state_params} + +The following parameters can be modified to tune the behavior of the controller during and as it +as it approaches corners. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `corner_segment_slowdown` | Flag to enable/disable the slowdown behaviour in MPC state: CORNER | [/navigation/*<controller>*/path_tracker](#file_location)| **bool** | +| `corner_lookahead` | The distance on the reference path from the UGVs current location, along which to determine if a corner is present. If a corner is present the MPC state will switch to CORNER state and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location)| **m** | +| `corner_detection_threshold` | Threshold on the path curvature, between the UGVs current location and the end of the corner_lookahead distance, above which to switch the MPC in state: CORNER, and begin reducing the horizon accordingly. | [/navigation/*<controller>*/path_tracker](#file_location)| **rad** | +| `corner_slowdown_multiplier` | The multiplier by which to increase the MPC horizon during the MPCs CORNER state in order to slow the UGV down from its top speed. This value should be greater than 1.0. | [/navigation/*<controller>*/path_tracker](#file_location)| **--** | +| `endpoint_multiplier_corner` | Weight multiplier of the very last point along the local plan segment in MPC state: CORNER. This value ensures convergence/stability of the optimizer by mimicking the MPCs infinite horizon by applying a terminal cost. | [/navigation/*<controller>*/path_tracker](#file_location)| **--** | + +#### OEM Specific Parameters {#oem_tuning_params} + +When tuning the controller on a third-party OEM UGV, there are several other considerations +that we will not have taken into account during the tuning of our UGVs. Below, we define +parameters that may be modified to tune the controller for your third-party OEM UGV. + +##### UGV Dynamics {#platform_dynamics_params} + +The following parameters can be used to modify the dynamics model that the contrller uses to +compute command velocities. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `no_turn_on_spot_motion` | Flag to enable/disable turn on spot motion. By default, the MPC motion model is represented by a differential drive kinematics. This parameter will modify the MPC motion model to remove turn in place motions and bias the motion in the forward direction. | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `min_fwd_turn` | | [/navigation/*<controller>*/path_tracker](#file_location) | **--** | +| `pivot_point_offset_x` | The longitudinal offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `pivot_point_offset_y` | The lateral offset that can be applied to the MPC model in order to account for a particular UGVs center of rotation | [/navigation/*<controller>*/path_tracker](#file_location) | - | +| `min_fwd_turn` | | [/navigation/*<controller>*/path_tracker](#file_location) | **--**| + +##### Delay Compensation {#delay_compensation_params} + +The following parameters can be used to compensate for any delays that are present in the system. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `enable_delay_compensation` | A boolean flag to enable/disable the delay compensation feature. The delay compensation feature is used to compensate for low-level dynamics delays that may be present in the UGV to be controlled. The user can apply an input controller delay and the feature will compute command velocities that compensate for such a delay. | [/navigation/*<controller>*/path_tracker](#file_location) | **bool** | +| `controller_delay` | The amount of controller delay that the delay compensation feature will attempt to compensate for, in ms. | [/navigation/*<controller>*/path_tracker](#file_location) | **ms** | + +##### Stop Distance {#stop_distance_params} + +The following parameters can be used to set a specific stop distance away from obstacles. + +| Parameter | Description | Namespace | SI Units | +|-----------|-------------|-----------|:--------:| +| `enable_stop_distance` | A flag to use enable/disable the stop distance feature. The stop distance feature forces the UGV to stop a specified distance in front of obstacles. | [/navigation/*<controller>*/path_tracker](#file_location) | **bool** | +| `obstacle_stop_distance` | The distance at which the UGV will stop in front of a detected obstacle. | [/navigation/*<controller>*/path_tracker](#file_location) | **m** | + + +## Path Planners {#path_planners} + +Information incoming in release 0.9. Please contact Clearpath customer support at to discuss the issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx new file mode 100644 index 00000000..17c27a3f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/customized_tuning/user_interface_customization.mdx @@ -0,0 +1,9 @@ +--- +title: "UI Customization" +sidebar_label: "UI Customization" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Information incoming in a future release. Please contact Clearpath customer support at to discuss any related issue. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx new file mode 100644 index 00000000..374e05b3 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/faq.mdx @@ -0,0 +1,194 @@ +--- +title: Frequently Asked Questions +sidebar_label: Frequently Asked Questions +sidebar_position: 10 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## General + +1. **How do I start, pause or stop a mission?** + + A mission can be started in a few different ways, i) through the web user interface (See [Mission Execution](./web_user_interface/ui_waypoint_mode.mdx#mission-execution)) or, + ii) through the ROS API (See [API Examples](./api/api_examples/api_examples.mdx)). + +2. **When I start a mission the UGV does not move. What could be the + problem?** + + There could be one of several reasons for why this is happening: + + 1. Check that none of the onboard Motion-Stop actuators are + activated. + 2. Check that none of the wireless Motion-Stops are engaged. This + can be checked via the UI (a red Status Indicator means + Motion-Stop is engaged) or the onboard UGV lights (will flash + when Motion-Stop is engaged). + 3. If OutdoorNav is running on a Clearpath Robotics Warthog UGV + that is programmed with a Futaba controller, then ensure that + the controller is turned off. If it is on then it will be + sending "no motion" commands that will be overriding the + autonomy commands. + 4. Check the task settings for each Waypoint in the Mission. + A missing task setting for a Move PTZ task will block the + execution of the Mission it is in. + +3. **What version of ROS is compatible with OutdoorNav?** + + Currently OutdoorNav is developed in ROS 1 (and is built in Docker containers on top of ROS 1 Noetic). + So, the recommended ROS version is ROS 1 Noetic. However, although not recommended, it is still + possible to use ROS 1 Melodic. Some issues may arise related to the mismatched message types. + Also, if trying to run any python scripts as Melodic targets Python2, whereas Noetic targets Python3. + + Finally, official ROS 2 compatibility is currently unsupported. In theory, if you only have ROS 2 installed + on your system, you can try to install ROS 1 Noetic as well and set up a ros1_to_ros2 bridge. Since the + OutdoorNav software is packaged in Dockers, it will communicate directly ROS 1 and then the data can be + redirected by the ros1_to_ros2 bridge to ROS 2. + +4. **How can I record ROS data?** + + There are two ways to record ROS data. The first is [through the UI](./features/rosbag_recorder.mdx) and the + second is the more traditional method of accessing the command line of the UGV's computer and running + [rosbag record commands](http://wiki.ros.org/rosbag/Commandline). + +5. **Where do all the video/audio/images get saved from the mission tasks?** + + All of the data that gets saved (ROSbags, video recordings, audio recordings, and saved images) gets stored on + UGV's computer at the following location: `/opt/onav/saved_files/...` + +## Autonomy + +1. **Am I able to send the UGV on a repeated loop?** + + When generating a single mission on the UI or through the API, it is not possible for the + mission to start at the location of the robot and end at the location of the robot. This has to do with + the navigation thinking that the UGV has already arrived at its goal and will not generate a path through + the Waypoints. However, it is possible to split the mission into two missions (ie. one to go to a + location and the second to return to the starting point). With these two missions you will then either be + able to send each mission one after the other or you can use the [Mission Scheduler](./features/mission_scheduler.mdx). + Add the two missions to the schedule and you will have the ability to also repeat this loop as many times as needed. + +2. **Why is surveying failing?** + + There are several checks that should be done: + + - Check that the base station is powered on, and that all the devices inside are powered on. + - From the UGV's computer, check that you can ping the base station. + +``` bash +ping 192.168.131.30 +``` + +  If all of these tests PASS, contact [Support](./support.mdx). + +3. **Is it possible to increase the maximum velocity of the UGV?** + + The OutdoorNav software has been tune for specific maximum velocities depending on the platform, + 1.2 m/s, 1.0 m/s and 2.0 m/s for Jackal, Husky and Warthog UGVs, respectively. The Husky maximum velocity + is 1.0 m/s so increasing above this is not possible however if you would like to increase the maximum + velocity for either the Jackal or the Warthog, further tuning may be required. Consult the + [tuning guide](./customized_tuning/tuning_instructions/differential_drive_dynamics.mdx) and contact + [Support](./support.mdx) if required. + +4. **My robot it detecting too many obstacles and replanning too frequently. How can I resolve this?** + + Please consult the [Limitations](./features/collision_avoidance.mdx#limitations) section of the collisison + avoidance feature. It will describe some limits to the obstaacle detection and can help you improve the + smoothness of the navigation. + +5. **I am getting a 'Robot too far off path warning'. What should I do?** + + These types of warnings appear on the UI under two conditions: + i) If the robot indicator (blue arrow on the UI) is not within 3.0 meters of the first Waypoint (the Green one on the UI). + ii) If the robot is outside of the allowable navigable space (defined by the path contraint, default: 3.0 meters around the reference path). + Enable the visualization of the [path contraint](./web_user_interface/ui_waypoint_mode.mdx#constrained_path) and Teleop the robot back into the + navigable space. + +6. **How can I remove certain sensors from the collision avoidance pipeline?** + + If your robot is equipped with collision avoidance sensors (eg. Velodyne, Hokuyo, Sick LMS), it is + possible to enable/disable the throughput of each sensor data into the collision avoidance pipeline. + Consult the [Collision Avoidance](./features/collision_avoidance.mdx) section for these instructions. + +7. **Can I use OutdoorNav without using the UI?** + + We empower customers to send mission via either the UI or our [ROS 1 API](./api/api_overview.mdx). Through this + API, you are enabled to write either CPP code or Python scripts where you would generate your mission, survey the base station, + set the datum, assign [custom tasks](./features/custom_tasks.mdx) to your mission. If using Python, we provide a set of libraries that + speed up the develpment process. See some of the [example codes](./api/api_examples/api_examples.mdx) for an idea of how to generate these scripts. + +## Web User Interface + +1. **How do I delete a waypoint on the UI?** + + Make sure the **Edit Missions** toggle is enabled, then click the + **Waypoint Mode** button. Now you can click the Waypoint you wish to + delete. A drop down list will appear. Select **Delete**. + +2. **How do I add a Task to a Waypoint on the UI?** + + See [Add Task to Waypoint](./web_user_interface/ui_waypoint_mode.mdx#add-task) for information on how + to add a Task to a Waypoint. + +3. **Why is the "Save Image" Task failing?** + + Check the Waypoints that have a **Save Image** task in the Waypoint panel. + If you see a red warning triangle beside the **Save Image** task it means + that the settings for this task were not properly set. Set them and rerun + the mission. + +4. **Are we able to make any changes to the UI?** + + Unfortunately, users are not currently enabled to make modifications to the user interface. + This feature will be available in a future release. Please direct any feature requests to [Support](./support.mdx). + +5. **What to do if my custom task is not working?** + + Ensure that you have followed the [Custom Tasks](./features/custom_tasks.mdx) instructions. When adding the + custom task to a Waypoint, it is important to double check that all the [fields](./web_user_interface/ui_waypoint_mode.mdx#add-task) + for your custom task are correct. + +6. **Why are either of the GNSS Status indicator (POS and/or DIR) on the UI not Green?** + + i) If the **POS** indicator is YELLOW, and you are using an RTK base station: + - Check communication between the robot and the base station by pinging 192.168.131.30 (from the UGV's computer) + - Re-survey the base station + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the both the base station IP (192.168.131.30) and the position unit IP (192.168.131.31) and ensure that certain + settings are set correctly: + On the base station unit: + 1) surveyed_position/broadcast = True + tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 72,74,117,65535,114 + tcp_server1/address = 55556 + On the position unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.30:55556 + ii) If the **POS** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and ensure that the unit is working by checking that satellites are being + tracked in the "Tracking" tab. + + iii) If the **DIR** indicator is YELLOW, + - Access the [Swift Console](https://support.swiftnav.com/support/solutions/articles/44001391679-swift-console) using + the position unit IP (192.168.131.31) and the heading unit IP (192.168.131.32), and ensure that certain + settings are set correctly: + On the position unit: + 1) tcp_server1/mode = SBP + tcp_server1/enabled sbp messages = 74,117 + tcp_server1/address = 55556 + On the heading unit: + 2) tcp_client0/mode = SBP + tcp_client0/enabled sbp messages = 0 + tcp_client0/address = 192.168.131.31:55556 + solution/dgnss_solution_mode = Time Matched + solution/heading offset = 0 + solution/send heading = True + solution/soln freq = 5 + solution/output ever n obs = 1 + + iv) If the **DIR** indicator is RED: + - Check communication between the robot and the position GNSS unit by pinging 192.168.131.31 (from the UGV's computer) + diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json new file mode 100644 index 00000000..732c6cb7 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "OutdoorNav Features", + "position": 8 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx new file mode 100644 index 00000000..74f5e010 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/assisted_teleoperation.mdx @@ -0,0 +1,105 @@ +--- +title: Assisted Teleoperation +sidebar_label: Assisted Teleoperation +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::danger SAFETY WARNING + +Making changes to any of the following variables will decrease system safety. It is recommended that users +only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + + +As of version 0.12.0, the OutdoorNav software contains an assisted teleoperation feature that will help users +teleoperate their UGV safely, without worry of colliding into obstacles. + +
+
+ +
Block Diagram of Assisted Teleoperation Twist Mux
+
+
+ + +The assisted teleoperation feature is intended to work with the following sources of velocity input: + +| Input source | Topic | +|--------------|--------| +| UI Joystick | `/ui_teleop/cmd_vel` | +| PS4 Controlller | `/bluetooth_teleop/cmd_vel` or `/joy_teleop/cmd_vel`| +| Logitech Controller | `/joy_teleop/cmd_vel` | + + +The Assisted teleop feature will **NOT** work on the following sources of velocity input: + +| Input source | Topic | +|--------------|-------| +| External Command | `/cmd_vel` | +| Keyboard Command | `/kb_teleop/cmd_vel` | +| Interactive Marker | `/twist_marker_server/cmd_vel` | + +The Assisted Teleoperation feature can be activated/deactivated according to your required application requirements. +This can be done by setting the **ENABLE_ASSISTED_TELEOP** environment variable in the +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. + +## Functionality + +The intended purpose for the assisted teleoperation feature is to provide some software level safety for users while they are teleoperating the UGV. +This feature is intended to solely provide software level safety and does not use any hardware level PLCs to trigger a motor disconnect. It is to be +treated as a tool that provides a sense of security to the user, such that they will not accidentally crash the UGV any obstacles. The feature +constantly monitors the 2D/3D LiDAR sensor data that it is provided and uses this information to control the velocity of the UGV. As the UGV +approaches obstacles, it will decrease the velocity of the UGV and will bring the UGV to a complete stop if the user continues to drive +towards the oncoming obstacle. + +For visualization details of the assisted teleoperation feature, please consult the [UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) page. + +### Enable/Disable from the UI + +From the OutdoorNav UI you are able to enable/disable the "Teleop Assist" by using the toggle that is located by the UI joystick. + +### Enable/Disable using Joystick + +To disable the "Teleop Assist" when driving the UGV with the PS4 or Logitech controllers, you will need to press and hold the following button: + +| Controller Type | Button | +|--------------|-------| +| PS4 controller | **O** | +| Logitech controller | **B** | + +### Error/Warnings + +OutdoorNav will throw warnings and display them on the UI related to the status of the assisted teleoperation feature. +Below are the errors/warnings you may see: + +| Error/Warning | Reason | +|---------------|--------| +| **"Error: Failed to communicate with the Assisted Teleop node"** | The assisted teleoperation node is not running or has crashed | +| **"Error: No sensors configured"** | The assisted teleoperation node is running but no sensors have been configured to be used as obstacle detection sources | +| **"Error: Invalid twist_mux configuration"** | The twists mux configuration has been modified and does not satisfy the requirements for safe operation under the requirements of assisted teleoperation | +| **"Error: Unknown platform type"** | The assisted teleoperation node cannot determine the type of platform you are on | +| **"WARNING: Assisted teleoperation OFF due to service"** | The UI toggle switch or the `/assisted_teleop/enable` service has disabled assisted teloperation | +| **"WARNING: Assisted teleoperation OFF due to joystick override"** | The enable/disable button on the UGV remote joystick has been pressed | +| **"WARNING: Assisted teleoperation OFF due to sensor timeout"** | Communication has been lost between the assisted teloperation node and one of the configured 2D/3D detection sensors. | +| **"Warning: Robot is in a collision state and cannot be driven while assisted teleop is enabled. Please disable assisted teleop to recover."** | The robot is is a state where is is too close to an obstacle. This will mostly occur when you are at a charge dock but may also occur if you are driving/rotating in a tight space. You may need to disable the Teleop Assist to continue remote operation | + + +## Limitations + +The assisted teleoperation features has similar limitations to those of our collision avoidance features. +Performance degradation will be experiences in rain and/or snow conditions, as well as in tall grass environments. +The assisted teleoperation feature also only work if obstacles are detected by the 3D sensors. If obstacles appear +in any of the UGVs blind spots, the assisted teleoperation feature will not prevent collision with these obstacles. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/collision_avoidance.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/collision_avoidance.mdx new file mode 100644 index 00000000..bec48f5f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/collision_avoidance.mdx @@ -0,0 +1,336 @@ +--- +title: Collision Avoidance +sidebar_label: Collision Avoidance +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::danger SAFETY WARNING + +Making changes to any of the following variables may decrease system safety. It is recommended that users +only modify these parameters in consultation with [Clearpath Robotics Support](../support.mdx). + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The collision avoidance feature of OutdoorNav allows our platforms to detect, +replan and then navigate around any obstacles that may be present in the UGV's +path. The workflow of this feature can be seen in the figure below. + + +
+
+ +
Collision avoidance workflow
+
+
+ +The detection sensors available on the UGV will have their data filtered, if necessary into data +that can be fed into the costmap(s). The costmap will then use this filtered data +to generate two costmaps (local and global). + +- **global costmap**: A large costmap (whose size gets set relative to the +Waypoints of the desired mission) the replanned paths around detected obstacles. +- **local costmap**: A smaller costmap that is used solely for detecting potential +collisions and triggering the path replanner. + +Therefore, there are two components in which we can tune the behaviour of the collision +avoidance feature: the sensor filters or the costmap generation. We will expand on these below. + +## Sensor Tuning + +The following table lists the sensors that are useable with the +OutdoorNav software. The sensor drivers can be turned on/off using +these environment variables, however, the sensor will always remain +powered on. The environment variables, should be added to the +`/opt/onav//config/sensors.env` file, where *onav_version* +is the currently running version of OutdoorNav. + +| Environment Variable | Description | Data Type +|--------------------------------|-------------------------------------------|-------------- +| **SWIFTNAV_ENABLE_DRIVER** | Enable/disable the Swiftnav Piksi/Duro ROS driver, if integrated. | bool | +| **UBLOX_ENABLE_DRIVER** | Enable/disable the UBlox ROS driver, if integrated. | bool | +| **MICROSTRAIN_ENABLE_DRIVER** | Enable/disable the Microstrain GX5/CV5 ROS driver, if integrated. | bool | +| **XSENS_ENABLE_DRIVER** | Enable/disable the XSens MTI ROS driver, if integrated. | bool | +| **VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_DRIVER** | Enable/disable the Velodyne ROS driver, if integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_DRIVER** | Enable/disbale the Sick LMS1XX ROS driver, if integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_DRIVER** | Enable/disbale the Hokuyo ROS driver, if integrated (rear unit if more than one). | bool | +| **D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_DRIVER** | Enable/disable the Realsense ROS driver, if integrated (rear unit if more than one). | bool | + + +### Sensor Filters + +:::info + +It is currently only possible to use one filter of the 3D LiDAR filters (voxel, cropbox, radius, or statistical outlier) at a +time on any source of data. In future releases we plan on expanding this to work as a filter chain. + +::: + +The following list of environment variables can be used to filter the +sensor data in order to modify/improve the sensory input to the +OutdoorNav autonomy. It is recommended that you first consult the +following links before attempting to modify these parameters. + +- [PCL Filters](http://wiki.ros.org/pcl_ros/Tutorials/filters) +- [PointCloud to LaserScan Filter](http://wiki.ros.org/pointcloud_to_laserscan) +- [DepthImage to LaserScan Filter](http://wiki.ros.org/depthimage_to_laserscan) + +#### Voxel Grid Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_VOXEL** | Enable/disable the PCL voxel filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FIL_FILTER_VOXEL_LEAF_SIZE** | The size of a leaf (on x,y,z), in meters, used for downsampling. Range: 0.0 to 1.0. | double (0.01) | + +#### Cropbox Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_CROPBOX** | Enable/disable the PCL cropbox filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_CROPBOX_MIN_X** | The lower bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(0.01) | +| **PCL_FILTER_CROPBOX_MAX_X** | The upper bound, in meters, on the x-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(2.0) | +| **PCL_FILTER_CROPBOX_MIN_Y** | The lower bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-10.0) | +| **PCL_FILTER_CROPBOX_MAX_Y** | The upper bound, in meters, on the y-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | +| **PCL_FILTER_CROPBOX_MIN_Z** | The lower bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(-0.5) | +| **PCL_FILTER_CROPBOX_MAX_Z** | The upper bound, in meters, on the z-axis within which to reject points from the pointcloud. Range: -1000.0 to 1000.0. | double
(10.0) | + +#### Radius Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_RADIUS_OUTLIER** | Enable/disable the PCL radius outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_ROR_RADIUS_SEARCH** | The number of points within this distance, in meters, from the query point will need to be equal or greater than PCL_FILTER_ROR_MIN_NEIGHBORS in order to be classified as an inlier point (i.e. will not be filtered). | double
(0.05) | +| **PCL_FILTER_ROR_MIN_NEIGHBORS** | The number of points within PCL_FILTER_ROR_RADIUS_SEARCH from the query point will need to be equal or greater than this number in order to be classified as an inlier point (i.e. will not be filtered). | int
(10) | + +#### Statistical Outlier Filter + +Applicable for 3D LiDAR data published on the `../pointcloud` topic. + +Eg. Velodyne, Ouster or Realsense +[`PointCloud2`](http://docs.ros.org/en/melodic/api/sensor_msgs/html/msg/PointCloud2.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_FILTER_STATISTICAL_OUTLIER** | Enable/disable the PCL statistical outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_FILTER_SOR_MEAN_K** | The number of points (k) to use for mean distance estimation Range: 2 to 100. | double
(5.0) | +| **PCL_FILTER_SOR_STD_DEV** | The standard deviation multiplier threshold. All points outside the mean +- sigma * std_mul will be considered outliers. Range: 0.0 to 5.0. | double
(0.3) | + +#### PointCloud to LaserScan Filter + +The following filter is enabled by default and is applied after any 3D LiDAR filtering has occured. It projects the final pointcloud topic onto the 2D plane that is then used to generate the costmap. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_POINTCLOUD_TO_LASERSCAN** | Enable/disable the pointcloud to laserscan outlier filter for the sensor of type .

type = {VLP, D435, REAR_VLP, REAR_D435} | bool
(false) | +| **PCL_TO_SCAN_MIN_HEIGHT** | The minimum height to sample in the point cloud, in meters. | double
(0.2) | +| **PCL_TO_SCAN_MAX_HEIGHT** | The maximum height to sample in the point cloud, in meters. | double
(1.2) | +| **PCL_TO_SCAN_MIN_ANGLE** | The minimum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_MAX_ANGLE** | The maximum scan angle, in radians. | double
(3.14) | +| **PCL_TO_SCAN_ANGLE_INCREMENT** | Resolution of laser scan, in radians, per ray. | double
(0.00218) | +| **PCL_TO_SCAN_TIME** | The scan rate in seconds. | double
(0.3333) | +| **PCL_TO_SCAN_MIN_RANGE** | The minimum ranges to return, in meters. | double
(0.3) | +| **PCL_TO_SCAN_MAX_RANGE** | The maximum ranges to return, in meters. | double
(100.0) | + + +#### DepthImage to LaserScan Filter + +Applicable for depth image data published on the `../depth/image_rect_raw` topic. + +Eg. Realsense [`DepthImage`](http://docs.ros.org/en/noetic/api/sensor_msgs/html/msg/Image.html) data. + +| Environment Variable | Description | Data Type (Default) | +|----------------------|------------------------------------------|---------------------| +| **_ENABLE_DEPTH_TO_LASERSCAN** | Enable/disable the depth image to laserscan outlier filter for the sensor of type .

type = {D435, REAR_D435} | bool
(false) | +| **DEPTH_TO_SCAN_HEIGHT** | The number of pixel rows to use to generate the laserscan. For each column, the scan will return the minimum value for those pixels centered vertically in the image. | int | +| **DEPTH_TO_SCAN_TIME** | Time between scans (seconds). Typically, 1.0/frame_rate. This value is not easily calculated from consecutive messages, and is thus left to the user to set correctly. | double | +| **DEPTH_TO_SCAN_MIN_RANGE** | The minimum ranges to return in meters. Ranges less than this will be output as -Inf. | double | +| **DEPTH_TO_SCAN_MAX_RANGE** | The maximum ranges to return in meters. Ranges greater than this will be output as +Inf. | double | + + +## Costmap Tuning + +The following section provides a list of environment variables that can +be modified in order to tune OutdoorNav. All of the environment variables listed below +can be modified in the `/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. + +### Costmap Inputs + +The following table lists the environment variables that can be used to +enable/disable which sensor is used as part of the collision avoidance +feature of OutdoorNav. + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_VLP_ENABLE_COSTMAP** | Enable/disable the Velodyne from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_LMS1XX_ENABLE_COSTMAP** | Enable/disable the Sick LMS1XX from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_HOKUYO_ENABLE_COSTMAP** | Enable/disable the Hokuyo from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | +| **D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (front unit if more than one). | bool | +| **REAR_D435_ENABLE_COSTMAP** | Enable/disable the Realsense from populating the costmap and being used for collision avoidance. This variable should only be used if the sensor is integrated (rear unit if more than one). | bool | + +### Costmap Generation + +The following list of environment variables can be used to modify some +of the navigation inputs of to the OutdoorNav autonomy. It is +recommended that you first consult the following link(s) before +attempting to modify these parameters. + +- [Costmap2D/ObstacleLayer](http://wiki.ros.org/costmap_2d/hydro/obstacles) + +| Environment Variable | Description | Data Type | +|----------------------|------------------------------------------|-----------| +| **COSTMAP\_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_OBSTACLE_RANGE** | The maximum range in meters at which to insert obstacles into the costmap using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (rear unit if more than one). | double | +| **COSTMAP\_REAR_LIDAR\_<2D/3D\>_RAYTRACE_RANGE** | The maximum range in meters at which to raytrace out obstacles from the map using sensor data. This can apply for either 2D or 3D variables, associated with 2D and 3D lidars, respectively (front unit if more than one). | double | + + +## Limitations + +The collision avoidance feature as it currently stands, does come with some limitations. These are listed listed below: + +#### Detection range limits + +The maximum collision avoidance range for the OutdoorNav Software is +UGV-dependent and is related to the maximum speed of the UGV. These +ranges for Clearpath Robotics UGVs are: + +- Jackal UGV: 4.5 meters +- Husky UGV: 4.5 meters +- Warthog UGV: 15.0 meters + +While the sensors are able to detect objects at further distances, the +OutdoorNav Software only considers obstacles detected within these +distances for collision avoidance. That is, the UGV will only begin to +decelerate as it detects obstacles within this range. + +The detection itself is also related to the horizontal size +(width/diameter) of the obstacle. The limitations in detecting objects +with small horizontal size are described in the table below. + +_Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size_ + +| Object Size (Horizontal) | Starter Sensor Kit | Standard/(CUstom w/ VLP) Sensor Kit | +|--------------------------|----------------------------------------------------------------|----------------------------------------------------------------| +| Less than 0.6 cm | No reliable detection | No reliable detection | +| 0.6 to 1.0 cm | 0.8 m | No reliable detection | +| 1.0 to 3.0 cm | 2.0 m | 1.75 m | +| Greater than 3.0 cm | Maximum collision avoidance distance (UGV-specific; see above) | Maximum collision avoidance distance (UGV-specific; see above) | + +Finally, the OutdoorNav Software bounds the obstacle detection to +prevent ground hits and to remove detections above the UGV body. The +following bounds are relative to the ground, assuming a flat surface. +Obstacles that are entirely below the lower bound or entirely above the +upper bound are not considered obstacles and will not be avoided. + +_Obstacle Detection Vertical Bounds_ + +| Vertical Bound | Jackal UGV | Husky UGV | Warthog UGV | +|-----------------------|------------|-----------|-------------| +| Lower Detection Bound | 0.3 m | 0.3 m | 0.3 m | +| Upper Detection Bound | 0.8 m | 1.3 m | 1.8 m | + +:::note + +The vertical detection bounds above are for the Standard Sensor Kit or a +custom sensor configuration that includes a Velodyne. The vertical +detection bounds for the Starter Sensor Kit have yet to be determined. + +::: + +#### Tall grass + +**Description**: Grass that is taller than 15cm may occasionally be detected as the robot is driving. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: There are a couple of ways to reduce the amount of detections of long blades of grass. + +1) Apply either a radial filter or a statistical outlier filter on the pointcloud data to filter out the stray detections. + +- File: `/opt/onav//config/sensors.env` +- Environment variable(s): `_ENABLE_FILTER_RADIUS_OUTLIER`, `_ENABLE_FILTER_STATISTICAL_OUTLIER` + +2) Increase the pointcloud to laserscan conversion filter minimum height parameter. The environment variable + +- File: `/opt/onav//config/sensors.env` +- Environment variable(s): `PCL_TO_SCAN_MIN_HEIGHT` + +#### Pitch changes + +**Description**: Pitch changes along the UGVs planned path may cause the ground to be detected and +unwanted replanning may occur. This occurs because since we do not track change in pitch of the robot, +and since we filter the sensor data such that essentially chop off the lower portion of the data. +With the change in pitch this lower plane will then cause ground detections. + +**Workaround Available?**: Yes (Mitigation) + +**Mitigating Solution**: Limit the range from the `base_link` that the costmap generates lethal +obstacles, for a specific sensor. Eg. If your UGV has both a 3D and a 2D LiDAR. We want to limit +the range at which the 2D LiDAR will generate obstacles since the 3D LiDAR will cover a majority +of the detections. You would be able to reduce the range that the 2D LiDAR generates obstacles, +so that it does not overlap with the detection field of the 3D LiDAR. + +- File: `/opt/onav//config/autonomy.env` +- Environment variable(s): `COSTMAP_LIDAR_2D_OBSTACLE_RANGE` and/or `COSTMAP_REAR_LIDAR_2D_OBSTACLE_RANGE` + +#### Branches across narrow path + +**Description**: If there are overhanging branches across a path (ie. not coming from the ground), +the navigation may not be able to maneuver through them. + +**Workaround Available?**: Limited to None + +**Mitigating Solution**: Reduction of the global costmap `inflation_radius` and/or `costmap_scaling_factor` +parameters may provide sufficient space for the navigation to replan though the branches. + +- File: `/opt/onav//app/autonomy/params//navigation/costmap_global.yaml` +- Environment variable(s): `/navigation/global_costmap/inflation/inflation_radius` and/or `/navigation/global_costmap/inflation/cost_scaling_factor` + +:::info + +See the bottom of [this](http://wiki.ros.org/costmap_2d/hydro/inflation) page for information on how the +costmap inflation layer costs are computed based on the above two parameters. + +::: + +#### Reflective surfaces + +**Description**: Reflective surfaces on or around the robot can cause false positive obstacle placement +at incorrect locations on the costmap. + +**Workaround Available?**: No software workaround available. + +**Mitigating Solution**: Remove/cover/re-position all reflective surfaces on the robot. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx new file mode 100644 index 00000000..5ecbb813 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/custom_tasks.mdx @@ -0,0 +1,206 @@ +--- +title: Custom Tasks +sidebar_label: Custom Tasks +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Users can create their custom tasks for their application following a specific template. +When creating these tasks, the user should begin by creating a python file in the +**/opt/onav//app/custom_tasks/** directory, where *onav_version* +is the currently running version of OutdoorNav. The file should be written following +the instructions provided below: + +1. Import the `custom_task_base` package. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +``` + +2. The user should then create a class name to replace `CustomTask` and initialize it with the +`CustomTaskBase`'s __init__ function and the action server name for the task. + +```python +class CustomTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("custom_task_name") +``` + +:::note + +The `CustomTaskBase` exposes a `SimpleActionServer` (see here +for further details) object as `_as`, a `UITaskFeedback` object as `_feedback` and a `UITaskResults` object as `_result` to be used as part of +the tasks functionality. + +::: + +3. The last requirement is that the `CustomTask` needs to have the `run_task(self, goal)` function be defined, +which takes in the UITaskGoal. + +```python + def run_task(self, goal): +``` + +:::note + +When running the task users may handle errors through the action servers `set_aborted()` function. When this function is called the entire mission +will be aborted. + +::: + +4. Restarting the UGV will trigger the system to load the custom task that was created, making it available for mission use. +If a custom task is not configured properly the custom task manager will ignore the task and proceed loading in the next task while logging an error with ROS. + + +## Sample Custom Tasks + +### Input Looper + +Below is a sample template file named "input_looper.py" which iterates throught the two data variables and publishes them to the feedback +topic. If neither of the variables have any data in them the task is aborted. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * + +class InputLooperTask(CustomTaskBase): + def __init__(self): + # The derived class must always call the super() and provide the action server name. + # This name will need to be unique among custom tasks and must match what is in the + # UI. + super().__init__("input_looper") + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + # Task and running mission will be aborted in this case + self._as.set_aborted() + return False + + # Loop through the strings and float values and publish them each to the /input_looper/feedback topic + for string in goal.strings: + self._feedback.state = string + self._as.publish_feedback(self._feedback) + + for num in goal.floats: + self._feedback.state = str(num) + self._as.publish_feedback(self._feedback) + + # Returning True or False will not currently impact the mission but will write the current state to the + # /task/result topic accordingly. + return True +``` + +### Record GNSS Data + +Below is a sample custom task file named "record_gnss.py" which outputs the current GNSS data to the console. + +```python +#!/usr/bin/python3 + +from onav_tasks.custom_task_base import * +from sensor_msgs.msg import NavSatFix +from threading import Lock +import rospy + +class RecorGNSSTask(CustomTaskBase): + def __init__(self): + super().__init__("record_gnss") + self._sub = rospy.Subscriber("/sensors/gps_0/fix", NavSatFix, self.gpsSubscriberCallback) + self.gps_lat = 0.0 + self.gps_lon = 0.0 + self._gps_coordinates_lock = Lock() + + def run_task(self, goal): + feedback = UITaskFeedback() + feedback.state = 'Recording GNSS lat/lon' + self._as.publish_feedback(feedback) + msg = "" + with self._gps_coordinates_lock: + msg = "ID: %f Name: %s Latitude: %f Longitude: %f" % ( + goal.floats[0], goal.strings[0], self.gps_lat, self.gps_lon) + rospy.loginfo(msg) + return True + + def gpsSubscriberCallback(self, msg): + with self._gps_coordinates_lock: + self.gps_lat = msg.latitude + self.gps_lon = msg.longitude +``` + + +### Move PTZ camera to a Lat/Lon + +Below is a more advanced custom task. The file is "move_ptz_lat_lon.py" which pans a PTZ camera to point to a specific lat/lon coordinate. + +```python +from onav_tasks.custom_task_base import * +import actionlib +from clearpath_localization_msgs.srv import * +from clearpath_navigation_msgs.msg import * +from nav_msgs.msg import Odometry +from ptz_action_server_msgs.msg import PtzAction +import ptz_action_server_msgs.msg +import math +from math import remainder, tau +import rospy +from sensor_msgs import * +from tf.transformations import euler_from_quaternion, quaternion_from_euler + + + +class MovePtzLatLon(CustomTaskBase): + def __init__(self): + super().__init__("move_ptz_lat_lon") + self.localization_subscriber_ = rospy.Subscriber("/localization/odom", Odometry, self.localizationCallback) + self.move_ptz_client_ = actionlib.SimpleActionClient('/sensors/camera_0/move_ptz', PtzAction) + self.service_ = rospy.ServiceProxy('/localization/lat_lon_to_xy', ConvertLatLonToCartesian) + self.current_pose = Odometry() + + def localizationCallback(self, odom_msg): + self.current_pose = odom_msg + + def run_task(self, goal): + if len(goal.strings) == 0 and len(goal.floats) == 0: + rospy.logwarn('Warning') + self._as.set_aborted() + return False + goal_latitude = goal.floats[0] + goal_longitude = goal.floats[1] + goal_zoom = goal.floats[2] + str2 = 'Received goal latitude: ' + str(goal_latitude) + ', goal longitude: ' + str(goal_longitude) + ', zoom: ' + str(goal_zoom) + feedback = UITaskFeedback() + feedback.state = 'Aiming camera at lat-lon (' + str(goal_latitude) + ', ' + str(goal_longitude)+')' + self._as.publish_feedback(feedback) + orientation_q = self.current_pose.pose.pose.orientation + orientation_list = [orientation_q.x, orientation_q.y, orientation_q.z, orientation_q.w] + (roll, pitch, yaw) = euler_from_quaternion (orientation_list) + + gps_msg = sensor_msgs.msg.NavSatFix() + gps_msg.latitude = goal_latitude + gps_msg.longitude = goal_longitude + goal_utm = self.service_(gps_msg) + + goal_x = goal_utm.pose.pose.position.x + goal_y = goal_utm.pose.pose.position.y + + goal_angle = math.atan2(goal_y - self.current_pose.pose.pose.position.y, goal_x - self.current_pose.pose.pose.position.x) + pan_angle = math.remainder(goal_angle - yaw, math.tau) + print(pan_angle) + + self.move_ptz_client_.wait_for_server() + goal = ptz_action_server_msgs.msg.PtzGoal() + goal.pan=pan_angle + goal.tilt=0 + goal.zoom=goal_zoom + self.move_ptz_client_.send_goal(goal) + self.move_ptz_client_.wait_for_result() + print(self.move_ptz_client_.get_result()) + return True +``` diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/foxglove_visualization.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/foxglove_visualization.mdx new file mode 100644 index 00000000..7a36a4fc --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/foxglove_visualization.mdx @@ -0,0 +1,27 @@ +--- +title: Foxglove Visualization +sidebar_label: Foxglove Visualization +sidebar_position: 6 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +We have enabled Foxglove visualization as part of OutdoornNav, for improved debugging and data visualization and analysis. +To access the Foxglove visualization interface for standard OutdoorNav configurations, navigate to the following +[URL](http://192.168.132.1/_/foxglove). + +For UGVs running OutdoorNav that are not equipped with a base station, you must first connect the UGV's computer to a network over the 192.168.131.xxx +subnet. You will then be able to access the platform at (`platform_pc_ip_address`/\_/foxglove), where the __ is +the IP address of the host (UGV) computer, typically 192.168.131.1. + +
+
+ +
Foxglove layout
+
+
+ +For more information on the available Foxglove panels and how to more thoroughly us it, please consult the [Foxglove documentation](https://foxglove.dev/docs/studio). \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx new file mode 100644 index 00000000..aef2ea67 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/mission_scheduler.mdx @@ -0,0 +1,50 @@ +--- +title: Mission Scheduler +sidebar_label: Mission Scheduler +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +### Scheduling missions + +By selecting the "SCHEDULER" option from the upper left hand menu, the user can open the Mission Scheduler interface. This interface +allows users to schedule groups of missions to run at a later time. These schedules can be set to run only once or to be looped over a period of time. +For example, a user could create a schedule that will run 3 missions starting at 9 AM and run every hour 8 times. Once the last iteration is run, the +schedule will disable itself and can be re-enabled to run again later. The view itself can be found in the image below and is elaborated further afterwards. + +:::note + +Presently only Waypoint Missions can be scheduled with the scheduler. A future update will allow users to schedule both Map and +Waypoint Missions together in a single schedule. + +::: + +
+
+ +
Mission Scheduler View
+
+
+ +#### Adding/Updating a Schedule + +The user can either create a new schedule by filling in the appropriate fields or edit a schedule by selecting the pencil icon for that schedule +in the bottom table. The input fields are outlined as follows: + +- Name: The name of the schedule. +- Start Time: The browser's local time that the schedule will start. This is stored as UTC time on the robot. +- Enabled: Enables/Disables the schedule. When schedules are completed they will disable themselves. +- Missions: The list of missions that will run. The schedule will run the missions in the order that they are added. +- Schedule Mode: Sets the kind of schedule mode to be either "Run Once" or "Looped". If it is set to run once, the next 2 inputs will be disabled. +- Loops: The number of iterations the schedule should run for. If for example it is set to Loop 5 times then the schedule will run 5 times (instead of run once and then re-runs 5 times). +- Loop Interval: The amount of time between the start of successive loop iterations. This is independent of the mission duration. +- Minimum Battery Charge: The minimum battery percentage that the UGV should be at to run the schedule. +- Timeout: The maximum amount of time to spend on running a single loop of the schedule. If a loop exceeds this timeout value the schedule is assumed to have failed and alerts the user + accordingly. This can be set to 0 to disable the timeout feature. + +#### Schedule Table + +Schedules found in the database are displayed in a simple table at the bottom of the screen. Schedules can be enabled, edited or deleted from this table through the +icons on the right hand side. The schedules can also be sorted by name or start time in ascending/descending order. The next schedule to run (if one is available) will have +a small information icon next to it's name and will also be reported at the top of the screen. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx new file mode 100644 index 00000000..d2e0284d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/navigation.mdx @@ -0,0 +1,38 @@ +--- +title: Navigation Features +sidebar_label: Navigation Features +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::danger SAFETY WARNING + +Making changes to any of the following variables may decrease system safety. It is recommended that users +only modify these parameters in consultation with Clearpath Robotics Support. + +::: + +:::note + +Changes to any of the following variables will only take effect after power cycling the UGV. + +::: + +The OutdoorNav Software contains a set of features that can be enabled +or disabled according to your required application requirements. These +features can be enabled or disabled through the use of environment +variables, which should be added to the +`/opt/onav//config/autonomy.env` file, where *onav_version* +is the currently running version of OutdoorNav. The following table describes +the available features, their default state and any additional parameters +that we expose that may also be included to tune the feature. + +| Feature | Description | +|-----------------------------|----------------------------------------| +| **Collision Avoidance** | Collision avoidance is the UGV's ability to detect obstacles and stop/maneuver around the obstacle without any collisions. If `true`, the UGV will detect obstacles and if `false` no obstacles will be detected. Setting to `false` is not recommended and may cause harm to property or to individuals.

Environment Variable: `ENABLE_COLLISION_AVOIDANCE` (Default: `true`). | +| **Constrained Planning** | The constrained replanning feature, which is always enabled, restricts the area in which the UGV can plan paths. For example, if the default `PATH_CONSTRAINT` of 3.0 m is used, the UGV will not be allowed to 1) produce paths that drive it more than 3.0 meters from the initial path, and 2) fail to compute paths if the UGV is further than 3.0 meters from the any of the Waypoints. This allowable planning/navigation area can be shown on the map over the connecting lines between Waypoints. See [Constrained Replanning](../web_user_interface/ui_waypoint_mode.mdx#constrained_path) for further details.

Use the `PATH_CONSTRAINT` environment variable to modify the path constraint (in meters). | +| **Path Smoothing** | Generate paths according to a specified turning radius.

Environment Variable: `ENABLE_DUBINS_PATH_SMOOTHER` (Default: `false`).

Use the `TURN_RADIUS` environment variable to modify the radius of the planned paths (in meters). | +| **Stop Distance** | The stop distance feature allows the UGV to stop a predefined distance away from obstacles. This is useful if a UGV cannot drive in reverse and needs the required room in front of it to replan around an obstacle.

Environment Variable: `ENABLE_STOP_DISTANCE` (Default: `false`)

Use the `STOP_DISTANCE` environment variable to modify the stop distance (in meters). Note that if the stop distance is larger than 4.5 meters for the Clearpath Robotics Jackal and Husky UGVs, or 10.0 meters for the Clearpath Robotics Warthog UGV, the computational load will increase and may cause a decrease in performance in the navigation. | +| **Delay Compensation** | The delay compensation feature is able to compensate for mechanical delay on UGVs where either the accelerator introduces delay into the linear velocity or the steering introduces delay in the angular velocity. This feature is not required for Clearpath Robotics UGVs as negligible delay is present in our system.

Environment Variable: `ENABLE_DELAY_COMPENSATION` (Default: `false`)

Use the `CONTROLLER_DELAY` environment variable to modify the amount of delay to be compensated (in milliseconds). | +| **Docking** | If purchased, autonomous docking will allow the user to autonomously dock/undock their UGV. If not purchased, enabling this environment variable will do nothing.

Environment Variable: `OUTDORRNAV_ENABLE_DOCKING` (Default: `false`).| diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx new file mode 100644 index 00000000..70a6c687 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/features/rosbag_recorder.mdx @@ -0,0 +1,34 @@ +--- +title: ROSbag Recorder +sidebar_label: ROSbag Recorder +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +If you need to perform a quick rosbag recording from the UI you can do +so by navigating to the Settings dropdown in the upper left hand menu and +select **Start rosbag recording**. This will record a rosbag of the +following topics (or all the topics in the namespace if followed by a +`/*`): + +- '/rosout(.*)' +- '/twist_marker_server/(.*)' +- '/dock/(.*)' +- '/laser_target_tracker/(.*)' +- '/localization/(.*)' +- '/localization_core/(.*)' +- '/localization_helper/(.*)' +- '/mission/(.*)' +- '/navigation/(.*)' +- '/onboard_systems/(.*)' +- '/platform/(.*)' +- '/swiftnav/(.*)' +- '/sensors/gps(.*)' +- '/sensors/imu(.*)' +- '/target/(.*)' +- '/tf(.*)' + +To stop the recording navigate to the Settings drop down and select +**Stop rosbag recording**. This will save the rosbag with the date and +time as its file name in the `/opt/onav/saved_files/rosbags/` directory. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json new file mode 100644 index 00000000..8b4a486d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 5 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx new file mode 100644 index 00000000..e7298e8a --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/first_time_checklist.mdx @@ -0,0 +1,114 @@ +--- +title: First Time Use Checklist +sidebar_label: First Time Use Checklist +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Hardware Setup + +### ☐ Has the Base Station been set up? + +Ensure that the Base Station has been set up approximately 5 meters +away from any buildings and is currently powered on. See +[System Startup](system_setup.mdx) for further +instructions related to setting up the Base Station. + +### ☐ Is the UGV connected to the Base Station? + +Check to see that the UGV can be pinged from the Base Station network. +See [Connecting to Web UI](system_setup.mdx#connecting_to_web_ui) for further +details. + +## Software Setup + +### ☐ Is ROS running on the UGV? + +SSH into the UGV and run `rostopic list` to generate a list of the +rostopics that are currently available. The list is generally fairly +long so if you are looking for any specific topic please refer to +[API Endpoints](../api/api_endpoints/api_endpoints.mdx). You can also check the +ROS status through the OutdoorNAV UI by referring to the diagnostics section +on the Status page. + +### ☐ Is the OutdoorNAV software running? + +Check to see if the relevant dockers are running (ssh into the UGV and +run `docker ps` which should show at least 5 separate docker containers +running). + +### ☐ Is the computer using the UI connected to the Base Station network? + +This can be confirmed by following the steps found in +[Connecting to Web UI](system_setup.mdx#connecting_to_web_ui). + +### ☐ Have you surveyed the Base Station? + +See [RTK Survey Positioning](../cpr_hardware.mdx#base-station-survey) for +information on how and when to survey the Base station. + +### ☐ Do you have a strong GPS signal? + +After surveying the Base Station check the upper right hand corner of +the UI to confirm that you have a strong GPS signal (the POS and DIR +icons should be green). If either of these icons are not green refer +to [Checking GPS RTK Fix](../cpr_hardware.mdx#base-station-survey) for further +troubleshooting information. + +### ☐ Is the map loading correctly? + +Currently the map requires internet access to load. Refer to +[Loading Map Tiles](system_setup.mdx#loading_map_tiles) for more details +related to setting up the map. + +### ☐ Has the Datum been set? + +See [Set Datum](system_setup.mdx#set-datum) for information on how +to set the Datum variables. + +### ☐ If docking is enabled has the location been set? + +If the Clearpath Robotics autonomous docking package was purchased the +docking location will need to be set. See +[Set Dock Location](system_setup.mdx#set-dock-location) for information on +how to set the docking location. + +### ☐ Is the Navbar status icon functioning? + +To check if the Navbar icon is functioning, trigger the UGV's motion stop +and check to see if it has turned to a red icon. Clicking the icon +will bring up the status information as well as any recent messages +(see below). + +![](/img/outdoornav_images/ugvStatusMessages.png) + +## Using the UI + +The following items are general checks to ensure that the UI is working +properly. + +### ☐ Can the virtual joystick drive the UGV? + +See [Web UI Manual Mode](../web_user_interface/ui_manual_mode.mdx) for further details +related to this. + +### ☐ Can you create a new mission? + +Select the mission list and then click on `Add Mission` to create a +new mission. To add new waypoints for the mission refer to +[Mission Creation](../web_user_interface/ui_waypoint_mode.mdx#mission-creation). + +### ☐ After creating a new mission, can you execute the mission? + +To execute a mission refer to [Mission Execution](../web_user_interface/ui_waypoint_mode.mdx#mission-execution). + +### ☐ Are the cameras (if present) active in the view bar section when running the mission? + +For more information related to camera views see +[Camera Views](../web_user_interface/ui_overview.mdx#camera-views). + +### ☐ Can you select a camera and save an image after it loads on the main screen? + +See [Pan-Tilt-Zoom (PTZ) View ](../web_user_interface/ui_overview.mdx#ptz-view) for more details related +to saving images. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx new file mode 100644 index 00000000..c8060f35 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/system_setup.mdx @@ -0,0 +1,230 @@ +--- +title: System Setup +sidebar_label: System Setup +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +This section outlines how to set up your OutdoorNav system for some +preliminary testing with the OutdoorNav Software on a UGV. For details +on simulation, refer to [Simulation](../simulation.mdx). + +These instructions assume that the UGV is already powered ON. + + + +## Connecting to Web UI {#connecting_to_web_ui} + +The web server for the UI typically runs on a computer on the UGV. As +such, it is necessary for the networking setup on the UGV to be complete +and for all related hardware to be powered on. + +:::note + +In the case of Clearpath Robotics OutdoorNav Hardware, ensure that the +Base Station is powered ON. + +::: + +Follow the steps below to connect to the Web UI. + +1. Connect your computer to the same network as the UGV. + + :::note + + For Clearpath Robotics OutdoorNav Hardware, use the Base Station + network. Enter the network list and find the wireless network + related for your UGV. The SSID of the network is located in the + Robosmith manual that was shipped with your UGV. + + ::: + +2. Open an Internet browser (preferably Chrome) on your computer. + +3. Enter the UGV's IP address followed by a forward slash in the + search bar. A bookmark of this page can also be created for future + sessions. + + :::note + + For Clearpath Robotics OutdoorNav Hardware, this will be + **192.168.131.1/** for normal use cases and **192.168.131.5/** for + systems with a separate OutdoorNav computer (including the + OutdoorNav Starter Kit and the OutdoorNav Backpack. + + ::: + +The above steps will open the Web UI, which will allow the user to +operate the UGV in Manual Mode (teleoperation) or in Autonomous Mode +(missions). Upon startup the user will be presented with a page that +shows the End-User License Agreement. This page will be visible each +time the UGV is restarted but only on the first navigation to the page. +The EULA should be reviewed prior to using the system. + +## Loading Map Tiles {#loading_map_tiles} + +The Web UI does not cache map tiles on the browser; therefore, the user +will need to ensure their computer has a connection to an Internet +source to load the map tiles. There are a several options to achieve +this: + +1. If the system includes a Base Station that is connected to the + Internet, you will be able to access the Internet and therefore map + tiles over the base station network without needing any further + updates. +2. Connect your phone via USB to your computer (or tablet) and enable + USB tethering on your phone to share the Internet from your phone. +3. Switch your computer (or tablet) to a network that is connected to + the Internet, zoom in/out of the map to load the tiles then switch + back to the original network. + +## Survey Base Station {#survey_base_station} + +If your system includes a Base Station, it must be surveyed using the +steps below to be able to to operate the UGV autonomously. + +1. Access the Menu → Settings → Map. +2. In the **Survey Base Station** section, click the **Start** button + begin the surveying process. + +During surveying, the Status Indicator will turn orange +and return to its green default state when surveying is +done . +Only then should the UGV be sent on autonomous missions. +The entire surveying will take approximately 5 minutes. A feedback bar +will also be displayed showing the current progress of the surveying. Do +not refresh the page or you will lose the feedback bar. + +:::warning + +For an accurate survey, do NOT move the Base Station during this +process. After the surveying has completed, the Base Station should not +be moved unless required. If you need to move the Base Station or it has +been moved accidentally, the surveying process needs to be run again. + +::: + +## Set Datum + +Before operating the UGV autonomously, the user will need to set the +datum, which is the reference point in the world coordinate frame. + +1. Access the Menu → Settings → Map. + +2. In the **Change Datum** section, enter the latitude and longitude of + a location close to the test site (within 10km). Decimal lat/lon are + expected. Use a minimum of 6 decimal places. + +3. Click **Set Datum** button to set the new datum. + + The user should see the blue dot (datum) and the blue arrow (UGV) + move to the test site. If the GPS status indicators are green, the + UGV should be at its correct position on the map as well as facing + in the correct direction. + +## Set Dock Location + +:::note + +If the Clearpath Robotics autonomous docking package has been purchased, +follow these instructions to set up the dock location. Otherwise, this +section can be skipped. + +::: + +:::warning + +Keep the area around the dock free of objects and people. There is no +obstacle detection between the pre-docking point and the dock; +similarly, there is no obstacle detection during the undocking +operation. + +::: + +
+
+ +
Autocharge Dock
+
+
+ +Before being able to dock the UGV autonomously, set up the dock +location. Follow these steps to position the UGV in its correct position +and orientation. + +1. Power ON the UGV and computer and wait for the system to finish + booting. For example, on the Clearpath Robotics Husky, booting is + complete when the COMM indicator turns green. + +2. Start by manually driving the UGV to the dock target and align it as + straight and centered as possible so that it begins charging. The + Wibotic receiver on the UGV should be centered longitudinally and + laterally with the circle on the Wibotic transmitter (TR-300). + +3. Let the UGV sit in this position for 2 minutes to acquire an RTK GPS + fix. The POS (position) and DIR (heading) GPS status indicators on + the UI should read as follows: . + + **If the GPS status indicators are yellow or red, the selected + location of the dock is NOT appropriate. Please change the dock + location such that the GPS antennas have a clearer visibility.** + +4. On the UI, access the drop down menu on the top-left of the page, + select **Settings** and click the **Add New Dock Location** button. The + dock location will be stored in 5 - 10 seconds as data is collected. + +If the Base Station has been moved (and therefore been resurveyed), or +if the dock has been moved to a new location, the user will need to +reset the location of the dock. This is done in the following manner: + +1. Repeat the previous set of instructions from step 1 to 4. + +2. While in **Edit Mode** select the dock on the UI. A drop down should appear + with the option to reset the dock location. Select that option. + +3. After approximately 5 - 10 seconds the dock location should be updated and the UI will + reflect the change accordingly. + +## Checking GPS RTK Fix {#checking-gpt-rtk-fix} + +Each time the UGV has been powered up (or moved from a GPS-denied +environment to a GPS-available environment), let the UGV sit in this +position for 2 minutes to acquire an RTK GPS fix. The POS (position) and +DIR (heading) GPS status indicators on the UI should be green: . + +**If the GPS status indicators are yellow or red, the selected location +does not have an adequate GPS signal. Move the UGV such that the GPS +antennas have a clearer visibility.** + +If using Switft Navigation Duros and/or a Clearpath Robotics Base +Station, each of these will have a solid blue LED on all of them when +the RTK GPS fix is acquired. + +## Recording a Rosbag + +See the [ROSbag Recorder](../features/rosbag_recorder.mdx) section for details on recording ROS data either. + +## Subsequent Sections + +The following sections of this manual will outline the instructions for +different tasks that can be accomplished while operating the UGV. + +1. **Web User Interface:** + - Overview of the Web UI components as well as the available views + and icons/buttons associated with them. + + - Overview of the buttons required to operate the UGV in Manual + Mode (teleoperation). + + - Overview of how to send missions using the Map mode. + + - Overview of how to send missions using the Waypoint mode. + +2. **Application Programming Interface:** Details on how to control the + UGV programmatically. +3. **OutdoorNav Features** Details on the features available as part of the + navigation software. +4. **Simulation:** Details on how to simulate autonomous operation of + the UGV. +5. **FAQs:** A list of frequently asked questions. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx new file mode 100644 index 00000000..aeedd85f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/terminal_interface.mdx @@ -0,0 +1,244 @@ +--- +title: Command Line Interface +sidebar_label: Command Line Interface +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +By default, the OutdoorNav Software begins automatically when the system +is powered on. This section outlines the OutdoorNav Command Line Interface (CLI), +the set of commands that can be used by developers who are debugging +the system or who want more precise control for managing the OutdoorNav +software. + +## Connecting to the OutdoorNav Computer {#connecting-to-outdoornav-computer} + +To connect to your UGV, consult its corresponding user manual. + +If you are using a Clearpath Robotics UGV with a separate OutdoorNav Computer, +first `ssh` to the UGV using the details provided in the UGV user +manual. Then, if a separate OutdoorNav Computer exists, you can +connect to it by running: + +``` bash +ssh administrator@192.168.131.5 +``` + +## OutdoorNav CLI Installation + +The OutdoorNav CLI is pre-installed on Clearpath robots. If it has not +been installed on your system, it can be installed by running the following +on the OutdoorNav Computer: + +```bash +sudo apt-get install python3-onav-cli +``` + +:::note + +The command above requires that the Clearpath Package Server has been +configured on your OutdoorNav Computer. This is pre-configured on +Clearpath robots. Refer to details on the +[Clearpath Package Server](http://packages.clearpathrobotics.com/) if +this is not configured on your computer. + +::: + +## Listing the OutdoorNav CLI Commands and Getting Help + +To list all of the CLI commands, run the following on the OutdoorNav Computer: + +```bash +onav help +``` + +The CLI commands are: + +- `install`: Download and configure OutdoorNav +- `key`: Get, set, or delete your OutdoorNav license key +- `download`: Download OutdoorNav, but do not configure it +- `configure`: (Re)configure OutdoorNav +- `upgrade`: Upgrade OutdoorNav to the latest vesion +- `uninstall`: Uninstall OutdoorNav +- `depends`: Verify and install dependencies +- `start`: Start OutdoorNav +- `stop`: Stop OutdoorNav +- `status`: Check the status of OutdoorNav +- `logs`: View OutdoorNav logs +- `versions`: Print versions available to install +- `help`: Show available commands + +To get help on an individual command, use the `-h` option. For example, to +get help on the `install` command, run `onav install -h`: + +``` +usage: onav install [-h] [-k KEY] [-b] [-c] [-H] VERSION + +positional arguments: + VERSION The OutdoorNav version to install (e.g. 0.11.0) + +optional arguments: + -h, --help show this help message and exit + -k KEY, --key KEY Your OutdoorNav installation key + -b, --backpack Configure in backpack/bridged mode + -c, --clean Clean any configurations from a prior installation +``` + +## Starting and Stopping the OutdoorNav Software {#starting-outdoornav} + +On UGV startup, all the sensors, the user interface, as well as the +autonomy software are set to start automatically. When debugging or when +greater control is desired, the CLI can be used to start and stop +the OutdoorNav software, in whole or in part. + +To see the current status of OutdoorNav software, run: + +```bash +onav status +``` + +To start the OutdoorNav software if it is not running, use the following command, +which starts the latest version of the software by default: + +```bash +onav start +``` + +To stop the OutdoorNav software, run: + +```bash +onav stop +``` + +## Stopping and Restarting the Autonomy Software Only + +To use the UGV without the autonomy software, use the following +command to stop the nodes and prevent them from automatic startup: + +``` bash +onav stop -s autonomy +``` + +The autonomy software can be restarted by running: + +``` bash +onav start -s autonomy +``` + +## Stopping/Restarting the Sensors + +To use the UGV without the sensors, use these commands to disable the +nodes and prevent them from automatic startup: + +``` bash +onav stop -s sensors +``` + +:::note + +This command will only disable the drivers for the sensors that are started +by the OutdoorNav software. This includes the GNSS units, the Microstrain IMU, +and any LiDAR/Stereo detection sources (not limited to Velodyne LiDARs, Realsense +cameras, 2D Lidars). + +::: + +The sensors software can be restarted by running: + +``` +onav start -s sensors +``` + +## Accessing the OutdoorNav Software Logs + +To check the logs of the OutdoorNav software, use the `onav logs` command +with the appropriate service. For example, to view the logs for the sensors +service, run: + +```bash +onav logs sensors +``` + +## Installing the OutdoorNav Software + +OutdoorNav is typically pre-installed on Clearpath robots, so most users should +not need to do a first-time installation of the software, though the process +is outlined below as a reference. + +As a first step, confirm that the robot has internet access. For example, confirm +that the following command is successful: + +``` +ping 8.8.8.8 +``` + +Second, the required dependencies need to be installed by running: + +```bash +onav depends +``` + +Third, a key needs to be added onto the robot to enable the installation +process. Contact [Clearpath Support](../support) if you did not receive your key. +To add your key, run the following, replacing `` with the actual value: + +```bash +onav key +``` + +Fourth, list the versions available for installation by running: + +```bash +onav versions +``` + +Fifth, install the OutdoorNav software for the desired version (typically the +newest version), by running the following, replacing `` with +the version to be installed: + +```bash +onav install +``` + +When prompted, trigger the reboot. + +Finally, following the reboot, run the following command to start the OutdoorNav +software. This will only be required the first time after installation. + +```bash +onav start +``` + +## Upgrading the OutdoorNav Software + +After receiving a notice that a new version of the OutdoorNav Software is +available, use the `onav upgrade` command with the appropriate version. +For example, to upgrade to the newest avialbel version that you are eligible +to receive, run the following command: + +``` +onav upgrade +``` + +:::note + +The upgrade requires internet access to download the new software. +Confirm that the OutdoorNav Computer has internet access by running a command +such as: + +``` +ping 8.8.8.8 +``` + +::: + +## Uninstalling Old Versions of OutdoorNav Software + +If old versions of OutdoorNav software are no longer being used, they can +be removed with the `onav uninstall` command. For example, to uninstall 0.11.0 +run: + +``` +onav uninstall 0.11.0 +``` \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx new file mode 100644 index 00000000..5ba3bab4 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/getting_started/tf_validation.mdx @@ -0,0 +1,80 @@ +--- +title: TF Validation +sidebar_label: TF Validation +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +:::note + +Sensor transform (TF) validation should only be required if the performance +is noticeably poor, such as when the UGV drifts off of the planned path or +oscillations occur around the path). + +::: + +The coordinate transformation of the two GPS antennas, the IMU, the 2D +and 3D Lidars to the base_link of the UGV should have already been set +prior to receiving the UGV. However, ensure that they are set correctly. + +The ROS coordinate frame base_link, shown in the figure below, is +located at the center of the bottom plate of the UGV. The environment +variables below should be taken with respect to this coordinate frame. +The X axis is in red (and pointing towards the front of the UGV), Y in +green (pointing towards the left of the UGV) and Z in blue (pointing +towards the sky). + +You can check the current value of the environment variables by running +the following on the robot (host) computer (and setting +to the names listed in the table below). + +``` bash +printenv | grep +``` + +The environment variables for the position and orientation of each +sensor are provided in the table below. + +_OutdoorNav sensor position and orientation environment variables_ + +| Environment Variable | Function | +|----------------------|---------------------------------------| +| POSITION_GPS_XYZ | [X,Y,Z] position, in meters, of the position GNSS antenna with respect to the base_link coordinate frame. | +| POSITION_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the position GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_XYZ | [X,Y,Z] position, in meters, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| HEADING_GPS_RPY | [Roll,Pitch,Yaw], in radians, of the heading GNSS antenna with respect to the base_link coordinate frame. | +| MICROSTRAIN_XYZ | [X,Y,Z] position, in meters, of the IMU with respect to the base_link coordinate frame. | +| MICROSTRAIN_RPY | [Roll,Pitch,Yaw], in radians, of the IMU with respect to the base_link coordinate frame. | +| VLP_XYZ | [X,Y,Z] position, in meters, of the 3D Lidar with respect to the base_link coordinate frame. | +| VLP_RPY | [Roll,Pitch,Yaw], in radians, of the 3D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| LMS1XX_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| HOKUYO_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_XYZ | [X,Y,Z] position, in meters, of the 2D Lidar with respect to the base_link coordinate frame. | +| D435_RPY | [Roll,Pitch,Yaw], in radians, of the 2D Lidar with respect to the base_link coordinate frame. | + +There may also be 2 of each of these detection sensors. The corresponding environment +variable is prefixed with `REAR_`. + +:::note + +When the printed Y axis on the IMU is pointing towards the front of the +robot (i.e., aligned to X axis of base_link), MICROSTRAIN_RPY = [0, 0, 0]. + +::: + +:::warning + +If you decide to move any of these sensors, you must modify these +variables accordingly in the `/opt/onav/outdoornav_host_setup.sh` file (on the host). + +
+
+ +
base_link coordinate frame
+
+
+ +::: diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx new file mode 100644 index 00000000..09a63a7f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/index.mdx @@ -0,0 +1,18 @@ +--- +title: OutdoorNav User Manual +sidebar_label: OutdoorNav User Manual +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +
+
+ +
+
+ +OutdoorNav is an outdoor autonomy software platform designed for vehicle developers, +OEMs and robotics researchers. Compatible with Clearpath outdoor mobile platforms +and third-party vehicles, OutdoorNav provides reliable, industry-leading GPS-based +navigation for faster, more efficient autonomous vehicle development. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json new file mode 100644 index 00000000..e9e0ff1d --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Appendix A: UGV Integration Requirements", + "position": 12 +} \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json new file mode 100644 index 00000000..75ebaf1b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Hardware Kit Installation", + "position": 2 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx new file mode 100644 index 00000000..36f5f77b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/custom_kit_hardware_checklist.mdx @@ -0,0 +1,19 @@ +--- +title: "Custom Kit Hardware Checklist" +sidebar_label: "Custom Kit Hardware Checklist" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +To integrate the custom hardware kit from Clearpath Robotics onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav +software. + +| | Requirement | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | All sensors have been mounted to the UGV with fixed brackets. Ie. the sensor should not move or rotate relative to the UGVs `base_link`. | +| | Spacing between the GNSS antennas is greater than 0.7 m. | +| | SwitfNav Piksi/Duro GNSS units, 2D/3D LiDAR units (Velodyne, Sick, Hokuyo) and Axis cameras have been configured to communicate over ethernet (IP). IP sensors are assigned within the following ranges on the `192.168.131.XXX` subnet and recorded in the table below.
**Cameras**: 192.168.131.10-19, **LiDARs**: 192.168.131.20-29, **GNSS**: 192.168.131.30-39, **Wireless**: 192.168.131.50-59

SensorSensor IPSensorSensor IP
| +| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](hardware_integration_requirements.mdx#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
| + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx new file mode 100644 index 00000000..88614cd5 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/hardware_integration_requirements.mdx @@ -0,0 +1,44 @@ +--- +title: "Hardware Kit Installation Requirements" +sidebar_label: "Hardware Kit Installation Requirements" +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Several hardware configurations are compatible with OutdoorNav Autonomy Software. +Select the checklist below that corresponds to your hardware kit. + +- [OutdoorNav Standard Kit Hardware Checklist](standard_kit_hardware_checklist.mdx) +- [OutdoorNav Starter Kit Hardware Checklist](starter_kit_hardware_checklist.mdx) +- [OutdoorNav Custom Kit Hardware Checklist](custom_kit_hardware_checklist.mdx) + +In addition, if the OutdoorNav software is not running on the UGV computer itself, which is the case with the Starter Kit and some custom integrations, ensure that the UGV computer is configured correctly by reviewing the following checklist. + +- [UGV Computer Checklist](../platform_computer_checklist.mdx) + +## Notes on Measuring Frame Relationships + +### `base_link` Frame {#base-link-frame} + +For mobile robots, `base_link` should be rigidly attached to the mobile UGV. +It can be attached at any position of the UGV to provide a point of reference. +We also expect the orientation of `base_link` to be in the NWU convention. +ROS standards for `base_link` can be found in [REP-103](https://www.ros.org/reps/rep-0103.html#axis-orientation) and [REP-105](https://www.ros.org/reps/rep-0105.html#base-link). + +### Starter Kit Frame {#starter-kit-frame} + +The starter kit frame (`starter_kit_link`) is located at the center of the bottom plate of the enclosure. +Its orientation is also in the NWU convention with the X-axis of the frame pointing out of the front RealSense camera and the Y-axis coming out of the side of the enclosure **without** the power and Ethernet breakouts. + +### Sensor Frame + +The sensors frame for each sensor will vary. Please consult the documentation for the specific sensor. + +### Measuring Relative Pose + +Consider frame A (eg. `starter_kit_link`) and frame B (eg. `base_link`), rigidly attached to the UGV. +The relationship of A relative to B consists of two parts, the relative position and relative orientation. +The position of A relative to B can be obtained by measuring the distance (in X, Y, Z axes) from frame B to frame A, and providing that value in frame B's coordinate frame. +The orientation of A relative to B is obtained by rotating the axes of frame B until they line up with frame A, noting that results in each axis are the rotation angles of the orientation. +A trick for the orientation's sign is to remember that if you rotate the X-axis towards the Y-axis or Z-axis the rotation will be positive and that if you rotate away from the Y-axis or X-axis, it results in negative rotations. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx new file mode 100644 index 00000000..451b6c81 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/standard_kit_hardware_checklist.mdx @@ -0,0 +1,24 @@ +--- +title: "Standard Kit Hardware Checklist" +sidebar_label: "Standard Kit Hardware Checklist" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav Standard Kit from Clearpath Robotics contains: + +- SwiftNav Piksi/Duro GNSS (x2) +- Microstrain GX5-25 AHRS +- Velodyne Puck (VLP-16) 3D LiDAR + +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. + +| | Requirement | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| | All sensors have been mounted to the UGV with fixed brackets. Ie. the sensor should not move or rotate relative to the UGVs base_link. | +| | Spacing between the GNSS antennas is greater than 0.7 m. | +| | SwitfNav Piksi/Duro GNSS units and Velodyne LiDAR unit have been configured to communicate over ethernet (IP). IP sensors are assigned within the following ranges on the `192.168.131.XXX` subnet and recorded in the table below.
**LiDARs**: 192.168.131.20-29, **GNSS**: 192.168.131.30-39, **Microhard**: 192.168.131.50-59

SensorSensor IP
SwiftNav Piksi/Duro (Reference)
SwiftNav Piksi/Duro (Attitude)
Velodyne VLP-16
Microhard Wireless (Base Station)
Microhard Wireless (UGV)
| +| | For each sensor that is to be integrated, measure the XYZ position, in metres, and RPY (roll/pitch/yaw) orientation, in radians, relative to the robot's [base_link frame](hardware_integration_requirements.mdx#base-link-frame). Record the XYZ and RPY values in the table below.

SensorXYZRPY
GNSS Antenna (Reference)0.00.00.0
GNSS Antenna (Attitude)0.00.00.0
Velodyne VLP-16
Microstrain GX5­-25 AHRS
| + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx new file mode 100644 index 00000000..f8b6842e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/hardware_integration_requirements/starter_kit_hardware_checklist.mdx @@ -0,0 +1,51 @@ +--- +title: "Starter Kit Hardware Checklist" +sidebar_label: "Starter Kit Hardware Checklist" +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The OutdoorNav Starter Kit from Clearpath Robotics contains: + +- Ublox F9P GNSS +- Phidget Spatial 3/3/3 IMU +- RealSense D435f (x2) Depth Camera + +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. +Refer to the [OutdoorNav Starter Kit](/docs/robots/accessories/add-ons/outdoornav_starter_kit) for additional +integration details. + +
+
+ +
Starter Kit Integration
+
+
+ +To integrate this kit onto your robot, ensure that all of the requirements below are satisfied for proper operation of the OutdoorNav software. + +| | Requirement | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | The Starter Kit should be rigidly fixed to the UGV. Ie. It should not move or rotate relative to the UGVs base_link. | +| | Once mounted, the XYZ position of the [Starter Kit frame](hardware_integration_requirements.mdx#starter-kit-frame) relative to the [base_link frame](hardware_integration_requirements.mdx#base-link-frame) has been noted here:
X: , Y: , Z: | +| | The Starter Kit is connected to the base robot computer via a gigabit ethernet cable (Cat6(a) minimum). | +| | The Starter Kit is power by an **18 - 75 V** source supplied by the UGV. | + +Should any of the external sensors positions need to be moved, the following constraints should be followed: + +- The GNSS antenna is to be placed upright, on an unobstructed part of the UGV with clear visibility. +- The RealSense D435f cameras should be placed with a minimal amount of their field of view (FoV) obstructed by the UGV body. + + The new XYZ position of the GNSS antenna and/or the Realsense D435f cameras relative to the [Starter Kit Frame](hardware_integration_requirements.mdx#starter-kit-frame) are noted below: + + | Sensor | X | Y | Z | R | P | Y | + | ----------------------- | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | ------------------------------ | + | **GNSS Antenna** | | | | **0.0** | **0.0** | **0.0** | + | **RealSense D435f (front)** | | | | | | | + | **RealSense D435f (rear)** | | | | | | | + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx new file mode 100644 index 00000000..00cf8a07 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/integration_overview.mdx @@ -0,0 +1,34 @@ +--- +title: "Integration Overview" +sidebar_label: "Integration Overview" +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The scope of work to transform a non-autonomous UGV into an autonomous +one will vary depending on the exact hardware capabilities and software +interfaces of the UGV. Development work will be required by Clearpath +Robotics, the end user, or a third party developer to bring the UGV into +compliance with the requirements listed in the table below. This may +involve implementing encoders and controllers to provide velocity +control of the UGV and implementing a CAN bus to ROS interface with +kinematic control. The table below provides a general outline of the +requirements; the detailed requirements are covered in the following +sections. + +_Navigation hardware and software general integration scope of work_ + +| \# | Task | Note | +|-----|----------------------------------|---------------------------------| +| 1 | **Convert UGV to drive by wire** | If required; can be a significant electromechanical integration | +| 1.1 | Implement actuated steering and throttle control if necessary | | +| 1.2 | Implement the encoder and controller hardware to provide wheel velocity control and odometry feedback | May require electronic power steering position feedback and controller | +| 2 | **Create a ROS interface** | | +| 2.1 | Commission an OutdoorNav computer running Ubuntu 20.04 and ROS Noetic | | +| 2.2 | Create a ROS interface to the UGV Often interfacing via CAN bus motor controllers and UGV controller | | +| 2.3 | Create a ROS driver including UGV kinematics with ROS-control | Accepts velocity input, commands motor controllers, provides other status feedback | +| 3 | **Install and configure OutdoorNav Hardware and Software** | | +| 3.1 | Install OutdoorNav computer and sensors on the UGV | Provide mechanical mounting, power and ethernet communication to UGV computer | +| 3.2 | Install, update and configure OutdoorNav Software on computer | Configure for sensor mounting locations, UGV kinematics and data topics. Can be done remotely with assistance from Clearpath Robotics Engineering. Approximately 1-2 days. | +| 3.3 | Tune the path planning and following controllers for new UGV | Can be done at a Clearpath Robotics facility. Can often be done at end user facility via remote login from Clearpath Robotics Engineering. Approximately 2-5 days. | diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx new file mode 100644 index 00000000..45cdfb2c --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/interface_control_requirements.mdx @@ -0,0 +1,119 @@ +--- +title: "ROS Interface Control Requirements" +sidebar_label: "ROS Interface Control Requirements" +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## ROS Interface Control Checklist + +Prior to the installation and tuning of Clearpath Robotics (CPR) +OutdoorNav software on your platform (robot computer), CPR requires that the platform's +ROS interface satisfies the conditions listed below. Ensure that all of the requirements +are satisfied for a smooth installation and tuning process. + +![](/img/outdoornav_images/onav_interface_control.png) + +| | Requirement | +|------|------------------------------------------------------------------| +| | The platform computer is on the 192.168.131.xxx subnet (ideally in the range 1-4). | +| | The platform computer has an installation of [ROS 1 Noetic](http://wiki.ros.org/noetic/Installation). | +| | A URDF is supplied to CPR by the customer, in which the `base_link` coordinate frame is defined according to the [REP-105 base-link](https://www.ros.org/reps/rep-0105.html#base-link) ROS standard. | +| | The platform outputs [tf2_msgs/TFMessage](http://docs.ros.org/en/jade/api/tf2_msgs/html/msg/TFMessage.html) messages on the ROS standard `/tf` topic, at a minimum rate of **30 Hz**. | +| | The platform outputs a latched [tf2_msgs/TFMessage](http://docs.ros.org/en/jade/api/tf2_msgs/html/msg/TFMessage.html) message on the ROS standard `/tf_static` topic. This should include any fixed frames of ROS enabled devices/sensors that are available on your platform. | +| | The platform computer has a velocity controller that accepts, as input, [geometry_msgs/Twist](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/Twist.html) messages on the ROS standard `/cmd_vel` topic, at a minimum rate of **10 Hz**. | +| | The platform computer has a velocity controller that tracks the input velocity and outputs the resulting platform velocity on the `/platform/cmd_vel` topic. | +| | The platform outputs [nav_msgs/Odometry](http://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html) messages on the `/platform/odom` topic, at a minimum rate of **10 Hz**. | +| | The `/platform/odom` topic publishes its data with the header.frame_id = `odom` and the child_frame_id = `base_link`, as per the [REP-105 odom](https://www.ros.org/reps/rep-0105.html#odom) ROS standard. **IMPORTANT**: The platform should however not broadcast the `odom` --> `base_link` transformation since the OutdoorNav software will do so. | +| | If available, the platform odometry output has less than ±5% linear position error. | +| | If available, the platform odometry output has less than ±5% orientation error. | +| | The platform outputs [std_msgs/Bool](http://docs.ros.org/en/noetic/api/std_msgs/html/msg/Bool.html) messages on the `/platform/emergency_stop` topic, at a minimum rate of **5 Hz**, indicating whether or not the platform is in a stopped state. | +| | Perform the validation tests described in [Interface Control Validation Test](#interface-control-validation) section and [record a rosbag](http://wiki.ros.org/rosbag/Commandline#rosbag_record) of all of your topics. The linear and angular velocities of the three trial runs recorded should be noted here:

Trial #1: Linear x: , Angular z:
Trial #2: Linear x: , Angular z:
Trial #3: Linear x: , Angular z:
| + +:::note + +Consult the [Platform API](../api/api_endpoints/platform_api.mdx#topics-published-by-platform) for +detailed information on the published/subscribed platform topics. + +::: + +If the platform is an Ackermann (or double Ackermann) drive vehicle: + +| | Requirement | +|------|------------------------------------------------------------------| +| | A conversion from [geometry_msgs/Twist](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/Twist.html) messages to Ackermann inputs is provided. | + +:::note + +Ackermann drive platforms require both steering and throttle inputs to +drive the platform. It is required that our OutdoorNav output `/cmd_vel` +be converted into a message suitable to your platform. An example of an +Ackermann message type can be found +[here](http://wiki.ros.org/teb_local_planner/Tutorials/Planning%20for%20car-like%20robots). +This may satisfy your particular platform, and is only a starting point +on how to do this conversion. + +::: + +If the platform computer is running a version of ROS 2: + +| | Requirement | +|------|------------------------------------------------------------------| +| | The platform computer has a [ROS 2 to ROS 1 bridge](https://github.com/ros2/ros1_bridge) is installed to enable the exchange of messages between the two ROS versions. | + +Signature: Date: + +## Interface Control Validation Test {#interface-control-validation} + +The following test is designed to validate the platforms velocity +controller. It will be required that you command the robot to drive in +three circles, of varying radii, by applying the following command to +the platform. + +``` bash +rostopic pub -r 10 /cmd_vel geometry_msgs/Twist "linear: +x: ___ +y: 0.0 +z: 0.0 +angular: +x: 0.0 +y: 0.0 +z: ___" +``` + +The three trials that we request will vary between platforms depending +on the its maximum linear $(v_{max})$ and angular velocities +$(\omega_{max})$, minimum linear $(v_{min})$ and angular velocities +$(\omega_{min})$, as well as limitations due to the minimum allowable +turning radius $(r_{min})$. Of these three trials, we would like to see +data within three linear velocity bands, as seen in the table below, +resulting in three different turning radii. For the purpose of these +tests, the following formula can be used when determining the required +linear and angular velocities to apply: $r = v/\omega$. + +| Trial \# | Linear X Bands \[m/s\] | Example Linear X Band \[m/s\] | +| ---------|--------------------------------------------|-------------------------------------| +| 1 | $v_{min} \cdot [1.0, 1.5]$ | $[0.5, 0.75]$ | +| 2 | $((v_{max} - v_{min})/2) \cdot [0.9, 1.1]$ | $[2.025, 2.475]$ | +| 3 | $v_{max} \cdot [0.9, 1.0]$ | $[4.5, 5.0]$ | + +As an example, a platform with specs $v \in [0.5, 5.0]$, $r_{min} = 3$ +would have linear x velocity bands as listed in the table above. The +trials could then be as outlined in the table below. + +| Trial \# | Linear X \[m/s\] | Angular Z \[rad/s\] |Turn Radius \[m\] | +|-----------|--------------------|---------------------|------------------| +| 1 | 0.75 | 0.25 | 3 | +| 2 | 2.25 | 0.5 | 4.5 | +| 3 | 4.5 | 0.75 | 6 | + +Finally, the test data in the collected ROSbag should include the +following: + +1. `/tf` and `/tf_static` +2. `/platform/cmd_vel` +3. `/platform/odom` +4. `/cmd_vel` +5. `/platform/emergency_stop` (if available) +6. raw NavSatFix data from a GPS unit (if possible). diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/platform_computer_checklist.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/platform_computer_checklist.mdx new file mode 100644 index 00000000..0f2f334f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/platform_computer_checklist.mdx @@ -0,0 +1,24 @@ +--- +title: "Platform Computer Checklist" +sidebar_label: "Platform Computer Checklist" +sidebar_position: 5 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- + +The following instructions are only required if intending to install the OutdoorNav software on a secondary or Starter Kit computer, henceforth named the **hardware kit**. If installed on the platform computer, please proceed to the [Interface Control Checklist](./interface_control_requirements.mdx). + +In addition to the electromechanical installation of the hardware kit, software updates are required to the platform computer, as outlined below. + +| | Requirement | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Connect an ethernet cable between the platform computer and the hardware kit, either directly between them or via an ethernet switch. Make note of which port was used on the platform computer so that it's IP address can be configured in the next step. | +| | Ensure network connectivity between the platform computer and the hardware kit on the `192.168.131.XXX` subnet. Configure the platform computer to have a static IP assigned on the interface that is used to connect to the hardware kit. Ideally this IP address will be `192.168.131.1`, but it can be in the `192.168.131.1-4` range. In some cases, this may require the creation of a virtual interface. Record the platform computer IP address.
Platform Computer IP Address: | +| | On the platform computer, add the following line to the `/etc/hosts` file:
`192.168.131.5 cpr--onav>` | +| | On the platform computer, run `ping cpr--onav>` and confirm it is successful. | +| | On the platform computer, [Install ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu) if not already installed (the `ros-noetic-ros-base` version is sufficient). | +| | On the platform computer, configure ROS Noetic so it is running with the `ROS_MASTER_URI` set to the base platform computer. Note that `localhost:11311` is acceptable only if the primary subnet on the platform computer is the `192.168.131.XXX` subnet. | +| | Restart both the platform computer and the hardware kit, then run `rostopic list` on the platform computer and confirm that it includes the OutdoorNav topics. | +| | On the platform computer, complete all checks in [Interface Control Checklist](interface_control_requirements.mdx) and confirm that all listed ROS topics are publishing as expected. | + +Signature: Date: diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx new file mode 100644 index 00000000..0ec7da2e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/integration_requirements/software_integration_instructions.mdx @@ -0,0 +1,132 @@ +--- +title: "Software Integration Instructions" +sidebar_label: "Software Integration Instructions" +sidebar_position: 4 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import versions from "@site/static/versions.js" + +Prior to installing the OutdoorNav software, ensure that you have completed the relevant [Hardware Kit Checklist](hardware_integration_requirements/hardware_integration_requirements.mdx). If installing on a secondary/backpack/Starter Kit computer, ensure to have also completed the: +- [Interface Control Checklist](interface_control_requirements.mdx) + +All the following instructions, unless otherwise specified, are to be run on the OutdoorNav computer. + +### Install Command-line Interface Tool (CLI) {#install-cli} + + +{` +sudo apt update +sudo apt install python3-onav-cli +`} + + +### Install OutdoorNav + + +{` +onav install -k +`} + + +where `license_key` is the license key that you have been assigned and `VERSION` is the version +of the software to be installed (eg. 0.11.0). Only one license key can be used per UGV. + +:::note + +In some cases, including first-time installations, a reboot is required after installing +the required dependencies. In this case, it is necessary to re-run +the `onav install -k ` command again following the reboot to complete +the installation. + +::: + +### Configure UGV Footprint {#configure-platform-footprint} + +If the UGV has sensors and/or parts that protrude outside of the UGV body, then a few environment variables will need to be modified to adjust the footprint of the robot. Things that could be extending past the footprint could include but are not limited to: + +- GPS antennae, +- Charging receivers, +- Arms, +- etc... + +Change the environment variables from the Table below, in the following file: + +``` +cd /opt/onav//config +nano autonomy.env +``` + +| Environment Variable | Description | Default | +|-----------------------------|----------------------------------------|---------| +| **FOOTPRINT_OFFSET_POS_X** | Distance from base_link to the furthest edge of any part/sensor at the front of the robot | 0.5 | +| **FOOTPRINT_OFFSET_NEG_X** | Distance from base_link to the furthest edge of any part/sensor at the rear of the robot | -0.5 | +| **FOOTPRINT_OFFSET_POS_Y** | Distance from base_link to the furthest edge of any part/sensor at the left of the robot | 0.35 | +| **FOOTPRINT_OFFSET_NEG_Y** | Distance from base_link to the furthest edge of any part/sensor at the right of the robot | -0.35 | + + +### Start/Stop the OutdoorNav + +To start up the OutdoorNav software run: + + +{` +onav start +`} + + +If you wish to start individual profiles or services, run `onav start -h` to see available profiles/services. + +To stop the OutdoorNav software run: + + +{` +onav stop +`} + + +For more information and available ONAV CLI commands, see the [Terminal Interface](../getting_started/terminal_interface.mdx) section. + +### Test OutdoorNav Installation + +1. Ping all of the network sensors to ensure proper communication with the UGV or secondary computer. + +2. Check the following topics and make sure there is data being published to them: + +``` bash +rostopic echo -n 1 /platform/odom +rostopic echo -n 1 /platform/cmd_vel + +rostopic echo -n 1 /localization/odom + +# GNSS units +rostopic echo /sensors/gps_/fix + +# IMU (if included) +rostopic echo -n 1 /sensors/imu_/data + +# Velodyne/Ouster/LMS1XX/Hokuyo/OutdoorScan (if included) +rostopic echo /sensors/lidar_/pointcloud +rostopic echo /sensors/lidar_/scan + +# Realsense D435 Front (if included) +rostopic echo -n 1 /sensors/stereo_0/pointcloud --noarr +rostopic echo -n 1 /sensors/stereo_0/image --noarr +rostopic echo -n 1 /sensors/stereo_0/depth/image_rect_raw --noarr + +# Realsense D435 Rear (if included) +rostopic echo -n 1 /sensors/stereo_1/pointcloud --noarr +rostopic echo -n 1 /sensors/stereo_1/image --noarr +rostopic echo -n 1 /sensors/stereo_1/depth/image_rect_raw --noarr +``` + + will be the number of the sensor as it was loaded into the software. Eg. If you have a VLP and an LMS1XX, then the VLP will be lidar_0, and the LMS1XX will be lidar_1. If we only have an LMS1XX, then it would be lidar_0. Ie. the 3D lidars have a higher "priority" and therefore will be loaded first. + +:::note + +The 2D LiDARs (LMS1XX, Hokuyo) will not have a pointcloud topic. + +::: + +Once installation is complete, you can proceed to [Getting Started](../getting_started/system_setup.mdx) to start using the software. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json new file mode 100644 index 00000000..663e4088 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Overview", + "position": 4 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx new file mode 100644 index 00000000..b6abe65e --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_hardware_requirements.mdx @@ -0,0 +1,44 @@ +--- +title: Hardware Requirements +sidebar_label: Hardware Requirements +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +OutdoorNav Software works with compatible UGVs, either from Clearpath +Robotics or third parties. High level requirements for compatible UGVs +are outlined below. Detailed qualification requirements are outlined in +[UGV Integration Requirements](../integration_requirements/integration_overview.mdx). + +## Requirements + +OutdoorNav software does not communicate directly with the UGV motors. +Rather, it publishes target linear and angular velocities packaged in +the [ROS Twist message](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +format and relies on the low level velocity controller of the vehicle to +translate these velocities into correct motor control commands. +Therefore, OutdoorNav Software requires that the UGV must accept the +control commands sent in the [ROS Twist message](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) +format. More detailed requirements are outlined in the following table. + +| # | Requirement | Notes | +| - | --------------------------------- | ----------------------------------- | +| 1 | The UGV must be a differential drive or Ackermann drive configuration | Ackerman drive is currently available as a custom implementation; standard in 2023 | +| 2 | The UGV must have velocity control of the wheels and provide kinematic control of the platform | | +| 3 | The UGV shall provide odometry feedback of the wheel direction and velocities and/or steering position | Recommended encoder resolution of 500 ticks per revolution or greater | +| 4 | The UGV should have an emergency stop system with status feedback | | +| 5 | The UGV must accept ROS 1 Twist Commands on the `/cmd_vel` topic | See [API Endpoints](../api/api_endpoints/api_endpoints.mdx); ROS 2 interface available in future release | +| 6 | The UGV must provide odometry and status feedback through ROS topics | See [API Endpoints](../api/api_endpoints/api_endpoints.mdx) | + +## Typical Hardware + +While a variety of different sensors and equipment can be used with +OutdoorNav Software, the following are used most commonly: + +- Clearpath Robotics UGV: Jackal, Husky or Warthog +- GPS System: Dual DURO RTK system or NovAtel Terrastar +- IMU: Microstrain 3DM-GX5-25 +- 3D Laser Sensor: Velodyne VLP-16 +- Tablet Computer: Getac F110 +- Clearpath Long Range Network Station with RTK corrections ("Base Station") diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx new file mode 100644 index 00000000..83bfa1d6 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_introduction.mdx @@ -0,0 +1,93 @@ +--- +title: Introduction +sidebar_label: Introduction +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Summary + +OutdoorNav Software is a software package developed by Clearpath +Robotics for autonomous and manual navigation of Unmanned Ground +Vehicles (UGVs) in outdoor environments. + +
+
+ +
Web UI Mission Planning View
+
+
+ +
+
+ +
Web UI Front Camera View
+
+
+ +## Compatible Platforms + +While it has been optimized for use with OutdoorNav Hardware from +Clearpath Robotics +([Husky](https://clearpathrobotics.com/husky-unmanned-ground-vehicle-robot/), +[Jackal](https://clearpathrobotics.com/jackal-small-unmanned-ground-vehicle/), +and +[Warthog](https://clearpathrobotics.com/warthog-unmanned-ground-vehicle-robot/)), +it has been designed so that it can be added easily to third-party UGVs. + +
+
+ +
Clearpath Robotics Warthog UGV with navigation equipment and operator control unit
+
+
+ +## Key Features + +Key features of OutdoorNav Software include: + +- Mission Planning and Autonomous Navigation + + - Robust GPS-based localization with sensor fusion of IMU, LiDAR + and platform odometry + - Autonomous path following via waypoints + - Obstacle Detection and Avoidance: Stop and wait or + autonomously plan a collision-free path around obstacles + without the need to stop + +- Teleoperation + + - Operate the robot remotely using an on-screen or physical + joystick + - Visualize what the robot sees by displaying its network + cameras and LiDAR data + +- Web User Interface (Web UI) + + - Build missions containing sets of paths, with optional task + execution on each path; tasks can be standard tasks (eg. save + camera image) or user provided functions + - View the robot's live position and attitude on the map + - Display robot data such as velocity, signal strength, status + of the motion stop, status of navigation system, and battery charge + - Save and export Missions + +- Application Programming Interface (API) + + - Build your own application and UI by accessing the navigation + API to control the UGV through software or implement fleet + management by accessing the mission API + +- Simulation + + - Begin development of your application prior to purchasing + licenses or commissioning hardware with OutdoorNav software and + the ROS Gazebo simulator + +- Third Party Integration + + - The Web UI and API can be accessed through a network connection; + cloud-based services are available from third parties to + facilitate remote connections and networking to robot hardware + such as Formant.io and Freedom Robotics diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx new file mode 100644 index 00000000..c02228aa --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_operating_conditions.mdx @@ -0,0 +1,177 @@ +--- +title: Operating Conditions +sidebar_label: Operating Conditions +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +OutdoorNav Software is designed and tested for use in rugged outdoor +environments. + +## Operating Conditions + +### Terrain + +OutdoorNav Software is compatible with terrains in which the UGV can be +driven manually without excessive slipping. The performance limits will +be a function of the base UGV traction. + +Using Clearpath Robotics Husky, Jackal, and Warthog as a the base UGV, +OutdoorNav Software is suitable for use in the following terrains: + +- asphalt +- concrete +- grass +- snow + +:::note + +Grass should not exceed 30 cm in height if collision avoidance is +enabled. + +::: + +:::note + +Winter/studded tires may be required for proper traction on snow. + +::: + +OutdoorNav Software is currently **not** suitable in the following +terrains: + +- ice +- loose gravel + +:::note + +Support for loose gravel environments is currently being tested and is +expected to be available in late 2023. + +::: + +The terrain capabilities of third-party UGVs will be dependent on a +variety of factors including the vehicle mass, the tire treading, and +motor power. + +### Environment + +OutdoorNav Software is suitable for use in the following environmental +conditions: + +- light rainfall (drizzle) +- light snowfall (powdery snow) + +:::note + +If erratic behavior, such as frequent replanning, is perceived in these +light precipitation conditions, disabling the "continuous planning" +feature may help. + +::: + +OutdoorNav Software is **not** suitable for use in the following +environmental conditions: + +- heavy rainfall +- heavy snowfall + +:::note + +If navigation is required in heavy rain or snow, disabling the collision +avoidance feature will allow the UGV to navigate properly. This should +be done with caution. + +![](/img/outdoornav_images/gps_danger.png) + +::: + +## Performance + +The performance of the system is highly dependent on both the base UGV, +the sensors, the system integration details, and the environment. The +following table provides typical performance metrics for Clearpath +Robotics Jackal and Husky UGVs. + +_System Performance for Husky/Jackal with Typical Sensors_ + +| | Starter Sensor Kit | Standard Sensor Kit (No RTK) | Standard Sensor Kit (RTK) | +|----------------------------------------|-----------------------------------|----------------------------------|----------------------------------| +| GPS sensors | UBlox F9P | 2x SwiftNav Duro | 2x SwiftNav Duro | +| Location accuracy (position & heading) | Less than 60 cm
Less than 10° | Less than 30 cm
Less than 5° | Less than 5 cm
Less than 2° | +| Path tracking accuracy (approximate) | 20 cm | 15 cm | 10 cm | + +## Limitations + +While OutdoorNav Software operates effectively in a range of rugged +outdoor environments, the operator should be aware of the following +limitations and plan accordingly. + +_OutdoorNav System Limitations_ + +| Limitation | Details | +|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| RTK accuracy | Localization accuracy for the Standard (RTK) configuration assumes the base station location has been accurately surveyed. | +| Localization accuracy | Localization accuracy is influenced by the quality of GNSS data that is available. Navigating in GNSS denied areas (e.g., under bridges, near tall buildings, etc.) will cause degradation in localization performance. | +| Negative obstacle detection not present | Outdoor Navigation Software does not have negative obstacle detection capability. Your UGV will not detect stairs, cliffs, potholes, depressions or edges and may drive into these obstacles causing harm to people or property. | +| Limited obstacle detection in vertical dimension | The small vertical field of view of 3D LiDARs limits the vertical obstacle detection capability of the OutdoorNav Software. See [Obstacle Detection Limitations](#obstacle-detection-limitations) for details. | +| Low traction may cause UGV to get stuck | Your UGV may navigate itself into a situation where wheels slip or do not make contact with the ground. | +| Rain and snow may affect obstacle detection | Adverse weather conditions may obscure obstacle detection and avoidance data from the VLP-16 LiDAR. Obstacle detection and avoidance may not function in all weather conditions and must be disabled to navigate in heavy snow or rain. | +| Maximum distance between two Viapoints | Distance between any two consecutive Viapoints of a Mission should be less than 20 meters. This will ensure that the global planner can find a valid path to the next Viapoint for the UGV in case there is an obstacle on the path of the UGV. | +| WiFi range limits | The current configurations of the OutdoorNav Software will continue navigation if the WiFi disconnects or goes out of range. The Web UI will reconnect once the WiFi has reconnected but certain functions of the UI may be limited such as the ability to issue a pause/stop commands or sending new missions to the UGV. | +| Wireless motion stop range limits | The UGV will motion stop if the UGV is driven out of range of the wireless motion stop device. | +| RTK GPS limited by WiFi range | If WiFi goes out of range, your UGV will not receive RTK corrections from the Base Station. This can potentially decrease the accuracy of the GPS signal which can subsequently degrade path following performance of your system. | +| Obstacle detection may cause UGV to become stuck | The UGV may stop and become stuck if obstacles are detected and not cleared from its path. If obstacle avoidance is enabled, it may not be able to calculate an acceptable path to the next Viapoint or Goal Point under all circumstances. This will result in the UGV becoming stuck and failing its Mission. | +| Failure to set Datum causes undefined behavior | If the Datum is not set or is not synchronized with the navigation module, the UGV's driven path is undefined and will move unpredictably if Missions are sent in this state. | +| Zones are not currently supported | It is not possible to define “keep-out” or “unsafe” zones that the UGV needs to avoid. Rather, careful use of Waypoint placement by the operator can be used to keep the UGV at a safe distance from unsafe zones. | +| No collision avoidance during teleoperation mode | When operating in Manual Mode (Teleoperation), no collision avoidance is enabled. The operator is responsible for avoiding collisions. | + +### Obstacle Detection Limitations {#obstacle-detection-limitations} + +The maximum collision avoidance range for the OutdoorNav Software is +UGV-dependent and is related to the maximum speed of the UGV. These +ranges for Clearpath Robotics UGVs are: + +- Jackal UGV: 4.5 meters +- Husky UGV: 4.5 meters +- Warthog UGV: 15.0 meters + +While the sensors are able to detect objects at further distances, the +OutdoorNav Software only considers obstacles detected within these +distances for collision avoidance. That is, the UGV will only begin to +decelerate as it detects obstacles within this range. + +The detection itself is also related to the horizontal size +(width/diameter) of the obstacle. The limitations in detecting objects +with small horizontal size are described in the table below. + +_Maximum Reliable Obstacle Detection Distance from UGV, according to Obstacle Horizontal Size_ + +| Object Size (Horizontal) | Starter Sensor Kit | Standard Sensor Kit | +|--------------------------|----------------------------------------------------------------|----------------------------------------------------------------| +| Less than 0.6 cm | No reliable detection | No reliable detection | +| 0.6 to 1.0 cm | 0.8 m | No reliable detection | +| 1.0 to 3.0 cm | 2.0 m | 1.75 m | +| Greater than 3.0 cm | Maximum collision avoidance distance (UGV-specific; see above) | Maximum collision avoidance distance (UGV-specific; see above) | + +Finally, the OutdoorNav Software bounds the obstacle detection to +prevent ground hits and to remove detections above the UGV body. The +following bounds are relative to the ground, assuming a flat surface. +Obstacles that are entirely below the lower bound or entirely above the +upper bound are not considered obstacles and will not be avoided. + +_Obstacle Detection Vertical Bounds_ + +| Vertical Bound | Jackal UGV | Husky UGV | Warthog UGV | +|-----------------------|------------|-----------|-------------| +| Lower Detection Bound | 0.3 m | 0.3 m | 0.3 m | +| Upper Detection Bound | 0.8 m | 1.3 m | 1.8 m | + +:::note + +The vertical detection bounds above are for the Standard Sensor Kit or a +custom sensor configuration that includes a Velodyne. The vertical +detection bounds for the Starter Sensor Kit have yet to be determined. + +::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx new file mode 100644 index 00000000..13f8b9af --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/overview/overview_scope.mdx @@ -0,0 +1,15 @@ +--- +title: Scope +sidebar_label: Scope +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +This documentation focuses on the OutdoorNav Software itself, including +hardware dependencies and integration, but not the specifics of UGV +hardware. For details on compatible Clearpath Robotics UGVs and custom +hardware integrations, contact or check +out our [YouTube channel](https://www.youtube.com/channel/UCNPP3C-ZK3mwpG2x89VE-2Q). + + diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx new file mode 100644 index 00000000..18d52693 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/release_notes.mdx @@ -0,0 +1,310 @@ +--- +title: Release Notes +sidebar_label: Release Notes +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## 0.12.0 + +### New Features +- Modified mission planning modes. Now includes: + - Map mode (which allows the user to create maps of an environment + and send mission using said map) + - Waypoint mode (which allows the user to create more direct mission + by placing waypoints directly on the Aerial overlay) +- Added an Assisted teleoperation feature to prevent robot collisions with + obstacles when it is being teleoperated. +- Added the upgrade command to the CLI tool. Customers can now upgrade their + software as long as they are eligible to be upgraded to the newest version. + Please contact [Support](./support.mdx) for more information. +- New visualization of status command in CLI tool +- Added a filebrowser extension to access/view the robot filesystem for easier + media access + +### API Features + +- Added new message definitions and service calls for the storage/editing of Maps + +### Bug Fixes + +- 1973: Fixed python “machineid” error during installation +- 2089: Fixed the no serial number on /platform/id topic +- 2169: Fixed the mission manager/scheduler still requesting during Teleop only mode + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect +- 2332: upgrading from 0.11 to 0.12.0 in teleoperation only configuration and Q62 + installed causes duplication of axis driver. Please contact [Support](./support.mdx) + if you run into this issue. +- 2344: Autonomy not going down during low-power mode +- 2360: Waypoint/Map modes use different mouse click to open context menus + +## 0.11.0 + +### New Features + +- Command Line Tool used to install/update/manage OutdoorNav +- Added the End User License Agreement to the UI upon start up +- Light and PTZ Pan/Tilt controls can now be mapped to a controller +- OutdoorNav/IndoorNav switch over improvements +- Can now place waypoints at UGV location via shortcut key (Shift + X) + +### API Features + +- Can now delete multiple mission objects (missions, waypoints, tasks) in single call +- Stack Light can now be manually overridden/muted +- Added ability to import single missions to the robot + +### Bug Fixes + +- 1688: Move PTZ task only ever uses the first PTZ camera's positions +- 2011: Filter false "Move PTZ Failure" notifications when moving PTZ camera + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.10.0 + +### New Features + +- Added the ability to start mission from a specific Waypoint +- Added the ability to resume mission from current location +- Added the option to include on-start and on-stop tasks to a Mission +- Added the option to continue a Mission if a Task should fail +- Full release of the API examples repository to the public (link API examples top level page) + +### API Features + +- Action definition changes (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx)) + - Mission.action added from_start and *start_waypoint_uuid* fields + - ExecuteMissionByUuid.action: added from_start and *start_waypoint_uuid* fields +- Message Definition changes + - Mission.msg: added an array of on_start and and array of on_stop tasks fields + - Task.msg: added a boolean allow_failure field +- Updated /safety/safety_stop message type (see [Definitions](./api/api_endpoints/definitions.mdx#msg-safety)) +- Added import/export services for /dock, /mission_manager/ and /mission_scheduler features + +### Bug Fixes + +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location +- 1764: Importing missions with docking tasks fails to bring in docks + +### Known Issues + +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint +- 1844: [MPC] Maximum acceleration param doesn't appear to have any effect + +## 0.9.0 + +### New Features + +- Operators can now Schedule Missions to run at specific times (see [Mission Scheduler](./features/mission_scheduler.mdx)) +- Added in support for BulletCat12 Microhard WiFi and Cellular connections +- Allow Audio recording as both tasks and manual operations if UGV has Microphones +- Create custom tasks that can be run during missions (see [Custom Tasks](./features/custom_tasks.mdx)) +- If installed with PDU, UGV can be set to Low Power mode to better conserve power +- New navigation topics added to ROS Autonomy API (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx)): + - /navigation/progress + - /navigation/motion_state + - /navigation/metrics +- Improved precision of docking +- Improved autonomy feedback when something goes wrong in the mission to increase the diagnosability of the error +- Updated Navigation features available to the customer: + - Continuous Replanning renamed to Continuous Planning and is always enabled. + - Constrained Planning is always enabled. Environment Variable to update the path constraint has been modified + (see [Navigation](./features/navigation.mdx)) + - Removed Obstacle Avoidance Mode. The UGV will always attempt to avoid obstacles. + - Removed Path Smoothing. This is always enabled. + - Docking feature added for customers who have purchased a dock. + +### Bug Fixes + +- 1324: Allow single Waypoint missions and/or tasks on first waypoint (required for undocking through tasks). +- 1340: Undocking not working through tasks +- 1607: Fixed MovePTZ task failures + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1396: Robot gets temporarily stuck at start of mission when near a Waypoint. +- 1546: Robot cannot start mission part-way through if a task is assigned on any Waypoint prior to its location. + +## 0.8.0 + +### New Features + +- Inertial Measurement Units (IMUs) integrated into localization. +- Added localization status topic (see [API Endpoints](./api/api_endpoints/autonomy_api.mdx#localizationstatus)). +- Added re-localization service (see [API Endpoints](./api/api_endpoints/definitions.mdx#srv-reset-localization)). +- Additional diagnostic information in the status view. +- Docking improvements including: multiple docks, visual representation of docks on map, + local docking/undocking through teleop view. Docking only functional with 2D LiDARs. +- Customization & Tuning Appendix C added. Lists of tuning parameters for navigation + and collision avoidance are now available. As well as, instructions/process on how to + tune UGVs with differential drive dynamics. Instructions for UGVs with Ackermann dynamics + are on their way. + +### Bug Fixes + +- 1134: Display/Hide Datum Point not working. +- 1139: Issues with non-husky platforms. +- 1137: Refreshing page re-enables edit button while mission running. +- 1276: Feedback added for incorrect first Waypoint placement. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1138: Issues with greying out Waypoints in edge cases. +- 1324: Allow single Waypoint missions and/or tasks on first waypoint (required for undocking through tasks). +- 1340: Undocking not working through tasks. + +## 0.7.0 + +### New Features + +- Goal terminology has been removed from the mission generation nomenclature (see + [Definitions](./web_user_interface/ui_waypoint_mode.mdx#definitions)) + Users can now add tasks, apply final headings, and set navigation tolerances + to any Waypoint in a Mission. +- Drag and Drop of Waypoints now available in Edit Mode. +- New Waypoints can be inserted between existing Waypoints in a Mission. +- Mission API now available to create/edit/load missions, waypoints and tasks. +- Mission execution via mission ID is now available. +- The base station location is now displayed in the UI after carrying out an automated survey. +- New coloring scheme for GNSS status icons to provide more accurate information. + +### Bug Fixes + +- 996: Axis camera missing ptz_state + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 1134: Display/Hide Datum point not working. +- 1137: Refreshing page re-enables edit button while mission running. +- 1138: Issues with greying out Waypoints in edge cases. + +## 0.6.0 + +### New Features + +- OutdoorNav ROS API updated. API now divided into Platform and + Autonomy sections. See [API Overview](./api/api_overview.mdx) + for more details. +- Simulation environment created with charge dock, base station and + camera plugins. +- Added deviation path visualization to UI when constrained replanning + is enabled. +- Modified goalpoint icons to reflect tasks assigned to them. +- Added the ability to record rosbags from UI. +- Added GPS signal strength to status page. +- Added improvements to PTZ controls (cosmetic changes, ability to + disable zoom, added a reset mark). +- User can set map source from OpenStreet, MapBox, Bing Maps, or + custom map tiles through UI. + +### Bug Fixes + +- 632: Prevent users from changing mission while a mission is running. +- 661: Removed map view when no map is provided in default-state.json. + file. +- 712: Fixed front end hanging when user opens menu from any view + other than main view. +- 716: Removed connecting lines from disabled goals. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. +- 751: Wireless icon in UI doesn't work for Ubiquity hardware. +- 756: Waypoints stop turning grey when they are hit if a waypoint is + skipped. + +## 0.5.0 + +### New Features + +- Sensor Kit Options: Starter, Standard, Backpack. +- New localization module. +- Added support for UBlox F9K and F9P GNSS receivers in the + localization module. +- Added support for either single or dual Swiftnav Duro/Piksi GNSS + receiver(s) in the localization module. +- Added support for Realsense D435 camera in collision avoidance + module. +- New/updated user modifiable environment variables for sensor and + navigation tuning. +- Added a Virtual Guided tour of the application for first time users. +- Added StreetView and Bing map tiles (to existing MapBox tile). +- Allow users to specify custom map tile source. +- Added cosmetic changes to traversed waypoints as well as a robot. + status icon with ROS topic health information. + +### Bug Fixes + +- 253: Replace default camera image for camera views when stream is + unavailable. +- 281: Fixed navigation latched in a PAUSE state. +- 574: Fixed map settings page to not rerender when robots position + changes. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 609: Realsense D435 collision avoidance not fully tuned. + +## 0.4.0 + +### New Features + +- Improved wireless charger docking workflow and added ROS Noetic + docking support. +- Added option to record videos from cameras. +- Improved Docker setup to allow concurrent installation with + IndoorNav. +- Added initial support for integration with + [Formant](https://formant.io/). +- Added Docker installation support for Jackal and Warthog robots. + +### Bug Fixes + +- 480: Added rate limiter for continuous planner. +- 490: Fixed base station survey pop up to better reflect survey time. + +### Known Issues + +- 131: Software upgrade process not documented fully. + +## 0.3.0 + +### New Features + +- Upgraded from ROS Melodic to ROS Noetic. +- Published initial performance metrics. +- Updated system architecture to work in Docker containers. + +### Bug Fixes + +- 266: Allowed map offsets to be set more than once without needing to + reset them back to zero. +- 365: Updated costmap to handle large stop distances properly. +- 377: Fixed handling of goal tolerances of 0.02m or less. +- 389: Fixed issue with goal being skipped in some cases where final + heading was specified. + +### Known Issues + +- 131: Software upgrade process not documented fully. +- 150: Docking not yet implemented in Noetic. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx new file mode 100644 index 00000000..ea70a51b --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/safety.mdx @@ -0,0 +1,144 @@ +--- +title: Safety +sidebar_label: Safety +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +## Important Safety Information + +The use of Unmanned Ground Vehicles (UGVs) can result in unexpected and +dangerous behavior. Although Clearpath Robotics endeavors to create safe +and reliable software and systems, autonomous outdoor UGVs should not be +considered safe for unsupervised use around humans or other obstacles. +No level of safety and reliability of software and non-safety rated +hardware components is guaranteed. + +Clearpath strongly recommends that users carry out a risk assessment +related to their application and deployment of autonomous UGVs. The +ISO-12100 standard [Risk assessment and risk reduction](https://www.iso.org/standard/51528.html) provides guidance on +performing risk assessments. + +Functional safety in robotics is often achieved through the use of +safety related parts and control systems to minimize risks such as +safety LiDARs for obstacle detection. These hardware components must be +designed into the UGV hardware and can be tightly integrated with +navigation software. Clearpath Robotics recommends that this process be +undertaken after the product or process has been fully defined. It can +be a significant design effort. + +## Safety Notice Levels + +For Clearpath Robotics hardware and software, the risk level is captured +using the following types of labels. + +![](/img/outdoornav_images/safety_information.png) + +## General Hazard Labels + +Review the following to learn more about the labels that may be used on +Clearpath Robotics products. Hazards can also apply to attachments and +accessories used in conjunction with a Clearpath Robotics product. UGVs +from other providers may present additional hazards and risks. + +_General Hazards_ + +| Label | Label Title | Label Description | +|--------------------------------------------------------------------------------------|----------------------|------------------------------------------| +|
| Automatic Motion Hazard | Clearpath Robotics UGVs may begin moving suddenly, either autonomously or when being driven manually. Always be aware of Clearpath Robotics products and their potential for movement. | +|
| Crushing Risk | Objects or personnel can be crushed between the Clearpath Robotics UGV and another object. Keep hands and other objects clear of crush points at all times. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Electrical Shock Risk | Clearpath Robotics UGVs contain circuitry and batteries that may cause electrical shock if not properly insulated. | +|
| Entanglement Risk | Clearpath Robotics UGVs as well as their cameras can lead to entanglement of hair or dangling materials during their rotation. Keep hair and dangling materials away from Clearpath Robotics UGVs during motion. | +|
| Environmental Hazard | Clearpath Robotics UGVs contain batteries and materials that may require special disposal methods. Consult local regulations. | +|
| Falling Object Risk | Beware of objects that may have shifted in any Clearpath Robotics UGV crate as they pose a risk of falling when opened. | +|
| High Surface Temperature Risk | UGV computer heat sinks and UGV motors can become extremely hot during operation. | +|
| Impact Risk | Clearpath Robotics UGVs travelling through a facility can potentially impact objects and personnel. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Laser Radiation Risk | Clearpath Robotics UGVs may use Class 1 laser products. These provide no hazard during normal use, however it is not recommended to stare directly into the beam(s). | +|
| Material Hazard - Lithium | Lithium UGV batteries contain harmful material. Always use proper handling procedures when handling UGV batteries. | +|
| Manual Load Lifting Risk | Always use ergonomic techniques when manually lifting loads. | +|
| Pinching Risk | Keep hands and other objects clear of pinch points at all times. Keep clear of all docking Clearpath Robotics UGVs. | +|
| Radio Frequency Risk | Clearpath Robotics UGVs and/or accessories may use radio frequency (RF) radiating antennas. These provide no hazard during normal use, however prolonged exposure around the antenna is not recommended. | +|
| Tripping Hazard | Clearpath Robotics products may pose a tripping hazard. | + +## Safety Awareness + +Personnel present during the operation of an Unmanned Ground Vehicle +(UGV) need to be made aware or be accompanied by personnel who are +familiar with the specific risks and hazards associated with autonomous +mobile robots (AMR). The following checklist identifies basic topics +that should be addressed by site-specific worker and visitor safety +orientation training. + +
+ +
+ +- Proper PPE must be worn, including safety footwear (ie. steel toe). +- Crossing into the path of a moving UGV should be avoided, as well as + placing or throwing obstacles into the path of a moving UGV. + +
+ +
+ +- Be aware that a UGV can be anywhere in the operating area of the + facility at any time, and may pose a tripping hazard even when not + in motion. +- Personnel need to be aware of the UGV docking and charging areas, + where detection fields are reduced. +- Personnel should be aware that Clearpath Robotics UGVs LiDAR safety + scanners use a class 1 laser and high intensity LED. +- Personnel should keep all loose clothing and body parts away from + UGVs, accessories, attachments, and payloads, while they are in + autonomous operation. Using an Emergency Stop button is the only + acceptable manner of interacting with a Clearpath Robotics UGV or + attachment while it is being operated autonomously. + +In addition to the preceding basic items for all workers and visitors, +the following should be considered for facility personnel, including +drivers of other UGVs: + +- When required to move a product manually, personnel must ensure it + is in an Emergency Stop state or shut down completely and should not + push manually for prolonged periods. +- Alert personnel that while operating a Clearpath Robotics UGV + outside of the Autonomy State, they are solely responsible for + obstacle and collision avoidance. +- Maintenance of a Clearpath UGV not outlined in either this document + or the operations and maintenance manual can only be performed by a + Clearpath Robotics Authorized Personnel. + +To reduce the risk of harming people or damaging properties, a trained +operator must monitor the behavior of the UGV under autonomous +navigation mode at all times. The operator should use the wireless +emergency stop device to immediately avert any possible damaging or +dangerous behavior from the UGV. Failure in proper use of the software +might result in collision of the UGV into objects. + +- The minimum height for detecting obstacles under ideal operation + conditions (flat ground, no snow/rain/fog, normal operation of the + LiDAR, etc) when using the standard Clearpath Robotics OutdoorNav + Hardware package on a Husky is typically 0.2 meters high at 2.3 + meters distance away from the UGV. Your UGV may differ. Ensure that + low-height obstacles are removed from the potential path of the UGV + prior to operation. +- OutdoorNav Software does not have negative obstacle detection + capability. This means that your UGV will not detect stairs, cliffs + or edges and may drive off these obstacles causing harm to people or + properties as well as potentially damage the UGV. +- Adverse weather conditions may obscure obstacle detection and + avoidance data from the VLP-16 LiDAR. Obstacle detection and + avoidance may not function properly in snow, rain or fog. +- The current configurations of the OutdoorNav Software will continue + navigation if the WiFi disconnects or goes out of range. The Web UI + will reconnect once the WiFi has reconnected but certain functions + of the Web UI may be limited such as the ability to issue a stop + command or send new missions to the UGV. +- If connection of the UGV to the base station is lost (e.g., WiFi + goes out of range, low battery level, etc), UGV will not receive RTK + corrections from the base station. This can potentially decrease the + accuracy of the GPS signal which can subsequently degrade path + following performance of your system. +- Obstacle detection and avoidance is disabled during the docking and + undocking operations. Keep this area clear of people and objects. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx new file mode 100644 index 00000000..44cff5f7 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/simulation.mdx @@ -0,0 +1,20 @@ +--- +title: Simulation +sidebar_label: Simulation +sidebar_position: 9 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +Simulation with OutdoorNav Software can be useful in several ways. + +- It provides an easy (and low cost!) way of evaluating the main + features in OutdoorNav Software prior to purchasing. +- It allows missions to be planned, executed, and refined in a + repeatable way prior to deployment on UGV hardware. This can be + particularly helpful when integrating OutdoorNav into a larger + software solution, such as a fleet manager. + +At present, OutdoorNav Software simulation is restricted to internal +Clearpath Robotics development and select partners, but is planned for +full deployment. Check back soon for further details. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx new file mode 100644 index 00000000..9212d99f --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/support.mdx @@ -0,0 +1,11 @@ +--- +title: Support +sidebar_label: Support +sidebar_position: 11 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +import OutdoorNavSupport from "/components/support_outdoornav.mdx"; + + \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json new file mode 100644 index 00000000..a07ca158 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Web User Interface", + "position": 6 +} diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx new file mode 100644 index 00000000..1447f480 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_manual_mode.mdx @@ -0,0 +1,55 @@ +--- +title: Web UI Manual Mode (Teleoperation) +sidebar_label: Web UI Manual Mode (Teleoperation) +sidebar_position: 2 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Manual Mode in the Web UI allows the user to operate the UGV +remotely (teleoperate) by using sensors on the UGV to visualize the +environment and by using a joystick to control the motion of the UGV. + +![](/img/outdoornav_images/teleop_danger.png) + +Ensure that you have read [Safety](../safety.mdx) and are +aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +
+
+ +
Teleoperation Components
+
+
+ +1. **Error/Warning Bar:** A bar along the top of the page reporting + the error or warning status of the Assisted Teleoperation feature. +2. **Joystick:** The joystick will allow the user to move the UGV + manually from the UI. Motion can be sent to the UGV in 360° + directions and the speed can be controlled by the distance of the + joystick from its neutral position. Four fixed direction buttons are + now present to move the UGV in purely forward/reverse directions or + clockwise/counter-clockwise. Finally, we overlay an obstacle map + on top of the joystick, representing obstacle distances from the + UGV. +3. **Speedometer:** An indicator of the UGV's current linear speed. +4. **Sensitivity Scale:** A UGV-specific scale that controls the + maximum allowable UGV velocities at each level. The default maximum + linear velocity is 1.0 meters per second and the maximum angular + velocity is 0.5 radians per second. These can be changed in the + [General Settings](./ui_overview.mdx#config-general-settings) page. + The scale levels are 100%, 80%, 50% and 20%, with the default set + to 80%. +5. **Teleop Assist Toggle:** The "Teleop Assist" toggle can be used to + enable/disable the Assisted Teleoperation feature. + +## Monitor Wireless Strength + +While teleoperating the UGV, the user will notice that the delay between +the time a command is sent and the time it is executed (and/or visible +on the UI camera views) will increase as the distance increases. This +effect will be further amplified by any obstacles between the UGV and +the base (eg. walls, vehicles, mounds, etc.). It is important to monitor +this delay an be cautious when driving the UGV with larger delay for +risk of crashing into obstacles. \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_map_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_map_mode.mdx new file mode 100644 index 00000000..b579ef50 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_map_mode.mdx @@ -0,0 +1,377 @@ +--- +title: Web UI Map Mode +sidebar_label: Web UI Map Mode +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +![](/img/outdoornav_images/gps_danger.png) + +Ensure that the [Safety](../safety.mdx) document has been +read and the Operator is aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +The Map Mode of OutdoorNav Software uses a set of robotic +navigation modules that allows the Operator(s) to define driveable paths and +then execute missions using these maps. The UGV leverages these paths +along with specified goal points to calculate a route. Operators can +define one-way or two-way paths, speed limits for paths, allowable +deviation distances from the paths and cost factors for each path. + +## Definitions {#definitions} + +The list below defines what a "Map" and "Mission" are in relation to the Map mode view. The list also includes +their relevant components. These terms are referred to throughout this page. + +- **Mission** A Mission is a set of one or more Goalpoints. +- **Map** A Operator created map that goes over the aerial view and is used to define valid driveable + areas for a mission. +- **Point** A map point used to help define a path. +- **Path** A connection between two points that the UGV can travel along for missions. Can be defined as + one way or two way. +- **Goalpoint** A Goalpoint is a mission relevant geographical point referenced by its + position relative to the datum in meters. These points are travelled to as part of the Mission. +- **Task** A Task is an automated activity or wait time implemented as + a ROS action at a specific event or Goalpoint. +- **GoToPoint** A Goalpoint that is independant of a mission. This point is meant to be a one off + position to send the UGV to. +- **Ghost point** A transparent point that is not part of the map. This + point appears between two other points when in map edit mode. The Operator can + drag and drop this ghost point to split a path. The newly created paths will + keep the same properties as the path that was split (speed limit, cost factor, etc. ) + +## Map Mode Bottom Bar + +
+
+ +
Map Mode Bottom Bar
+
+
+ +1. **Map List:** Contains the list of Maps that Operator(s) have + created. The system also performs a health check of the map + to ensure that the UGV can't get into a stuck state. This is + shown with various icons by the map's name. + + - Valid Map: Every path is + reachable within the map and the UGV should not become trapped. + + - Disconnected Points: + The map contains points that will trap the UGV if it navigates to it. The best example of these are one-way paths that + lead to dead ends. + + - Disconnected Maps: + There are groups of paths that are not connected and are treated as separate maps. This may be desired by the Operator but + it can lead to situations where the UGV has sections that aren't navigable. + +2. **Edit Map Toggle:** This toggle allows the Operator to start + creating Points and Paths for the current Map. The Operator will also be able to + drag and drop Points in this mode. Once this button is enabled, + the Path Type Button and Point Drop Button will be visible and useable. + + :::note + + If the toggle is enabled while an autonomous Mission is running, it + will cancel the current Mission. + + ::: + +3. **Map Panel Toggle:** View/Edit details of the current Map including number or points, paths, and default settings. + +4. **Path Type Button:** The Path connection button that is used to set the type of path being connected between + points (one-way/two-way). When in connection mode the button will be highlighted. + +5. **Point Drop Button:** Drops a point at the UGV's current location. This action can also be accomplished by pressing Shift + P. + +6. **Mission List** Contains the list of Missions that Operator(s) have created. + +7. **Edit Mission Toggle** This toggle allows the Operator to start creating Goalpoints and editing currently existing Goalpoints. Once this button + is enabled the Goalpoint Drop button will become visible and useable. + + :::note + + Only one mode at a time can be enabled. If Edit Mission is toggled the Edit Map Toggle will be set to false. + + ::: + +8. **Mission Panel Toggle:** View/Edit details of the current Mission including a list of the Goalpoints, Mission tasks, and Return to dock functionality. + +9. **Goalpoint Drop Button:** The Goalpoint indicator marker on the + bottom bar allows the Operator to place a Goalpoint at the location of the UGV. + This action can also be triggered by using the shortcut key combination Shift + X. + +## Map Creation {#mapCreation} + +Before creating a mission the Operator will need to first create a map that the UGV can use +to generate paths. First ensure that the UI is in "Map Edit Mode" (select the pencil icon in the bottom bar next to +the map selection drop down). Open the drop down menu and select the "Add Map" option. From here the Operator can create +a new map from scratch, clone the current map that is open or import a previously exported map. Once created the Operator can +start placing points and building paths. + +### Map Points + +To add points to the map, ensure that the UI is still in "Map Edit Mode" and click on the map. This will +add a point to the map and also trigger the "Connection Mode". The path type button (one-way/two-way) will +turn blue to indicate that the next point that is added will be connected to the previously created point. +A Operator may cancel this connection by pressing the ESC key or by clicking the path type button. Points can be +dragged and dropped to adjust their positions. To delete a point, right click the point and select Delete. + +While in edit mode, Ghost points will appear in the center of each path that can be dragged and dropped to split the +path. + +### Map Paths + +Paths are generally added as part of the Point placement process as mentioned above. However, there may be +cases where a Operator would like to connect existing points. To accomplish this, simply exit out of connection mode +then click on the existing points. Once the first point is clicked on, connection mode will be re-established with +the previously clicked point as the starting location. + +As paths are added they will be visible in the Map properties table, along with their relevant details. To edit a +path's details a Operator can simply right click on the path or select the gear icon for the specific path in the table. +This will open an overlay on the map that will allow the Operator to edit both one-way paths and two-way paths. In the +case of two-way paths users can keep both ways in sync with each other or vary the properties depending on the +direction. + +
+
+ +
Editing a two-way path that's in sync
+
+
+ +### Map Panel + +
+
+ +
Map Panel
+
+
+ +Enable the "Map Panel" toggle to open the details of the current map. This table will +show the maps current default settings, the "Network Path Recorder" and the general +map details. The Operator can modify the maps name, default path properties and edit path's through this +view. + +### Rename Map + +To rename the Map click the Map name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Map Defaults + +When adding paths the map uses defined default values to set the maximum driving radius +and speed limit. If a Operator wishes to adjust these defaults this can be done here. This will +only affect paths created after the changes have been made. + +### Network Path Recorder + +An Operator can start a path recorder to place map points based on the UGV's position as it drives. +As the UGV drives a preview path will be generated to show generally where the path will be placed. +The Operator can then choose to save the path which will generate the relevant points and paths or cancel +the recording which will remove the preview. + +### Map Details + +The general map details includes the total number of points as well as a table that highlights each +path within the map. Operators can delete paths or edit paths through this table as needed. If a path is +one-way it will show a directional arrow next to it. Two-way paths are shown as a single row unless they +are out of sync regarding their cost factor, speed limit or maximum driving radius. + +## Mission Creation + +To create a new Mission first ensure that the UI is in "Mission Edit Mode" ( +select the rightmost pencil icon in the bottom bar). Then open the drop down menu in the bottom +bar and select the "Add Mission" option. This will allow the Operator to create a new Mission +which can then be defined with Goalpoints. + +### Goalpoint Mode + +To add new Goalpoints to a Mission while edit mode is enabled select the +"Goalpoint Mode" button. This will allow the Operator to place Goalpoints at +locations where the Operator clicks on the map. These will appear as a circle +with an arrow pointing in the direction the UGV will face upon arriving +at the Goalpoint. The arrow can be rotated by holding the CTRL key and dragging +the Goalpoint to the new direction. It can also be modified through the Mission Panel's Goalpoint Advanced Settings. +When not holding the CTRL key the Goal point can be dragged and dropped +to new locations in the same way as map Points. + +### Preview Path + +
+
+ +
Mission Path Preview
+
+
+ +As Goalpoints are placed on the map the system will generate a path preview based on the UGV's +location and the order the Goalpoints are placed in. This can be used to help determine the +general route the UGV will attempt to take. + +:::note + +** In order for the UGV to reach the Goalpoint it must be on a reachable path. The preview path will look like a segmented red line for any points that +the UGV cannot reach.** + +::: + +### Goalpoint Panel + +
+
+ +
Goalpoint Panel
+
+
+ +Enable the "Goalpoint Panel" toggle to open the list of available Goalpoints +within the selected Mission as shown in the figure above. The Operator can +now rearrange the list, add Tasks to the Goalpoints, and modify the final heading +and/or tolerance of each Goalpoint. The Operator can also modify mission properties such +as the mission name, a return to dock threshold, and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Return to Dock + +A Operator may wish to add a flag to the mission to indicate when and if the UGV should +return to the dock while executing the mission. When enabled, the Operator can input a +battery percentage that once reached the UGV will begin navigating back to the specified +dock or to the closest dock. They can then set the minimum battery life before the UGV +is expected to resume the mission. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### Rearrange List of Goalpoints + +Goalpoints can be rearranged in order of operation in the list. To do this, +enable the "Goalpoints Panel" toggle to access the list of Goalpoints. Here, the +Operator will be able to drag and drop the Goalpoints to reorder them. + +### Add Tasks to Goalpoint {#add-task} + +
+
+ +
Add Task to Goalpoint
+
+
+ +To add a Task to a Goalpoint: + +1. Click the "+" icon (beside the Gear icon) in the Goalpoint row the Task is + to be added to. + +2. Click the "Add Task" button that has appeared. + +3. Select the Task from the dropdown list. Standard Goalpoint icons will be + decorated accordingly depending on the task selected. Goalpoints in the + table will also have a small icon to indicate if tasks are assigned to the + Goalpoint accordingly. + +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Goalpoint. + If its not checked, the Mission will become cancelled upon the Task's failure. + +5. Click the Gear icon next to the selected Task to modify or add required Task testings. + +### Advanced Settings + +#### Goalpoint Heading + +When creating a Goalpoint, the Operator has the option of setting a final heading +for the Goalpoint. For example, when creating a Goalpoint at an inspection point, +the Operator may want the UGV to navigate and stop facing a certain +direction. In [Goalpoint Panel](#goalpoint-panel), the list of +Goalpoints can be seen and the advanced settings of each Goalpoint can be accessed +by clicking the "Gear" icon. + +To set the Goalpoint's final heading, the Operator will need to check the +"Final Heading Enabled" checkbox and enter the heading value in +degrees. The heading indicator on the top bar can be used to help set +this value. See the figure below showing the advanced settings. + +:::note + +Goalpoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
Goalpoint Advanced Settings
+
+
+ +This heading is the same heading that is applied to the Goalpoint icon's arrow direction. + +#### Goalpoint Tolerance + +When creating a Mission, the Operator has the option of setting a specific +tolerance for each Goalpoint. By default, the Goalpoint position and orientation +tolerances are 0.3 meters and 180°, respectively. If a specific Goalpoint +requires that the tolerances be either increased or decreased, these +values can be modified in the advanced settings. For example, if it's +required that the position and/or orientation at a Goalpoint be very accurate, +such as 0.1 meters position and 5° orientation, or looser at 1.0 meter +position, this can be done within these settings. + +In [Goalpoint Panel](#goalpoint-panel), the list of Goalpoints can be +seen and the advanced settings of each Goalpoint can be accessed by clicking +the "Gear" icon. To set the Goalpoint's tolerance, the Operator will need to +check the "Goalpoint Tolerance Enabled" checkbox and enter the position and +orientation values, in meters and degrees, respectively. + +## Mission Execution + +### Start Mission + +In the bottom bar of the UI, the Operator has the ability to start the currently selected Mission by +clicking the "Play" button . + +When a Mission has been started the Play button will turn green. + +### Pause Mission + +At the bottom of the UI, the Operator has the ability to pause the currently +running mission by clicking the "Pause" button . When the +mission has been paused this button will turn yellow. Pausing a mission +allows the Operator to take time to look around with the camera or to +teleoperate the UGV to a nearby location to perform an inspection. For +ease of operation, the Operator must PAUSE the active mission if the Operator +wants to teleoperate the UGV. + +### Cancel Mission/Task + +At the bottom of the UI, the Operator has the ability to stop the currently +running mission or task by clicking the "Stop" button . When the +mission/task has been cancelled this button will turn red. The name of +the mission/task will be shown to be cancelled in the feedback bar. + +### Navigate to GoToPoint + +
+
+ +
GoToPoint with preview path
+
+
+ +When a Map has been created a user can right click on a path or a path's driveable area to place a GoToPoint. This +point will be a single point that will also create a small overlay to allow users to start or cancel the "Go To" +execution. Before starting the execution the GoToPoint can be dragged to any driveable area or rotated using the CTRL +key just like with Goalpoints. diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx new file mode 100644 index 00000000..132e5b41 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_overview.mdx @@ -0,0 +1,623 @@ +--- +title: Web UI Overview +sidebar_label: Web UI Overview +sidebar_position: 1 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +The Web User Interface (Web UI) provides a easy, graphical, means to +control both manual and autonomous operation of your UGV. The following +sections outline: the components and views of the UI, the details of +operating in manual mode, and the details of operating in autonomous +mode. + +## Main Components + +
+
+ +
UI Main Components
+
+
+ +1. **Menu:** A dropdown menu allowing the user to access the Dashboard + (ie. Home), Settings, Status, Scheduler, Help, and File pages. The User + can also run the UI Virtual Tour from this menu. + +2. **Feedback Bar:** The feedback bar will display information + regarding the execution state of the navigation and of any Tasks + being executed. + +3. **Path Progress Meter:** A meter indicating the percentage complete + of a Mission. + +4. **UGV Position:** The UGV's X and Y position in the world frame + relative to the Datum. Can also be shown in Lat/Lon coordinates + +5. **UGV Heading:** The UGV's heading in the world frame. 0 degrees is North, 90 degrees is East, 180 degrees is South and 270 degrees is West. + +6. **Status Indicator:** The status indicator will display information + regarding various UGV status monitors such as the Emergency Stop, + Surveying, etc. When the UGV is fully operational, the indicator + will be green. Operators can click on the status indicator to see more details + pertaining to the current state as well as past messages. + +7. **GPS Status Indicator:** The GPS status indicators will display GPS + signal accuracy for position (POS indicator) and heading (DIR + indicator). Green indicators represent RTK accuracy and are + currently required for accurate autonomous navigation. Yellow and orange + indicators represent SBAS and SPP accuracy respectively and noticeable + oscillations may occur in such cases. Red indicators mean no GPS signal + and autonomous navigation missions should not be started. + +8. **Battery Life Indicator:** The UGV's battery life indicator. + + :::note + + If the indicator is stuck at 50%, that means that your UGV does not + have a supported battery management system and this indicator is not + active. + + ::: + +9. **Wireless Connection Indicator:** The wireless connection indicator + represents the signal strength between the wifi access point + (typically the Base Station) and the UGV. If the system can support + cellular connections a cellular indicator will appear next to the + wifi icon with the currently active connection being highlighted in green. + +10. **Stack Light:** If a Stack Light is configured for the UGV its current status + will show here. + +11. **Views List:** A dropdown list of available views, detailed later + in this section. Some of the available views are Map, Camera and 3D + views, etc. + +12. **Local Docking/Undocking:** The local docking/undocking buttons used + to dock/undock the UGV. The UGV must have it's charging adaptor facing the dock + when performing the local dock action. + +13. **Lights Control:** If the UGV is equipped with software controllable lights they can be + controlled through a simple drop down button as well as relevant hotkeys, + depending on the configuration. + +14. **Record Audio:** If the UGV is equipped with a microphone the user + can start/stop recording manually by clicking this icon. + +15. **Mission Execution Buttons:** These buttons allow users to Start, Pause and Stop an + autonomous mission. + + +By opening the dropdown list "Views", on the right side of the UI, the +Operator can access the following views: + +- Map View +- PTZ Camera View (if available) +- Front/Back Camera View (if available) + +## Map View + +
+
+ +
Map View
+
+
+ +1. **Zoom Buttons:** These buttons allow the user to zoom in/out of the + map levels. +2. **Zoom-to-Fit Button:** This button will zoom the map to where there + is activity (ie. where the datum is set or where features have been + set on the map. +3. **UGV:** The blue arrow represents the UGV. Its location is its + position in the world frame and its orientation is the heading in + the world frame. +4. **Base Station:** The yellow antenna icon is the last known location of + the base station based on the last survey performed. By clicking it the + user will be presented with the base station's coordinates, when it was + surveyed, and how many samples were taken during the survey. +5. **Dock:** If a dock is configured for the UGV it will appear on the map in + this format. When in Waypoint mode the Docks pre-dock radius will appear as + a circle around the dock when in Edit Mission mode. +6. **Datum:** The blue Waypoint marker on the map view represents the + location of the reference point (ie. (x,y)=(0,0)) of the world + coordinate system. The world (ie. map) coordinate system is in the + ENU convention. + +## Camera Views + +:::note + +If PTZ and/or Front/Back camera(s) are included on the UGV, their feeds +can be viewed through the UI and the PTZ can be controlled through the +UI. If not, there will not be any PTZ, Front/Back view(s) in the list of +available views. + +::: + +### Pan-Tilt-Zoom (PTZ) View {#ptz-view} + +
+
+ +
PTZ Camera View
+
+
+ +1. **Tilt Slider:** The left slider can be used to tilt the camera in a + vertical motion, (ie. upwards or downwards motion). By default, the + slider is at its neutral ("zero") position. +2. **Pan Slider:** The bottom slider can be used to pan/rotate the + camera, (ie. rotational motion). By default, the slider is at its + neutral ("zero") position. +3. **Zoom Slider:** The right slider can be used to zoom the camera + feed. By default, the slider is at its neutral ("zero") position. +4. **Save Image:** Depending on the current camera view selected, this + button will save an image to the computer/tablet running the UI. + Images will be saved to the location in which your browser saves + files. +5. **Camera Positions List:** Display the list of available camera + positions that have been saved. These camera positions can be + deleted from this list by clicking the "garbage can" icon beside + the corresponding position. +6. **Save Camera Position:** This button will save the camera position + to be used in the "Move PTZ" task. An example use case would be: + 1. Switch to the PTZ camera view. + 2. Teleoperate the UGV to a location at which the user can inspect + something. + 3. Move the camera sliders to orient the camera such that it is + looking at the inspection point. + 4. Click the "Save Camera Position". + 5. When creating an autonomous mission to this inspection point, + add the "Move PTZ" task to a Waypoint. + 6. Click the settings button beside the task and add the camera + position related to the inspection point. + +### Front and Back Views + +
+
+ +
Front View
+
+
+ +
+
+ +
Back View
+
+
+ +## 3D View + +The 3D view allows the user to visualize the pointcloud data being +acquired by the VLP-16 LiDAR. + +
+
+ +
3D View
+
+
+ +## System Configuration + +### General Settings {#config-general-settings} + +The General settings section can be found in through the upper left hand menu and allows the Operator to modify +general features of the UGV. + +
+
+ +
General Settings Page
+
+
+ +#### Coordinates + +The Operator can change the coordinate space from X/Y relative to the Datum to Latitude/Longitude. + +#### Save Image Location + +The Operator can choose to store images saved manually to the robot directly or to download them onto their computer. This +feature only affects the manual save image option found on each relevant camera view. + +#### Robot Internet Connection Type + +If the UGV is equipped with SIM card and can switch between Cellular and WiFi connections, the Operator can manually trigger this +change through the general settings page. This switchover will take approximately 30 seconds and will require a refresh on the UI. + +#### Show Path Deviation Distance + +When a mission is running the UGV will have a maximum path deviation distance that it shouldn't cross if it needs to replan. If this +toggle is set to true, while in edit mode this buffer is shown over top of the path as the Operator creates/edits the mission. This +toggle does not disable the path deviation distance feature. + +#### Low Power Mode + +If the UGV is equipped with a Low Power Module this toggle allows the user to switch the UGV into a low power state that will drastically +limit functionality but help conserve power. This mode is best used to help better facilitate charging while the UGV is not in use. + +#### Joystick Max Speeds + +The Operator can choose to set the Maximum Linear Speed and the Maximum Angular Speed that the teleoperation will use. These are limited to the +maximum speeds of the UGV itself. + +### Aerial Overlay Settings + +
+
+ +
Aerial Overlay settings
+
+
+ +To access the Aerial Overlay Settings: Menu → Settings → Aerial Overlay: + +1. **Offset:** The map tiles used in this software are not + perfectly aligned with the real world. Therefore, the user may need + to apply an offset to the map so that the UGV's position in the + real world matches its position on the map. +2. **Change Datum:** The datum is represented by a blue marker on the + map and should be set to a location within 10km of the test site. + The user can change this value in the Map Settings page. Enter the + new values and click the "Set Datum" button. + +### Map Source Configuration + +The Web UI ships with access to free +[OpenStreetMap](https://www.openstreetmap.org/) maps. Aerial view +requires access to third-party aerial maps or your own aerial maps. + +The Web UI is pre-configured to work with +[MapBox](https://www.mapbox.com/) and [Bing +Maps](https://www.bingmapsportal.com/) once a suitable map key has been +acquired. Both services offer a free tier that will be sufficient in +almost all cases. + +#### Using OpenStreetMap Maps + +As no key is required to use +[OpenStreetMap](https://www.openstreetmap.org/) maps, the process to +select these maps in the Web UI is simple. + +1. In the Web UI, from the menu, select **Settings→Map** to bring up + the **Map Settings** page. +2. Select **OpenStreetMap** +3. Click **Ok**. + +
+
+ +
Using Map Settings to select OpenStreetMap
+
+
+ +#### Using MapBox Maps + +Using [MapBox](https://www.mapbox.com/) maps requires a key, which can +then be used by the Web UI. The steps to set up MapBox are outlined +below. + +1. Acquire a MapBox key from the [MapBox + website](https://account.mapbox.com/auth/signup/). Review the + license terms and select the appropriate plan. In most cases, the + free tier will be sufficient. +2. Back in the Web UI, from the menu, select **Settings→Map** to bring + up the **Map Settings** page. +3. Select **MapBox**. +4. Copy the MapBox key from Step 1 into the **Map Key** field. +5. Click **Ok**. + +
+
+ +
Using Map Settings to select MapBox
+
+
+ +#### Using Bing Maps + +Using [Bing Maps](https://www.bingmapsportal.com/) requires a key, which +can then be used by the Web UI. The steps to set up Bing Maps are +outlined below. + +1. Acquire a Bing Maps key from the [Bing + website](https://www.microsoft.com/en-us/maps/create-a-bing-maps-key). + Review the license terms and select the appropriate plan. In most + cases, the free tier will be sufficient. +2. Back in the Web UI, from the menu, select **Settings→Map** to bring + up the **Map Settings** page. +3. Select **Bing Maps**. +4. Copy the Bing Maps key from Step 1 into the **Map Key** field. +5. Click **Ok**. + +
+
+ +
Using Map Settings to select Bing Maps
+
+
+ +#### Using Custom Maps {#using_custom_maps} + +Custom Maps allow you to use another set of maps in XYZ format, either +from a third-party map provider or from maps that you have generated on +your own, such as from drone aerial images. Custom maps can be selected +by using the steps below. + +1. Ensure that the maps are accessible on an internal network or on the + Internet by the device that is being used to display the Web UI, + such as a laptop, tablet, or desktop computer. +2. Ensure that the directory structure for the individual tiles is well + defined. See the section below for details on + [Preparing Custom Map Tiles from Drone Aerial Images](#preparing_custom_map_tiles). +3. In the Web UI, from the menu, select **Settings→Map** to bring up + the **Map Settings** page. +4. Select **Custom**. +5. Enter the network path for the maps into the **Custom URL** field. + If hosting the maps on your local computer, this will be similar to + . Note how the + URL is parameterized with `{z}`, `{x}`, and `{-y}` values. This will + need to be adapted to match the directory structure of your map tile + images. +6. Click **Ok**. + +
+
+ +
Using Map Settings to select Custom maps
+
+
+ +#### Preparing Custom Map Tiles from Drone Aerial Images {#preparing_custom_map_tiles} + +In some cases, it is desirable to create your own maps rather than using +third party maps which might be outdated. One way to do this is to use a +drone to capture aerial images and convert those images into map tiles. +While there are many ways to accomplish this, one approach is outlined +below. + +1. Use a drone to collect top-down photos covering the area of + interest. It is highly recommended to use a drone control app that + allows you to specify the area of interest and desired image overlap + (recommended \~75%) and takes care of coverage planning, drone + control, and image acquisition. + +2. Perform ortho-mosaicing/ortho-rectification to stitch the collected + images together into a single orthographic image. [Open Drone + Map](https://www.opendronemap.org/) is a popular open source project + that Clearpath has used for stitching, but there are also paid + services that automate the process. + +3. Georeference the orthographic image. One way to do this is to define + the locations of well-defined features (sewer grates, utility holes, + etc.) based on their known positions, such as their position data + from an existing mapping service (e.g., Google Maps). Open source + tools, such as [QGIS](https://www.qgis.org/en/site/) can help with + this process. + +4. Generate the map tiles. Using Ubuntu, this can be accomplished with + the following commands, where `GEOREFERENCED_IMG.tif` is the output + of the previous step. + + ``` + sudo apt install gdal-bin + gdal2tiles.py + ``` + +5. Use a web server to host the tiles locally. Using Ubuntu, one way to + accomplish this is to use the commands below, which will make the + tiles available at: . + + ``` + cd /base/directory/of/tiles + python3 -m http.server + ``` + +Once your map tiles are available on the network, you can follow the +steps in [Using Custom Maps](#using_custom_maps) to have the +Web UI use your custom tiles. + +## Autonomous Features + +There are presently 2 autonomous modes that the UGV can be used in, [Waypoint Mode](ui_waypoint_mode.mdx) and [Map Mode](ui_map_mode.mdx). +While each mode leverages different features, some are shared and are elaborated on here. + +:::note + +Some objects that appear on the overlay have context menus associated with them. However there is a known issue related to opening this context menu +between Autonomy modes. At present to open a context menu in the Waypoint Mode, left click the object, and when in Map Mode right click the object. +This issue will be reconciled in a future release. + +::: + +### Tasks + +When running a mission autonomously the user can assign tasks to various events. These tasks, along with their decoration icons, are found below: + +- Dock Robot: + Will dock the UGV to begin charging the UGV's + battery. There are 3 kinds of docking that can be used; Network, Radius and Local. + See [Autonomous Docking](#autonomous-docking) for more information on + the autonomous docking feature. + +- Move PTZ: + Will move the PTZ camera to the position selected + in the task settings. + + Settings: Select the camera position. See + [Pan-Tilt-Zoom (PTZ) View](ui_overview.mdx#ptz-view) for details on how to + save camera positions. + +- Save Image: + Will save an image using one of the UGV camera(s) + to the /opt/onav/saved_files/media/... directory and can be retrieved using a tool + such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which camera the image will be saved from. + +- / Start/Stop Video Recording: + Will start/stop recording video using one of the + UGV camera(s) to the /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which camera the recording will come from. + +- Start/Stop Audio Recording: + Will start/stop recording audio using one of the + UGV microphone(s) to the /opt/onav/saved_files/media/... folder and can be retrieved + using a tool such as FileZilla or by navigating to the Files section in the hamburger menu. + + Settings: Select which microphone the recording will come from. + +- Undock UGV: + Will undock the UGV from the autocharge dock. Once + completed, the UGV can be sent on autonomous missions. It is + often recommended to place the undock task first in the list of Waypoints or as a start Mission Task; + that way, the UGV will automatically continue towards its next + Waypoint once undocked. + + :::note + + If the users places the Undock Task in the start Mission event for a Waypoint Mission the first Waypoint should be + approximately 2-3 meters behind the UGV's docked position. + + ::: + +- Wait: + Will pause and wait for the specified number of + seconds at the end of the Waypoint. + + Settings: Enter the amount of time to wait, in seconds. + +- New Custom Task: + Creates a new custom task that is defined by the user. +
+
+ +
Custom Task Settings Dialog
+
+
+ + - Task Name: Task name that will show up in the list of available tasks on the UI. + - Action Server Name: The namespace of the custom task action server. + - Float CSV: A list of comma seperated float values that consist of the numerical inputs to the custom task. + - String CSV: A list of comma seperated string values that consist of the semantic inputs to the custom task. + + See the [Custom Tasks](../features/custom_tasks.mdx) section + for details on how to develop custom tasks for your application. + + +:::note + +If a Waypoint/Goalpoint has more than one task assigned to it, the icon will +be replaced with a sheet of paper icon like so: + +::: + +### Autonomous Docking + +
+
+ +
Dock Icon
+
+
+ +### Docking The UGV + +To dock the UGV autonomously the user can use the following methods: + +#### Dock (Local) + +If there is a valid dock within its driveable range the UGV will attempt to dock. +This docking method can be done by selecting the Dock button in the bottom bar or by adding a +"Dock Robot (Local)" task to either an event or a mission point. + +#### Dock (Radius) + +If the UGV is within the specified docks radius the UGV will first navigate to a predock location +and then attempt to dock. When in Waypoint Mode a user can dock via this method as follows: + +- Enable the "Edit Mission" toggle. +- Maneuver the UGV so that is somewhere within the dock's radius. +- Click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Radius)" task to either +an event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +#### Dock (Network) + +:::note + +This mode is only available in [Map mode](ui_map_mode.mdx). Please see the Map mode page for further +details on map generation. + +::: + +If the UGV and the dock are within a map's driveable area the UGV will first navigate to a +predock location based on the map paths available. A user can dock manually using this method as follows: + +- Enable the "Edit Map" toggle. +- Maneuver the UGV so that is within the driveable range of the map. +- Ensure the dock is within the driveable range of the map. +- Right click the dock that the UGV will be docking at and select "Dock Robot Here". + +This docking method can also be accomplished by adding a "Dock Robot (Network)" task to either an +event or a mission point. A dock will need to be provided for the task to function which can be done +through the task settings modal. + +### Undocking The UGV + +To undock the UGV autonomously, the user can apply a "Undock Robot" task to a mission event or +point. The user can also click the Undock button in the bottom bar's left hand corner. + +### Compatibility with a Doghouse + +In order for the autonomous docking feature to be compatible with a doghouse, the +doghouse must conform to a few specifications: + +- Must be installed on a flat surface, and have no elevation change between the + charge-dock and the outdoor surface (ie. no ramp into the doghouse). +- Must be greater than 1.2 m wide. +- Must be between 1.5 and 2.5 m long. +- Dock target should be installed centered along the back of the doghouse. + +### Recover from Failed Docking or Undocking + +If for any reason, the docking or undocking tasks fail, the user can: + +- Manually drive the UGV towards the dock target, aligning the + charging unit with the receiver on the UGV. +- Manually drive the UGV in reverse away from the dock target. It is + suggested that the user reverse roughly 2-3 meters away from the target, + then wait 1-2 minutes before starting any autonomous navigation + missions. + +## Switching to IndoorNav + +If it is included in the UGV, IndoorNav can be executed through the OutdoorNav software. +To switch between the modes in OutdoorNav select the 'Navigation Mode' option found +in the hamburger menu. This will navigate to a page that shows the current mode and +provides an option to switch. When in IndoorNav mode the user may navigate to +the IndoorNav Web GUI directly or work within the OutdoorNav view as can be seen +below. + +
+
+ +
+
+ +:::note + +When in IndoorNav mode the OutdoorNav Autonomy software is switched off. The UI will +disable OutdoorNav UI features related to Autonomy but will still allow users the +option to view camera streams. + +::: \ No newline at end of file diff --git a/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx new file mode 100644 index 00000000..daf67ed9 --- /dev/null +++ b/outdoornav_user_manual_versioned_docs/version-0.12.0/web_user_interface/ui_waypoint_mode.mdx @@ -0,0 +1,271 @@ +--- +title: Web UI Waypoint Mode +sidebar_label: Web UI Waypoint Mode +sidebar_position: 3 +toc_min_heading_level: 2 +toc_max_heading_level: 4 +--- + +![](/img/outdoornav_images/gps_danger.png) + +Ensure that the [Safety](../safety.mdx) document has been +read and the user is aware of possible hazards when using this product as well as the safety +methods that can be used to stop the moving UGV. + +The Autonomous Mode of OutdoorNav Software is a set of robotic +navigation modules that enables robotics developers to define and then +autonomously execute missions on UGVs, getting work done without +requiring direct operator action. This software is composed of four main +modules: localization, navigation, safety monitoring and user control +unit. This a combination of Clearpath's proprietary packages and custom +configured open-source packages from ROS community. Please see the +software architecture section for more information. + +## Definitions {#definitions} + +The list below defines what a "Mission" is as well as its components. +These components are referred to throughout this manual. + +- **Mission** A Mission is a set of one or more Waypoints. +- **Path** The list of Waypoints that will determine the path + for the specific Mission. +- **Waypoint** A Waypoint is any geographical point referenced by its + position relative to the datum in meters. +- **Task** A Task is an automated activity or wait time implemented as + a ROS action at a specific Waypoint. Tasks are called in the order they are + added to a Waypoint. +- **Ghost Waypoint** A transparent waypoint that is not part of the mission. This + Waypoint appears between two other waypoints when in edit mode. The user can + drag and drop this ghost waypoint to add a new waypoint to the mission between + the other two waypoints. + +## Mission Creation + +To create a new Mission first ensure that the UI is in "Edit Mode" ( +select the pencil icon in the bottom bar). Then open the drop down menu in the bottom +bar and select the "Add Mission" option. This will allow the user to create a new Mission +which can then be defined with Waypoints. + +### Waypoint Mode + +To add new Waypoints to a Mission while edit mode is enabled select the +"Waypoint Mode" button. This will allow the user to place Waypoints at +locations where the user clicks on the map. These will appear as red +Waypoints with the exception of the first waypoint (green) and the last waypoint (yellow). + +:::note + +**The first Waypoint in the Mission must be within 3.0 meters of the UGV's current position.** + +::: + +As Waypoints are placed, a "ghost waypoint" will appear between each pair of real +Waypoints and can be dragged to a new spot to insert a real Waypoint +between them. Waypoints can also be dragged and dropped on the map to +modify their positions. + +### Waypoint Panel + +
+
+ +
Waypoint Panel
+
+
+ +Enable the "Waypoint Panel" toggle to open the list of available Waypoints +within the selected Mission as shown in the figure above. The user can +now rearrange the list, rename Waypoints, add Tasks to the Waypoints, +and modify the final heading and/or tolerance of each Waypoint. The user can +also rename the mission and apply Tasks to when the Mission starts and stops. + +### Rename Mission + +To rename the Mission click the Mission name as it appears in the upper left +hand corner. This should change the text into an input box that can then be +modified. Press enter/click aside to save the change. + +### Mission Tasks + +A Mission can have Tasks assigned to when it starts and when it stops. These +Tasks will run in the order they are listed in and will always run whenever the Mission +starts or stops. + +### Rearrange List of Waypoints + +Waypoints can be rearranged in order of operation in the list. To do this, +enable the "Waypoints Panel" toggle to access the list of Waypoints. Here, the +user will be able to drag and drop the Waypoints to reorder them. + +### Rename Waypoint + +By default, once Waypoints are created they are assigned a default name +which is the word "Waypoint" followed by a numeric value representing the +the number of Waypoints that have been created plus one. The user has the +option to rename these Waypoints in order for them to have more descriptive +meaning. + +To rename a Waypoint follow these steps: + +1. Enable the "Waypoint Panel" toggle. See [Waypoint Panel](#waypoint-panel) + for further details. +2. Click the name of the Waypoint which the user wants to rename. +3. Erase the current name and type the new name. + +### Add Task to Waypoint {#add-task} + +
+
+ +
Add Task to Waypoint
+
+
+ +To add a Task to the end of a Mission: + +1. Click the "+" icon (beside the Gear icon) in the Waypoint Row the Task is + to be added to. + +2. Click the "Add Task" Button that has appeared. + +3. Select the Task from the dropdown list. Standard waypoint icons will be + replaced accordingly depending on the task selected (waypoint icons will keep the colours + assigned to them based on placement). Waypoints in the table will also have a small icon to indicate + if tasks are assigned to the Waypoint accordingly. + +4. The check box next to the Task name controls mission behaviour in the event that the Task fails. If the checkbox is + checked the Mission will proceed to the next step in it's process, such as the next task or navigating to the next Waypoint. + If its not checked, the Mission will become cancelled upon the Task's failure. +5. Click the Gear icon next to the selected Task to add the required + Settings. + + :::note + + If a waypoint has more than one task assigned to it, the icon will + be replaced with + + ::: + +### Advanced Settings + + + +#### Waypoint Heading + +When creating a Waypoint, the user has the option of setting a final heading +for the Waypoint. For example, when creating a Waypoint at an inspection point, +the user may want the UGV to navigate and stop facing a certain +direction. In [Waypoint Panel](#waypoint-panel), the list of +Waypoints can be seen and the advanced settings of each Waypoint can be accessed +by clicking the "Gear" icon. + +To set the Waypoint's final heading, the user will need to check the +"Final Heading Enabled" checkbox and enter the heading value in +degrees. The heading indicator on the top bar can be used to help set +this value. See the figure below showing the advanced settings. + +:::note + +Waypoints that have a heading or tolerance assigned to them will show a different colour +on their settings icon. + +::: + +
+
+ +
Waypoint Advanced Settings
+
+
+ +The heading that has been entered will only be applied to the Waypoint +(ie. the robot will only align itself with the correct heading at the +Waypoint). If the robot is required to be at specific headings at +other Waypoints the user will need to enter these in for each specific Waypoint. + +#### Waypoint Tolerance + +When creating a Mission, the user has the option of setting a specific +tolerance for each Waypoint. By default, the Waypoint position and orientation +tolerances are 0.3 meters and 180°, respectively. If a specific Waypoint +requires that the tolerances be either increased or decreased, these +values can be modified in the advanced settings. For example, if it's +required that the position and/or orientation at a Waypoint be very accurate, +such as 0.1 meters position and 5° orientation, or looser at 1.0 meter +position, this can be done within these settings. + +In [Waypoint Panel](#waypoint-panel), the list of waypoints can be +seen and the advanced settings of each Waypoint can be accessed by clicking +the "Gear" icon. To set the Waypoint's tolerance, the user will need to +check the "Waypoint Tolerance Enabled" checkbox and enter the position and +orientation values, in meters and degrees, respectively. + +### Constrained Replanning {#constrained_path} + +To enable the visualization of the contrained area of traversal (defined by +the path contraint around the reference path), navigate to the General settings +in the hamburger menu. Enable/disable the visualization of the path ui_route_deviation +distance using the switch button (see image below). + +
+
+ +
General settings
+
+
+ +Once enabled the area of possible deviation will show +over the planned route as can be seen in the following figure. + +
+
+ +
Route with maximum path deviation
+
+
+ +:::note + +If the UGV is manually driven outside of the constrained replanning area +while a Mission is running, the Mission will not be able to be resumed until the +UGV is returned within the navigable area defined by the path contraint. + +::: + +## Mission Execution + +### Start Mission + +There are multiple ways to start a Mission. At the bottom of the UI, the user has the ability to start the currently +selected Mission by clicking the "Play" button . +Starting the Mission this will start the Mission from the first Waypoint. The user may also select the drop down next to the button +to start the Mission from the current UGV position. This is a useful way to start a Mission in the event that the UGV was blocked by +obstacles that were later moved. Another way that a user can start a Mission is by selecting a waypoint in edit mode and then clicking on +"Start Mission from Here" option. If the UGV is within 3 metres of that Waypoint the Mission will start from there. + +
+
+ +
Starting from a specific Waypoint
+
+
+ +When the Mission has been started the Play button will turn green, regardless of how it has been started. + +### Pause Mission + +At the bottom of the UI, the user has the ability to pause the currently +running mission by clicking the "Pause" button . When the +mission has been paused this button will turn yellow. Pausing a mission +allows the user to take time to look around with the camera or to +teleoperate the UGV to a nearby location to perform an inspection. For +ease of operation, the user must PAUSE the active mission if the user +wants to teleoperate the UGV. + +### Cancel Mission/Task + +At the bottom of the UI, the user has the ability to stop the currently +running mission or task by clicking the "Stop" button . When the +mission/task has been cancelled this button will turn red. The name of +the mission/task will be shown to be cancelled in the feedback bar. + diff --git a/outdoornav_user_manual_versioned_sidebars/version-0.12.0-sidebars.json b/outdoornav_user_manual_versioned_sidebars/version-0.12.0-sidebars.json new file mode 100644 index 00000000..2782dc0f --- /dev/null +++ b/outdoornav_user_manual_versioned_sidebars/version-0.12.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "sidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/outdoornav_user_manual_versions.json b/outdoornav_user_manual_versions.json index f45c560e..f6853e76 100644 --- a/outdoornav_user_manual_versions.json +++ b/outdoornav_user_manual_versions.json @@ -1,4 +1,5 @@ [ + "0.12.0", "0.11.0", "0.10.0", "0.9.0", diff --git a/static/img/outdoornav_images/assisted_teleop_twist_mux.png b/static/img/outdoornav_images/assisted_teleop_twist_mux.png new file mode 100644 index 00000000..2d818b28 Binary files /dev/null and b/static/img/outdoornav_images/assisted_teleop_twist_mux.png differ diff --git a/static/img/outdoornav_images/disconnected_maps_icon.png b/static/img/outdoornav_images/disconnected_maps_icon.png new file mode 100644 index 00000000..b0674aba Binary files /dev/null and b/static/img/outdoornav_images/disconnected_maps_icon.png differ diff --git a/static/img/outdoornav_images/disconnected_points_icon.png b/static/img/outdoornav_images/disconnected_points_icon.png new file mode 100644 index 00000000..9d09be87 Binary files /dev/null and b/static/img/outdoornav_images/disconnected_points_icon.png differ diff --git a/static/img/outdoornav_images/movePTZTask.png b/static/img/outdoornav_images/movePTZTask.png new file mode 100644 index 00000000..e14e435d Binary files /dev/null and b/static/img/outdoornav_images/movePTZTask.png differ diff --git a/static/img/outdoornav_images/network-map-google-earth.png b/static/img/outdoornav_images/network-map-google-earth.png new file mode 100644 index 00000000..14d11ec9 Binary files /dev/null and b/static/img/outdoornav_images/network-map-google-earth.png differ diff --git a/static/img/outdoornav_images/parking_lot_map.png b/static/img/outdoornav_images/parking_lot_map.png new file mode 100644 index 00000000..9e424b78 Binary files /dev/null and b/static/img/outdoornav_images/parking_lot_map.png differ diff --git a/static/img/outdoornav_images/task_audio.png b/static/img/outdoornav_images/task_audio.png new file mode 100644 index 00000000..2640ce94 Binary files /dev/null and b/static/img/outdoornav_images/task_audio.png differ diff --git a/static/img/outdoornav_images/task_camera.png b/static/img/outdoornav_images/task_camera.png new file mode 100644 index 00000000..ce213650 Binary files /dev/null and b/static/img/outdoornav_images/task_camera.png differ diff --git a/static/img/outdoornav_images/task_custom.png b/static/img/outdoornav_images/task_custom.png new file mode 100644 index 00000000..21fc2c35 Binary files /dev/null and b/static/img/outdoornav_images/task_custom.png differ diff --git a/static/img/outdoornav_images/task_dock.png b/static/img/outdoornav_images/task_dock.png new file mode 100644 index 00000000..5f5a0048 Binary files /dev/null and b/static/img/outdoornav_images/task_dock.png differ diff --git a/static/img/outdoornav_images/task_multi.png b/static/img/outdoornav_images/task_multi.png new file mode 100644 index 00000000..eecbda42 Binary files /dev/null and b/static/img/outdoornav_images/task_multi.png differ diff --git a/static/img/outdoornav_images/task_record.png b/static/img/outdoornav_images/task_record.png new file mode 100644 index 00000000..b3e1989d Binary files /dev/null and b/static/img/outdoornav_images/task_record.png differ diff --git a/static/img/outdoornav_images/task_stopRecord.png b/static/img/outdoornav_images/task_stopRecord.png new file mode 100644 index 00000000..e6b1d305 Binary files /dev/null and b/static/img/outdoornav_images/task_stopRecord.png differ diff --git a/static/img/outdoornav_images/task_undock.png b/static/img/outdoornav_images/task_undock.png new file mode 100644 index 00000000..2e263614 Binary files /dev/null and b/static/img/outdoornav_images/task_undock.png differ diff --git a/static/img/outdoornav_images/task_wait.png b/static/img/outdoornav_images/task_wait.png new file mode 100644 index 00000000..381b91f4 Binary files /dev/null and b/static/img/outdoornav_images/task_wait.png differ diff --git a/static/img/outdoornav_images/ui_adv_goalpoint_settings.png b/static/img/outdoornav_images/ui_adv_goalpoint_settings.png new file mode 100644 index 00000000..daa86042 Binary files /dev/null and b/static/img/outdoornav_images/ui_adv_goalpoint_settings.png differ diff --git a/static/img/outdoornav_images/ui_editing_two_path.png b/static/img/outdoornav_images/ui_editing_two_path.png new file mode 100644 index 00000000..64af75e5 Binary files /dev/null and b/static/img/outdoornav_images/ui_editing_two_path.png differ diff --git a/static/img/outdoornav_images/ui_general_settings.png b/static/img/outdoornav_images/ui_general_settings.png index d0a41d1e..3a676580 100644 Binary files a/static/img/outdoornav_images/ui_general_settings.png and b/static/img/outdoornav_images/ui_general_settings.png differ diff --git a/static/img/outdoornav_images/ui_goal_tasks.png b/static/img/outdoornav_images/ui_goal_tasks.png new file mode 100644 index 00000000..eab1c129 Binary files /dev/null and b/static/img/outdoornav_images/ui_goal_tasks.png differ diff --git a/static/img/outdoornav_images/ui_goalpoint_panel.png b/static/img/outdoornav_images/ui_goalpoint_panel.png new file mode 100644 index 00000000..ac0d21a6 Binary files /dev/null and b/static/img/outdoornav_images/ui_goalpoint_panel.png differ diff --git a/static/img/outdoornav_images/ui_goto_point.png b/static/img/outdoornav_images/ui_goto_point.png new file mode 100644 index 00000000..475e6b70 Binary files /dev/null and b/static/img/outdoornav_images/ui_goto_point.png differ diff --git a/static/img/outdoornav_images/ui_main_components.png b/static/img/outdoornav_images/ui_main_components.png index 76ca0a69..4fa71f3a 100644 Binary files a/static/img/outdoornav_images/ui_main_components.png and b/static/img/outdoornav_images/ui_main_components.png differ diff --git a/static/img/outdoornav_images/ui_manual_mode_page.png b/static/img/outdoornav_images/ui_manual_mode_page.png new file mode 100644 index 00000000..4473f28b Binary files /dev/null and b/static/img/outdoornav_images/ui_manual_mode_page.png differ diff --git a/static/img/outdoornav_images/ui_map_mode_bottom_bar.png b/static/img/outdoornav_images/ui_map_mode_bottom_bar.png new file mode 100644 index 00000000..d3031b2b Binary files /dev/null and b/static/img/outdoornav_images/ui_map_mode_bottom_bar.png differ diff --git a/static/img/outdoornav_images/ui_map_panel.png b/static/img/outdoornav_images/ui_map_panel.png new file mode 100644 index 00000000..5d1f6b94 Binary files /dev/null and b/static/img/outdoornav_images/ui_map_panel.png differ diff --git a/static/img/outdoornav_images/ui_map_path_preview.png b/static/img/outdoornav_images/ui_map_path_preview.png new file mode 100644 index 00000000..79d07173 Binary files /dev/null and b/static/img/outdoornav_images/ui_map_path_preview.png differ diff --git a/static/img/outdoornav_images/ui_map_settings.png b/static/img/outdoornav_images/ui_map_settings.png index 0da69f27..e32fc85f 100644 Binary files a/static/img/outdoornav_images/ui_map_settings.png and b/static/img/outdoornav_images/ui_map_settings.png differ diff --git a/static/img/outdoornav_images/ui_map_view.png b/static/img/outdoornav_images/ui_map_view.png index 2227d13f..55179330 100644 Binary files a/static/img/outdoornav_images/ui_map_view.png and b/static/img/outdoornav_images/ui_map_view.png differ diff --git a/static/img/outdoornav_images/ui_start_button_simple.png b/static/img/outdoornav_images/ui_start_button_simple.png new file mode 100644 index 00000000..7ab75c53 Binary files /dev/null and b/static/img/outdoornav_images/ui_start_button_simple.png differ diff --git a/static/img/outdoornav_images/valid_map_icon.png b/static/img/outdoornav_images/valid_map_icon.png new file mode 100644 index 00000000..c021ca3c Binary files /dev/null and b/static/img/outdoornav_images/valid_map_icon.png differ diff --git a/static/versions.js b/static/versions.js index b1075573..c5507b1e 100644 --- a/static/versions.js +++ b/static/versions.js @@ -1,5 +1,5 @@ const versions = Object.freeze({ - "outdoornav": "0.11.0", + "outdoornav": "0.12.0", }); export default versions;