Skip to content

Commit 33f1719

Browse files
ipa-nhgipa-nhg
committed
[Documenation] Update creation of communication objects
1 parent ada034d commit 33f1719

1 file changed

Lines changed: 140 additions & 44 deletions

File tree

‎docu/NewCommunicationObjects.md‎

Lines changed: 140 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,11 @@
22

33
### Autogeneration tools
44

5-
We facilitate a couple of tools to auto generate the corresponding model (these tools work only for messages and services, the action types, in the majority of the cases, have to be unfortunately implemented manually):
6-
7-
- Use our cloud facilities : [ROS Model Extractor](http://ros-model.seronet-project.de/) and navigate to the tag "Specification Analysis". There, if the package that contains the message types is released for Melodic you just have to give the name of the package and press **Submit**. Otherwise please specify first the name of the Git repository that hold the package
8-
9-
- Use locally the helper script (:bangbang::bangbang: this method requires a local ROS installation):
5+
For the autogeneration of of model objects we facilitate a bash (:bangbang::bangbang: this method requires a local ROS installation):
106

117
```
128
source /your_ROS_workspace
13-
wget https://raw.githubusercontent.com/ipa320/ros-model-cloud/master/extractor-interface/scripts/generate_messages_model_helper.sh
9+
wget https://raw.githubusercontent.com/ipa320/RosCommonObjects/YamlFormat/de.fraunhofer.ipa.ros.communication.objects/basic_msgs/generate_messages_model_helper.sh
1410
chmod +x generate_messages_model_helper.sh
1511
./generate_messages_model_helper.sh ROS_PACKAGE_NAME > ROS_PACKAGE_NAME.ros
1612
```
@@ -24,30 +20,91 @@ To modify the ROS models (.ros) manually the ROS tooling provides a customized e
2420
This editor contains an autocomplete function (by pressing Ctrl+Space) and will report any error made by editing. The first step is define a PackageSet (that correspond to a metapackage for ROS, this definition is optional and its name can be kept empty). Then, the ROS package which contains the msgs have to be defined and within it the option "spec" have to be selected to write down the objects. In the practice that means that the initial *.ros file that describes ROS objects looks:
2521

2622
```
27-
PackageSet { package { CatkinPackage ros_package_name {
28-
spec {}
29-
}}}
23+
ros_package_name:
24+
msgs:
25+
msg_name
26+
message
27+
type name
3028
```
3129

32-
The grammar supports 3 types of communication objects TopicSpec (to describe ROS msgs), ServiceSpec (to describe ROS srvs) and ActionSpec (to describe ROS actions), and consequentially each of these 3 types support different specifications types:
30+
The grammar supports 3 types of communication objects messages, services and actions, and consequentially each of these 3 types support different specifications types:
3331

3432
- ROS msgs
3533

36-
**TopicSpec** SpecName { **message** { ElementType ElementName ... } }
34+
```
35+
ros_package_name:
36+
**msgs:**
37+
msg_name
38+
**message**
39+
ElementType ElementName
40+
```
3741

38-
​ -> Example ```TopicSpec Point{ message { float64 x float64 y float64 z }}```
42+
For example:
43+
```
44+
std_msgs:
45+
msgs:
46+
ColorRGBA
47+
message
48+
float32 r
49+
float32 g
50+
float32 b
51+
float32 a
52+
```
3953

4054
- ROS srvs
4155

42-
**ServiceSpec** SpecName { **request** { ElementType ElementName ..} **response** { ElementType ElementName .. } }
56+
```
57+
ros_package_name:
58+
**srvs:**
59+
srv_name
60+
**request**
61+
ElementType ElementName
62+
**response**
63+
ElementType ElementName
64+
```
65+
66+
For example:
67+
```
68+
std_srvs:
69+
srvs:
70+
SetBool
71+
request
72+
bool data
73+
response
74+
bool success
75+
string message
76+
```
4377

44-
​ -> Example ```ServiceSpec SetBool{ request { bool data } response { bool success string message } }```
4578

4679
- ROS actions
4780

48-
**ActionSpec** SpecName { **goal** { ElementType ElementName .. } **result** { ElementType ElementName ..} **feedback** { ElementType ElementName .. }}
81+
```
82+
ros_package_name:
83+
**actions:**
84+
action_name
85+
**goal**
86+
ElementType ElementName
87+
**result**
88+
ElementType ElementName
89+
**feedback**
90+
ElementType ElementName
91+
```
4992

50-
​ -> Example ```ActionSpec Say { goal { string test } result { bool sucess string message} feedback {} }```
93+
For example:
94+
```
95+
control_msgs:
96+
actions:
97+
PointHead
98+
goal
99+
'geometry_msgs/msg/PointStamped'[] target
100+
'geometry_msgs/msg/Vector3'[] pointing_axis
101+
string pointing_frame
102+
'builtin_interfaces/msg/Duration'[] min_duration
103+
float64 max_velocity
104+
result
105+
feedback
106+
float64 pointing_angle_error
107+
```
51108

52109
Where , quite similar to ROS, the allowed element types are:
53110

@@ -69,47 +126,86 @@ Where , quite similar to ROS, the allowed element types are:
69126

70127
- Relative reference to other object:
71128
- NameOftheObject (if it is described within the same ROS package) -> for example **Point32**
72-
- 'ROSPackage_name.NameOftheObject' (if it is described in other ROS package) -> for example **'geometry_msgs.Point32'**
129+
- 'ROSPackage_name/NameOftheObject' (if it is described in other ROS package) -> for example **'geometry_msgs/Point32'**
73130

74131
- Arrays of element types:
75-
- ElementType[] -> for example **string[]** or **Point32[]** or **'geometry_msgs.Point32'[]**
132+
- ElementType[] -> for example **string[]** or **Point32[]** or **'geometry_msgs/Point32'[]**
76133

77134

78135
Additionally the definition of constants with its value is also supported and follows a patter very similar to the ROS one: ```constanttype1 CONSTANTNAME1=constantvalue1```, for example ```byte OK=0 byte WARN=1 byte ERROR=2 byte STALE=3```.
79136

80137
The following extract shows the ROS model description correspondent to the [nav_msgs](http://wiki.ros.org/nav_msgs) package:
81138

82139
```
83-
PackageSet {
84-
Package nav_msgs{ Specs {
85-
TopicSpec GetMapAction{ message { GetMapActionGoal action_goal GetMapActionResult action_result GetMapActionFeedback action_feedback }},
86-
TopicSpec GetMapActionFeedback{ message { Header header "actionlib_msgs.GoalStatus" status GetMapFeedback feedback }},
87-
TopicSpec GetMapActionGoal{ message { Header header "actionlib_msgs.GoalID" goal_id GetMapGoal goal }},
88-
TopicSpec GetMapActionResult{ message { Header header "actionlib_msgs.GoalStatus" status GetMapResult result }},
89-
TopicSpec GetMapFeedback{ message { }},
90-
TopicSpec GetMapGoal{ message { }},
91-
TopicSpec GetMapResult{ message { "nav_msgs.OccupancyGrid" map }},
92-
TopicSpec GridCells{ message { Header header float32 cell_width float32 cell_height "geometry_msgs.Point"[] cells }},
93-
TopicSpec MapMetaData{ message { time map_load_time float32 resolution uint32 width uint32 height "geometry_msgs.Pose" origin }},
94-
TopicSpec OccupancyGrid{ message { Header header MapMetaData info int8[] data }},
95-
TopicSpec Odometry{ message { Header header string child_frame_id "geometry_msgs.PoseWithCovariance" pose "geometry_msgs.TwistWithCovariance" twist }},
96-
TopicSpec Path{ message { Header header "geometry_msgs.PoseStamped"[] poses }},
97-
ServiceSpec GetMap{ request { } response { "nav_msgs.OccupancyGrid" map } },
98-
ServiceSpec GetPlan{ request { "geometry_msgs.PoseStamped" start "geometry_msgs.PoseStamped" goal float32 tolerance } response { "nav_msgs.Path" plan } },
99-
ServiceSpec SetMap{ request { "nav_msgs.OccupancyGrid" map "geometry_msgs.PoseWithCovarianceStamped" initial_pose } response { bool success } }
100-
}}
101-
}}
140+
nav_msgs:
141+
msgs:
142+
Path
143+
message
144+
'std_msgs/msg/Header'[] header
145+
'geometry_msgs/msg/PoseStamped'[] poses
146+
OccupancyGrid
147+
message
148+
'std_msgs/msg/Header'[] header
149+
'nav_msgs/msg/MapMetaData'[] info
150+
int8[] data
151+
Odometry
152+
message
153+
'std_msgs/msg/Header'[] header
154+
string child_frame_id
155+
'geometry_msgs/msg/PoseWithCovariance'[] pose
156+
'geometry_msgs/msg/TwistWithCovariance'[] twist
157+
GridCells
158+
message
159+
'std_msgs/msg/Header'[] header
160+
float32 cell_width
161+
float32 cell_height
162+
'geometry_msgs/msg/Point'[] cells
163+
MapMetaData
164+
message
165+
'builtin_interfaces/msg/Time'[] map_load_time
166+
float32 resolution
167+
uint32 width
168+
uint32 height
169+
'geometry_msgs/msg/Pose'[] origin
170+
srvs:
171+
SetMap
172+
request
173+
'nav_msgs/msg/OccupancyGrid'[] map
174+
'geometry_msgs/msg/PoseWithCovarianceStamped'[] initial_pose
175+
response
176+
bool success
177+
LoadMap
178+
request
179+
string map_url
180+
response
181+
'nav_msgs/msg/OccupancyGrid'[] map
182+
uint8 result
183+
GetPlan
184+
request
185+
'geometry_msgs/msg/PoseStamped'[] start
186+
'geometry_msgs/msg/PoseStamped'[] goal
187+
float32 tolerance
188+
response
189+
'nav_msgs/msg/Path'[] plan
190+
GetMap
191+
request
192+
response
193+
'nav_msgs/msg/OccupancyGrid'[] map
102194
```
103195
:bangbang::bangbang: This model doesn't allow the creation of 2 specification with the same name, although they have different types. That means a ROS model like the following one is not allow:
104196

105197
```
106-
PackageSet {
107-
Package my_msgs { Specs {
108-
TopicSpec hello { message { String data }},
109-
ServiceSpec hello { request { } response { String data }},
110-
}}
111-
}}
198+
my_msgs:
199+
msgs:
200+
hello:
201+
message
202+
String data
203+
srvs:
204+
hello
205+
request
206+
response
207+
String data
112208
```
113-
The reason is that when one of these objects have to be referenced during the definition of a node it will be imposible for the model to distinguish which is the correct one (both are defined as my_msgs.Hello and whitin the dame model file). For these cases we recommend to split the objects into two different model files.
209+
The reason is that when one of these objects have to be referenced during the definition of a node it will be imposible for the model to distinguish which is the correct one (both are defined as my_msgs/Hello and whitin the dame model file). For these cases we recommend to split the objects into two different model files.
114210

115211
The repository [RosCommonObjects](https://github.com/ipa320/RosCommonObjects) holds further examples.

0 commit comments

Comments
 (0)