You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| autonomy/network_mission |[clearpath_navigation_msgs/action/ExecuteNetworkMissionByUuid](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionByUuid.html)| Execute an autonomous mission |
110
-
| autonomy/network_mission_from_goal |[clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal.html)| Execute and autonomous mission, starting from a specific goal |
113
+
| autonomy/network_mission_from_goal |[clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal.html)| Execute an autonomous mission, starting from a specific goal |
111
114
| autonomy/network_goto |[clearpath_navigation_msgs/action/ExecuteNetworkGoTo](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkGoTo.html)| Send platform to location |
112
115
| autonomy/network_goto_poi |[clearpath_navigation_msgs/action/ExecuteNetworkGoToPOI](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkGoToPOI.html)| Send platform to a point of interest |
113
116
| autonomy/local_dock |[clearpath_dock_msgs/action/Dock](pathname:///api/html/clearpath_dock_msgs/action/Dock.html)| Dock the platform (charge target must be visible by platform 2D lidar sensor) |
Copy file name to clipboardExpand all lines: docs_outdoornav_user_manual/api/api_overview.mdx
+88Lines changed: 88 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,3 +39,91 @@ The API is divided into two sections, whose details are provided below:
39
39
and modifying OutdoorNav Missions
40
40
-[API Examples](./api_examples/api_examples_overview): Example code to come.
41
41
42
+
43
+
## QoS Profiles {#qos-profiles}
44
+
45
+
Topics and services in ROS 2 use Quality of Service (QoS) profiles to change communication policies. The QoS profile
46
+
of a topic or service has several policies such as history, depth, reliability, durability, and more. For more details on
47
+
QoS settings, visit the [ROS 2 documentation](https://docs.ros.org/en/jazzy/Concepts/About-Quality-of-Service-Settings.html).
48
+
49
+
For Clearpath platforms, the main policies that may change between different topics and services are reliability and durability. For reliability
50
+
there are two options: _Best Effort_, and _Reliable_. A _Best Effort_ reliability suggests that an attempt will be made to publish
51
+
the data, but if the network is not robust then the data may be lost. On the other hand, _Reliable_ guarantees that the data will be received.
52
+
This may require that the data be sent multiple times.
53
+
54
+
The durability of a QoS profile can be either _Transient Local_ or _Volatile_. _Transient Local_ means that data for published messages will
55
+
be stored by the publisher even after it has been published. A new subscriber will receive the data even if a lot of time has passed since it was originally published.
56
+
This durability is typically used for data that only needs to be published once, such as the robot description. The other durability policy is _Volatile_ which does not
57
+
store old messages. The messages are published and only active subscribers will receive the data. New subscribers will have to wait for the next message to be published.
58
+
Most topics will use a _Volatile_ durability policy.
59
+
60
+
It is important to check for [QoS compatibility](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-compatibilities) when interacting with ROS 2.
61
+
Mixing of QoS policies when publishing or subscribing to topics can lead to incompatibility. For example, subscribing to a Best Effort publisher with a Reliable subscriber
62
+
is not compatible and will result in no data being received on the subscriber. The easiest way to check the QoS profile of a topic is to use the ROS 2 command line interface.
63
+
64
+
```
65
+
ros2 topic info /topic_name -v
66
+
```
67
+
68
+
## Common QoS profiles {#common-qos-profiles}
69
+
70
+
The following are some common QoS profiles used by Clearpath platforms.
71
+
72
+
### System Default
73
+
74
+
-**History**: _Keep Last_
75
+
-**Depth**: _10_
76
+
-**Reliability**: _Reliable_
77
+
-**Durability**: _Volatile_
78
+
-**Deadline**: _System Default_
79
+
-**Lifespan**: _System Default_
80
+
-**Liveliness**: _Automatic_
81
+
-**Lease Duration**: _System Default_
82
+
83
+
The _System Default_ QoS profile is the most common profile used by most topics.
84
+
85
+
### Sensor Data
86
+
87
+
-**History**: _Keep Last_
88
+
-**Depth**: _5_
89
+
-**Reliability**: _Best Effort_
90
+
-**Durability**: _Volatile_
91
+
-**Deadline**: _System Default_
92
+
-**Lifespan**: _System Default_
93
+
-**Liveliness**: _Automatic_
94
+
-**Lease Duration**: _System Default_
95
+
96
+
The _Sensor Data_ QoS Profile uses a _Best Effort_ reliability to send the latest data
97
+
as soon as possible, without bothering to resend data that was not received. This is mostly used
98
+
by the MCU and sensor drivers.
99
+
100
+
:::note
101
+
102
+
Not all sensor drivers use this QoS profile. Always check the QoS profile before trying to subscribe to the topic.
103
+
104
+
:::
105
+
106
+
### Transient Local
107
+
108
+
-**History**: _Keep Last_
109
+
-**Depth**: _10_
110
+
-**Reliability**: _Reliable_
111
+
-**Durability**: _Transient Local_
112
+
-**Deadline**: _System Default_
113
+
-**Lifespan**: _System Default_
114
+
-**Liveliness**: _Automatic_
115
+
-**Lease Duration**: _System Default_
116
+
117
+
The _Transient Local_ QoS Profile offers a _Transient Local_ durability, and is typically used by topics that only
118
+
want to send messages once. For Clearpath platforms, this includes the robot description topic and the `/rosout` topic
119
+
which offers system logs.
120
+
121
+
## Namespacing
122
+
123
+
Namespacing is the method of adding a prefix to a robot's nodes and topics; this helps differentiate them from another robot that
124
+
may be on the same network. For example, every robot will have a `cmd_vel` topic for commanding velocity. If both robots
125
+
used the same topic, then they would both drive when a message is published to that topic. By namespacing, we can remap the topic
126
+
to `robot1/cmd_vel` and `robot2/cmd_vel` for each respective robot.
127
+
128
+
By default, the namespace of the robot will be obtained from the serial number of the robot. If your serial number is `cpr-a300-00001`, then your namespace
129
+
will be `a300_00001`. This can be overwritten in the [robot.yaml](../config/yaml/overview) file.
| autonomy/network_mission |[clearpath_navigation_msgs/action/ExecuteNetworkMissionByUuid](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionByUuid.html)| Execute an autonomous mission |
110
-
| autonomy/network_mission_from_goal |[clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal.html)| Execute and autonomous mission, starting from a specific goal |
113
+
| autonomy/network_mission_from_goal |[clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkMissionFromGoal.html)| Execute an autonomous mission, starting from a specific goal |
111
114
| autonomy/network_goto |[clearpath_navigation_msgs/action/ExecuteNetworkGoTo](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkGoTo.html)| Send platform to location |
112
115
| autonomy/network_goto_poi |[clearpath_navigation_msgs/action/ExecuteNetworkGoToPOI](pathname:///api/html/clearpath_navigation_msgs/action/ExecuteNetworkGoToPOI.html)| Send platform to a point of interest |
113
116
| autonomy/local_dock |[clearpath_dock_msgs/action/Dock](pathname:///api/html/clearpath_dock_msgs/action/Dock.html)| Dock the platform (charge target must be visible by platform 2D lidar sensor) |
Copy file name to clipboardExpand all lines: outdoornav_user_manual_versioned_docs/version-2.0.0/api/api_overview.mdx
+89-1Lines changed: 89 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ While the Web User Interface provides a great way to get started quickly
10
10
with OutdoorNav Software, some users will want programmatic control or
11
11
may wish to develop their own graphical user interfaces \-- for those
12
12
users, the Application Programming Interface (API) provides the
13
-
flexibility to do so. This is illustrated in the figure below.
13
+
flexibility to do so.
14
14
15
15
The API is, at present, a [ROS 2 Jazzy](https://docs.ros.org/en/jazzy/index.html) API.
16
16
The API is divided into two sections, whose details are provided below:
@@ -39,3 +39,91 @@ The API is divided into two sections, whose details are provided below:
39
39
and modifying OutdoorNav Missions
40
40
-[API Examples](./api_examples/api_examples_overview): Example code to come.
41
41
42
+
43
+
## QoS Profiles {#qos-profiles}
44
+
45
+
Topics and services in ROS 2 use Quality of Service (QoS) profiles to change communication policies. The QoS profile
46
+
of a topic or service has several policies such as history, depth, reliability, durability, and more. For more details on
47
+
QoS settings, visit the [ROS 2 documentation](https://docs.ros.org/en/jazzy/Concepts/About-Quality-of-Service-Settings.html).
48
+
49
+
For Clearpath platforms, the main policies that may change between different topics and services are reliability and durability. For reliability
50
+
there are two options: _Best Effort_, and _Reliable_. A _Best Effort_ reliability suggests that an attempt will be made to publish
51
+
the data, but if the network is not robust then the data may be lost. On the other hand, _Reliable_ guarantees that the data will be received.
52
+
This may require that the data be sent multiple times.
53
+
54
+
The durability of a QoS profile can be either _Transient Local_ or _Volatile_. _Transient Local_ means that data for published messages will
55
+
be stored by the publisher even after it has been published. A new subscriber will receive the data even if a lot of time has passed since it was originally published.
56
+
This durability is typically used for data that only needs to be published once, such as the robot description. The other durability policy is _Volatile_ which does not
57
+
store old messages. The messages are published and only active subscribers will receive the data. New subscribers will have to wait for the next message to be published.
58
+
Most topics will use a _Volatile_ durability policy.
59
+
60
+
It is important to check for [QoS compatibility](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Quality-of-Service-Settings.html#qos-compatibilities) when interacting with ROS 2.
61
+
Mixing of QoS policies when publishing or subscribing to topics can lead to incompatibility. For example, subscribing to a Best Effort publisher with a Reliable subscriber
62
+
is not compatible and will result in no data being received on the subscriber. The easiest way to check the QoS profile of a topic is to use the ROS 2 command line interface.
63
+
64
+
```
65
+
ros2 topic info /topic_name -v
66
+
```
67
+
68
+
## Common QoS profiles {#common-qos-profiles}
69
+
70
+
The following are some common QoS profiles used by Clearpath platforms.
71
+
72
+
### System Default
73
+
74
+
-**History**: _Keep Last_
75
+
-**Depth**: _10_
76
+
-**Reliability**: _Reliable_
77
+
-**Durability**: _Volatile_
78
+
-**Deadline**: _System Default_
79
+
-**Lifespan**: _System Default_
80
+
-**Liveliness**: _Automatic_
81
+
-**Lease Duration**: _System Default_
82
+
83
+
The _System Default_ QoS profile is the most common profile used by most topics.
84
+
85
+
### Sensor Data
86
+
87
+
-**History**: _Keep Last_
88
+
-**Depth**: _5_
89
+
-**Reliability**: _Best Effort_
90
+
-**Durability**: _Volatile_
91
+
-**Deadline**: _System Default_
92
+
-**Lifespan**: _System Default_
93
+
-**Liveliness**: _Automatic_
94
+
-**Lease Duration**: _System Default_
95
+
96
+
The _Sensor Data_ QoS Profile uses a _Best Effort_ reliability to send the latest data
97
+
as soon as possible, without bothering to resend data that was not received. This is mostly used
98
+
by the MCU and sensor drivers.
99
+
100
+
:::note
101
+
102
+
Not all sensor drivers use this QoS profile. Always check the QoS profile before trying to subscribe to the topic.
103
+
104
+
:::
105
+
106
+
### Transient Local
107
+
108
+
-**History**: _Keep Last_
109
+
-**Depth**: _10_
110
+
-**Reliability**: _Reliable_
111
+
-**Durability**: _Transient Local_
112
+
-**Deadline**: _System Default_
113
+
-**Lifespan**: _System Default_
114
+
-**Liveliness**: _Automatic_
115
+
-**Lease Duration**: _System Default_
116
+
117
+
The _Transient Local_ QoS Profile offers a _Transient Local_ durability, and is typically used by topics that only
118
+
want to send messages once. For Clearpath platforms, this includes the robot description topic and the `/rosout` topic
119
+
which offers system logs.
120
+
121
+
## Namespacing
122
+
123
+
Namespacing is the method of adding a prefix to a robot's nodes and topics; this helps differentiate them from another robot that
124
+
may be on the same network. For example, every robot will have a `cmd_vel` topic for commanding velocity. If both robots
125
+
used the same topic, then they would both drive when a message is published to that topic. By namespacing, we can remap the topic
126
+
to `robot1/cmd_vel` and `robot2/cmd_vel` for each respective robot.
127
+
128
+
By default, the namespace of the robot will be obtained from the serial number of the robot. If your serial number is `cpr-a300-00001`, then your namespace
129
+
will be `a300_00001`. This can be overwritten in the [robot.yaml](../config/yaml/overview) file.
0 commit comments