Add new tutorials (#692)

The tutorials contain the code for the new Connext Guide.

README.md

@@ -1,15 +1,27 @@
-# rticonnextdds-examples
+# RTI Connext Examples
 
-This repository includes examples on how to use specific features of RTI
-Connext DDS.
+This repository includes:
 
-To contribute enhancements or additional examples to the repository, follow the
-instructions on our [RTI Connext DDS Examples
-Wiki](https://github.com/rticommunity/rticonnextdds-examples/wiki). Your
-contributions will be reviewed and as soon as they are approved they will
-automatically be included in the [RTI Community Portal Examples
-Section](http://community.rti.com). See [CONTRIBUTING.md](https://github.com/rticommunity/rticonnextdds-examples/blob/master/CONTRIBUTING.md)
-for further information about how to contribute with new examples to this repository.
+- Code examples on how to use specific Connext features (under [examples/](./examples))
+- Supporting code for learning materials (under [tutorials/](./tutorials))
+
+## Cloning the repository
+
+To clone the repository you will need to run `git clone` as follows to download
+both the repository and its submodule dependencies:
+
+```bash
+git clone --recurse-submodule https://github.com/rticommunity/rticonnextdds-examples.git
+```
+
+If you forget to clone the repository with `--recurse-submodule`, simply run
+the following command to pull all the dependencies:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Versioning
 
 The examples contained in the
 [master](https://github.com/rticommunity/rticonnextdds-examples/tree/master)
@@ -29,18 +41,12 @@ versions of RTI Connext DDS, please check out the appropriate branch:
 - [release/5.1.0](https://github.com/rticommunity/rticonnextdds-examples/tree/release/5.1.0)
 - [release/5.0.0](https://github.com/rticommunity/rticonnextdds-examples/tree/release/5.0.0)
 
-## Cloning Repository
-
-To clone the repository you will need to run `git clone` as follows to download
-both the repository and its submodule dependencies:
-
-```bash
-git clone --recurse-submodule https://github.com/rticommunity/rticonnextdds-examples.git
-```
-
-If you forget to clone the repository with `--recurse-submodule`, simply run
-the following command to pull all the dependencies:
+## How to contribute
 
-```bash
-git submodule update --init --recursive
-```
+To contribute enhancements or additional examples to the repository, follow the
+instructions on our [RTI Connext DDS Examples
+Wiki](https://github.com/rticommunity/rticonnextdds-examples/wiki). Your
+contributions will be reviewed and as soon as they are approved they will
+automatically be included in the [RTI Community Portal Examples
+Section](http://community.rti.com). See [CONTRIBUTING.md](https://github.com/rticommunity/rticonnextdds-examples/blob/master/CONTRIBUTING.md)
+for further information about how to contribute with new examples to this repository.

tutorials/README.md

@@ -0,0 +1,8 @@
+# RTI Connext Tutorials
+
+The code included in this directory is the supporting material for the tutorials
+in the
+[Connext Developer](https://community.rti.com/static/documentation/developers/index.html)
+page.
+
+Please follow the instructions for each tutorial under *Learn*.

tutorials/content_filtering/c++11/CMakeLists.txt

@@ -0,0 +1,61 @@
+#
+# (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+#
+# RTI grants Licensee a license to use, modify, compile, and create derivative
+# works of the Software.  Licensee has the right to distribute object form
+# only for use with RTI products.  The Software is provided "as is", with no
+# warranty of any type, including any warranty for fitness for any purpose.
+# RTI is under no obligation to maintain or support the Software.  RTI shall
+# not be liable for any incidental or consequential damages arising out of the
+# use or inability to use the software.
+#
+
+cmake_minimum_required(VERSION 3.11)
+project(connext-tutorial-content-filtering)
+list(APPEND CMAKE_MODULE_PATH
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../resources/cmake/Modules"
+)
+include(ConnextDdsConfigureCmakeUtils)
+connextdds_configure_cmake_utils()
+
+# Include ConnextDdsAddExample.cmake from resources/cmake
+include(ConnextDdsAddExample)
+
+connextdds_call_codegen(
+    IDL "home_automation"
+    LANG "C++11"
+    PREFIX "home_automation"
+)
+
+connextdds_add_application(
+    TARGET "publisher"
+    LANG "C++11"
+    OUTPUT_NAME "home_automation_publisher"
+    SOURCES
+        $<TARGET_OBJECTS:home_automation_CXX11_obj>
+        "${CMAKE_CURRENT_SOURCE_DIR}/home_automation_publisher.cxx"
+    DEPENDENCIES
+    ${_CONNEXT_DEPENDENCIES}
+)
+
+connextdds_add_application(
+    TARGET "subscriber"
+    LANG "C++11"
+    OUTPUT_NAME "home_automation_subscriber"
+    SOURCES
+        $<TARGET_OBJECTS:home_automation_CXX11_obj>
+        "${CMAKE_CURRENT_SOURCE_DIR}/home_automation_subscriber.cxx"
+    DEPENDENCIES
+    ${_CONNEXT_DEPENDENCIES}
+)
+
+connextdds_add_application(
+    TARGET "subscriber_update_filter"
+    LANG "C++11"
+    OUTPUT_NAME "home_automation_subscriber_update_filter"
+    SOURCES
+        $<TARGET_OBJECTS:home_automation_CXX11_obj>
+        "${CMAKE_CURRENT_SOURCE_DIR}/home_automation_subscriber_update_filter.cxx"
+    DEPENDENCIES
+    ${_CONNEXT_DEPENDENCIES}
+)

tutorials/content_filtering/c++11/README.md

@@ -0,0 +1,50 @@
+# Tutorial: Content Filtering
+
+This code is part of the Connext
+[Content Filtering](https://community.rti.com/static/documentation/developers/learn/content-filtering.html)
+tutorial.
+
+## Building the Example :wrench:
+
+You can build the example following the instructions in the tutorial, or you can
+build it using CMake as follows.
+
+1.  Generate the build files:
+
+```sh
+mkdir build
+cd build
+cmake ..
+```
+
+This command will try to find the location of your Connext installation. If it
+can't find it, specify it with the ``-DCONNEXTDDS_DIR`` option, for example:
+
+```sh
+cmake -DCONNEXTDDS_DIR=/home/rti/rti_connext_dds-x.y.z ..
+```
+
+If you are compiling for windows you may also need to specify the
+[generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html),
+and platform.
+
+```sh
+cmake .. -G "Visual Studio 17 2022" -A x64
+```
+
+2.  Build the applications:
+
+```sh
+cmake --build .
+```
+
+If you are using a multi-configuration generator, such as Visual Studio
+solutions, you can specify the configuration mode to build as follows:
+
+```sh
+cmake --build . --config Release|Debug
+```
+
+## Running the Example :rocket:
+
+See the tutorial for instructions.

tutorials/content_filtering/c++11/USER_QOS_PROFILES.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+ RTI grants Licensee a license to use, modify, compile, and create derivative
+ works of the Software.  Licensee has the right to distribute object form only
+ for use with RTI products.  The Software is provided "as is", with no warranty
+ of any type, including any warranty for fitness for any purpose. RTI is under
+ no obligation to maintain or support the Software.  RTI shall not be liable for
+ any incidental or consequential damages arising out of the use or inability to
+ use the software.
+ -->
+<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://community.rti.com/schema/current/rti_dds_profiles.xsd">
+    <qos_library name="MyLibrary">
+        <qos_profile name="MyProfile" is_default_qos="true">
+            <base_name>
+                <element>BuiltinQosLib::Generic.StrictReliable</element>
+            </base_name>
+        </qos_profile>
+    </qos_library>
+</dds>

tutorials/content_filtering/c++11/home_automation.idl

@@ -0,0 +1,17 @@
+/*
+ * (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+ *
+ * RTI grants Licensee a license to use, modify, compile, and create derivative
+ * works of the Software.  Licensee has the right to distribute object form
+ * only for use with RTI products.  The Software is provided "as is", with no
+ * warranty of any type, including any warranty for fitness for any purpose.
+ * RTI is under no obligation to maintain or support the Software.  RTI shall
+ * not be liable for any incidental or consequential damages arising out of the
+ * use or inability to use the software.
+ */
+
+struct DeviceStatus {
+    @key string sensor_name;
+    string room_name;
+    boolean is_open;
+};

tutorials/content_filtering/c++11/home_automation_publisher.cxx

@@ -0,0 +1,39 @@
+//
+// (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+//
+//  RTI grants Licensee a license to use, modify, compile, and create derivative
+//  works of the Software.  Licensee has the right to distribute object form
+//  only for use with RTI products.  The Software is provided "as is", with no
+//  warranty of any type, including any warranty for fitness for any purpose.
+//  RTI is under no obligation to maintain or support the Software.  RTI shall
+//  not be liable for any incidental or consequential damages arising out of the
+//  use or inability to use the software.
+//
+
+#include <iostream>
+#include <thread>
+#include <rti/rti.hpp>
+#include "home_automation.hpp"
+
+void publish_sensor(
+        const std::string &sensor_name,
+        const std::string &room_name)
+{
+    dds::domain::DomainParticipant participant(0);
+    dds::topic::Topic<DeviceStatus> topic(participant, "WindowStatus");
+    dds::pub::DataWriter<DeviceStatus> writer(topic);
+
+    DeviceStatus device_status { sensor_name, room_name, false };
+    for (int i = 0; i < 1000; i++) {
+        device_status.is_open(!device_status.is_open());
+        writer.write(device_status);
+        std::this_thread::sleep_for(std::chrono::seconds(2));
+    }
+}
+
+int main(int argc, char **argv)
+{
+    std::string sensor_name = (argc > 1) ? argv[1] : "Window1";
+    std::string room_name = (argc > 2) ? argv[2] : "LivingRoom";
+    publish_sensor(sensor_name, room_name);
+}

tutorials/content_filtering/c++11/home_automation_subscriber.cxx

@@ -0,0 +1,45 @@
+//
+// (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+//
+//  RTI grants Licensee a license to use, modify, compile, and create derivative
+//  works of the Software.  Licensee has the right to distribute object form
+//  only for use with RTI products.  The Software is provided "as is", with no
+//  warranty of any type, including any warranty for fitness for any purpose.
+//  RTI is under no obligation to maintain or support the Software.  RTI shall
+//  not be liable for any incidental or consequential damages arising out of the
+//  use or inability to use the software.
+//
+
+#include <iostream>
+#include <thread>
+
+#include "rti/rti.hpp"
+#include "rti/sub/SampleProcessor.hpp"
+#include "home_automation.hpp"
+
+int main(int argc, char **argv)
+{
+    dds::domain::DomainParticipant participant(0);
+    dds::topic::Topic<DeviceStatus> topic(participant, "WindowStatus");
+    dds::topic::ContentFilteredTopic<DeviceStatus> content_filtered_topic(
+            topic,
+            "FilterRoomAndOpenWindows",
+            dds::topic::Filter("is_open = true and room_name = 'LivingRoom'"));
+    dds::sub::DataReader<DeviceStatus> reader(content_filtered_topic);
+
+    rti::sub::SampleProcessor sample_processor;
+    sample_processor.attach_reader(
+            reader,
+            [](const rti::sub::LoanedSample<DeviceStatus> &sample) {
+                if (sample.info().valid()) {  // ignore samples with only
+                                              // meta-data
+                    std::cout << "WARNING: " << sample.data().sensor_name()
+                              << " in " << sample.data().room_name()
+                              << " is open!" << std::endl;
+                }
+            });
+
+    while (true) {  // wait in a loop
+        std::this_thread::sleep_for(std::chrono::seconds(4));
+    }
+}

tutorials/content_filtering/c++11/home_automation_subscriber_update_filter.cxx

@@ -0,0 +1,53 @@
+//
+// (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+//
+//  RTI grants Licensee a license to use, modify, compile, and create derivative
+//  works of the Software.  Licensee has the right to distribute object form
+//  only for use with RTI products.  The Software is provided "as is", with no
+//  warranty of any type, including any warranty for fitness for any purpose.
+//  RTI is under no obligation to maintain or support the Software.  RTI shall
+//  not be liable for any incidental or consequential damages arising out of the
+//  use or inability to use the software.
+//
+
+#include <iostream>
+#include <thread>
+
+#include "rti/rti.hpp"
+#include "rti/sub/SampleProcessor.hpp"
+#include "home_automation.hpp"
+
+int main(int argc, char **argv)
+{
+    dds::domain::DomainParticipant participant(0);
+    dds::topic::Topic<DeviceStatus> topic(participant, "WindowStatus");
+    dds::core::StringSeq parameters(1, "'LivingRoom'");
+    dds::topic::ContentFilteredTopic<DeviceStatus> content_filtered_topic(
+            topic,
+            "FilterRoomAndOpenWindows",
+            dds::topic::Filter(
+                    "is_open = true and room_name = %0",
+                    parameters));
+    dds::sub::DataReader<DeviceStatus> reader(content_filtered_topic);
+
+    parameters[0] = "'Kitchen'";
+    content_filtered_topic.filter_parameters(
+            parameters.begin(),
+            parameters.end());
+
+    rti::sub::SampleProcessor sample_processor;
+    sample_processor.attach_reader(
+            reader,
+            [](const rti::sub::LoanedSample<DeviceStatus> &sample) {
+                if (sample.info().valid()) {  // ignore samples with only
+                                              // meta-data
+                    std::cout << "WARNING: " << sample.data().sensor_name()
+                              << " in " << sample.data().room_name()
+                              << " is open!" << std::endl;
+                }
+            });
+
+    while (true) {  // wait in a loop
+        std::this_thread::sleep_for(std::chrono::seconds(4));
+    }
+}

tutorials/content_filtering/py/README.md

@@ -0,0 +1,7 @@
+# Tutorial: Content Filtering
+
+This code is part of the Connext
+[Content Filtering](https://community.rti.com/static/documentation/developers/learn/content-filtering.html)
+tutorial and is included here in full for convenience.
+
+Please see the tutorial for instructions.

tutorials/content_filtering/py/USER_QOS_PROFILES.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ (c) 2024 Copyright, Real-Time Innovations, Inc.  All rights reserved.
+ RTI grants Licensee a license to use, modify, compile, and create derivative
+ works of the Software.  Licensee has the right to distribute object form only
+ for use with RTI products.  The Software is provided "as is", with no warranty
+ of any type, including any warranty for fitness for any purpose. RTI is under
+ no obligation to maintain or support the Software.  RTI shall not be liable for
+ any incidental or consequential damages arising out of the use or inability to
+ use the software.
+ -->
+<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://community.rti.com/schema/current/rti_dds_profiles.xsd">
+    <qos_library name="MyLibrary">
+        <qos_profile name="MyProfile" is_default_qos="true">
+            <base_name>
+                <element>BuiltinQosLib::Generic.StrictReliable</element>
+            </base_name>
+        </qos_profile>
+    </qos_library>
+</dds>