Skip to content

Commit 6e0d1cb

Browse files
SteveMacenskiSteveMacenski
committed
adding readme config table
1 parent 75766a4 commit 6e0d1cb

File tree

3 files changed

+76
-25
lines changed

3 files changed

+76
-25
lines changed

‎README.md

+75-23
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Nav2 Complete Coverage
22

3-
This package contains the Complete Coverage Task server utilizing the [Fields2Cover](https://github.com/Fields2Cover/Fields2Cover) complete coverage planning system which includes a great deal of options in headland, swath, route, and final path planning. You can find more information about Fields2Cover (F2C) in its [ReadTheDocs Documentation](https://fields2cover.github.io/index.html). It can accept both GPS and Cartesian coordinates.
3+
This package contains the Complete Coverage Task Server & auxiliary tools utilizing the [Fields2Cover](https://github.com/Fields2Cover/Fields2Cover) complete coverage planning system which includes a great deal of options in headland, swath, route, and final path planning. You can find more information about Fields2Cover (F2C) in its [ReadTheDocs Documentation](https://fields2cover.github.io/index.html). It can accept both GPS and Cartesian coordinates and publishes the field, headland, swaths, and route as separate topics in cartesian coordinates for debugging and visualization.
44

55
This capability was created by [Open Navigation LLC](https://www.opennav.org/) in partnership with [Bonsai Robotics](https://www.bonsairobotics.ai/). Bonsai Robotics funded the development of this work for their own product and has graciously allowed Open Navigation to open-source it for the community to leverage in their own systems. Please thank Bonsai Robotics for their commendable donation to the ROS community!
66

7-
TODO Bonsai x Open Navigation logo
7+
![BonsaixOpenNavigation](https://github.com/ros-planning/navigation2/assets/14944147/b5c23851-0694-4b87-b5ab-fb7c957413f4)
88

9-
This server exposes all of the features of Fields2Cover as a Lifecycle-Component Nav2 Task Server like all others within the Nav2 Framework, so it should feel very familiar to those using Nav2 already. This capability is split into 4 packages:
9+
This server exposes all of the features of Fields2Cover as a Lifecycle-Component Nav2 Task Server like all others within the Nav2 Framework, so it should feel very familiar to those using Nav2 already. The server is split into modular stages with factories and enum types for all known options which can be easily expanded up over time scalably. It even could be expanded to include custom coverage capabilities separate of F2C if desired. This capability is split into 4 packages:
1010

1111
- `nav2_coverage`: Contains the main Nav2 Task Server.
1212

@@ -16,8 +16,6 @@ This server exposes all of the features of Fields2Cover as a Lifecycle-Component
1616

1717
- `nav2_coverage_navigator`: Contains the BT Navigator plugin exposing `NavigateCompleteCoverage` action server analog to `NavigateToPose` and `NavigateThroughPoses`.
1818

19-
Note: `NavigateCompleteCoverage` message and its `CoverageNavigator` are subject to API changes to continue to be most useful to users! The current API is relatively basic and will be adapted as more users adopt its use and need additional fields exposed to the application layer. If you need any adjustments, feel free to ask!
20-
2119
Fields2Cover is a living library with new features planned to be added (for example those discussed in a [Nav2 integration ticket](https://github.com/Fields2Cover/Fields2Cover/issues/73)). As such, as new F2C capabilities are created, they will be welcome for integration here. If you see anything missing, please let us know or submit a PR to expose it!
2220

2321
## Interfaces
@@ -28,13 +26,13 @@ The two main interfaces are `NavigateCompleteCoverage` and `ComputeCoveragePath`
2826

2927
This contains `generate_headland`, `generate_route`, and `generate_path` about whether the coverage task should remove a set headland, generate route to order the coverage swaths, or compute a path connecting the ordered route swaths; respectively. You can learn more about these stages in F2C's documentation - particularly from the graphic on its [index page](https://fields2cover.github.io/index.html).
3028

31-
Each of the stages (includeing `generate_swaths`, which is always on) has its own `_mode` message in the action containing its potential parameters to specify a mode. If not modified, it uses the parameters set in the server at launch time or after dynamic reconfiguration. See the parameter information below or the message files for complete details.
29+
Each of the stages (including `generate_swaths`, which is always on) has its own `_mode` message in the action containing its potential parameters to specify a mode. If not modified, it uses the parameters set in the server at launch time or after dynamic reconfiguration. See the parameter information below or the message files for complete details.
3230

33-
Finally, it contains the polygon information. This can be represented either as GML files, with [an example in `nav2_coverage/test`](./nav2_coverage/test/test_field.xml), or as a polygon in the message itself. If using GML files, set `goal.use_gml_file = true`. If your GML file contains multiple fields, set the ID of which to use with `goal.gml_field_id = id`, whereas the number is its ordered postion in the file.
31+
Finally, it contains the polygon information. This can be represented either as GML files, with [an example in `nav2_coverage/test`](./nav2_coverage/test/test_field.xml), or as a polygon in the message itself. If using GML files, set `goal.use_gml_file = true`. If your GML file contains multiple fields, set the ID of which to use with `goal.gml_field_id = id`, whereas the number is its ordered position in the file.
3432

3533
When setting the polygon (`goal.polygons`), this is a vector of polygons. If only considering a bounding field, only populate the first field shape. If there are internal voids, use subsequent polygons to indicate them. The coordinate type has `axis1` and `axis2` instead of X and Y as the server can process both GPS and cartesian coordinates. If specifying the polygon outside of GML files, you must specify the frame of reference of the polygon using the `goal.frame_id` field. This is not used for GML files as those should contain the frame within it.
3634

37-
The result returns a `result.nav_path` -- which is a `nav_msgs/Path` containing the coverage path requested **only if** all `generate_` fields are `true`. This can be followed by a local trajectory planner or controller directly. This is what is used in the `nav2_coverage_bt` examples for basic coverage navigation. It also returns `result.coverage_path` which contains an ordered set of swaths and paths to connect them (if applicable settings enabled) which can be used for more task-specific navigation. For example, navigating with a tool down or enabled on swaths and raised in turns to connect to other swaths. A utility is provided in `nav2_coverage/utils.hpp` for iterating through this custom `coverage_path` for convenience.
35+
The result returns a `result.nav_path` -- which is a `nav_msgs/Path` containing the coverage path requested **only if** all `generate_path` is `true`. This can be followed by a local trajectory planner or controller directly. This is what is used in the `nav2_coverage_bt` examples for basic coverage navigation. It also returns `result.coverage_path` which contains an ordered set of swaths and paths to connect them (if applicable settings enabled) which can be used for more task-specific navigation. For example, navigating with a tool down or enabled on swaths and raised in turns to connect to other swaths. A utility is provided in `nav2_coverage/utils.hpp` for iterating through this custom `coverage_path` for convenience.
3836

3937
It also returns an error code, if any error occurred and the total planning time for metrics analysis.
4038

@@ -44,13 +42,78 @@ The Coverage Navigator calls the `ComputeCoveragePath` action within its BT XML.
4442

4543
It returns the error code from the BT's error code IDs if any error occurs. Otherwise, it returns live regular feedback on the robot's current position, navigation time elapsed, number of recoveries enacted, distance remaining in the path (if `nav_path` valid), and a rough ETA.
4644

47-
Note that Navigator Plugins require **ROS 2 Iron or newer**. Otherwise, you may still use the Coverage Server in **Foxy or newer**, just don't compile the `nav2_coverage_navigator` package.
45+
Navigator Plugins require **ROS 2 Iron or newer**. Otherwise, you may still use the Coverage Server in **Foxy or newer**, just don't compile the `nav2_coverage_navigator` package.
46+
47+
Note: `NavigateCompleteCoverage` action message and `CoverageNavigator` are subject to API changes to continue to be most useful to users! The current API is relatively basic and will be adapted as more users adopt its use and need additional fields exposed to the application layer. If you need any adjustments, feel free to ask!
4848

4949
## Configuration
5050

5151
The complete set of options are exposed as both dynamic parameters and through the Action definition to be used as you prefer. Parameters are useful for consistent requests with the same configurations and actions are useful when changing parameters on a per-request basis. When any of the fields in `XYZMode.msg` messages are filled in, all must be filled in to be a complete request of a stage's mode parameters. `HeadlandMode`, `SwathMode`, `RouteMode`, and `PathMode` contain the complete parameter options for each of those stages in F2C coverage planning. The parameters given (or defaults) will be used for each stage, but any single stage can be overwritten via the Action message.
5252

53-
TODO config guide full
53+
### Coverage Server
54+
55+
56+
| Parameter | Description | Type |
57+
|------------------------------|------------------------------------------------|--------|
58+
| action_server_result_timeout | Action server result holding timeout (s) | double |
59+
| coordinates_in_cartesian_frame | Whether incoming requests are in cartesian or GPS coordinates | bool |
60+
| robot_width | Robots width (m) | double |
61+
| operation_width | Width of implement or task for coverage | double |
62+
| min_turning_radius | Minimum turning radius for path planning | double |
63+
| linear_curv_change | Max linear curvature change | double |
64+
| default_allow_overlap | Whether to allow some coverage overlap in final pass to fill space by default | bool |
65+
| default_custom_order | Default custom order of swaths -> route in CUSTOM mode | `vector<int>` |
66+
| default_headland_type | Default headland mode. Option: CONSTANT | String |
67+
| default_headland_width | Default headland width to remove from field | double |
68+
| default_path_continuity_type | Default path continuity mode. Option: DISCONTINUOUS, CONTINUOUS | String |
69+
| default_path_type | Default path mode. Option: DUBIN, REEDS_SHEPP | String |
70+
| default_route_type | Default route mode. Option: BOUSTROPHEDON, SNAKE, SPIRAL, CUSTOM | String |
71+
| default_spiral_n | Default number for spiraling, when set as default | int |
72+
| default_step_angle | Default angular step to attempt swath generating in BRUTE_FORCE mode | double |
73+
| default_swath_angle | Default swath angle to use when known for swathc generation in SET_ANGLE mode | double |
74+
| default_swath_angle_type | Default swath angle computation type. Options: BRUTE_FORCE,SET_ANGLE | String |
75+
| default_swath_type | Default swath computation objective. Option: LENGTH, COVERAGE, NUMBER | String |
76+
| default_turn_point_distance | Distance between points in path turns between swaths | double |
77+
78+
79+
### CoverageNavigator
80+
81+
All type string.
82+
83+
| Parameter | Description | Type |
84+
|------------------------------|------------------------------------------------|--------|
85+
| path_blackboard_id | Blackboard variable holding the path | String |
86+
| field_file_blackboard_id | Blackboard variable holding the field filepath | String |
87+
| field_polygon_blackboard_id | Blackboard variable holding the polygon field | String |
88+
| polygon_frame_blackboard_id | Blackboard variable holding the polygon frame | String |
89+
90+
### Behavior Tree Nodes
91+
92+
#### ComputeCoveragePathAction Ports
93+
94+
95+
| InputPort | Description | Type |
96+
|-------------------|-------------------|--------|
97+
| generate_headland | Whether to remove headland from field for coverage | bool |
98+
| generate_route | Whether to generate ordered route of swaths | bool |
99+
| generate_path | Whether to generate a path connecting ordered route swaths | bool |
100+
| file_field | The filepath to the field GML | string |
101+
| file_field_id | The ID of the GML file to use | int |
102+
| polygons | The polygonsof the field | `vector<geometry_msgs/Polygon>` |
103+
| polygons_frame_id | The polygon's frame of reference | string |
104+
105+
106+
| OutputPort | Description | Type |
107+
|-------------------|-------------------|--------|
108+
| error_code_id | The complete coverage error code" | uint |
109+
| planning_time | The time to compute coverage plan | double |
110+
| nav_path | The coverage plan as a nav_msgs/Path to track directly | `nav_msgs/Path` |
111+
| coverage_path | The coverage plan as an ordered set of swaths and route connections | `nav2_coverage_msgs/PathComponents` |
112+
113+
114+
#### CoverageCancel Ports
115+
116+
N/A
54117

55118
## Citation
56119

@@ -84,22 +147,11 @@ If you use this work, please make sure to cite both Nav2 and Fields2Cover:
84147
}
85148
```
86149

87-
## Notes of Wisdom
88-
89-
TODO
90-
- Visualize major stages for debugging
91-
- Modular stages retained; optional to which you'd like when
92-
- Each stage has factories and enums for options; can be expanded past F2C as well
150+
## Current Work
93151

94-
95-
Future
96-
- README
97-
- Rename packages / repo?
152+
- Rename packages / repo? opennav_nav2? nav2_coverage_msgs? opennav_ prefix?
98153
- A couple of utilities for the BT nodes to iterate through the swath-turn combos (optional)
99154

100155

101156

102157
- Use setup with BT nodes / XML / Navigator. Simulator demo altogether. Demo video (in readme).
103-
104-
- Python3 API from tester.py
105-
- Nav2 docs to include / config guide. BT ports. Groot index

‎nav2_coverage/test/tester.py

-1
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,6 @@ def main():
125125
goal.generate_path = True
126126

127127
goal.use_gml_file = True
128-
goal.frame_cartesian = True
129128
goal.gml_field = get_package_share_directory('nav2_coverage') + '/test_field.xml'
130129
goal.gml_field_id = 0
131130

‎nav2_coverage_bt/include/nav2_coverage_bt/compute_complete_coverage_path.hpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ class ComputeCoveragePathAction
9797
"planning_time", "The time to compute coverage plan"),
9898
BT::OutputPort<nav_msgs::msg::Path>(
9999
"nav_path", "The coverage plan as a nav_msgs/Path to track directly"),
100-
BT::OutputPort<nav_msgs::msg::Path>(
100+
BT::OutputPort<ActionResult::_coverage_path_type>(
101101
"coverage_path", "The coverage plan as an ordered set of swaths and route connections"),
102102
});
103103
}

0 commit comments

Comments
 (0)