Skip to content

Commit cacf885

Browse files
cferreiragonzcferreiragonz
committed
Refs #20629: Update CLI and examples
Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>
1 parent 301f139 commit cacf885

1 file changed

Lines changed: 65 additions & 82 deletions

File tree

‎docs/fastddscli/cli/cli.rst‎

Lines changed: 65 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,9 @@ discovery
5151

5252
This command launches a |SERVER| (or |BACKUP|) for :ref:`Discovery Server <discovery_server>`. This *server* will manage
5353
the discovery phases of the |CLIENTS| which are connected to it.
54-
*Clients* must know how to reach the *server*, which is accomplished by specifying an IP address, the *servers* GUID
55-
prefix, and a transport protocol like UDP or TCP.
56-
*Servers* do not need any prior knowledge of their *clients*, but require a GUID prefix, and the listening IP address
54+
*Clients* must know how to reach the *server*, which is accomplished by specifying an IP address, a port and
55+
a transport protocol like UDP or TCP.
56+
*Servers* do not need any prior knowledge of their *clients*, but require the listening IP address and port
5757
where they may be reached.
5858
For more information on the different *Fast DDS* discovery mechanisms and how to configure them, please refer to
5959
:ref:`discovery`.
@@ -72,29 +72,26 @@ On a shell, execute:
7272

7373
.. code-block:: bash
7474
75-
fastdds discovery -i {0-255} [optional parameters]
75+
fastdds discovery [optional parameters]
7676
7777
Where the parameters are:
7878

7979
+--------------------------+-------------------------------------------------------------------------------------------+
8080
| Option | Description |
8181
+==========================+===========================================================================================+
82-
| ``-h -help`` | Produce help message. |
83-
+--------------------------+-------------------------------------------------------------------------------------------+
84-
| ``-i --server-id`` | Unique server identifier. Specifies zero based server position in |br| |
85-
| | ``ROS_DISCOVERY_SERVER`` environment variable. Must be an integer in range [0, 255] |br| |
86-
| | If not specified, it must be defined using a XML configuration file. |
82+
| ``-h --help`` | Produce help message with examples. |
8783
+--------------------------+-------------------------------------------------------------------------------------------+
8884
| ``-l --udp-address`` | IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any |br| |
8985
| | (0.0.0.0/::0). Instead of an address, a DNS domain name can be specified. |
9086
+--------------------------+-------------------------------------------------------------------------------------------+
91-
| ``-p --udp-port`` | UDP port chosen to listen the clients. Defaults to '11811'. |
87+
| ``-p --udp-port`` | UDP port chosen to listen the clients. Defaults to '11811'. Only one server can be |br| |
88+
| | configured using the default UDP port. |
9289
+--------------------------+-------------------------------------------------------------------------------------------+
9390
| ``-t --tcp-address`` | IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an |br| |
94-
| | address, a DNS domain name can be specified. Defaults to localhost (127.0.0.1). |
91+
| | address, a DNS domain name can be specified. Defaults to any (0.0.0.0). |
9592
+--------------------------+-------------------------------------------------------------------------------------------+
9693
| ``-q --tcp-port`` | TCP port chosen to listen the clients. Defaults to '42100'. Only one server can be |br| |
97-
| | configured using the default port. |
94+
| | configured using the default TCP port. |
9895
+--------------------------+-------------------------------------------------------------------------------------------+
9996
| ``-b --backup`` | Creates a BACKUP *server* (see :ref:`discovery_protocol`) |
10097
+--------------------------+-------------------------------------------------------------------------------------------+
@@ -103,6 +100,11 @@ Where the parameters are:
103100
| | that specific parameter. The default profile in the XML file is loaded except if |br| |
104101
| | a specific profile name is specified: ``profile_name@xml_file`` |
105102
+--------------------------+-------------------------------------------------------------------------------------------+
103+
| ``-i --server-id`` | Unique server identifier. Its functionality its deprecated. It can be used to select |br| |
104+
| | a fixed GUID in the form shown below. Must be an integer in range [0, 255]. |
105+
+--------------------------+-------------------------------------------------------------------------------------------+
106+
107+
Executing the command without parameters will launch a *server* with default UDP values.
106108

107109
The output is:
108110

@@ -111,8 +113,7 @@ The output is:
111113
### Server is running ###
112114
Participant Type: <SERVER|BACKUP>
113115
Security: <YES|NO>
114-
Server ID: <server-id>
115-
Server GUID prefix: 44.53.<server-id-in-hex>.5f.45.50.52.4f.53.49.4d.41
116+
Server GUID prefix: <Default>|44.53.<server-id-in-hex>.5f.45.50.52.4f.53.49.4d.41
116117
Server Addresses: UDPv4:[<ip-address>]:<port>
117118
UDPv6:[<ip-address>]:<port>
118119
TCPv4:[<ip-address>]:<physical-port>-<logical-port>
@@ -131,13 +132,12 @@ Once the *server* is instantiated, the *clients* can be configured either progra
131132
Examples
132133
^^^^^^^^
133134

