DDS Blockset Shapes Demo

This example uses:

This example demonstrates the DDS Blockset Shapes Demo application. The Shapes Demo is a common Data Distribution Service (DDS) application used to introduce DDS concepts, with which you can publish and subscribe to topics represented as simple shapes (circles, squares, and triangles) and observe publisher-subscriber connectivity. Many organizations that provide products and services that use the DDS standard provide their own versions of the Shapes Demo to demonstrate core DDS capabilities.

The DDS Blockset version of the Shapes Demo subscribes to the Square topic, processes the subscriber sample data, which includes an (x, y) position, and publishes a Circle topic that uses the Square (x, y) position values, each offset by a constant.

In this example, you will:

Review type, domain, and topic definitions used by the DDS Blockset Shapes Demo.
Review the Simulink model elements that implement the subscriber and publisher.
Review the DDS interface mapping between the model elements and the DDS topic, data reader, and data writer definitions.
Build the application.
Use a third-party Shapes Demo to communicate with the DDS Blockset executable.

DDS Blockset enables out-of-the-box support for the DDS vendors RTI and eProsima. This demo uses the DDS RTI Connext® software and requires RTI Connext 6.1.2+ software to be installed. If needed, you can use a provided file exchange version of RTI Connext software. For download and install information, see DDS Blockset System Requirements. Embedded Coder® is also required for building and deploying DDS Blockset models.

View Type and Domain Definitions

This demo uses the shapesdemo.slx model, which has type and domain participant definitions already imported from an XML file.

The DDS definitions were imported from the DDS XML file shapesexample.xml and are saved in the shapesexample.sldd dictionary. You can open the shapesexample.xml file to view the XML descriptions. For more information about how to import XML or IDL definitions, see Import or Create DDS Definitions.

To view the imported DDS definitions in the DDS Dictionary, open the .sldd file.

open shapesexample.sldd

The data dictionary opens in Model Explorer. In the Model Hierarchy pane, select Simulink Root > shapesexample > DDS Libraries. Then, click Open DDS Libraries.

Under the Types tab in the DDS Dictionary, view the imported data types. For each imported data type, you can see property information in the Details pane. For example, the Simulink.Bus structure ShapeType defines members color, x, y, and shapesize.

These data types in the DDS Dictionary are types and definitions imported directly from the XML file shapesexample.xml.

<types>
    <const name="MAX_COLOR_LEN" type="int32" value="128" />
    <struct name="ShapeType">
        <member name="color" stringMaxLength="128" type="string" key="true"/>
        <member name="x" type="int32" />
        <member name="y" type="int32" />
        <member name="shapesize" type="int32" />
    </struct>
</types>

Under the Domains tab, view domain and topic definitions. The domain ShapesDomain uses a domain ID of 0 and includes topics Circle, Square, and Triangle. Each topic uses the registered data type ShapeType, which describes payload data for the topic.

These domain participant definitions in the DDS Dictionary are imported directly from the XML file shapesexample.xml.

<domain_participant_library name="MyParticipantLibrary">
    <domain_participant name="MyParticipant"
                     domain_ref="ShapesDomainLibrary::ShapesDomain">
        <register_type name="ShapeType" type_ref="ShapeType" />
        <topic name="Square" register_type_ref="ShapeType" />
        <topic name="Circle" register_type_ref="ShapeType" />
        <topic name="Triangle" register_type_ref="ShapeType" />
        ...
    </domain_participant>
</domain_participant_library>

Under the QoS tab, you would view Quality of Service (QoS) definitions. Since QoS definitions are not provided in the XML for this example, this tab is empty. The publisher and subscriber in this demo use the default QoS profile provided by the DDS vendor.

View Publisher and Subscriber Model Construction

Open the Shapes Demo model.

open_system("shapesdemo");

In the Simulink model for the Shapes Demo, view how the ports and the Take DDS Sample block and Write DDS Sample block are used to subscribe to and publish sample data for the shape.

Review Subscribe Blocks

Right-click the Bus Element In block MySubscriber.Square and select Block Parameters. The DDS type of the input port is ShapeType and the bus is nonvirtual.

Right-click the Take DDS Sample block, and select Block Parameters. The Take DDS Sample block converts the DDS data type to a Simulink data type.

Review Logic Subsystem

