.. include:: vars.rst .. _section-advanced: ***************************************** Advanced Configuration of the |PJ_PLUGIN| ***************************************** The |RTI_CONFIGURATION_DIALOG| ============================== The |RTI_CONFIGURATION_DIALOG| opens each time that you start the |RTI_PLUGIN|. This window provides most of the configuration options allowing the |RTI_PLUGIN| to join the DDS domain, selecting the Topics to subscribe, and so on. .. figure:: _static/img/topic_dialog.png :alt: Topic Dialog :align: center :figwidth: 75 % :name: TopicDialog |RTI_CONFIGURATION_DIALOG| Choosing the DomainId, DomainTag, and Qos Profile ------------------------------------------------- The first thing to do is create the DDS *DomainParticipant* in order to join a *DDS Domain*. This is done by clicking in the "**Join DDS Domain**" button (**C**). Before doing it, you may want to change the "**Domain Id**", "**Domain Tag**", and "**Qos Profile**" from their default values. Once the *DomainParticipant* has been created the button changes to "**Leave DDS Domain**". If you want to join a different *DDS Domain* you must first leave the DDS Domain (which will delete the DDS *DomainParticipant*), change the **Domain Id**, optionally the **Domain Tag** and **Qos Profile**, and join the *DDS Domain* again. By default the *DomainParticipant* will use a builtin profile called "**PJ_Lib::Basic_Profile**." To use a different profile, use the "**Select...**" button (**D**) to select a XML file containing additional Qos profiles. The XML file will be parsed and any QoS profiles found in the file will appear in the "**Qos Profile**" pulldown menu (**E**) and you can select one of them. Autojoin option --------------- You may check the "**auto join**" checkbox (**F**) to join the *DDS Domain* automatically whenever you open the |RTI_CONFIGURATION| dialog. |PJ| will remember the last configuration used and join the *DDS Domain* using the same settings. Maximum size of arrays and sequences ------------------------------------ |PJ| limits the maximum size of the arrays and sequences that appear inside *DDS Topics*. If your Topic contains arrays or sequences, you may want to change the default value of the maximum. The value of the maximum can specified in the **Max Size** spin box found under the "**Array/Sequence settings**" (**G**). When data is received containing an array or sequence that exceeds the specified maximum size, the behavior depends on the setting of the **Discard** and **Clamp** choice buttons. - If the **clamp** choice is selected, the array (or sequence) will be truncated leaving only the elements below the maximum which will appear in the time-series. - If the **discard** choice is selected, the whole array (or sequence) will be discarded and none of the elements will appear in the time series. The value of maximum size is interpreted differently for multi-dimensional arrays and sequences: - For ``arrays`` the *maximum size* applies *across all dimensions* (i.e. as if the array was flattened into a single dimension). For example, assume **clamp** is chosen, the maximum size is set to **6**, and |PJ| receives a 4x4 two-dimensional array (e.. ``int32 a[4][4];`` ) you will get the following 6 elements in the time-series: .. code-block:: c a[0][0], a[0][1], a[0][2], a[0][3], a[1][0], a[1][1] - For ``sequences`` the *maximum size* applies *independently to each dimension* (i.e. there is no flattening). For example, assume **clamp** is chosen, the maximum size is set to **6**, and |PJ| receives a 10x10 two-dimensional sequence (e.g. ``sequence, 10> seq;``) you will get the following **60** elements in the time-series: .. code-block:: c seq[0][0], ... seq[0][5], seq[1][0], ... seq[1][5], ... seq[9][0], ... seq[9][5] Discovered versus Selected Topics ================================= At the center of the dialog you will notice two main tables: - The "**Discovered Topics**" table (**H**), on the left side. - The "**Selected Topics**" table (**J**), on the right side. Discovered Topics Table ----------------------- The "**Discovered Topics**" table (**H**), contains the ``DDS Topics`` that are (fully) discovered in the ``DDS Domain``. This table will be empty if you have still not joined the ``DDS Domain``. Each time you select a `Topic` in this table you will see the associated ``Data Type`` in the "**Topic Data type (shown as equivalent IDL)**" area below (**I**). Only "fully discovered" topics are shown. To be "fully discovered" DDS must have discovered a DataWriter for the Topics as well as the data-type associated with the Topic. If you have joined a domain and do not see some of the Topics that are being published, you can use **RTI Admin Console** to check whether the type information is being propagated or not. For each Discovered Topics you can see the current number of discovered DataWriter for the Topic. Once fully discovered the Topic is remembered and kept in the table even if all DataWriters go away. In this case you will see the number shown the **Writers** column become 0. Selected Topics Table ----------------------- The "**Selected Topics**" table (**J**), contains all the topics that are either subscribed or are intended to be subscribed. Topics are placed into the "**Selected Topics**" the following ways: - Double-clicking on the Topic name on the "**Discovered Topics**" table. - Selecting a set of topics in the "**Discovered Topics**" table and then clicking the "**>>**" arrow between the two tables in order to "push" the topic(s) to the "**Selected Topics**" table. - Type the Topic name manually using the "**(+)**" to the right of "**Selected Topics**" label (**K**). This method is useful to add topics that have not been discovered yet. - Upon re-start |PJ| remembers the set of topics that were selected the last time the tool was run and automatically adds them to the "**Selected Topics**" table. Regardless of the method, when a topic is first added to the "**Selected Topics**" table, it is always placed in the *Unconfirmed* state. |PJ| will not try to subscribe to the Topic until you "confirm" this selection by clicking on the **OK (Confirm)** button. See below. The second column of the "**Selected Topics**" table, called "**All Instances**" contains a checkbox (**M**). The use if this checkbox is explained later in section "**Instance filtering.**" The third column of the "**Selected Topics**" table, called "**Status**" indicates the status of each selected topic: - **Unconfirmed**. The Topic was added to the "**Selected Topics**" table but the "**OK (Confirm)**" button has no been pressed to confirm the addition. These Topics are retained in the "**Selected Topics**" table but |PJ| will not try to subscribe to them until they are 'confirmed' by pressing the "**OK (Confirm)**" button at the bottom of the dialog. - **Undiscovered**. The Topic selection has been confirmed, but the Topic has not been fully discovered yet. |PJ| will subscribe to it soon as a the *Topic* is "fully discovered" meaning both a *DataWriter* of the *Topic* and the corresponding *Data Type* have been discovered. - **Subscribed**. The Topic is subscribed to and its data is visible to |PJ|, subject to any specified instance and content filters. In this case the number of matched writers is indicated as well. In some cases you may observe that even if a *Topic* is subscribed, the number of matched writers shown in the "**Selected Topics**" table, is not the same as the number of writers in the "**Discovered Topics**" table. This indicates that is some incompatibility between some of the DataWriters and the DataReader that |PJ| has created. Those "incompatible" DataWriters will not be counted in the "**Selected Topics**" 'matches'. If you observe this, you may use **RTI Admin Console** to determine the reason for the incompatibility. Additionally, you can add a *Content Filter* to your topics in "**Content Filter**" area (**L**). In order to enter a *Content Filter* you must select the corresponding Topic in the "**Selected Topics**" table. Instance filtering ================== If the data-type associated with a Topic has annotated any field(s) as "**key**", then the Topic can have multiple instances associated with it. In the example above, we can see how the topic "nested_keys" has two key fields called "code" and "key". For these "keyed" Topics, |PJ| will create a separate time series for each Topic Instance. In the example shown we see that the left time series area (**A**) has 4 labels created to identify the 4 different instances discovered: .. code-block:: c [code=1; key=10;] [code=1; key=20;] [code=2; key=10;] [code=2; key=20;] By pressing the **gear** button (**B**) and selecting "**Configure topic instance (key) filters**", you will open the "**Topic instance (key) filters**" dialog **C**, that allows configuring the set of instances that are read by |PJ|. .. figure:: _static/img/instance_filter.png :alt: Instance Filter :align: center :figwidth: 75 % :name: InstanceFilter *Instance Filter* The default behavior of |PJ| when new instances are discovered for subscribed topics depends on whether the checkbox "**All Instances**" was checked for the corresponding Topic: - If the **checkbox** was checked, newly discovered instances will be read by default (subject to passing the content-filter specified on the Topic, if any). - If the **checkbox** was not checked, newly discovered instances will be not read by default. Independent of the default behavior, you can always select manually which instances are read. This is also done using the "**Topic instance (key) filters**" dialog. Note that if the data-type associated with a Topic does not define any key fields, then the "**All Instances**" checkbox is ignored and the Topic will not appear in the "**Topic instance (key) filters**" dialog. ## Instance lifecycle For topics that defined some fields as "**key**" the corresponding instances can transition from being ``ALIVE`` to being ``NOT_ALIVE``. - An instance is ALIVE when it has a matched DDS *DataWriter* that is actively writing it. It initially becomes ``ALIVE`` when it is first discovered and remains in that state until there is an event that causes it to become ``NOT_ALIVE``. - An instance becomes `NOT_ALIVE` when one of two things happen: - A DDS DataWriter "disposes" it. That happens if it calls the ``DataWriter::dispose()`` operation on the instance. In this case the instance is transitioned to the ``NOT_ALIVE_DISPOSED`` state. - All the DDS *DataWriters* that were writing the instance either unregister the instance (i.e. call the ``DataWriter::unregister()`` operation on the instance) or, alternatively, "disappear from the system". A `DataWriter` "disappears" if is deleted or loses its liveliness. In this case the instance is transitioned to the ``NOT_ALIVE_NOWRITER`` state. If data is received on an instance that is in a ``NOT_ALIVE`` state it will transition back to the ``ALIVE`` state. Note that DDS *DataWriters* may configured with a QoS setting that specifies to "**auto dispose unregistered instances**" in this case when the *DataWriter* is deleted, it will automatically dispose all the instances the *DataWriter* was writing. In this case so you may see transitions to the ``NOT_ALIVE_DISPOSED`` when those *DataWriters* are deleted even if they never called ``DataWriter::dispose()`` explicitly. When an instance transitions to a ``NOT_ALIVE`` state, all the associated time-series are colored in **red** to indicate that there the instance is not alive and no data will be received. Hovering the mouse cursor over the time series brings up a tooltip that indicates whether the instance is in the state ``NOT_ALIVE_DISPOSED`` or ``NOT_ALIVE_NOWRIT0ERS``. .. figure:: _static/img/treeview_not_alive.png :alt: Tree View Not Alive :align: center :figwidth: 40 % :name: TreeViewNotAlive *Tree View Not Alive* The "**Topic instance (key) filters**" dialog shows instances even if they are in a ``NOT_ALIVE`` state. This allows you to select the behavior in case the instance transitions to ``ALIVE`` again. Connext DDS Notifications ========================= The |RTI_PLUGIN| generates notifications and log messages informing the user of events of interest, such as, discovery of new Topics and Instances, addition or removal of content filters, etc. The presence of notifications is indicated by a **bell** button on the main window below the *combobox* showing "**RTI Connext DDS**" (**A**). Note that the *bell* button will only be visible if there are any outstanding notifications. Clicking on the **bell** button will open the |RTI_NOTIFICATION_DIALOG|. Alternatively the dialog may also be opened pressing the **gear** button in the main window (**B**) and selecting the **Show Notifications Messages** option. .. figure:: _static/img/notifications_menu.png :alt: Notifications Menu :align: center :figwidth: 40 % :name: NotificationsMenu *Notifications Menu* The |RTI_NOTIFICATION_DIALOG| (see below) shows the notifications produced by the |RTI_PLUGIN| ordered by timestamp. .. figure:: _static/img/notifications_dialog.png :alt: Notifications Dialog :align: center :figwidth: 60 % :name: NotificationsDialog *Notifications Dialog* You may choose the type of notifications displayed on the window by checking the various checkboxes in the header (**C**). You may also enter a regular expression on the **Text Filter** text box (**D**) to temporarily hide log messages that do not match the expression. Clicking on the **Clear Notifications** button (**E**) removes all the log messages produced so far. Clicking on the **Close** button (**F**) will close the dialog without clearing any messages.