134-
1. Launch a **default server** with id 0 (first on ``ROS_DISCOVERY_SERVER``)
135-
listening on all available interfaces on UDP port '11811'. Only one
136-
server can use default values per machine.
135+
1. Launch a **default server** listening on all available interfaces on UDP port '11811'.
136+
Only one server can use default values per machine.
137137

138138
.. code-block:: bash
139139
140-
fastdds discovery -i 0
140+
fastdds discovery
141141
142142
Output:
143143

@@ -146,17 +146,15 @@ Examples
146146
### Server is running ###
147147
Participant Type: SERVER
148148
Security: NO
149-
Server ID: 0
150-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
149+
Server GUID prefix: <Default GUID>
151150
Server Addresses: UDPv4:[0.0.0.0]:11811
152151
153-
2. Launch a default server with id 1 (second on ``ROS_DISCOVERY_SERVER``)
154-
listening on localhost with UDP port 14520. Only localhost clients
155-
can reach the server defining as `ROS_DISCOVERY_SERVER=;127.0.0.1:14520` .
152+
2. Launch a default server listening on localhost with UDP port 14520.
153+
Only localhost clients can reach the server defining as `ROS_DISCOVERY_SERVER=127.0.0.1:14520`.
156154

157155
.. code-block:: bash
158156
159-
fastdds discovery -i 1 -l 127.0.0.1 -p 14520
157+
fastdds discovery -l 127.0.0.1 -p 14520
160158
161159
Output:
162160

@@ -165,8 +163,7 @@ Examples
165163
### Server is running ###
166164
Participant Type: SERVER
167165
Security: NO
168-
Server ID: 1
169-
Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41
166+
Server GUID prefix: <Default GUID>
170167
Server Addresses: UDPv4:[127.0.0.1]:14520
171168
172169
This same output can be obtained loading the following XML configuration file ``DiscoveryServerCLI.xml``:
@@ -180,12 +177,31 @@ Examples
180177
181178
fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml
182179
183-
3. Launch a default server with id 1 (second on ``ROS_DISCOVERY_SERVER``)
180+
3. Launch a default server listening on all available interfaces on TCP port '42100'.
181+
Only one server can use default values per machine.
182+
183+
.. code-block:: bash
184+
185+
fastdds discovery -t
186+
187+
Output:
188+
189+
.. code-block:: bash
190+
191+
### Server is running ###
192+
Participant Type: SERVER
193+
Security: NO
194+
Server GUID prefix: <Default GUID>
195+
Server Addresses: TCPv4:[0.0.0.0]:42100
196+
197+
.. _Deprecated_CLI: https://fast-dds.docs.eprosima.com/en/v2.14.0/fastddscli/cli/cli.html
198+
199+
4. Launch a default server with GUID corresponding to id 1 (see `Deprecated_CLI`_)
184200
listening on IPv6 address ``2a02:ec80:600:ed1a::3`` with UDP port 14520.
185201

186202
.. code-block:: bash
187203
188-
fast-discovery-serverd-1.0.1.exe -i 1 -l 2a02:ec80:600:ed1a::3 -p 14520
204+
fastdds discovery -i 1 -l 2a02:ec80:600:ed1a::3 -p 14520
189205
190206
Output:
191207

@@ -194,18 +210,16 @@ Examples
194210
### Server is running ###
195211
Participant Type: SERVER
196212
Security: NO
197-
Server ID: 1
198213
Server GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41
199214
Server Addresses: UDPv6:[2a02:ec80:600:ed1a::3]:14520
200215
201-
4. Launch a default server with id 2 (third on ``ROS_DISCOVERY_SERVER``)
202-
listening on WiFi (192.168.36.34) and Ethernet (172.20.96.1) local
203-
interfaces with UDP ports 8783 and 51083 respectively
216+
5. Launch a default server listening on WiFi (192.168.36.34) and Ethernet (172.20.96.1)
217+
local interfaces with UDP ports 8783 and 51083 respectively
204218
(addresses and ports are made up for the example).
205219

206220
.. code-block:: bash
207221
208-
fastdds discovery -i 2 -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083
222+
fastdds discovery -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083
209223
210224
Output:
211225

@@ -214,8 +228,7 @@ Examples
214228
### Server is running ###
215229
Participant Type SERVER
216230
Security: NO
217-
Server ID: 2
218-
Server GUID prefix: 44.53.02.5f.45.50.52.4f.53.49.4d.41
231+
Server GUID prefix: <Default GUID>
219232
Server Addresses: UDPv4:[192.168.36.34]:8783
220233
UDPv4:[172.20.96.1]:51083
221234
@@ -226,14 +239,12 @@ Examples
226239
227240
fastdds discovery -x second_participant_profile_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml
228241
229-
5. Launch a default server with id 3 (fourth on ``ROS_DISCOVERY_SERVER``)
230-
listening on 172.30.144.1 with UDP port 12345 and provided with a
231-
backup file. If the server crashes it will automatically restore its
232-
previous state when re-enacted.
242+
6. Launch a default server listening on 172.30.144.1 with UDP port 12345 and provided with a
243+
backup file. If the server crashes it will automatically restore its previous state when re-enacted.
233244

