Documentation review (#17)

* Modified Subscriber example. * Refs 3297. Improved Agent documentation. * misspellings and minor fixes * Updated readme image * Minnor changes * Refs #3599. Simplified Agent XML example. * Refs 3599. Fixed some grammatical and spelling erros. * Refs #3599. Attended pull request comments. * Update docs/agent.rst Co-Authored-By: julianbermudez <[email protected]> * Fix image.
eProsima · Nov 5, 2018 · 62b99ec · 62b99ec
1 parent 4192feb
commit 62b99ec
Show file tree

Hide file tree

Showing 19 changed files with 387 additions and 283 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ The *Micro XRCE-DDS Agent* acts on behalf of the *Micro XRCE-DDS Clients* and en
 
 *Micro XRCE-DDS* provides both, a plug and play *Micro XRCE-DDS Agent* and an API layer which allows you to implement your *Micro XRCE-DDS Clients*.
 
-![Architecture](docs/images/xrcedds_architecture.svg)
+![Architecture](docs/images/xrcedds_architecture.png)
 
 ## Documentation
 

diff --git a/docs/agent.rst b/docs/agent.rst
@@ -3,34 +3,86 @@
 Micro XRCE-DDS Agent
 ====================
 
-*Micro XRCE-DDS Agent* acts as a server between the DDS Network and *Micro XRCE-DDS Clients*.
-Agents receive messages containing operations from clients.
-Also agents keep track of the clients and the entities they create.
-The Agent uses the entities to interact with the DDS Global Data Space on behalf of the client.
+*Micro XRCE-DDS Agent* acts as a server between the DDS Network and *Micro XRCE-DDS Clients* applications.
+*Agents* receive messages containing operations from *Clients*.
+Also *Agents* keep track of the *Clients* and the entities they create.
+The *Agent* uses the entities to interact with the DDS Global Data Space on behalf of the *Clients*.
+
+The communication between a *Client* and an *Agent* currently supports UDP, TCP and Serial (dependent on the platform).
+While it is running, the *Agent* will attend any received request from the *Clients* and answers back with the result of that request.
+
+Configuration
+-------------
+
+There are several configuration parameters which can be set at **compile time** in order to configure the *Micro RTPS Agent*.
+These parameters can be selected as CMake flags (``-D<parameter>=<value>``) before the compilation.
+The following is a list of the aforementioned parameters:
+
+``CONFIG_RELIABLE_STREAM_DEPTH``
+    Specify the history of the reliable streams (default 16).
+
+``CONFIG_BEST_EFFORT_STREAM_DEPTH``
+    Specify the history of the best-effort streams (default 16).
+
+``CONFIG_HEARTBEAT_PERIOD``
+    Specify the ``HEARTBEAT`` message period in millisecond (default 200).
+
+``CONFIG_SERIAL_TRANSPORT_MTU``
+    Specify the `Maximum Transmission Unit` able to send and receive by Serial (default 512).
+
+``CONFIG_UDP_TRANSPORT_MTU``
+    Specify the `Maximum Transmission Unit` able to send and receive by UDP (default 512).
+
+``CONFIG_TCP_TRANSPORT_MTU``
+    Specify the `Maximum Transmission Unit` able to send and receive by TCP (default 512).
+
+``CONFIG_TCP_MAX_CONNECTIONS``
+    Specify the maximum number of connections, the *Agent* is able to manage (default 100).
+
+``CONFIG_TCP_MAX_BACKLOG_CONNECTIONS``
+    Specify the maximum number of incoming connections (pending to establish), the *Agent* is able to manage (default 100).
+
 
-The communication between a client and an agent currently supports UDP, TCP and serial (dependent on the platform).
-While running agent will attend any received request from your clients and answers back with the result of that request.
 
 Run an Agent
 ------------
 
-To run the agent you should build it as indicated in :ref:`installation_label`.
+To run the *Agent* you should build it as indicated in :ref:`installation_label`.
 Once it is built successfully you just need to launch it executing the following command.
 
-For serial communication: ::
+For Serial communication: ::
+
+    $ ./MicroXRCEAgent serial <device>
+
+For UDP communication: ::
+
+    $ ./MicroXRCEAgent udp <port> [<discovery-port>]
+
+For TCP communication: ::
+
+    $ ./MicroXRCEAgent tcp <port> [<discovery-port>]
+
+If the transport used is a reliable transport, the use of a best-effort stream over it is equivalent to use a reliable stream over a not reliable transport.
 
-    $ ./MicroXRCE-DDSAgent serial <device>
+For running the *Agent* is necessary that the file ``DEFAULT_FASTRTPS_PROFILES.xml`` is located in the runtime folder.
+This file contains XML profiles of `Participants`, `Topic`, `DataWriters` and `DataReaders` referenced by a ``profile_name``.
+The *Client* can use the aforementioned ``profile_name`` in order to create these entities using the reference representation.
+Let's see an example.
 
-For udp communication: ::
+The ``DEFAULT_FASTRTPS_PROFILES.xml`` contains the following participant profile:
 
-    $ ./MicroXRCE-DDSAgent udp <port>
+.. code-block:: xml
 
-For tcp communication: ::
+    <profiles>
+      <participant profile_name="default_xrce_participant_profile">
+        <rtps>
+          <name>default_participant</name>
+        </rtps>
+      </participant>
+    </profile>
 
-    $ ./MicroXRCE-DDSAgent tcp <port>
+therefore, the *Client* can use `default_xrce_participant_profile` as ``ref`` in the ``mr_buffer_create_participant_ref`` function.
 
-If the transport used is a reliability transport, the use of a best effort stream over it is equivalent to use a reliable stream over a not reliable transport.
+Default installation place this file along with the *Agent* executable into ``/usr/local/bin`` for Linux or ``C:/Program Files/microxrcedds_agent/bin`` for Windows.
 
-For running the agent is necessary that the file ``DEFAULT_FASTRTPS_PROFILES.xml`` be located in the folder where the
-agent is located. Default installation place this file along with the agent executable into ``/usr/local/bin``.