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.

../../_images/shapesdemo_general.png

Note

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 Square, Circle and Triangle with default settings.

../../_images/shapesdemo_publisher.png

Now, run another instance in the other network and subscribe to the same topics chosen in the publisher side (use default settings).

../../_images/shapesdemo_subscriber.png

Note

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 allowlist. A 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 Square topic:

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.

../../_images/shapesdemo_detailed.png

The only configuration required for simple participants is the DDS domain identifier.

  - 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. Note that a unique id must be set for every WAN participant, and this entry should also be included in connection 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: v2.0

allowlist:
  - name: Square

participants:

  - name: SimpleParticipant
    kind: local
    domain: 0

  - name: ClientWAN
    kind: wan
    discovery-server-guid:
      id: 1
    connection-addresses:
      - discovery-server-guid:
          id: 0
        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: v2.0

allowlist:
  - name: Square


participants:

  - name: SimpleParticipant
    kind: local
    domain: 1

  - name: ServerWAN
    kind: wan
    discovery-server-guid:
      id: 0
    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.

../../_images/shapesdemo_square.png

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 on allowlisting.

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.

../../_images/shapesdemo_circle.png

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.