![Abstract geometric design with overlapping colored triangles and a stylized 'V' symbol (no text or symbols present)](.vortex-opensplice-python-dcps-api/68175a8f8936e97d2226734d8f07ba2818ebbfedf62402f8c6a8d9d8060f46c9.jpg) # ORTEX # Python DCPS API Guide # Release 6.x # Contents # 1 Preface 1 1.1 About the Python DCPS API Guide 1.2 Intended Audience # 2 Introduction 2 2.1 DDS 2 # 3 Installation 3 3.1 System Requirements 3 3.2 Dependencies . 3 3.3 OpenSplice (OSPL) and Python DCPS API Installation 3 3.4 Python DCPS API Setup 4 3.4.1 Install Python DCPS API package from python wheel . 4 3.4.2 Install Python DCPS API package from source 4 3.5 Examples and Documentation 5 # 4 Examples 6 4.1 Example Files 6 4.1.1 File Types . . 6 4.1.2 Examples 6 4.2 Running Examples 6 # 5 Python API for Vortex DDS 8 5.1 API Usage Patterns . 8 5.2 dds.Topic 9 5.3 dds.DomainParticipant 9 5.4 dds.Publisher 10 5.5 dds.DataWriter 10 5.6 dds.Subscriber 12 5.7 dds.DataReader 12 5.8 dds.QueryCondition 14 # 6 Quality of Service (QoS) 15 6.1 Setting QoS Using QoS Provider XML File 15 6.1.1 QoS Profile 15 6.1.2 Applying QoS Profile 16 6.2 Setting QoS Using Python DCPS API Classes 16 # 7 Topic Generation and Discovery 18 7.1 Over the Wire Discovery 18 7.2 Static Generation of Python Topic Classes Using IDL 19 7.3 Dynamic Generation of Python Topic Classes Using IDL and Name 19 # 8 Python Generation from IDL 20 8.1 Running IDLPP 20 8.1.1 Static Generation 20 8.1.2 Dynamic Generation 20 8.1.3 Generated Artifacts 21 8.2 Limitations of Python Support . . 22 # 9 Contacts & Notices 23 9.1 Contacts 23 9.2 Notices 23 # 1 # Preface # 1.1 About the Python DCPS API Guide The Python DCPS API Guide is a starting point for anyone using, developing or running Python applications with Vortex OpenSplice. This guide contains: • Python DCSP API installation instructions • location of Python DCPS API dds module documentation • overview of general DDS concepts and Python API for Vortex DDS • a listing of examples, and how to run them • detailed information on how to specify DDS entity Quality of Service (QoS) • how to discover and register DDS topics This reference guide is based on the OMG’s Data Distribution Service Specification and Python Language Mapping Specification. Please note that this guide is not intended to provide a detailed explanation of the aforementioned OMG specifications or the Vortex OpenSplice product. It provides an introduction to the essential concepts and enables users to begin using the Python DCPS API as quickly as possible. # 1.2 Intended Audience The Python Reference Guide is intended to be used by Python programmers who are using Vortex OpenSplice to develop applications. # 2 # Introduction The Python DCPS API provides users with Python classes to model DDS communication using Python and pure DDS applications. The Python DCPS API is a native Python binding that supports full DDS functionality. The language binding consists of a Python interface and a C wrapper implementation of the C99 API (C API for DDS). It makes use of Python language features and leverages ease of use by providing a higher level of abstraction. # 2.1 DDS # What is DDS? “The Data Distribution Service (DDS™) is a middleware protocol and API standard for data-centric connectivity from the Object Management Group® (OMG®). It integrates the components of a system together, providing low-latency data connectivity, extreme reliability, and a scalable architecture that business and mission-critical Internet of Things (IoT) applications need.” “The main goal of DDS is to share the right data at the right place at the right time, even between time-decoupled publishers and consumers. DDS implements global data space by carefully replicating relevant portions of the logically shared dataspace.” DDS specification ![**Labeled Blocks:**\n* **Data-Object** (Top oval)\n* **Publisher** (Left box)\n* **DataWriter** (Left box)\n* **Subscriber** (Right boxes, appears twice)\n* **DataReader** (Right boxes, appears twice)\n\n**Connections and Text:**\n* **DataWriter** to **Publisher**: Solid arrow labeled 'data values'.\n* **Publisher** to **Subscriber** (both instances): Dashed line labeled 'dissemination'.\n* **Subscriber** to **DataReader** (both instances): Solid arrow labeled 'data values'.\n* **Publisher** to **Data-Object**: Dashed line labeled 'Identified by means of the Topic'.\n* **DataReader** (top right box) to **Data-Object**: Dashed line labeled 'Identified by means of the Topic'.\n* **DataReader** (bottom right box) to **Data-Object**: Dashed line along the far right edge.](.vortex-opensplice-python-dcps-api/66e4402dd1e48c2ebdd022bd71ba24c4bab93897a33f445678c1cc4a96f50810.jpg) # Further Documentation http://portals.omg.org/dds/ http://ist.adlinktech.com/ # 3 # Installation This section describes the procedure to install the Python DCPS API on a Linux or Windows platform. # 3.1 System Requirements Operating System: Linux or Windows # 3.2 Dependencies # Linux • Python3 version 3.4.0 or later • pip3 (package “python3-pip” on most linux package managers) • GCC 4.8 or later # Windows • Python version 3.5.0 • pip (usually already included in Python for Windows) • Visual Studio 14 (2015) C compiler or later # Python modules • Cython version 0.27 or later (install using “pip3 install Cython”) # 3.3 OpenSplice (OSPL) and Python DCPS API Installation # Steps: 1. Install OSPL. The Python DCPS API is included in this installer. 2. Setup OSPL license. Copy the license.lic file into the appropriate license directory. /INSTALLDIR/Vortex\_v2/license 3. Python DCPS API files are contained in a tools/python folder Example: \$OSPL\_HOME/tools/python ![python\nx86_64.linux tools python\nRecent\nHome\nDesktop\nDocuments\nDownloads\nMusic\nPictures\nVideos\nTrash\nName\ndocs\nexamples\nsrc\ndds-6.9.1-cp35-cp35m-linux...\nSize\n4 items Folder\n11 items Folder\n5 items Folder\n1.0 MB Archive](.vortex-opensplice-python-dcps-api/ef68efd830a33fbf11d9d429bb4364a0c68024926eaf1aeed756edc2d97d31f9.jpg) # 3.4 Python DCPS API Setup # 3.4.1 Install Python DCPS API package from python wheel In certain Vortex OpenSplice installs, the python api is bundled as a python wheel file in the \$OSPL\_HOME/tools/python directory. This way it avoids needing a native compiler and Cython prerequisites before installation. Simply install using pip. For example, executing the command will install the wheel package, which is targeted for python 3.4 64-bit Linux: \$pip3 install dds-6.9.0-cp34-cp34m-linux\_x86\_64.whl Or similarly, for python 3.5 64-bit Windows: >pip install dds-6.9.0-cp35-cp35m-win\_amd64.whl If the binary wheel package is not present or is not compatible with your python version, then it is preferable to install the api from source. # 3.4.2 Install Python DCPS API package from source If the dependencies are satisfied, and the Vortex OpenSplice environment is set (OSPL\_HOME and associated environment variables), then installation is just one command to execute in the \$OSPL\_HOME/python/src directory: \$python3 setup.py install # Note: • In either case, installing from wheel or from source may require administrator or superuser privileges if python was installed for all users. • To check modules are installed correctly try importing the installed modules. ```txt >>> import dds >>> import ddsutil ``` # 3.4. Python DCPS API Setup # 3.5 Examples and Documentation # 1. Examples The examples can be found in the following directory: • \$OSPL\_HOME/tools/python/examples # 2. Python DCPS API Documentation The Python DCPS API can be found in the following directory: • \$OSPL\_HOME/tools/python/docs/html # 3. Python DCPS User Guide (HTML and PDF) The user guide can be found in the following directories: • \$OSPL\_HOME/docs/html • \$OSPL\_HOME/docs/pdf # 4 # Examples Several examples are provided to demonstrate the Python DCPS features. The examples can be found in the following directory: • \$OSPL\_HOME/tools/python/examples # 4.1 Example Files # 4.1.1 File Types The examples directory contains files of different types. The runnable python script files reference the xml and idl files.
File TypeDescription
pyA program file or script written in Python
xmlAn XML file that contains one or more Quality of Service (QoS) profiles for DDS entities.
idlAn interface description language file used to define topic(s).
# 4.1.2 Examples
ExampleDescription
qos_example.pyAn example that demonstrates how to specify QoS settings using Python DCPS APIs. Also shows usage of a waitset.
example1.pyDynamic generation of Python Topic classes using IDL file and name. Uses a topic with a sequence.
example2.pyDynamic generation of Python Topic classes using Enumeration and nested modules.
example4.pyDemonstrate finding DDS topics over-the-wire. Find topics registered by other processes, and read and write samples to those topics.
# 4.2 Running Examples To run an example python script: 1. Setup OSPL environment variables. Linux • source release.com Windows • release.bat 2. Run an example python script • > python3 example1.py # 5 # Python API for Vortex DDS The Python DCPS API provides users with Python classes to model DDS communication using Python and pure DDS applications. The Python DCPS API consists of 2 modules. • dds module • ddsutil module This section provides an overview of the main DDS concepts and Python API examples for these DDS concepts. # Note: • The Python DCPS API can be found in the following directory: \$OSPL\_HOME/tools/python/docs/html # 5.1 API Usage Patterns The typical usage pattern for the Python DCPS API for Vortex DDS is the following: • optional - Model your DDS topics using IDL. Alternatively, the python scripts can use topics that already exist in the DDS system. • optional - Statically generate Python topic classes using idlpp -l python. If using IDL, the user also has the option to dynamically generate Python topic classes in python scripts. See Python Generation from IDL. • Start writing your Python program using the Python API for Vortex DDS. The core classes you must use are dds.Topic, dds.DomainParticipant and either dds.DataReader or dds.DataWriter. Other classes may be required, especially if you need to adjust the Quality of Service (QoS) defaults. For details on setting QoS values with the API, see Quality of Service (QoS). The following list shows the sequence in which you would use the Vortex classes: • Create a dds.DomainParticipant instance. • Create one or more dds.Topic instances for the IDL topics your program will read or write. • If you require publisher or subscriber level non-default QoS settings, create dds.Publisher and/or dds.Subscriber instances. (The most common reason for changing publisher/subscriber QoS is to define non-default partitions.) • Create dds.DataReader and/or dds.DataWriter classes using the dds.Topic instances that you created. • If you required data filtering, create dds.QueryCondition objects. • Create the core of program, creating instances of your topic classes and writing them; or, reading data and processing it. # 5.2 dds.Topic The Python Topic class represents a DDS topic type. The DDS topic corresponds to a single data type. In DDS, data is distributed by publishing and subscribing topic data samples. For a DDS Topic type definition, a corresponding Python class must be defined. These topic classes are either a class created statically using idlpp, dynamically using an idl file or dynamically for an existing topic discovered in the system. (see Topic Generation and Discovery) # API Examples Create a Vortex DDS topic named ‘Msg1’ based on the DDS Topic type Msg. ```python TOPIC_NAME = 'Msg1' TOPIC_TYPE = 'HelloWorldData::Msg' IDL_FILE = 'idl/HelloWorldData.idl' # Create domain participant dp = DomainParticipant() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl(IDL_FILE, TOPIC_TYPE) # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.RELIABLE)]) topic = gen_info.register_topic(dp, TOPIC_NAME, qos) ``` # 5.3 dds.DomainParticipant The Python‘‘dds.DomainParticipant‘‘ class represents a DDS domain participant entity. In DDS - “A domain participant represents the local membership of the application in a domain. A domain is a distributed concept that links all the applications able to communicate with each other. It represents a communication plane: only the publishers and subscribers attached to the same domain may interact.” The dds.DomainParticipant has two optional parameters on creation. If these parameters are not provided, defaults are used. Parameters: • qos (Qos) – Participant QoS. Default: None • listener (Listener) – Participant listener Default: None # API Examples Create a Vortex DDS domain participant. Returns participant or throws a dds.DDSException if the participant cannot be created. Create a domain participant in the default DDS domain (the one specified by the OSLP\_URI environment variable). ```python # Create domain participant dp = DomainParticipant() ``` Create a participant on default domain with QoS profile. ```python qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') # Create participant dp = DomainParticipant(qos = qp.get_participant_qos()) ``` Create a participant on domain with QoS profile and listener. TODO # 5.2. dds.Topic ```python qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') # Create participant dp = DomainParticipant(qos = qp.get_participant_qos()) ``` # 5.4 dds.Publisher The Python dds.Publisher class represents a DDS publisher entity. In DDS, a publisher is “an object responsible for data distribution. It may publish data of different data types.” Use of the dds.Publisher class is optional. In it’s place, you can use a dds.DomainParticipant instance. Reasons for explicitly creating a dds.Publisher instance are: • to specify non-default QoS settings, including specifying the DDS partition upon which samples are written. • to control the timing of publisher creation and deletion. # API Examples Create a DDS Publisher entity. Returns publisher or throws a dds.DDSException if the publisher cannot be created. Create a publisher with participant. ```python # Create participant dp = DomainParticipant() # Create publisher pub = dp.create_publisher() ``` Create a publisher with participant and QoS profile. ```python qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') # Create participant dp = DomainParticipant(qos = qp.get_participant_qos()) # Create publisher pub = dp.create_publisher(qos = qp.get_publisher_qos()) ``` # 5.5 dds.DataWriter The Python dds.Writer class represents a DDS data writer entity. In DDS - “The DataWriter is the object the application must use to communicate to a publisher the existence and value of data-objects of a given type.” A dds.DataWriter class is required in order to write data to a DDS domain. It is attached to a DDS publisher or a DDS domain participant. A dds.DataWriter class instance references an existing dds.Topic instance. # API Examples Create a Vortex DDS domain writer. Returns writer or throws a dds.DDSException if the writer cannot be created. Create a writer within a domain participant, and with default QoS. ```python # Create domain participant dp = DomainParticipant() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl('idl/HelloWorldData.idl', 'HelloWorldData::Msg') # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityK topic = gen_info.register_topic(dp, 'Msg1', qos) # Create a writer writer = dp.create_datawriter(topic) ``` Create a writer within a publisher, and with default QoS. ```python # Create domain participant dp = DomainParticipant() # Create publisher pub = dp.create_publisher() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl('idl/HelloWorldData.idl', 'HelloWorldData::Msg') # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityK topic = gen_info.register_topic(dp, 'Msg1', qos) # Create a writer writer = pub.create_datawriter(topic) ``` Create a writer with publisher or participant, topic and QoS profile. ```python # Create domain participant dp = DomainParticipant() # Create publisher pub = dp.create_publisher() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl('idl/HelloWorldData.idl', 'HelloWorldData::Msg') # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.Trans, qos) # Create a writer qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') writer = pub.create_datawriter(topic) writer = pub.create_datawriter(topic, qp.get_writer_qos()) ``` Write a Msg topic class instance to a writer. ```python # Topic data class idMessage = 1 message1 = 'Hello World' s = gen_info.topic_data_class (userID = idMessage, message = message1) # Write data writer.write(s) ``` Dispose a DDS topic instance. # 5.5. dds.DataWriter ```txt # dispose instance writer.dispose_instance(s) ``` Unregister a DDS topic instance. TODO no equivalent in Python API % writer: a Vortex.Writer instance % ShapeType: a ‘topic class’ created manually or via IDLPP data = ShapeType(); % create an object instance % set data key values... data.color = ‘RED’; ddsStatus = writer.unregister(data); # 5.6 dds.Subscriber The Python dds.Subscriber class represents a DDS subscriber entity. In DDS, a subscriber is “an object responsible for receiving published data and making it available to the receiving application. It may receive and dispatch data of different specified types.” Use of the dds.Subscriber class is optional. In it’s place, you can use a dds.DomainParticipant instance. Reasons for explicitly creating a dds.Subscriber instance are: • to specify non-default QoS settings, including specifying the DDS partition upon which samples are written. • to control the timing of subscriber creation and deletion. # API Examples Create a Vortex DDS domain subscriber. Returns subscriber or throw a dds.DDSException if the subscriber cannot be created. Create a subscriber with participant. ```python # Create participant dp = DomainParticipant() # Create Subscriber sub = dp.create_subscriber() ``` Create a subscriber with participant and QoS profile. ```python qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') # Create participant dp = DomainParticipant(qos = qp.get_participant_qos()) # Create Subscriber sub = dp.create_subscriber(qos = qp.get_subscriber_qos()) ``` # 5.7 dds.DataReader The Python Vortex.Reader class represents a DDS data reader entity. In DDS - “To access the received data, the application must use a typed DataReader attached to the subscriber.” A dds.DataReader class is required in order to write data to a DDS domain. It is attached to a DDS subscriber or a DDS domain participant. A dds.DataReader class instance references an existing dds.Topic instance. # API Examples Create a Vortex DDS domain reader. Returns reader or throw a dds.DDSException instance if the reader cannot be created. Create a reader for a topic within a participant, and with default QoS. ```python # Create domain participant dp = DomainParticipant() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl('idl/HelloWorldData.idl', 'HelloWorldData::Msg') # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityK topic = gen_info.register_topic(dp, 'Msg1', qos) # Create a reader reader = dp.create_datareader(topic) ``` Create a reader for a topic within a subscriber, and with default QoS. ```python # Create domain participant dp = DomainParticipant() # Create subscriber sub = dp.create_subscriber() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl(IDL_FILE, TOPIC_TYPE) # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityK topic = gen_info.register_topic(dp, TOPIC_NAME, qos) # Create a reader reader = sub.create_datareader(topic) ``` Create a reader for a topic within a subscriber or participant, with with a QoS profile. ```python # Create domain participant dp = DomainParticipant() # Create subscriber sub = dp.create_subscriber() # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl(IDL_FILE, TOPIC_TYPE) # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityK topic = gen_info.register_topic(dp, TOPIC_NAME, qos) # Create a reader qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') reader = sub.create_datareader(topic, qp.get_reader_qos()) ``` Take data from a data reader. ```txt l = reader.take(10) ``` Read data from a data reader. ```txt l = reader.read(10) ``` Specify a wait timeout, in seconds, before read or take will return without receiving data TODO change description the code is wrong ```txt # Create waitset waitset = WaitSet() qc = QueryCondition(reader, DDSMaskUtil.all_samples(), 'long1 > 1') ``` ```python waitset.attach(qc) # Wait for data conditions = waitset.wait() # Print data l = reader.take(10) ``` # 5.8 dds.QueryCondition The Python dds.QueryCondition class represents a DDS query entity. A query is a data reader, restricted to accessing data that matches specific status conditions and/or a filter expression. A dds.Query class instance references an existing dds.DataReader instance. # API Examples Create a dds.QueryCondition with a state mask and a filter expression for a reader and take data. ```python # Create waitset waitset = WaitSet() qc = QueryCondition(reader, DDSMaskUtil.all_samples(), 'long1 > 1') waitset.attach(qc) # Wait for data conditions = waitset.wait() # Print data l = reader.take(10) for sd, si in l: sd.print_vars() ``` # 6 # Quality of Service (QoS) The following section explains how to set the Quality of Service (QoS) for a DDS entity. Users have two options available to set the QoS for an entity or entities. They can define the QoS settings using an XML file, or they can use the Python DCPS APIs. Both of these options are explained. If a QoS setting for an entity is not set using an xml file or the Python DCPS APIs, the defaults will be used. This allows a user the ability to override only those settings that require non-default values. The code snippets referenced are taken from the runnable examples. # Note: • The Examples section provides the examples directory location, example descriptions and running instructions. # 6.1 Setting QoS Using QoS Provider XML File QoS for DDS entities can be set using XML files based on the XML schema file QoSProfile.xsd. These XML files contain one or more QoS profiles for DDS entities. Sample QoS Profile XML files can be found in the examples directory. # 6.1.1 QoS Profile A QoS profile consists of a name and optionally a base\_name attribute. The base\_name attribute allows a QoS or a profile to inherit values from another QoS or profile in the same file. The file contains QoS elements for one or more DDS entities. A skeleton file without any QoS values is displayed below to show the structure of the file. ```xml <dds xmlns="http://www.omg.org/dds/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:sci> <qos_profile name="DDS QoS Profile Name"> <datareader_qos></datareader_qos> <datawriter_qos></datawriter_qos> <domainparticipant_qos></domainparticipant_qos> <subscriber_qos></subscriber_qos> <publisher_qos></publisher_qos> <topic_qos></topic_qos> </qos_profile> </dds> ``` # Example: Specify Publisher Partition The example below specifies the publisher’s partitions as A and B. ```xml <publisher_qos> <partition> <name> <element>A</element> <element>B</element> ``` ```xml </name> </partition> </publisher_qos> ``` # 6.1.2 Applying QoS Profile To set the QoS profile for a DDS entity using the Python DCPS API and an XML file, the user specifies the File URI and the QoS profile name as parameters. example1.py ```python qp = QosProvider('file://DDS_DefaultQoS_All.xml', 'DDS DefaultQosProfile') # Create participant dp = DomainParticipant(qos = qp.get_participant_qos()) # Create publisher pub = dp.create_publisher(qos = qp.get_publisher_qos()) # Create Subscriber sub = dp.create_subscriber(qos = qp.get_subscriber_qos()) ``` # 6.2 Setting QoS Using Python DCPS API Classes QoS settings can also be set by using the python classes alone. (No XML files required.) Below is a code snippet that demonstrates how to specify the QoS settings for a writer using the python DCPS apis. In this example, all the QoS settings for the writer are set and all of the default QoS settings are overridden. If a QoS setting for an entity is not set, the default is used. qos\_example.py ```txt ... writer_qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), DeadlineQosPolicy(DDSDuration(500)), LatencyBudgetQosPolicy(DDSDuration(3000)), LivelinessQosPolicy(DDSLivelinessKind.MANUAL_BY_PARTICIPANT), ReliabilityQosPolicy(DDSReliabilityKind.RELIABLE, DDSDuration.infinity()), DestinationOrderQosPolicy(DDSDestinationOrderKind.BY_SOURCE_TIMESTAMP), HistoryQosPolicy(DDSHistoryKind.KEEP_ALL), ResourceLimitsQosPolicy(10, 10, 10), TransportPriorityQosPolicy(700), LifespanQosPolicy(DDSDuration(10, 500)), OwnershipQosPolicy(DDSOwnershipKind.EXCLUSIVE), OwnershipStrengthQosPolicy(100), WriterDataLifecycleQosPolicy(False) ]) ``` In the next example, a topic QoS is created that overrides only a subset of the QoS settings. HelloWorldDataSubscriber.py ```txt ... # Create domain participant dp = DomainParticipant() # Create subscriber sub = dp.create_subscriber() ``` ```python # Generate python classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl(IDL_FILE, TOPIC_TYPE) # Create a topic QoS that overrides defaults for durability and reliability qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.RELIABLE)]) topic = gen_info.register_topic(dp, TOPIC_NAME, qos) ... ``` # 7 # Topic Generation and Discovery A DDS Topic represents the unit for information that can be produced or consumed by a DDS application. Topics are defined by a name, a type, and a set of QoS policies. The Python DCPS API provides several ways of generating Python classes to represent DDS topics. • over the wire discovery • dynamic generation of Python Topic classes using parameters IDL file and topic name • static generation of Python Topic classes using IDL # Note: • The Examples section provides the examples directory location, example descriptions and running instructions. # 7.1 Over the Wire Discovery Python topic classes can be generated for existing DDS topics in the DDS system. These topics are “discovered over the wire”. The Python classes are generated when the topic is requested by name. A code snippet is provided from example4.py. This example finds a topic registered by another process, and reads and writes samples to that topic. # example4.py ```python ... print('Connecting to DDS domain...' dp = dds.DomainParticipant() print('Finding OsplTestTopic...' found_topic = dp.find_topic('OsplTestTopic') print('Registering OsplTestTopic locally') local_topic = ddsutil.register_found_topic_as_local(found_topic) print('Getting Python classes for the found topic...' gen_info = ddsutil.get_dds_classes_for_found_topic(found_topic) OsplTestTopic = gen_info.get_class(found_topic.type_name) Tstate = gen_info.get_class('ospllog::Tstate') print('Creating sample data to write...' data = OsplTestTopic(id=11,index=22, x=1.2, y=2.3, z=3.4, t=9.8, state=Tstate.init, description='Hello from Python') print('Creating readers and writers...' pub = dp.create_publisher() wr = pub.create_datawriter(local_topic, found_topic.qos) ``` ```matlab sub = dp.create_subscriber() rd = sub.create_datareader(local_topic, found_topic.qos) print('Writing sample data...') wr.write(data) print('Wrote: %s' % (str(data))) ... ``` # 7.2 Static Generation of Python Topic Classes Using IDL The Python topic classes can be generated statically using an IDL file. Please see Static Generation for more information. # 7.3 Dynamic Generation of Python Topic Classes Using IDL and Name The Python topic classes can be generated dynamically using an IDL file, and the topic name. Please see Dynamic Generation for more information. # 8 # Python Generation from IDL The Python DCPS API supports generation of Python topic classes from IDL. This chapter describes the details of the IDL-Python binding. # 8.1 Running IDLPP # 8.1.1 Static Generation The Python topic classes can be generated statically using an IDL file. Compiling IDL into python code is done using the -l python switch on idlpp: ```batch idlpp -l python idl-file-to-compile.idl ``` # Note: • A Python package with the same name as the idl file (without the .idl extension) is always created. • It defines types not included in an IDL module. IDL modules become Python packages within this base package. # 8.1.2 Dynamic Generation The Python topic classes can be generated dynamically using an IDL file, and the topic name. An api, ddsutil.get\_dds\_classes\_from\_idl, is provided to generate the topic classes at runtime from within a Python script. # HelloWorldDataPublisher.py ```python ... TOPIC_NAME = 'Msg1' TOPIC_TYPE = 'HelloWorldData::Msg' IDL_FILE = 'idl/HelloWorldData.idl' # Create domain participant dp = DomainParticipant() # Create publisher pub = dp.create_publisher() # Generate python topic classes from IDL file gen_info = ddsutil.get_dds_classes_from_idl(IDL_FILE, TOPIC_TYPE) # Type support class qos = Qos([DurabilityQosPolicy(DDSDurabilityKind.TRANSIENT), ReliabilityQosPolicy(DDSReliabilityKind.RELIABLE)]) # Register topic ``` ```python topic = gen_info.register_topic(dp, TOPIC_NAME, qos) # Create a writer writer = pub.create_datawriter(topic) # Topic data class idMessage = 1 message1 = 'Hello World' s = gen_info.topic_data_class(userID = idMessage, message = message1) # Write data writer.write(s) # output to console print('=== [Publisher] writing a message containing : ') print('userID :', idMessage) print('message :', message1) ... ``` # 8.1.3 Generated Artifacts The following table defines the Python artifacts generated from IDL concepts:
IDLConceptPythonConceptComment
modulepackageFolder with module name, plus __init__.py that defines types defined within the module.
enumclassDefined in __init__.py files.
enum valueenum valueDefined in __init__.py files.
structclassDefined in __init__.py files.
fieldclass propertyDefined in __init__.py files.
unionunionDefined in __init__.py files. (Only statically generated supported)
# Datatype mappings The following table shows the Python equivalents to IDL primitive types:
IDL TypePython Type
booleanbool
charstr, length==1
octetint
shortint
ushortint
longint
ulongint
long longint
ulong longint
floatfloat
doublefloat
stringstr
wcharUnsupported
wstringUnsupported
anyUnsupported
long doubleUnsupported
# Implementing Arrays and Sequences in Python Both IDL arrays and IDL sequences are mapped to Python lists. The constructors for generated classes always fully allocate any array fields. Sequences are always initialized to the empty list. # 8.1. Running IDLPP # 8.2 Limitations of Python Support The IDL-to-Python binding has the following limitations: • IDL unions are Supported by statically generated Python, but not by dynamic or over-the-wire. • The following IDL data types are not supported: wchar, wstring, any and long double . # 9 # Contacts & Notices # 9.1 Contacts # ADLINK Technology Corporation 400 TradeCenter Suite 5900 Woburn, MA 01801 USA Tel: +1 781 569 5819 # ADLINK Technology Limited The Edge 5th Avenue Team Valley Gateshead NE11 0XA UK Tel: +44 (0)191 497 9900 # ADLINK Technology SARL 28 rue Jean Rostand 91400 Orsay France Tel: +33 (1) 69 015354 Web: http://ist.adlinktech.com/ Contact: http://ist.adlinktech.com E-mail: ist\_info@adlinktech.com LinkedIn: https://www.linkedin.com/company/79111/ Twitter: https://twitter.com/ADLINKTech\_usa Facebook: https://www.facebook.com/ADLINKTECH # 9.2 Notices Copyright © 2018 ADLINK Technology Limited. All rights reserved. This document may be reproduced in whole but not in part. The information contained in this document is subject to change without notice and is made available in good faith without liability on the part of ADLINK Technology Limited. All trademarks acknowledged. [🔗 Link to the original document](.vortex-opensplice-python-dcps-api/vortex-opensplice-python-dcps-api.pdf)