diff --git a/README.md b/README.md index 48494b80..4e1d3da4 100644 --- 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 index c4782ee0..d1333fbd 100644 --- 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=``) 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 + +For UDP communication: :: + + $ ./MicroXRCEAgent udp [] + +For TCP communication: :: + + $ ./MicroXRCEAgent tcp [] + +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 +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 +.. code-block:: xml -For tcp communication: :: + + + + default_participant + + + - $ ./MicroXRCE-DDSAgent tcp +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``. diff --git a/docs/client.rst b/docs/client.rst index 928b7dce..afde215f 100644 --- a/docs/client.rst +++ b/docs/client.rst @@ -5,18 +5,18 @@ Micro XRCE-DDS Client In *Micro XRCE-DDS*, a *Client* can communicate with DDS Network as any other DDS actor could do. *Clients* can publish and subscribe to data Topics in the DDS Global Data Space. -*Micro XRCE-DDS* provides you with a C API to create *Micro XRCE-DDS Clients*. +*Micro XRCE-DDS* provides you with a C API to create *Micro XRCE-DDS Clients* application. All functions needed to set up the *Client* can be found into ``client.h`` header. This is the only header you need to include. Profiles -------- -The client library follows a profile concept that enables to choose add or remove some features in configuration time. -This allows to reduce the client library size, if there are features that are not used. +The *Client* library follows a profile concept that enables to choose, add or remove some features in configuration time. +This allows to customize the *Client* library size, if there are features that are not used. The profiles can be chosen in ``client.config`` and start with the prefix ``PROFILE``. As part of these profiles, you can choose between several transport layers. -Communication with the agent is done through the transport you choose. +Communication with the *Agent* is done through the transport you choose. The implementation of the transport depends of the platform. The next tables show the current implementation. @@ -34,8 +34,8 @@ See the current transport implementations as an example for a new custom transpo Configuration ------------- -There are several definitions for configuring and building of the client library at **compile time**. -These allow you to create a version of the library according to your requirements. +There are several definitions for configuring and building of the *Client* library at **compile time**. +These definitions allow you to create a version of the library according to your requirements. These definitions can be modified at ``client.config`` file. For incorporating the changes to your project, is necessary to run the ``cmake`` command every time the definitions change. @@ -43,7 +43,7 @@ For incorporating the changes to your project, is necessary to run the ``cmake`` Enables or disables the functions related to create entities by reference. ``PROFILE_CREATE_ENTITIES_XML=`` - Enables or disables the functions related to create entities by xml. + Enables or disables the functions related to create entities by XML. ``PROFILE_READ_ACCESS=`` Enables or disables the functions related to read topics. @@ -55,13 +55,13 @@ For incorporating the changes to your project, is necessary to run the ``cmake`` Enables or disables the functions the discovery feature. ``PROFILE_UDP_TRANSPORT=`` - Enables or disables the posibility to connect with the agent by UDP. + Enables or disables the posibility to connect with the *Agent* by UDP. ``PROFILE_TCP_TRANSPORT=`` - Enables or disables the posibility to connect with the agent by TCP. + Enables or disables the posibility to connect with the *Agent* by TCP. ``PROFILE_SERIAL_TRANSPORT=`` - Enables or disables the posibility to connect with the agent by Serial. + Enables or disables the posibility to connect with the *Agent* by Serial. ``CONFIG_MAX_OUTPUT_BEST_EFFORT_STREAMS=`` Configures the maximun output best effort streams that a session could have. @@ -72,7 +72,7 @@ For incorporating the changes to your project, is necessary to run the ``cmake`` The calls to ``uxr_create_output_reliable_stream`` function for a session must be less or equal that this value. ``CONFIG_MAX_INPUT_BEST_EFFORT_STREAMS=`` - Configure the maximun input best effort streams that a session could have. + Configures the maximun input best effort streams that a session could have. The calls to ``uxr_create_input_best_effort_stream`` function for a session must be less or equal that this value. ``CONFIG_MAX_INPUT_RELIABLE_STREAMS=`` @@ -94,21 +94,21 @@ For incorporating the changes to your project, is necessary to run the ``cmake`` It is measured in milliseconds. ``CONFIG_MACHINE_ENDIANNESS=`` - This value must be correspond to the memory endianness of the device in which the client is running. + This value must be correspond to the memory endianness of the device in which the *Client* is running. `0` implies that the machine is little endian and `1` implies big endian. It this entry is not in the ``client.config`` the build system will get this value from the machine that is compiling the library. - For cross compiling, you must set this value manually with the endianness of the device that run the client. + For cross compiling, you must set this value manually with the endianness of the device that run the *Client*. ``CONFIG_UDP_TRANSPORT_MTU=`` - This value corresponds to the `Maximun Transmission Unit` able to send and receive by UDP. + This value corresponds to the `Maximum Transmission Unit` able to send and receive by UDP. Internally a buffer is created with this size. ``CONFIG_TCP_TRANSPORT_MTU=`` - This value corresponds to the `Maximun Transmission Unit` able to send and receive by TCP. + This value corresponds to the `Maximum Transmission Unit` able to send and receive by TCP. Internally a buffer is created with this size. ``CONFIG_SERIAL_TRANSPORT_MTU=`` - This value corresponds to the `Maximun Transmission Unit` able to send and receive by Serial. + This value corresponds to the `Maximum Transmission Unit` able to send and receive by Serial. Internally a buffer is created proportional to this size. Streams @@ -161,9 +161,9 @@ Initializes a session structure. Once this function is called, a ``create_session`` call can be performed. :session: Session structure where manage the session data. -:key: The identifying key of the client. - All clients connected to an agent must have different key. -:comm: Communication used for connecting to the agent. +:key: The key identifier of the *Client*. + All *Clients* connected to an *Agent* must have different key. +:comm: Communication used for connecting to the *Agent*. All different transports have a common attribute uxrCommunication. This parameter can not be shared between active sessions. @@ -173,10 +173,10 @@ Once this function is called, a ``create_session`` call can be performed. void uxr_set_status_callback(uxrSession* session, uxrOnStatusFunc on_status_func, void* args); -Assigns the callback for the agent status messages. +Assigns the callback for the *Agent* status messages. :session: Session structure previously initialized. -:on_status_func: Function callback that will be called when a valid status message comes from the agent. +:on_status_func: Function callback that will be called when a valid status message comes from the *Agent*. :args: User pointer data. The args will be provided to ``on_status_func`` function. @@ -190,7 +190,7 @@ Assigns the callback for topics. The topics will be received only if a ``request_data`` function has been called. :session: Session structure previously initialized. -:on_status_func: Function callback that will be called when a valid data message comes from the agent. +:on_status_func: Function callback that will be called when a valid data message comes from the *Agent*. :args: User pointer data. The args will be provided to ``on_topic_func`` function. @@ -200,8 +200,8 @@ The topics will be received only if a ``request_data`` function has been called. bool uxr_create_session(uxrSession* session); -Creates a new session with the agent. -This function logs in a session, enabling any other XRCE communication with the agent. +Creates a new session with the *Agent*. +This function logs in a session, enabling any other XRCE communication with the *Agent*. :session: Session structure previously initialized. @@ -213,7 +213,7 @@ This function logs in a session, enabling any other XRCE communication with the Deletes a session previously created. All `XRCE` entities created with the session will be removed. -This function logs out a session, disabling any other `XRCE` communication with the agent. +This function logs out a session, disabling any other `XRCE` communication with the *Agent*. :session: Session structure previously initialized. @@ -293,13 +293,12 @@ Flashes all output streams sending the data through the transport. void uxr_run_session_time(uxrSession* session, int time); -The main library function. This function processes the internal functionality of a session. This implies: 1. Flashes all output streams sending the data through the transport. 2. If there is any reliable stream, it will perform the asociated reliable behaviour to ensure the communication. -3. Listens messages from the agent and call the associated callback if exists (a topic callback or a status callback). +3. Listens messages from the *Agent* and call the associated callback if exists (a topic callback or an status callback). The ``time`` suffix function version will perform these actions and will listen messages for a ``time`` duration. Only when the time waiting for a message overcome the ``time`` duration, the function finishes. @@ -315,13 +314,12 @@ The function will return ``true`` if the sent data have been confirmed, ``false` void uxr_run_session_until_timeout(uxrSession* session, int timeout); -The main library function. This function processes the internal functionality of a session. This implies: 1. Flashes all output streams sending the data through the transport. 2. If there is any reliable stream, it will perform the asociated reliable behaviour to ensure the communication. -3. Listens messages from the agent and call the associated callback if exists (a topic callback or a status callback). +3. Listens messages from the *Agent* and call the associated callback if exists (a topic callback or an status callback). The ``_until_timeout`` suffix function version will perform these actions until receiving one message. Once the message has been received or the timeout has been reached, the function finishes. @@ -338,20 +336,19 @@ The function will return ``true`` if has received a message, ``false`` if the ti bool uxr_run_session_until_confirm_delivery(uxrSession* session, int timeout); -The main library function. This function processes the internal functionality of a session. This implies: 1. Flashes all output streams sending the data through the transport. 2. If there is any reliable stream, it will perform the asociated reliable behaviour to ensure the communication. -3. Listenes messages from the agent and call the associated callback if exists (a topic callback or a status callback). +3. Listenes messages from the *Agent* and call the associated callback if exists (a topic callback or an status callback). -The ``_until_confirm_delivery`` suffix function version will perform these actions during ``timeout`` duration -or until the output reliable streams confirm that the sent messages have been received by the agent. +The ``_until_confirm_delivery`` suffix function version will perform these actions during ``timeout`` +or until the output reliable streams confirm that the sent messages have been received by the *Agent*. The function will return ``true`` if the sent data have been confirmed, ``false`` otherwise. :session: Session structure previously initialized. -:timeout: Maximun time for waiting to a new message, in milliseconds. +:timeout: Maximun waiting time for a new message, in milliseconds. For waiting without timeout, set the value to ``UXR_TIMEOUT_INF`` ------ @@ -360,24 +357,23 @@ The function will return ``true`` if the sent data have been confirmed, ``false` bool uxr_run_session_until_all_status(uxrSession* session, int timeout, const uint16_t* request_list, uint8_t* status_list, size_t list_size); -The main library function. This function processes the internal functionality of a session. This implies: 1. Flashes all output streams sending the data through the transport. 2. If there is any reliable stream, it will perform the asociated reliable behaviour to ensure the communication. -3. Listenes messages from the agent and call the associated callback if exists (a topic callback or a status callback). +3. Listenes messages from the *Agent* and call the associated callback if exists (a topic callback or an status callback). The ``_until_all_status`` suffix function version will perform these actions during ``timeout`` duration or until all requested status had been received. The function will return ``true`` if all status have been received and all of them have the value ``UXR_STATUS_OK`` or ``UXR_STATUS_OK_MATCHED``, ``false`` otherwise. :session: Session structure previously initialized. -:timeout: Maximun time for waiting to a new message, in milliseconds. +:timeout: Maximun waiting time for a new message, in milliseconds. For waiting without timeout, set the value to ``UXR_TIMEOUT_INF`` -:request_list: An array of request to confirm with a status. +:request_list: An array of request to confirm with an status. :status_list: An uninitialized array with the same size as ``request_list`` where the status values will be written. - The position of a status in the list corresponds to the request at the same position in ``request_list``. + The position of an status in the list corresponds to the request at the same position in ``request_list``. :list_size: The size of ``request_list`` and ``status_list`` arrays. ------ @@ -386,20 +382,19 @@ The function will return ``true`` if all status have been received and all of th bool uxr_run_session_until_one_status(uxrSession* session, int timeout, const uint16_t* request_list, uint8_t* status_list, size_t list_size); -The main library function. This function processes the internal functionality of a session. This implies: 1. Flashes all output streams sending the data through the transport. 2. If there is any reliable stream, it will perform the asociated reliable behaviour to ensure the communication. -3. Listenes messages from the agent and call the associated callback if exists (a topic callback or a status callback). +3. Listenes messages from the *Agent* and call the associated callback if exists (a topic callback or an status callback). The ``_until_one_status`` suffix function version will perform these actions during ``timeout`` duration or until one requested status had been received. The function will return ``true`` if one status have been received and has the value ``UXR_STATUS_OK`` or ``UXR_STATUS_OK_MATCHED``, ``false`` otherwise. :session: Session structure previously initialized. -:timeout: Maximun time for waiting to a new message, in milliseconds. +:timeout: Maximun waiting time for a new message, in milliseconds. For waiting without timeout, set the value to ``UXR_TIMEOUT_INF`` :request_list: An array of request that can be confirmed. :status_list: An uninitialized array with the same size as ``request_list`` where the statu value will be written. @@ -410,7 +405,7 @@ The function will return ``true`` if one status have been received and has the v Create entities by XML profile `````````````````````````````` -These functions are enabled when ``PROFILE_CREATE_ENTITIES_XML`` is enabled in the ``client.config`` file. +These functions are enabled when ``PROFILE_CREATE_ENTITIES_XML`` is selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/session/create_entities_xml.h``. ------ @@ -419,7 +414,7 @@ The declaration of these functions can be found in ``uxr/client/profile/session/ uint16_t uxr_buffer_create_participant_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uint16_t domain, const char* xml, uint8_t mode); -Creates a `participant` entity in the agent. +Creates a `participant` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -428,11 +423,9 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_PARTICIPANT_ID`` -:xml: A xml representation of the new entity. +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ @@ -440,7 +433,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux uint16_t uxr_buffer_create_topic_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId participant_id, const char* xml, uint8_t mode); -Creates a `topic` entity in the agent. +Creates a `topic` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -449,11 +442,11 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_TOPIC_ID`` -:xml: A xml representation of the new entity. +:participant_id: The identifier of the associated participant. + The type must be ``UXR_PARTICIPANT_ID`` +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ @@ -461,7 +454,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux uint16_t uxr_buffer_create_publisher_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId participant_id, const char* xml, uint8_t mode); -Creates a `publisher` entity in the agent. +Creates a `publisher` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -470,11 +463,11 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_PUBLISHER_ID`` -:xml: A xml representation of the new entity. +:participant_id: The identifier of the associated participant. + The type must be ``UXR_PARTICIPANT_ID`` +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ @@ -482,7 +475,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux uint16_t uxr_buffer_create_subscriber_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId participant_id, const char* xml, uint8_t mode); -Creates a `publisher` entity in the agent. +Creates a `subscriber` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -491,11 +484,11 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_SUBSCRIBER_ID`` -:xml: A xml representation of the new entity. +:participant_id: The identifier of the associated participant. + The type must be ``UXR_PARTICIPANT_ID`` +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ @@ -503,7 +496,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux uint16_t uxr_buffer_create_datawriter_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId publisher_id, const char* xml, uint8_t mode); -Creates a `datawriter_id` entity in the agent. +Creates a `datawriter` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -512,11 +505,11 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_DATAWRITER_ID`` -:xml: A xml representation of the new entity. +:publisher_id: The identifier of the associated participant. + The type must be ``UXR_PUBLISHER_ID`` +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ @@ -524,7 +517,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux uint16_t uxr_buffer_create_datareader_xml(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId subscriber_id, const char* xml, uint8_t mode); -Creates a `datareader` entity in the agent. +Creates a `datareader` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -533,17 +526,17 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. The type must be ``UXR_DATAREADER_ID`` -:xml: A xml representation of the new entity. +:subscriber_id: The identifier of the associated participant. + The type must be ``UXR_SUBSCRIBER_ID`` +:xml: A XML representation of the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ Create entities by reference profile ```````````````````````````````````` -These functions are enabled when ``PROFILE_CREATE_ENTITIES_REF`` is enabled in the ``client.config`` file. +These functions are enabled when ``PROFILE_CREATE_ENTITIES_REF`` is selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/session/create_entities_ref.h``. ------ @@ -552,7 +545,7 @@ The declaration of these functions can be found in ``uxr/client/profile/session/ uint16_t uxr_buffer_create_participant_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, const char* ref, uint8_t mode); -Creates a `datareader` entity in the agent. +Creates a `participant` entity in the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. @@ -560,18 +553,79 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux :stream_id: The output stream ID where the message will be written. :object_id: The identifier of the new entity. Later, the entity can be referenced with this id. - The type must be ``UXR_DATAREADER_ID`` -:xml: A xml representation of the new entity. + The type must be ``UXR_PARTICIPANT_ID`` +:ref: A reference to the new entity. +:mode: Determines the creation entity mode. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. + +------ + +.. code-block:: c + + uint16_t uxr_buffer_create_topic_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId participant_id, const char* ref, uint8_t mode); + +Creates a `topic` entity in the *Agent*. +The message is only written into the stream buffer. +To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. + +:session: Session structure previously initialized. +:stream_id: The output stream ID where the message will be written. +:object_id: The identifier of the new entity. + Later, the entity can be referenced with this id. + The type must be ``UXR_TOPIC_ID`` +:participant_id: The identifier of the associated participant. + The type must be ``UXR_PARTICIPANT_ID`` +:ref: A reference to the new entity. +:mode: Determines the creation entity mode. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. + +------ + +.. code-block:: c + + uint16_t uxr_buffer_create_datawriter_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId publisher_id, const char* ref, uint8_t mode); + +Creates a `datawriter` entity in the *Agent*. +The message is only written into the stream buffer. +To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. + +:session: Session structure previously initialized. +:stream_id: The output stream ID where the message will be written. +:object_id: The identifier of the new entity. + Later, the entity can be referenced with this id. + The type must be ``UXR_DATAWRITER_ID`` +:publisher_id: The identifier of the associated publisher. + The type must be ``UXR_PUBLISHER_ID`` +:ref: A reference to the new entity. :mode: Determines the creation entity mode. - Currently, only soported ``UXR_REPLACE``. - It will delete the entity previously in the agent if exists. - A ``0`` value, implies that only creates the entity if it does not exists. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. + +------ + +.. code-block:: c + + uint16_t uxr_buffer_create_datareader_ref(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id, uxrObjectId subscriber_id, const char* ref, uint8_t mode); + +Creates a `datareader` entity in the *Agent*. +The message is only written into the stream buffer. +To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. + +:session: Session structure previously initialized. +:stream_id: The output stream ID where the message will be written. +:object_id: The identifier of the new entity. + Later, the entity can be referenced with this id. + The type must be ``UXR_DATAREADER_ID``. +:subscriber_id: The identifier of the associated subscriber. + The type must be ``UXR_SUBSCRIBER_ID``. +:ref: A reference to the new entity. +:mode: Determines the creation entity mode. + The Creation Mode Table decribes the entities creation behaviour according with the ``UXR_REUSE`` and ``UXR_REPLACE`` flags. ------ Create entities common profile `````````````````````````````` -These functions are enabled when ``PROFILE_CREATE_ENTITIES_XML`` or ``PROFILE_CREATE_ENTITIES_REF`` are enabled in the ``client.config`` file. +These functions are enabled when ``PROFILE_CREATE_ENTITIES_XML`` or ``PROFILE_CREATE_ENTITIES_REF`` are selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/session/common_create_entities.h``. ------ @@ -580,19 +634,19 @@ The declaration of these functions can be found in ``uxr/client/profile/session/ uint16_t uxr_buffer_delete_entity(uxrSession* session, uxrStreamId stream_id, uxrObjectId object_id); -Removes a entity. +Removes an entity. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. :session: Session structure previously initialized. :stream_id: The output stream ID where the message will be written. -:object_id: The identifier that will be deleted. +:object_id: The identifier of the object which will be deleted. ------ Read access profile ``````````````````` -These functions are enabled when PROFILE_READ_ACCESS is enabled in the ``client.config`` file. +These functions are enabled when ``PROFILE_READ_ACCESS`` is selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/session/read_access.h``. ------ @@ -601,18 +655,18 @@ The declaration of these functions can be found in ``uxr/client/profile/session/ uint16_t uxr_buffer_request_data(uxrSession* session, uxrStreamId stream_id, uxrObjectId datareader_id, uxrStreamId data_stream_id, uxrDeliveryControl* delivery_control); -This function requests a read from a datareader of the agent. +This function requests a read from a datareader of the *Agent*. The returned value is an identifier of the request. All received topic will have the same request identifier. The topics will be received at the callback topic through the ``run_session`` function. -If there is no error with the request data, the topics will be received generating a status callback with the value ``UXR_STATUS_OK``. -If there is an error, a status error will be sent by the agent. +If there is no error with the request data, the topics will be received generating an status callback with the value ``UXR_STATUS_OK``. +If there is an error, an status error will be sent by the *Agent*. The message is only written into the stream buffer. To send the message is necessary call to ``uxr_flash_output_streams`` or to ``uxr_run_session`` function. :session: Session structure previously initialized. :stream_id: The output stream ID where the message will be written. -:object_id: The Data Reader ID that will read the topic from the DDS World. +:object_id: The `datareader` ID that will read the topic from the DDS World. :data_stream_id: The input stream ID where the data will be received. :delivery_control: Optional information about how the delivery must be. A ``NULL`` value is accepted, in this case, only one topic will be received. @@ -621,7 +675,7 @@ To send the message is necessary call to ``uxr_flash_output_streams`` or to ``ux Write access profile ```````````````````` -These functions are enabled when PROFILE_WRITE_ACCESS is enabled in the ``client.config`` file. +These functions are enabled when ``PROFILE_WRITE_ACCESS`` is selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/session/write_access.h``. ------ @@ -632,17 +686,16 @@ The declaration of these functions can be found in ``uxr/client/profile/session/ struct ucdrBuffer* mb_topic, uint32_t topic_size); Requests a writing into a specific output stream. -For that this function will initialize a ``ucdrBuffer`` struct where a topic of ``topic_size`` size must be serialized. -If the returned value is ``true``, exists the necessary gap for writing a ``topic_size`` bytes into the stream. -If the returned value is ``false``, the topic can no be serialized into the stream. +For this function will initialize an ``ucdrBuffer`` struct where a topic of ``topic_size`` size must be serialized. +Whether the necessary gap for writting a ``topic_size`` bytes into the stream, the returned value is ``true``, otherwise ``false``. The topic will be sent in the next ``run_session`` function. -NOTE: All `topic_size` bytes requested will be sent to the agent after a ``run_session`` call, no matter if the ``ucdrBuffer`` has been used or not. +NOTE: All ``topic_size`` bytes requested will be sent to the *Agent* after a ``run_session`` call, no matter if the ``ucdrBuffer`` has been used or not. :session: Session structure previously initialized. :stream_id: The output stream ID where the message will be written. -:datawriter_id: The DataWriter ID that will write the topic to the DDS World. -:mb_topic: A ``ucdrBuffer`` struct used to serialize the topic. +:datawriter_id: The `datawriter` ID that will write the topic to the DDS World. +:mb_topic: An ``ucdrBuffer`` struct used to serialize the topic. This struct points to a requested gap into the stream. :topic_size: The bytes that will be reserved in the stream. @@ -650,15 +703,13 @@ NOTE: All `topic_size` bytes requested will be sent to the agent after a ``run_s Discovery profile ``````````````````` -The discovery profile allows to discover agents in the network by UDP. -The reachable agents will respond to the discovery call sending information about them, as their ip and port. +The discovery profile allows to discover *Agents* in the network by UDP. +The reachable *Agents* will respond to the discovery call sending information about them, as their IP and port. There is two modes: multicast and unicast. -The discovery phase can be performed before the `uxr_create_session` call in order to determine the agent to connect with. -These functions are enabled when PROFILE_DISCOVERY is enabled in the ``client.config`` file. +The discovery phase can be performed before the `uxr_create_session` call in order to determine the *Agent* to connect with. +These functions are enabled when ``PROFILE_DISCOVERY`` is selected in the ``client.config`` file. The declaration of these functions can be found in ``uxr/client/profile/discovery/discovery.h``. -bool uxr_discovery_agents_multicast(uint32_t attemps, int period, uxrOnAgentFound on_agent_func, void* args, uxrAgentAddress* chosen); - ------ .. code-block:: c @@ -666,17 +717,17 @@ bool uxr_discovery_agents_multicast(uint32_t attemps, int period, uxrOnAgentFoun bool uxr_discovery_agents_multicast(uint32_t attempts, int period, uxrOnAgentFound on_agent_func, void* args, uxrAgentAddress* chosen); -Searches into the network using multicast ip "239.255.0.2" and port 7400 (default used by the agent) in order to discover agents. +Searches into the network using multicast IP "239.255.0.2" and port 7400 (default used by the *Agent*) in order to discover *Agents*. :attempts: The number of attempts to send the discovery message to the network. :period: How often will be sent the discovery message to the network. -:on_agent_func: The callback function that will be called when an agent was discovered. +:on_agent_func: The callback function that will be called when an *Agent* was discovered. The callback returns a boolean value. - A `true` means that the discovery rutine will be end and exit. - The current agent will be selected as *chosen*. - A `false` implies that the discovery rutine must to continue searching agents. + A `true` means that the discovery routine will be finished. + The current *Agent* will be selected as *chosen*. + A `false` implies that the discovery routine must continue searching *Agents*. :args: User arguments passed to the callback function. -:chosen: If the callback function was returned `true`, this value will contains the agent value of the callback. +:chosen: If the callback function was returned `true`, this value will contain the *Agent* value of the callback. ------ @@ -686,19 +737,19 @@ Searches into the network using multicast ip "239.255.0.2" and port 7400 (defaul uxrOnAgentFound on_agent_func, void* args, uxrAgentAddress* chosen, const uxrAgentAddress* agent_list, size_t agent_list_size); -Searches into the network using a list of unicast directions in order to discover agents. +Searches into the network using a list of unicast directions in order to discover *Agents*. :attempts: The number of attempts to send the discovery message to the network. :period: How often will be sent the discovery message to the network. -:on_agent_func: The callback function that will be called when an agent was discovered. +:on_agent_func: The callback function that will be called when an *Agent* is discovered. The callback returns a boolean value. - A ``true`` means that the discovery rutine will be end and exit. - The current agent will be selected as *chosen*. - A ``false`` implies that the discovery rutine must to continue searching agents. + A ``true`` means that the discovery routine will be finished. + The current *Agent* will be selected as *chosen*. + A ``false`` implies that the discovery routine must continue searching *Agents*. :args: User arguments passed to the callback function. -:chosen: If the callback function was returned ``true``, this value will contains the agent value of the callback. -:agent_list: The list of address where discover agent. - By default the agents will be listen at **port 7400** the discovery messages.. +:chosen: If the callback function was returned ``true``, this value will contain the *Agent* value of the callback. +:agent_list: The list of addresses where discover *Agent*. + By default the *Agents* will be listen at **port 7400** the discovery messages. :agent_list_size: The size of the ``agent_list``. ------ @@ -706,7 +757,7 @@ Searches into the network using a list of unicast directions in order to discove Topic serialization ``````````````````` Functions to serialize and deserialize topics. -These functions are generated automatically by `Micro XRCE-DDS Gen` utility over an idl file with a topic `TOPICTYPE`. +These functions are generated automatically by `Micro XRCE-DDS Gen` utility over an IDL file with a topic `TOPICTYPE`. The declaration of these function can be found in the generated file ``TOPICTYPE.h``. ------ @@ -715,10 +766,10 @@ The declaration of these function can be found in the generated file ``TOPICTYPE bool TOPICTYPE_serialize_topic(struct ucdrBuffer* writer, const TOPICTYPE* topic); -It serializes a topic into a ucdrBuffer. +Serializes a topic into an ``ucdrBuffer``. The returned value indicates if the serialization was successful. -:writer: A ucdrBuffer representing the buffer for the serialization. +:writer: An ``ucdrBuffer`` representing the buffer for the serialization. :topic: Struct to serialize. ------ @@ -727,10 +778,10 @@ The returned value indicates if the serialization was successful. bool TOPICTYPE_deserialize_topic(struct ucdrBuffer* reader, TOPICTYPE* topic); -It deserializes a topic from a ucdrBuffer. +Deserializes a topic from an ucdrBuffer. The returned value indicates if the serialization was successful. -:reader: A ucdrBuffer representing the buffer for the deserialization. +:reader: An ucdrBuffer representing the buffer for the deserialization. :topic: Struct where deserialize. ------ @@ -739,7 +790,7 @@ The returned value indicates if the serialization was successful. uint32_t TOPICTYPE_size_of_topic(const TOPICTYPE* topic, uint32_t size); -It counts the number of bytes that the topic will need in a `ucdrBuffer`. +Counts the number of bytes that the topic will need in an `ucdrBuffer`. :topic: Struct to count the size. :size: Number of bytes already written into the `ucdrBuffer`. @@ -759,11 +810,11 @@ The declaration of these functions can be found in ``uxr/client/core/session/str uxrStreamId uxr_stream_id(uint8_t index, uxrStreamType type, uxrStreamDirection direction); Creates an stream identifier. -This function does not create a new stream, only creates its identifier to be used in the `Client` API. +This function does not create a new stream, only creates its identifier to be used in the *Client* API. :index: Identifier of the stream, its value correspond to the creation order of the stream, different for each `type`. -:type: The type of the stream, it can be UXR_BEST_EFFORT_STREAM or UXR_RELIABLE_STREAM. -:direction: Represents the direccion of the stream, it can be UXR_INPUT_STREAM or MT_OUTPUT_STREAM. +:type: The type of the stream, it can be ``UXR_BEST_EFFORT_STREAM`` or ``UXR_RELIABLE_STREAM``. +:direction: Represents the direccion of the stream, it can be ``UXR_INPUT_STREAM`` or ``UXR_OUTPUT_STREAM``. ------ @@ -772,14 +823,14 @@ This function does not create a new stream, only creates its identifier to be us uxrStreamId uxr_stream_id_from_raw(uint8_t stream_id_raw, uxrStreamDirection direction); Creates an stream identifier. -This function does not create a new stream, only creates its identifier to be used in the `Client` API. +This function does not create a new stream, only creates its identifier to be used in the *Client* API. -:raw: identifier of the stream. +:stream_id_raw: Identifier of the stream. It goes from 0 to 255. 0 is for internal library use. 1 to 127, for best effort. 128 to 255, for reliable. -:direction: Represents the direccion of the stream, it can be UXR_INPUT_STREAM or MT_OUTPUT_STREAM. +:direction: Represents the direction of the stream, it can be ``UXR_INPUT_STREAM`` or ``MT_OUTPUT_STREAM``. ------ @@ -789,16 +840,10 @@ This function does not create a new stream, only creates its identifier to be us Creates a identifier for reference an entity. -:id: identifier of the object, different for each `type` - (Can be several ids with the same id if they have different types) +:id: Identifier of the object, different for each `type` + (can be several IDs with the same ID if they have different types). :type: The type of the entity. - It can be: - * UXR_PARTICIPANT_ID - * UXR_TOPIC_ID - * UXR_PUBLISHER_ID - * UXR_SUBSCRIBER_ID - * UXR_DATAWRITER_ID - * UXR_DATAREADER_ID + It can be: ``UXR_PARTICIPANT_ID``, ``UXR_TOPIC_ID``, ``UXR_PUBLISHER_ID``, ``UXR_SUBSCRIBER_ID``, ``UXR_DATAWRITER_ID`` or ``UXR_DATAREADER_ID``. ------ @@ -813,58 +858,46 @@ The common init transport functions follow the next nomenclature. .. code-block:: c - bool uxr_init_udp_transport(UDPTransport* transport, const char* ip, uint16_t port); + bool uxr_init_udp_transport(uxrUDPTransport* transport, uxrUDPPlatform* platform, const char* ip, uint16_t port); Initializes an UDP connection. :transport: The uninitialized structure used for managing the transport. - This structure must to be accesible during the connection. -:ip: Agent ip. -:port: Agent port. + This structure must to be accessible during the connection. +:platform: Structure which contains platform dependent members. +:ip: *Agent* IP. +:port: *Agent* port. ------ .. code-block:: c - bool uxr_init_tcp_transport(TCPTransport* transport, const char* ip, uint16_t port); + bool uxr_init_tcp_transport(uxrTCPTransport* transport, uxrTCPPlatform* platform, const char* ip, uint16_t port); Initializes a TCP connection. -If the TCP is used, the behaviour of best effort streams will be similiar to reliable streams in UDP. - -:transport: The uninitialized structure used for managing the transport. - This structure must to be accesible during the connection. -:ip: Agent ip. -:port: Agent port. - ------- - -.. code-block:: c - - bool uxr_init_serial_transport(SerialTransport* transport, const char* device, uint8_t remote_addr, uint8_t local_addr); - -Initializes a Serial connection using a device. +If the TCP is used, the behaviour of best effort streams will be similar to reliable streams in UDP. :transport: The uninitialized structure used for managing the transport. - This structure must to be accesible during the connection. -:device: Device used for the serial connection. -:remote_addr: Identifier of the agent in the serial connection. - By default, the agent identifier in a serial is 0. -:local_addr: Identifier of the client in the serial connection. + This structure must to be accessible during the connection. +:platform: Structure which contains platform dependent members. +:ip: *Agent* IP. +:port: *Agent* port. ------ .. code-block:: c - bool uxr_init_serial_transport_fd(SerialTransport* transport, const int fd, uint8_t remote_addr, uint8_t local_addr); + bool uxr_init_serial_transport(uxrSerialTransport* transport, uxrSerialPlatform* platform, const int fd, uint8_t remote_addr, uint8_t local_addr); Initializes a Serial connection using a file descriptor :transport: The uninitialized structure used for managing the transport. - This structure must to be accesible during the connection. + This structure must to be accessible during the connection. +:platform: Structure which contains platform dependent members. :fd: File descriptor of the serial connection. Usually, the fd comes from the ``open`` OS function. -:remote_addr: Identifier of the agent in the serial connection. - By default, the agent identifier in a serial is 0. -:local_addr: Identifier of the client in the serial connection. +:remote_addr: Identifier of the *Agent* in the serial connection. + By default, the *Agent* identifier in a serial is 0. +:local_addr: Identifier of the *Client* in the serial connection. ------ @@ -876,3 +909,19 @@ Closes a transport previously opened. `PROTOCOL` can be ``udp``, ``tcp`` or ``se :transport: The transport to close. +Creation Mode Table +################### + +The following table summarize the behaviour of the *Agent* under entity creation request. + +=========================== ================= ========== +**Creation flags** **Entity exists** **Result** +=========================== ================= ========== +Don't care NO Entity is created. +``0`` YES No action is taken, and ``UXR_STATUS_ERR_ALREADY_EXITS`` is returned. +``UXR_REPLACE`` YES Existing entity is deleted, requested entity is created and ``UXR_STATUS_OK`` is returned. +``UXR_REUSE`` YES | If entity matches no action is taken and ``UXR_STATUS_OK_MATCHED`` is returned. + | If entity does not match no action is taken and ``UXR_STATUS_ERR_MISMATCH`` is returned. +``UXR_REUSE | UXR_REPLACE`` YES | If entity matches no action is taken and ``UXR_STATUS_OK_MATCHED`` is returned. + | If entity does not match, exiting entity is deleted, requested entity is created and ``UXR_STATUS_OK`` is returned. +=========================== ================= ========== diff --git a/docs/conf.py b/docs/conf.py index 1052cb9d..903736d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,7 +49,7 @@ # General information about the project. project = u'Micro XRCE-DDS' -copyright = u'2017, eProsima' +copyright = u'2018, eProsima' author = u'eProsima' # The version info for the project you're documenting, acts as replacement for @@ -59,7 +59,7 @@ # The short X.Y version. version = u'1.0.0' # The full version, including alpha/beta/rc tags. -release = u'1.0.0Beta2' +release = u'1.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/dependencies.rst b/docs/dependencies.rst index 4cbe9ca7..29208757 100644 --- a/docs/dependencies.rst +++ b/docs/dependencies.rst @@ -3,9 +3,9 @@ External dependencies Required dependences -------------------- -*Micro XRCE-DDS - Client* does not require external dependencies. +*Micro XRCE-DDS Client* does not require external dependencies. -*Micro XRCE-DDS - Agent* requires following packages to work: +*Micro XRCE-DDS Agent* requires the following packages to work: Fast RTPS *eProsima Fast RTPS* could be installed following the instructions: @@ -13,8 +13,8 @@ Fast RTPS Windows ~~~~~~~ -Microsoft Visual C++ 2013 or 2015 - *eProsima Micro XRCE-DDS* is supported on Windows over Microsoft Visual C++ 2013 or 2015 framework. +Microsoft Visual C++ 2015 or 2017 + *eProsima Micro XRCE-DDS* is supported on Windows over Microsoft Visual C++ 2015 or 2017 framework. Additional Dependencies ----------------------- diff --git a/docs/deployment.rst b/docs/deployment.rst index c2d49789..36012a21 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -3,20 +3,20 @@ Deployment example ================== -This part will show how to deploy a system using *Micro XRCE-DDS* in a real enviroment. +This part will show how to deploy a system using *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 for configurating 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. +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. -This way allows to create easy clients in production only with the purpose of send and receive data. -Related to it, exists the concept of `profile` that allows to build the client library only with the behavior chosen (only publish or only subscribe, for example). +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). See :ref:`micro_xrce_dds_client_label` for more information about this. -Next diagram shows an example about how to configure the enviroment using a `configurator client`. +Next diagram shows an example about how to configure the environment using a `configurator client`. Initial state ------------- @@ -25,7 +25,7 @@ Initial state :width: 600 px :align: center -The enviroment contains two agents (is perfectly possible to use only one agent too), and two clients, one for publishing and other subscribing. +The environment contains two *Agents* (is perfectly possible to use only one *Agent* too), and two *Clients*, one for publishing and another for subscribing. Configurate the publisher @@ -35,11 +35,11 @@ Configurate the publisher :width: 600 px :align: center -In this state a `configurator client` is connected to the agent `A` with the `client key` that will be used by the future `publisher client` (0xAABBCCDD). -Once a session is logged in, the `configurator client` creates all necesary entities for the `publisher client`. +In this state a `configurator client` is connected to the *Agent* `A` with the `client key` that will be used by the future `publisher client` (0xAABBCCDD). +Once a session is logged in, the `configurator client` creates all the necessary entities for the `publisher client`. This implies the creation of `participant`, `topic`, `publisher`, and `datawriter` entities. These entities have a representation as DDS entities, and can be reached now from the DDS world. -That implies that a possible `subscriber DDS entity` could be already listening topics if it match with a `publisher DDS entity` through `DDS` world. +That implies that a possible `subscriber DDS entity` could already be listening topics if it matches with a `publisher DDS entity` through `DDS` world. Publish ------- @@ -47,10 +47,10 @@ Publish :width: 600 px :align: center -Then, the `publisher client` is connected to the agent `A`. -This client logs in session with its client key (0xAABBCCDD). +Then, the `publisher client` is connected to the *Agent* `A`. +This *Client* logs in session with its *Client* key (0xAABBCCDD). At that moment, it can use all entities created related to this `client key`. -Because all entities that it uses were created successful by the `configurator client`, the `publisher client` can inmediately publish to `DDS`. +Because all entities that it used were successfully created by the `configurator client`, the `publisher client` can immediately publish to `DDS`. Configurate the subscriber @@ -60,7 +60,7 @@ Configurate the subscriber :width: 600 px :align: center -Again, the `configurator client` connects and logs in, this time to agent `B`, now with the subscriber's key (0x11223344). +Again, the `configurator client` connects and logs in, this time to *Agent* `B`, now with the subscriber's key (0x11223344). In this case, the entities that the `configurator client` creates are a `participant`, a `topic`, a `subscriber`, and a `datareader`. The entities created by the `configuraton client` will be available until the session is deleted. @@ -71,7 +71,7 @@ Subscriber :width: 600 px :align: center -Once the subscriber is configured, the `subscriber client` logs in the agent `B`. +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. 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 index 8884ccc0..4199b47c 100644 --- a/docs/entities.rst +++ b/docs/entities.rst @@ -7,8 +7,8 @@ The protocol under `Micro XRCE-DDS` (XRCE), defines entities that have a direct 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 entities are uniquely identified by an ID called `Object ID`. `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`. +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*. Type of Entities ---------------- diff --git a/docs/gen.rst b/docs/gen.rst index 1ef69e57..4925ee41 100644 --- a/docs/gen.rst +++ b/docs/gen.rst @@ -7,7 +7,7 @@ Micro XRCE-DDS Gen 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 of generate a sample demo that works with proposed topic. +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. :: @@ -64,18 +64,18 @@ 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 speficified in the IDL file adding the flag ``-example``: :: +*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 -In order to use these examples, the client library must be compiled with the ``WRITE_ACCESS_PROFILE`` option for the *publisher* +In order to use these examples, the *Client* library must be compiled with the ``WRITE_ACCESS_PROFILE`` option for the *publisher* and the ``READ_ACCESS_PROFILE`` option for the *subscriber*. Installation ------------ -For use *Micro XRCE-DDS Gen* you have to follow the next steps: +In order to use *Micro XRCE-DDS Gen*, it is needed to follow the next steps: 1. Install its dependencies: diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 5a4f1117..8f32b742 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -39,7 +39,7 @@ Also, we will specify the max buffer for the streams and its historical associat #define STREAM_HISTORY 8 #define BUFFER_SIZE UXR_CONFIG_UDP_TRANSPORT_MTU * STREAM_HISTORY -Before create a Session we need to indicate the transport to use (the agent must be configured for listening from udp at port 2018). +Before create a Session we need to indicate the transport to use (the *Agent* must be configured for listening from UDP at port 2018). .. code-block:: C @@ -51,7 +51,7 @@ Before create a Session we need to indicate the transport to use (the agent must return 1; } -Next, we will create a session that allow us interact with the agent: +Next, we will create a session that allows us interact with the *Agent*: .. code-block:: C @@ -64,10 +64,10 @@ Next, we will create a session that allow us interact with the agent: return 1; } -The first function ``uxr_init_session`` initializes the ``Session`` structure with the transport and the `Client Key` (the session identifier for an agent). -The ``uxr_set_topic_callback`` function is for registering the function ``on_topic`` which has been called when the `Client` receive a topic. -Once the session has been initialized, we can send the first message for login the client in agent side: ``uxr_create_session``. -This function will try to connect with the agent by ``CONFIG_MAX_SESSION_CONNECTION_ATTEMPTS`` attempts (the value can be configurable at ``client.config``). +The first function ``uxr_init_session`` initializes the ``session`` structure with the transport and the `Client Key` (the session identifier for an *Agent*). +The ``uxr_set_topic_callback`` function is for registering the function ``on_topic`` which will be called when the `Client` receive a topic. +Once the session has been initialized, we can send the first message for login the `Client` in the *Agent* side: ``uxr_create_session``. +This function will try to connect with the *Agent* by ``CONFIG_MAX_SESSION_CONNECTION_ATTEMPTS`` attempts (configurable at ``client.config``). Optionally, we also could add a status callback with the function ``uxr_set_status_callback``, but for the purpose of this example we do not need it. @@ -82,14 +82,14 @@ In this case, we will use two, both reliables, for input and output. uint8_t input_reliable_stream_buffer[BUFFER_SIZE]; uxrStreamId reliable_in = uxr_create_input_reliable_stream(&session, input_reliable_stream_buffer, BUFFER_SIZE, STREAM_HISTORY); -In order to publish and/or subscribe a topic, we need to create a hierarchy of XRCE entities in the agent side. -These entities will be created from the client. +In order to publish and/or subscribe a topic, we need to create a hierarchy of XRCE entities in the *Agent* side. +These entities will be created from the *Client*. .. image:: images/entities_hierarchy.svg Setup a Participant ^^^^^^^^^^^^^^^^^^^ -For establishing DDS communication we need to create a `Participant` entity for the `Client` in the `Agent`. +For establishing DDS communication we need to create a `Participant` entity for the `Client` in the *Agent*. We can do this calling *Create participant* operation: .. code-block:: C @@ -106,11 +106,11 @@ We can do this calling *Create participant* operation: In any `XRCE Operation` that creates an entity, an `Object ID` is necessary. It is used to represent and manage the entity in the *Client* side. -In this case we will create the entity by its XML description, but also could be done by a reference of the entity in the agent. +In this case we will create the entity by its XML description, but also could be done by a reference of the entity in the *Agent*. Each operation, returns a `Request ID`. This identifier of the operation can be used later for associating the status with the operation. In this case, the operation has been written into the stream ``reliable_out``. -Later, in the ``run_session`` function, the data written in the stream will be sent to the agent. +Later, in the ``run_session`` function, the data written in the stream will be sent to the *Agent*. Creating topics ^^^^^^^^^^^^^^^^ @@ -129,7 +129,7 @@ Once the `Participant` has been created, we can use `Create topic` operation for As any other XRCE Operation used to create an entity, an Object ID must be specified to represent the entity. The ``participant_id`` is the participant where the Topic will be registered. -In order to determine which topic will be used, an XML is sent to the agent for creating and defining the Topic in the DDS Global Data Space. +In order to determine which topic will be used, an XML is sent to the *Agent* for creating and defining the Topic in the DDS Global Data Space. That definition consists of a name and a type. Publishers & Subscribers @@ -147,7 +147,7 @@ We create a publisher or subscriber on a participant entity, so it is necessary const char* subscriber_xml = ""; uint16_t subscriber_req = uxr_buffer_create_subscriber_xml(&session, reliable_out, subscriber_id, participant_id, subscriber_xml, UXR_REPLACE); -The `Publisher` and `Subscriber` xml information is given when the `DataWriter` and `DataReader` be created. +The `Publisher` and `Subscriber` XML information is given when the `DataWriter` and `DataReader` are created. DataWriters & DataReaders ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -190,8 +190,7 @@ an 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. -The different status values that the agent can send to the client are the following: -(You can see the definitions in ``uxr/client/core/sesssion/session_info.h`` file) +The different status values that the *Agent* can send to the *Client* are the following (defined in ``uxr/client/core/session/session_info.h``): .. code-block:: C @@ -220,7 +219,7 @@ The status can be handle by the ``on_status_callback`` callback (configured in ` } 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. +They performs 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`` @@ -253,7 +252,7 @@ The function ``uxr_prepare_output_stream`` requests a writing for a topic of ``t with a ``datawriter_id`` (correspond to the data writer entity used for sending the data in the `DDS World`). If the stream is available and the topic fits in it, the function will initialize the ``ucdrBuffer`` structure ``mb``. 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`` +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. To send the topic is necessary call to a ``run_session`` function. @@ -262,8 +261,8 @@ In this case, we call to ``uxr_run_session_until_confirmed_delivery`` that will Read Data ^^^^^^^^^ Once we have created a valid `DataReader` entity, we can read data from the DDS Global Data Space using the read operation. -This operation configures how the agent will send the data to the client. -Current implementation sends one topic to the client for each read data operation of the client. +This operation configures how the *Agent* will send the data to the *Client*. +Current implementation sends one topic to the *Client* for each read data operation of the *Client*. .. code-block:: C @@ -272,12 +271,12 @@ Current implementation sends one topic to the client for each read data operatio uint16_t read_data_req = uxr_buffer_request_data(&session, reliable_out, datareader_id, reliable_in, &delivery_control); -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. +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 option, and allow to specify how the data will be deliverd to the client. -For the example purpose, we set it as `unlimited`, so any number HelloWorld topic will be delivered to the client. +The ``delivery_control`` parameter is optional, and allows to specify 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. +The ``run_session`` function will call the topic callback each time a topic will be received from the *Agent*. .. code-block:: C @@ -296,7 +295,7 @@ The ``args`` argument correspond to user free data, that has been given at `uxr_ Closing the Client ^^^^^^^^^^^^^^^^^^ To close a `Client`, we must perform two steps. -First, we need to tell the agent that the session is no longer available. +First, we need to tell the *Agent* that the session is no longer available. This is done sending the next message: .. code-block:: C diff --git a/docs/images/xrcedds_architecture.png b/docs/images/xrcedds_architecture.png new file mode 100644 index 00000000..1990a401 Binary files /dev/null and b/docs/images/xrcedds_architecture.png differ diff --git a/docs/images/xrcedds_architecture.svg b/docs/images/xrcedds_architecture.svg deleted file mode 100644 index ae5e3071..00000000 --- a/docs/images/xrcedds_architecture.svg +++ /dev/null @@ -1,2 +0,0 @@ - -
Micro XRCE-DDS Agent
[Not supported by viewer]
DDS-XRCE
[Not supported by viewer]
RTPS
RTPS
Low Resources Device
Low Resources Device
Micro XRCE-DDS Client
<b>Micro XRCE-DDS Client</b>
DDS-XRCE
[Not supported by viewer]
Low Resources Device
Low Resources Device
Micro XRCE-DDS Client
<b>Micro XRCE-DDS Client</b> \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 58890f3a..cfc23bd2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ eProsima Micro XRCE-DDS ----------------------- *eProsima Micro XRCE-DDS* is a software solution which allows to communicate eXtremely Resource Constrained Environments (XRCEs) with an existing DDS network. -This implementation complies with the specification proposal, "eXtremely Resource Constrained Environments DDS (DDS-XRCE)" submitted to the Object Management Group (OMG) consortium. +This implementation complies with the specification proposal, "DDS for eXtremely Resource Constrained Environments" submitted to the Object Management Group (OMG) consortium. *Micro XRCE-DDS* implements a client-server protocol to enable resource-constrained devices (clients) to take part in DDS communications. *Micro XRCE-DDS Agent* (server) makes possible this communication acting on behalf of the *Micro XRCE-DDS Clients* @@ -15,7 +15,7 @@ and enables them to take part as DDS publishers and/or subscribers in the DDS Gl *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*. -.. image:: images/xrcedds_architecture.svg +.. image:: images/xrcedds_architecture.png Main features ~~~~~~~~~~~~~ @@ -71,10 +71,10 @@ To test *Micro XRCE-DDS* in your computer, you can follow the :ref:`quickstart_l This page shows how to create a simple publisher as a XRCE client that send topics into the DDS World. Additionally, there is an interactive example called :ref:`shapes_demo_label` that allow you to create entities and -to send/receive topics by the instructions given by command line. +to send/receive topics by instructions given by command line. This example is useful to understand how XRCE protocol works along to the DDS World. -To create your own client, you can follow the the instructions of :ref:`getting_started_label` page. +To create your own client, you can follow the instructions of :ref:`getting_started_label` page. This is a tutorial that describe briefly how *Micro XRCE-DDS* API is and how it works. To know more about *Micro XRCE-DDS*, you can read the corresponding parts to the :ref:`micro_xrce_dds_client_label` or the :ref:`micro_xrce_dds_agent_label`. diff --git a/docs/installation.rst b/docs/installation.rst index e628796e..17e88bb1 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -71,13 +71,13 @@ On Windows first select the Visual Studio version: :: $ cmake --build . --target install If you want to install the *Micro XRCE-DDS Client* examples you can add ``-DEPROSIMA_BUILD_EXAMPLES=ON`` to the CMake command line options. -This flag will enable the compilation of the examples when the project it is compiled. +This flag will enable the compilation of the examples when the project is compiled. There are several CMake definitions for configuring the build of the client library at compile time. You can found them in :ref:`micro_xrce_dds_client_label` page under `Configuration` section. Compiling an app with the Client library ---------------------------------------- -For building your client program you need to build against the following libs: :: +For building your Client app you need to build against the following libs: :: gcc -lmicrocdr -lmicroxrcedds_client diff --git a/docs/introduction.rst b/docs/introduction.rst index 769c0492..6112cd08 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -8,24 +8,24 @@ DDS-XRCE protocol `Micro XRCE-DDS` implements `DDS-XRCE protocol `_ specified in the `DDS for eXtremely Resource Constrained Environments` proposal submitted to the `Object Management Group (OMG)` consortium. -This protocol allows to communicate resource constrained clients with a larger `DDS (Data Distribution Service)` network. +This protocol allows to communicate resource constrained devices with a larger `DDS (Data Distribution Service)` network. This communication is done using a client-server architecture, where the server (Agent) acts as an intermediary between clients and `DDS Global Data Space`. `DDS-XRCE protocol` defines a wire protocol between XRCE Agents and XRCE Clients. -This message exchanged revolves around operations and their responses. +The messages exchanged revolve around operations and their responses. XRCE Clients ask the XRCE Agents to run operations and the XRCE Agents reply with the result of those requested operations. Making use of those operations, XRCE Clients are able to create the DDS entities hierarchy necessary to publish and/or receive data from DDS. DDS entities are created and stored on the XRCE Agent side so the XRCE Clients can reuse them at will. -`Micro XRCE-DDS` implements the DDS-XRCE protocol using a *Micro XRCE-DDS Agent* as server and providing a C API for developing XRCE Clients. +`Micro XRCE-DDS` implements the DDS-XRCE protocol using a *Micro XRCE-DDS Agent* as server and providing a C API for developing XRCE Clients applications. `Micro XRCE-DDS Agent` uses `Fast RTPS` to reach the DDS Global Data Space. -.. image:: images/xrcedds_architecture.svg +.. image:: images/xrcedds_architecture.png Fast RTPS ````````` -*eProsima Fast RTPS* is a C++ implementation of the `XRCE-DDS (Real-Time Publish-Subscribe)` protocol, +*eProsima Fast RTPS* is a C++ implementation of the `RTPS (Real-Time Publish-Subscribe)` protocol, which provides publisher-subscriber communications over unreliable transports such as UDP, as defined and maintained by the `OMG` consortium. XRCE-DDS is also the wire interoperability protocol defined for the `DDS` standard, again by the `OMG`. @@ -35,8 +35,7 @@ For deeper information please refer to the official documentation: `eProsima Fas Operations and entities ----------------------- *Micro XRCE-DDS* communication between XRCE Client and XRCE Agent is based upon :ref:`operations_label` and responses. -Clients request operations to the Agent. -The Agent will process the received operations and generate responses with the result of these operations. +Clients request operations to the Agent which will generate responses with the result of these operations. Clients may process the responses to know how an operations request has ended in the Agent. *Micro XRCE-DDS Client* can request a variety of operations to the *Micro XRCE-DDS Agent*: @@ -45,14 +44,14 @@ Clients may process the responses to know how an operations request has ended in * Create and delete entities. * Write and read Data. -First of all the `Agent` must know about any `Client`. +First of all, the `Agent` must know about any `Client`. This is done by sending a `Create session` operation from the `Client` to the `Agent`, which will register the `Client`. If you do not register the session, all the operations sending to the `Agent` will be refused. Once registered, the `Client` can request operations to the `Agent`. The `Client` can create and query entities using operations. The communication with `DDS` is handled by `Agent` using :ref:`entities_label`. -`Create entity` Operation is the request you use to create entities on the `Agent`. +`Create entity` Operation is the request you use to create entities in the `Agent`. Each one of these entities corresponds with a `Fast RTPS` object. The entities you can create are: @@ -73,7 +72,7 @@ Also, if you want to log out a `Client` session from the `Agent`, you can use th Topic Type ---------- The data sent by the `Client` to the `DDS Global Data Space` uses the same principles as in `Fast RTPS`. -The `Interface Definition Language (IDL) `_ is used to define the type and must be known by the client. +The `Interface Definition Language (IDL) `_ is used to define the type and must be known by the `Client`. Having the type defined as `IDL` we provide the :ref:`microxrceddsgen_label` tool. This tool is able to generate a compatible type that the *Micro XRCE-DDS Client* can use to send and receive. The type should match the one used on the DDS Side. diff --git a/docs/notes.rst b/docs/notes.rst index a4965ca8..7640ee2e 100644 --- a/docs/notes.rst +++ b/docs/notes.rst @@ -3,12 +3,12 @@ Version 1.0.0 This release includes the following features: -* Extended C topic code generation tool (strings, sequences, n-dimensional arrays). +* Extended C topic code generation tool (strings, sequences and n-dimensional arrays). * Discovery profile. * Native write access profile (without using Micro XRCE-DDS Gen) -* Creation and configuration by xml. +* Creation and configuration by XML. * Creation by reference. -* Added reuse flag at create entities. +* Added `REUSE` flag at create entities. * Added prefix to functions. * Transport stack modification. * More tests. @@ -23,8 +23,8 @@ Version 1.0.0Beta2 ~~~~~~~~~~~~~~~~~~ This release includes the following features: -* Reability. -* Stream concept (best effort, reliable). +* Reliability. +* Stream concept (best-effort, reliable). * Multiples streams of same type. * Configurable data delivery control. * C Topic example code generation tool. diff --git a/docs/operations.rst b/docs/operations.rst index 8e898bde..ad2f5813 100644 --- a/docs/operations.rst +++ b/docs/operations.rst @@ -3,13 +3,13 @@ Operations ========== Operations are the possible actions your *Micro XRCE-DDS Client* can ask to the *Micro XRCE-DDS Agent*. -Operations revolve around `entities`. :ref:`entities_label`. +Operations revolve around :ref:`entities_label`. *Micro XRCE-DDS Agent* will respond to all the requests with the status of the operation. Types ----- `Create session` - `Create session` asks the agent to register a session. + `Create session` asks the *Agent* to register a session. This is the first operation that you must request. If this operation fails or you don't request it, any of the following operations will not work. This operation will create the session corresponding to the *Client-Agent* connection. @@ -24,18 +24,15 @@ Types Each `Create entity` operation are related to an ID for its management. `Delete entity` - Analogous to create entities a session can to drop the entities on the *Agent*. + Analogous to create entities a session can drop the entities on the *Agent*. To drop an entity you need to request a deletion of the entity to the *Agent* using the entity ID. `Request Data` - This operation configures how do you want to receive data, and the Agent will deliver it from the DDS to your *Client*. + This operation configures how do you want to receive data, and the *Agent* will deliver it from the DDS to your *Client*. This data will be receive asynchronously, in accordance with the data delivery control setted in this operation. - Reading data is done using a DataReader entity. + Reading data is done using a `DataReader` entity. About XML Representation ------------------------ -Creating a Topic, a DataWriter or a DataReader needs to be done using DDS XML configuration of the object to create. +`Participats`, `Topics`, `DataWriters` and `DataReaders` creation needs to be done using DDS XML configuration of the object to create. That XML configuration follows the same rules as in *Fast RTPS*. - -Creating a Participant is done using the ``default participant`` profile found already preconfigured in the agent. -Yo can change the Participant configuration changing the ``DEFAULT_FASTRTPS_PROFILES.xml`` file found along with de *Micro XRCE-DDS Agent* installation. diff --git a/docs/optimization.rst b/docs/optimization.rst index 78c1311c..8df7764f 100644 --- a/docs/optimization.rst +++ b/docs/optimization.rst @@ -9,21 +9,24 @@ In order to manage the executable code size, the library can be compiled enablin To add or remove a profile from the library, edit the ``client.config`` file. More information can be found at: :ref:`micro_xrce_dds_client_label`. +NOTE: If you are compiling your app with *gcc*, its highly recommended compile it with the linker flag: ``-Wl,--gc-sections``. +This will remove the code that your app does not use from the final executable. + Runtime size ------------ -The client is dynamic memory free and static memory free. +The *Client* is dynamic memory free and static memory free. This implies that all memory charge depends only on how the stack grows during the execution. To control the stack, there are some values that can be modified and that impact to a large degree: Stream buffers ~~~~~~~~~~~~~~ -1. Make sure you defined only the streams that will be used. - You can define a maximun `127` best effort streams and `128` reliable streams, - but for the majory of purposes, only one stream of either best effort or reliable can be used. +1. Make sure you define only the streams that will be used. + You can define a maximum `127` best-effort streams and `128` reliable streams, + but for the majority of purposes, only one stream of either best effort or reliable can be used. 2. The history of a reliable streams is used for recovering from lost messages and speeding up the communication. - For output streams, more history value will allow writing and send more messages without wait confirmation. - If a history of an output stream is full (no messages were still confirmed by the agent), no more messages can be storaged into the stream. + For output streams, more history value will allow to write and send more messages without wait confirmation. + If a history of an output stream is full (no messages were still confirmed by the *Agent*), no more messages can be storaged into the stream. For input streams, the history is used for recovering faster when the messages are lost using less extra band-width. If your connection is highly reliable and to save memory is a priority, a reduced history can be used. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 73d44277..a8db2e86 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -205,8 +205,15 @@ The code of the *SubscriberHelloWorldClient* is the following: { if(args >= 2 && (0 == strcmp("-h", argv[1]) || 0 == strcmp("--help", argv[1]) || 0 == atoi(argv[1]))) { - printf("usage: program [-h | --help | ]\n"); - return 0; + (void) session; (void) object_id; (void) request_id; (void) stream_id; + + HelloWorld topic; + HelloWorld_deserialize_topic(mb, &topic); + + printf("Received topic: %s, id: %i\n", topic.message, topic.index); + + uint32_t* count_ptr = (uint32_t*) args; + (*count_ptr)++; } uint32_t count = 0; @@ -319,7 +326,7 @@ To learn more about DDS and Fast RTPS: `eProsima Fast RTPS `_ is an interactive example for testing how `Fast RTPS` working in the `DDS Global Data Space`. -Because the aim of `Micro XRCE-DDS` is connect a `XRCE Client` to the `DDS World`, in this example we will create a client which will interact with the `Shapes Demo`. +Because the aim of `Micro XRCE-DDS` is connect an `XRCE Client` to the `DDS World`, in this example we will create a *Client* which will interact with the `Shapes Demo`. It can be found at `examples/uxr/client/ShapeDemoClient` inside of the installation directory. -This interactive client waits for user input indicating commands to execute. +This interactive *Client* waits for user input indicating commands to execute. The available commands are the following: @@ -44,7 +44,7 @@ tree, entity_tree : h, help: Shows this message. -For example, to create a publisher client that sends an square Topic in reliable mode, you need to run the following commands in order: :: +For example, to create a publisher *Client* that sends an square Topic in reliable mode, you need to run the following commands: :: > create_session > create_participant 1 @@ -53,9 +53,9 @@ For example, to create a publisher client that sends an square Topic in reliable > create_datawriter 1 1 > write_data 1 128 200 200 40 BLUE -This client will publish a topic in reliable mode that will have color BLUE, x coordinate 200, y coordinate 200, size 40. +This *Client* will publish a topic in reliable mode that will have color BLUE, x coordinate 200, y coordinate 200 and size 40. -In case of a subscriber client that receives square topics in a reliable mode, run the following: :: +In case of a subscriber *Client* that receives square topics in a reliable mode, run the following: :: > create_session > create_participant 1 @@ -64,7 +64,7 @@ In case of a subscriber client that receives square topics in a reliable mode, r > create_datareader 1 1 > request_data 1 128 5 -This client will received 10 topics in reliable mode. +This *Client* will received 5 topics in reliable mode. To create the entities tree easily, you can run the command ``entity_tree ``. For example, the following command creates the necessary entities for publishing and subscribing data with id `3`: :: @@ -79,9 +79,9 @@ For example, the following command creates the necessary entities for publishing To modify the output default stream, you can change it with `stream `. - > stream 1 - The maximun available streams corresponds with the ``CONFIG_MAX_OUTPUT_BEST_EFFORT_STREAMS`` and ``CONFIG_MAX_OUTPUT_RELIABLE_STREAMS`` properties configurable in ``client.config`` file. + > stream 1 + Now the messages will be send in best effort mode.