234245
.. code-block:: bash
235246
236-
fastdds discovery -i 3 -l 172.30.144.1 -p 12345 -b
247+
fastdds discovery -l 172.30.144.1 -p 12345 -b
237248
238249
Output:
239250

@@ -242,31 +253,10 @@ Examples
242253
### Server is running ###
243254
Participant Type BACKUP
244255
Security: NO
245-
Server ID: 3
246-
Server GUID prefix: 44.53.03.5f.45.50.52.4f.53.49.4d.41
256+
Server GUID prefix: <Default GUID>
247257
Server Addresses: UDPv4:[172.30.144.1]:12345
248258
249-
6. Launch a default server with id 0 (first on ``ROS_DISCOVERY_SERVER``)
250-
listening on localhost with UDP port 14520. Only localhost clients
251-
can reach the server defining as `ROS_DISCOVERY_SERVER=localhost:14520`.
252-
253-
.. code-block:: bash
254-
255-
fastdds discovery -i 0 -l localhost -p 14520
256-
257-
Output:
258-
259-
.. code-block:: bash
260-
261-
### Server is running ###
262-
Participant Type: SERVER
263-
Security: NO
264-
Server ID: 0
265-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
266-
Server Addresses: UDPv4:[127.0.0.1]:14520
267-
268-
7. Launch a secure server with id 0 (first on ``ROS_DISCOVERY_SERVER``)
269-
listening on all available interfaces on UDP port '11811'.
259+
7. Launch a secure server listening on all available interfaces on UDP port '11811'.
270260

271261
.. code-block:: bash
272262
@@ -279,16 +269,14 @@ Examples
279269
### Server is running ###
280270
Participant Type: SERVER
281271
Security: YES
282-
Server ID: 0
283-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
272+
Server GUID prefix: <Default GUID>
284273
Server Addresses: UDPv4:[0.0.0.0]:11811
285274
286-
8. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) reading
287-
specific `profile_name` configuration from XML file.
275+
8. Launch a server reading specific `profile_name` configuration from XML file.
288276

289277
.. code-block:: bash
290278
291-
fastdds discovery -i 0 -x profile_name@[PATH_TO_FILE]/config.xml
279+
fastdds discovery -x profile_name@[PATH_TO_FILE]/config.xml
292280
293281
Output:
294282

@@ -297,16 +285,14 @@ Examples
297285
### Server is running ###
298286
Participant Type: SERVER
299287
Security: NO
300-
Server ID: 0
301-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
288+
Server GUID prefix: <Default GUID>
302289
Server Addresses: UDPv4:[127.0.0.1]:56542
303290
304-
9. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening
305-
on localhost on default TCP port '42100'.
291+
9. Launch a server listening on localhost on default TCP port '42100'.
306292

307293
.. code-block:: bash
308294
309-
fastdds discovery -i 0 -t 127.0.0.1
295+
fastdds discovery -t 127.0.0.1
310296
311297
Output:
312298

@@ -315,17 +301,15 @@ Examples
315301
### Server is running ###
316302
Participant Type: SERVER
317303
Security: NO
318-
Server ID: 0
319-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
304+
Server GUID prefix: <Default GUID>
320305
Server Addresses: TCPv4:[127.0.0.1]:42100-42100
321306
322-
10. Launch a server with id 0 (first on ``ROS_DISCOVERY_SERVER``) listening
323-
on localhost and WiFi (192.163.6.34). Two TCP ports need to be
324-
specified because TCP transports cannot share ports.
307+
10. Launch a server listening on localhost and WiFi (192.163.6.34). Two TCP ports need to be
308+
specified because transports cannot share ports.
325309

326310
.. code-block:: bash
327311
328-
fastdds discovery -i 0 -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101
312+
fastdds discovery -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101
329313
330314
Output:
331315

@@ -334,8 +318,7 @@ Examples
334318
### Server is running ###
335319
Participant Type: SERVER
336320
Security: NO
337-
Server ID: 0
338-
Server GUID prefix: 44.53.00.5f.45.50.52.4f.53.49.4d.41
321+
Server GUID prefix: <Default GUID>
339322
Server Addresses: TCPv4:[127.0.0.1]:42100-42100
340323
TCPv4:[192.163.6.34]:42101-42101
341324
@@ -347,7 +330,7 @@ Examples
347330
.. note::
348331
A server can be instantiated just by passing the port arguments ``-p``
349332
and ``-q``. Fast DDS CLI will use the default values of the IP addresses,
350-
that is, ``0.0.0.0`` for UDP and ``127.0.0.1`` for TCP.
333+
that is, ``0.0.0.0`` for UDP and ``0.0.0.0`` for TCP.
351334

352335
.. _cli_shm:
353336

0 commit comments

Comments
 (0)