2. Example of usage¶
This example will serve as a hands-on tutorial, aimed at introducing some of the key concepts and features that eProsima DDS Router has to offer.
Two disjoint DDS networks will be bridged by means of a pair of routers, allowing for the connection between endpoints hosted at each of the networks. In particular, two ShapesDemo instances will establish communication after proper configuration and deployment of the two aforementioned routers.
This example applies to both LAN and WAN scenarios. For the WAN case, make sure that public IP addresses are used instead of private ones, and that the provided ports are reachable by properly configuring port forwarding in your Internet router devices.
2.1. Launching ShapesDemo¶
ShapesDemo is an application that publishes and subscribes to shapes of different colors and sizes moving on a board. This is nothing more than a graphical tool to test the correctness of a specific DDS protocol implementation, as well as to prove interoperability with other implementations.
Let us launch a ShapesDemo instance in one of the DDS networks, and start publishing in topics
Triangle with default settings.
Now, run another instance in the other network and subscribe to the same topics chosen in the publisher side (use default settings).
If you are trying this example in the LAN scenario, make sure a different DDS domain id is used in one of the ShapesDemo instances in order to avoid direct communication between them.
2.2. Router configuration¶
A configuration file is all that is required in order to run a DDS Router instance. In a nutshell, each router will
forward messages if their associated topics match the filters contained in its
blocklist may also
be specified, on its own or in addition to an
allowlist, but we will not be covering this here.
Let us first add only the
allowlist: - name: Square
Apart from selecting on which topics we wish to send/receive data, we must configure as well the participants that will ultimately perform communication. Each router instance will contain a simple and a WAN participants. In brief, the simple participants will be in charge of locally communicating with the corresponding ShapesDemo application, while the WAN participants will be the ones bridging the connection between the two DDS networks.
The only configuration required for simple participants is the DDS
- name: SimpleParticipant kind: local domain: 0
If launching the two routers in the same LAN, set a different
domain id in one of the two configuration files (same
as the one previously set for ShapesDemo).
The configuration of WAN participants is more complex, and we will not be covering it here in detail. In short, in this
example both WAN participants will communicate through UDP, with one being the client and the other one having the
server role. Both participants are required to have a
listening address (for the UDP case) where they will expect to
receive traffic, and a
connection address in the case of the client, which points at the server’s
listening address. Refer to WAN Participant and
WAN Configuration for more information. You may also have a look at
WAN Example for a detailed explanation on how to configure this kind of participant.
Following is an example of client and server configuration files:
# client-ddsrouter.yaml version: v3.0 allowlist: - name: Square participants: - name: SimpleParticipant kind: local domain: 0 - name: ClientWAN kind: wan connection-addresses: - ip: 192.168.1.8 port: 11800 transport: udp listening-addresses: - ip: 192.168.1.4 port: 11008 transport: udp
# server-ddsrouter.yaml version: v3.0 allowlist: - name: Square participants: - name: SimpleParticipant kind: local domain: 1 - name: ServerWAN kind: wan listening-addresses: - ip: 192.168.1.8 port: 11800 transport: udp
2.3. Router execution¶
Now, with the configuration files ready, launching a DDS Router instance is as easy as executing the following command:
ddsrouter -c config-file.yaml
After setting up both routers, communication between the two ShapesDemo instances should have been established so the square shape is now visible in the subscriber’s panel.
DDS Router supports the dynamic addition/deletion of topics at runtime (see
Reload Topics). Let us test this feature by adding the circle topic to
the allowlist of both routers. Also, by removing the square topic (removing this topic from one of the routers’
allowlist will suffice) the square data should stop reaching the subscriber. Alternatively, the square topic may be
added to the
blocklist, achieving the same effect. See Topic Filtering for more details
allowlist: - name: Circle
After applying these changes, the square should no longer be updated in the subscriber’s side (appearing visible but frozen), while the circle should.
Please feel free to explore sections Examples and Use Cases for more information on how to configure and set up a router, as well as to discover multiple scenarios where DDS Router may serve as a useful tool.