Hotfix/changelogs (#32)

* Refs #3807. Added fragmentation capability to streams. Updated to 1.1.0 (#21) * Refs #3807. Added fragmentation capability to streams. Updated to 1.1.0 * Refs #3807. Added pull request comments. (#22) * Product name. (#24) * Refs #4258. Changed product name. * Update docs/introduction.rst Co-Authored-By: julianbermudez <[email protected]> * Update docs/index.rst Co-Authored-By: julianbermudez <[email protected]> * Update docs/optimization.rst Co-Authored-By: julianbermudez <[email protected]> * Update docs/gen.rst Co-Authored-By: julianbermudez <[email protected]> * Update docs/shapes_demo.rst Co-Authored-By: julianbermudez <[email protected]> * Refs #3846. Title length fixes and agent usage changes. (#25) * Bugfix - discovery not supported on windows (#23) * Specified that discovery is not supported on windows. * Update docs/client.rst Co-Authored-By: lemunozm <[email protected]> * Update docs/client.rst * Update docs/client.rst Co-Authored-By: julianbermudez <[email protected]> * Refs #4310. Added docs to custom ip and port example modifications. (#26) * Transport documentation [4495] (#30) * Refs #4169. Add first version of Transport documentation. * Refs #4169. Add Serial Transport subsection. * Refs #4169. Finish transport docs. * Update docs/transport.rst Co-Authored-By: Luis Enrique Muñoz Martín <[email protected]> * Update docs/transport.rst Co-Authored-By: Luis Enrique Muñoz Martín <[email protected]> * Add review (#33) * Add review. * Update docs/transport.rst Co-Authored-By: Julián Bermúdez Ortega <[email protected]> * Refs #4495. Attend pull request comments. * Fix unsupported text format. * Update release notes. * Use different master file for pdf generation. * Unify case usage. * Add transport to content. * Update transport images.
eProsima · May 29, 2019 · 286cb8c · 286cb8c
1 parent d07b692
commit 286cb8c
Show file tree

Hide file tree

Showing 31 changed files with 895 additions and 197 deletions.
diff --git a/docs/_static/css/fiware_readthedocs.css b/docs/_static/css/fiware_readthedocs.css
@@ -62,5 +62,5 @@ src:url("Fonts/742885/39974d8a-38de-4853-a4d1-778234a08061.eot?#iefix") format("
 
 /* Custom width read the docs */
 .wy-nav-content {
-  max-width: none !important;
+  max-width: 800px !important;
 }
diff --git a/docs/agent.rst b/docs/agent.rst
@@ -1,9 +1,9 @@
 .. _micro_xrce_dds_agent_label:
 
-Micro XRCE-DDS Agent
-====================
+eProsima Micro XRCE-DDS Agent
+=============================
 
-*Micro XRCE-DDS Agent* acts as a server between the DDS Network and *Micro XRCE-DDS Clients* applications.
+*eProsima Micro XRCE-DDS Agent* acts as a server between the DDS Network and *eProsima 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*.
@@ -14,7 +14,7 @@ While it is running, the *Agent* will attend any received request from the *Clie
 Configuration
 -------------
 
-There are several configuration parameters which can be set at **compile time** in order to configure the *Micro RTPS Agent*.
+There are several configuration parameters which can be set at **compile time** in order to configure the *eProsima Micro XRCE-DDS Agent*.
 These parameters can be selected as CMake flags (``-D<parameter>=<value>``) before the compilation.
 The following is a list of the aforementioned parameters:
 
@@ -27,23 +27,13 @@ The following is a list of the aforementioned parameters:
 ``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).
 
 
-
 Run an Agent
 ------------
 

diff --git a/docs/client.rst b/docs/client.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,7 +29,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ["sphinx.ext.imgconverter"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -48,7 +48,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Micro XRCE-DDS'
+project = u'eProsima Micro XRCE-DDS'
 copyright = u'2018, eProsima'
 author = u'eProsima'
 
@@ -57,9 +57,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'1.0.0'
+version = u'1.0.2'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0'
+release = u'1.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -266,7 +266,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'MicroXRCE-DDS.tex', u'MicroXRCE-DDS Documentation',
+    ("contents", 'MicroXRCE-DDS.tex', u'MicroXRCE-DDS Documentation',
      u'eProsima', 'manual'),
 ]
 

diff --git a/docs/contents.rst b/docs/contents.rst
@@ -0,0 +1,34 @@
+Table Of contents
+=================
+
+.. toctree::
+    :caption: General
+
+    index
+
+.. toctree::
+   :caption: Installation manual
+
+   dependencies
+   installation
+
+.. toctree::
+   :caption: User Manual
+
+   introduction
+   quickstart
+   getting_started
+   shapes_demo
+   client
+   gen
+   agent
+   entities
+   operations
+   deployment
+   optimization
+   transport
+
+.. toctree::
+   :caption: Release Notes
+
+   notes
diff --git a/docs/dependencies.rst b/docs/dependencies.rst
@@ -3,15 +3,15 @@ External dependencies
 
 Required dependences
 --------------------
-*Micro XRCE-DDS Client* does not require external dependencies.
+*eProsima Micro XRCE-DDS Client* does not require external dependencies.
 
-*Micro XRCE-DDS Agent* requires the following packages to work:
+*eProsima Micro XRCE-DDS Agent* requires the following packages to work:
 
-Fast RTPS
+*eProsima Fast RTPS*
     *eProsima Fast RTPS* could be installed following the instructions:
     `eProsima Fast RTPS installation guide <http://eprosima-fast-rtps.readthedocs.io/en/latest/index.html#installation>`_.
 
-NOTE: *Micro XRCE-DDS Agent* is currently working under Fast RTPS develop branch until new Fast RTPS v1.7.0 Release is launched.
+NOTE: *eProsima Micro XRCE-DDS Agent* is currently working under *eProsima Fast RTPS* develop branch until new *eProsima Fast RTPS* v1.7.0 Release is launched.
 
 Windows
 ~~~~~~~
@@ -20,11 +20,11 @@ Microsoft Visual C++ 2015 or 2017
 
 Additional Dependencies
 -----------------------
-The following dependences are not necessary to run Micro XRCE-DDS.
+The following dependences are not necessary to run *eProsima Micro XRCE-DDS*.
 
 GTEST
     Gtest is the framework used to test the code through a complete set of tests.
 
 Java & Gradle
-    Java & Gradle is required to compile the code generation tool *Micro XRCE-DDS Gen*.
+    Java & Gradle is required to compile the code generation tool *eProsima Micro XRCE-DDS Gen*.
 
diff --git a/docs/deployment.rst b/docs/deployment.rst
@@ -3,14 +3,14 @@
 Deployment example
 ==================
 
-This part will show how to deploy a system using *Micro XRCE-DDS* in a real environment.
+This part will show how to deploy a system using *eProsima Micro XRCE-DDS* in a real environment.
 An example of this can be found into ``examples/Deployment`` folder.
 
 Previous tutorials are based in `all in one` examples, that is, examples that create entities, publish or subscribe and then delete the resources.
 One possible real purpose of this, consists in differentiate the logic of `creating entities` and the actions of `publishing and subscribing`.
 This can be done creating two differents *Clients*.
 One in charge of configure the entities in the *Agent*, and run possibly once, only for creating the entities at configuration time.
-And other/s that logs in the same session as the configure *Client* (sharing the entities) and only publishes or subscribes data.
+And other/s that logs in the same session as the configured *Client* (sharing the entities) and only publishes or subscribes data.
 
 This way allows to easily create *Clients* in a real scenario only with the purpose of send and receive data.
 Related to it, the concept of `profile` allows to build the *Client* library only with the chosen behavior (only publish or only subscribe, for example).
@@ -72,6 +72,6 @@ Subscriber
         :align: center
 
 Once the subscriber is configured, the `subscriber client` logs in the *Agent* `B`.
-As all their entities have been created previously, so it only need to configure the read after log in.
+As all their entities have been created previously, so it only needs to configure the read after log in.
 Once the data request message has been sent, the subscriber will receive the topics from the publisher through `DDS` world.
 
diff --git a/docs/entities.rst b/docs/entities.rst
@@ -3,9 +3,9 @@
 Entities
 ========
 
-The protocol under `Micro XRCE-DDS` (XRCE), defines entities that have a direct correspondence with their analogous actors on `Fast RTPS` (DDS).
-The entities manage the communication between `Micro XRCE-DDS Client` and the DDS Global Data Space.
-Entities are stored in the `Micro XRCE-DDS Agent` and the `Micro XRCE-DDS Client` can create, use and destroy these entities.
+The protocol under *eProsima Micro XRCE-DDS* (XRCE), defines entities that have a direct correspondence with their analogous actors on *eProsima Fast RTPS* (DDS).
+The entities manage the communication between *eProsima Micro XRCE-DDS Client* and the DDS Global Data Space.
+Entities are stored in the *eProsima Micro XRCE-DDS Agent* and the *eProsima Micro XRCE-DDS Client* can create, use and destroy these entities.
 
 The entities are uniquely identified by an ID called `Object ID`. The `Object ID` is the way a *Client* refers to them inside an *Agent*.
 In most of the *Client* request operations is necessary to specify an ID referring to one of the *Client* entities stored in the *Agent*.

diff --git a/docs/gen.rst b/docs/gen.rst
@@ -1,14 +1,14 @@
 .. _microxrceddsgen_label:
 
-Micro XRCE-DDS Gen
-==================
+eProsima Micro XRCE-DDS Gen
+===========================
 
-*Micro XRCE-DDS Gen* is a Java application used to generate source code for the *eProsima Micro XRCE-DDS* software.
+*eProsima Micro XRCE-DDS Gen* is a Java application used to generate source code for the *eProsima Micro XRCE-DDS* software.
 
 This tool is able to generate from a given IDL specification file, the C struct associated with the
 Topic, as well as, the serialization and deserialization methods.
 Also, it has the possibility to generate a sample demo that works with the proposed topic.
-As an example of the powerful of this tool, the following shows the source code generated from the ShapeDemo IDL file.
+As an example of the potential of this tool, the following shows the source code generated from the ShapeDemo IDL file.
 
 ::
 
@@ -64,7 +64,7 @@ it will generate the following header file and its corresponding source:
     #endif // _ShapeType_H_
 
 
-*Micro XRCE-DDS Gen* is also able to generate both *publisher* and *subscriber* source code examples, related with the topic specified in the IDL file, by adding the flag ``-example``: ::
+*eProsima Micro XRCE-DDS Gen* is also able to generate both *publisher* and *subscriber* source code examples, related with the topic specified in the IDL file, by adding the flag ``-example``: ::
 
     $ microxrceddsgen -example <file.idl>
 
@@ -75,7 +75,7 @@ and the ``READ_ACCESS_PROFILE`` option for the *subscriber*.
 Installation
 ------------
 
-In order to use *Micro XRCE-DDS Gen*, it is needed to follow the next steps:
+In order to use *eProsima Micro XRCE-DDS Gen*, it is needed to follow the next steps:
 
 1. Install its dependencies:
 
@@ -95,5 +95,5 @@ In order to use *Micro XRCE-DDS Gen*, it is needed to follow the next steps:
 Notes
 -----
 
-At the present time, *Micro XRCE-DDS Gen* only supports Structs composed of integer, string, array and sequence types
-even though it is planned to enhance the capabilities of the *Micro XRCE-DDS Gen* tool in a near future.
+At the present time, *eProsima Micro XRCE-DDS Gen* only supports Structs composed of integer, string, array and sequence types
+even though it is planned to enhance the capabilities of the *eProsima Micro XRCE-DDS Gen* tool in a near future.
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -2,7 +2,7 @@
 
 Getting started
 ===============
-This page shows how to get started with the *Micro XRCE-DDS Client* development.
+This page shows how to get started with the *eProsima Micro XRCE-DDS Client* development.
 We will create a *Client* that can publish and subscribe a topic.
 This tutorial has been extract from the examples found into ``examples/PublisherHelloWorld`` and ``examples/SubscriberHelloWorld``.
 
@@ -29,7 +29,7 @@ This is done automatically by :ref:`microxrceddsgen_label`: ::
 
 Initialize a Session
 ^^^^^^^^^^^^^^^^^^^^
-In the source example file, we include the generated type code, in order to have access to its serialization/deserialization functions along to the write function.
+In the source example file, we include the generated type code, in order to have access to its serialization/deserialization functions along to the writing function.
 Also, we will specify the max buffer for the streams and its historical associated for the reliable streams.
 
 .. code-block:: C
@@ -185,7 +185,7 @@ The configuration about how these `DataReaders` and data writers works is contai
 Agent response
 ^^^^^^^^^^^^^^
 In operations such as create session, create entity or request data from the *Agent*,
-an status is sent from the *Agent* to the *Client* indicating what happened.
+a status is sent from the *Agent* to the *Client* indicating what happened.
 
 For `Create session` or `Detele session` operations the status value is stored into the ``session.info.last_request_status``.
 For the rest of the operations, the status are sent to the input reliable stream ``0x80``, that is, the first input reliable stream created, with index 0.
@@ -206,7 +206,7 @@ The different status values that the *Agent* can send to the *Client* are the fo
     UXR_STATUS_ERR_RESOURCES
     UXR_STATUS_NONE (never send, only used when the status is known)
 
-The status can be handle by the ``on_status_callback`` callback (configured in ``uxr_set_status_callback`` function) or by the ``run_session_until_all_status`` as we will see.
+The status can be handled by the ``on_status_callback`` callback (configured in ``uxr_set_status_callback`` function) or by the ``run_session_until_all_status`` as we will see.
 
 .. code-block:: C
 
@@ -218,8 +218,8 @@ The status can be handle by the ``on_status_callback`` callback (configured in `
         return 1;
     }
 
-The ``run_session`` functions are the main functions of the `Micro RTP Client` library.
-They performs serveral tasks: send the stream data to the *Agent*, listen data from the *Agent*, call callbacks, and manage the reliable connection.
+The ``run_session`` functions are the main functions of the *eProsima Micro XRCE-DDS Client* library.
+They perform serveral tasks: send the stream data to the *Agent*, listen data from the *Agent*, call callbacks, and manage the reliable connection.
 There are five variations of ``run_session`` function:
 - ``uxr_run_session_time``
 - ``uxr_run_session_until_timeout``
@@ -233,8 +233,8 @@ After call this function, the status can be read from the ``status`` array previ
 
 Write Data
 ^^^^^^^^^^
-Once we have created a valid data writer entity, we can write data into the DDS Global Data Space using the write operation.
-For creating a message with data, first we must to decide which stream we want to use, and write that topic in this stream.
+Once we have created a valid data writer entity, we can write data into the DDS Global Data Space using the writing operation.
+For creating a message with data, first we must decide which stream we want to use, and write that topic in this stream.
 
 .. code-block:: C
 
@@ -254,7 +254,7 @@ If the stream is available and the topic fits in it, the function will initializ
 Once the ``ucdrBuffer`` is prepared, the topic can be serialized into it.
 We are careless about ``uxr_prepare_output_stream`` return value because the serialization only will occur if the ``ucdrBuffer`` is valid.
 
-After the write function, as happened with the creation of entities, the topic has been serialized into the buffer but it has not been sent yet.
+After the writing function, as happened with the creation of entities, the topic has been serialized into the buffer but it has not been sent yet.
 To send the topic is necessary call to a ``run_session`` function.
 In this case, we call to ``uxr_run_session_until_confirmed_delivery`` that will wait until the message was confirmed or until the timeout has been reached.
 
@@ -273,7 +273,7 @@ Current implementation sends one topic to the *Client* for each read data operat
 
 In order to configure how the *Agent* will send the topic, we must set the input stream. In this case, we use the input reliable stream previously defined.
 ``datareader_id`` corresponds with the `DataDeader` entity used for receiving the data.
-The ``delivery_control`` parameter is optional, and allows to specify how the data will be delivered to the *Client*.
+The ``delivery_control`` parameter is optional, and allows specifying how the data will be delivered to the *Client*.
 For the example purpose, we set it as `unlimited`, so any number HelloWorld topic will be delivered to the *Client*.
 
 The ``run_session`` function will call the topic callback each time a topic will be received from the *Agent*.

diff --git a/docs/images/agent_transport_architecture.puml b/docs/images/agent_transport_architecture.puml
@@ -0,0 +1,59 @@
+@startuml
+
+skinparam roundcorner 20
+skinparam monochrome true
+
+package "server layer" <<Rectangle>> {
+    class Server 
+}
+
+interface Server {
+    +virtual void <b>on_create_client()</b> = 0
+    +virtual void <b>on_delete_client()</b> = 0
+    +virtual ClientKey <b>get_client_key()</b> = 0
+    +virtual EndPoint <b>get_source()</b> = 0
+    ....
+    -virtual bool <b>init()</b> = 0
+    -virtual bool <b>close()</b> = 0
+    -virtual bool <b>recv_message()</b> = 0
+    -virtual bool <b>send_message()</b> = 0
+    -virtual int <b>get_error()</b> = 0
+}
+
+package "transport layer" <<Rectangle>> {
+    class UDPServerBase
+}
+
+class UDPServerBase {
+    +void <b>on_create_client()</b> override
+    +void <b>on_delete_client()</b> override
+    +virtual ClientKey <b>get_client_key()</b> = 0
+    +virtual EndPoint <b>get_source()</b> = 0
+}
+
+package "platform layer" <<Rectangle>> {
+    class UDPServerLinux
+    class UDPServerWindows
+}
+
+class UDPServerLinux {
+    -bool <b>init()</b> override
+    -bool <b>close()</b> override
+    -bool <b>recv_message()</b> override
+    -bool <b>send_message()</b> override
+    -int <b>get_error()</b> override
+}
+
+class UDPServerWindows {
+    -bool <b>init()</b> override
+    -bool <b>close()</b> override
+    -bool <b>recv_message()</b> override
+    -bool <b>send_message()</b> override
+    -int <b>get_error()</b> override
+}
+
+Server <|-- UDPServerBase
+UDPServerBase <|-- UDPServerLinux
+UDPServerBase <|-- UDPServerWindows
+
+@enduml
diff --git a/docs/images/agent_transport_architecture.svg b/docs/images/agent_transport_architecture.svg