Double-click the Logic subsystem of the Shapes Demo model to open. The logic component uses the Simulink data types and sets the data sample values for the publisher. The Logic subsystem configures the output color to a constant "RED", sets the output (x, y) position to the input (x, y) position with each value offset by the constant Distance, and sets the output shape size to a constant MyShapeSize.

Review Publish Blocks

Double-click the Write DDS Sample block to see its properties. The Write DDS Sample block converts the Simulink data types to a DDS data sample to send.

Right-click the Bus Element Out block MyPublisher.Circle, and select Block Parameters. The DDS type of the output port is ShapeType, where the updated position is provided by the x and y bus elements.

Additionally, in the Configuration Parameters, root-level output logging is unset for this model.

View Configured DDS Interface

The imported XML descriptions also include the DataWriter and DataReader definitions for publishers and subscribers. You use the Code Mapping editor to map topics, data readers, and data writers to the input and output ports.

On the toolstrip, click Code Interface and select Individual Elements Code Mappings. The Code Mappings panel opens.

Inports

To view the topic and data reader mapped to the input ports, click the Inports tab. Under the Topic column, you can map topics that are defined in the DDS dictionary. Under Reader XML Path column, you can map imported DDS DataReaders.

Outports

To view the topic and data writers mapped to the output ports, click the Outports tab.

Build and Deploy the Shapes Demo

DDS Blockset enables out-of-the-box support for the DDS vendors RTI and eProsima. This demo generates an executable specific to the DDS RTI Connext® software and requires that RTI Connext 6.1.2+ software be installed. For eProsima, the FastDDS product is included with DDS Blockset, and no additional setup would be required.

If you do not have RTI Connext software installed, see the DDS Blockset System Requirements page for information about getting started with RTI Connext. Embedded Coder® is also required for building and deploying DDS Blockset models.

Additionally, before building your model, in the MATLAB® Command Window, use the mex command to verify that a supported C++ compiler and supported compiler version are set up for your platform. See DDS Blockset System Requirements for more information about the requirements for each platform.

mex -setup c++
   MEX configured to use 'Microsoft Visual C++ 2019' for C++ language compilation.
   To choose a different C++ compiler, select one from the following:
   ...

To build your application model and generate C++ code, on the toolstrip under the DDS tab, click Build.

To deploy your generated executable, in the MATLAB® Command Window, run the shapesdemo.exe executable:

cd shapesdemo_ert_rtw/exe
!shapesdemo.exe

When the DDS Blockset Shapes Demo application runs, it subscribes to the Square topic and publishes a Circle topic that provides an offset (x, y) position. You will not see output at the MATLAB® Command Window. The executable runs in the foreground, so you will not have access to the MATLAB prompt while shapesdemo.exe is running.

The next section provides information for optionally verifying connectivity of your DDS executable with a different DDS application that subscribes to the Circle topic and publishes a Square topic.

Use Third-Party Shapes Demo Applications to Communicate with DDS Blockset Shapes Demo

You can use the DDS Blockset Shapes executable to exchange DDS data with other DDS applications that use the same data type. The ShapeType data type is a widely used type in DDS for demo purposes, and different DDS vendors have already created a desktop Shapes Demo application using this ShapeType.

Information in this section applies to using the trial version of RTI Shapes Demo to communicate with the DDS Blockset Shapes Demo executable. Running the RTI Shapes Demo provides a graphical interface that displays the published and subscribed to ShapeType data on a canvas. Alternatively, you can use the RTI Shapes Demo provided with the RTI Launcher.

To view connectivity, you can use the RTI Shapes Demo application to publish one shape on the Square topic and subscribe to the Circle topic. This is configured by launching the RTI Shapes Demo application and in the control window, clicking "Square" under Publish, clicking "Circle" under Subscribe, and using the defaults for both.

The DDS Blockset Shapes Demo application subscribes to the Square topic. It receives the Square sample data published from the RTI Shapes Demo third-party application, adds an offset to the (x, y) position of the Square, and publishes a red Circle that uses the offset (x, y) position.

After you launch and configure the RTI Shapes Demo application, you can see this communication in the RTI Shapes Demo control window. The canvas displays the blue square, which is published by the RTI Shapes Demo, and displays the last six samples of red circles trailing the square. The circles are published by the DDS Blockset Shapes Demo and are subscribed to by the RTI Shapes Demo. The RTI Shapes Demo shows six red circles because the default "History" QoS value is set to 6 when creating the subscriber, which can be changed by the user.