5. Installation and Configuration

Follow the instructions in this chapter to install and configure Vortex OpenSplice and its tools. Information on running the Vortex OpenSplice examples are provided at the end of the chapter under Examples.

5.1. Vortex OpenSplice Development and Run-Time

Vortex OpenSplice is provided in two installers. The HDE (Host Development Environment) is the standard and the RTS (Run Time System).

The HDE contains all of the services, libraries, header files and tools needed to develop applications using Vortex OpenSplice, and the RTS is a subset of the HDE which contains all of the services, libraries and tools needed to deploy applications using Vortex OpenSplice.

5.2. Installation for UNIX and Windows Platforms

This section describes the normal procedure to install Vortex OpenSplice on a UNIX or Windows platform. The exception is the procedure to install Vortex OpenSplice on a UNIX ARM platform which is described in section UNIX ARM platform

Step 1

Install Vortex OpenSplice.

Run the installation wizard for your particular installation, using:

P<code>-VortexOpenSplice<version>-<E>-<platform>.<os>-<comp>-<type>-<target>-installer.<ext>

where, some being optional,

<code> - ADLINK’s code for the platform <version> - the Vortex OpenSplice version number, for example V6.0

<E> - the environment, either HDE or RTS

<platform> - the platform architecture, for example sparc or x86

<os> - the operating system for example solaris8 or linux2.6

<comp> - the compiler or glibc version

<type> - release, debug or dev, which is release with symbols

<target> - the target architecture for host/target builds.

<ext> - the platform executable extension, either run or exe

The directories in the Vortex OpenSplice distribution are named after the installation package they contain. Each package consists of an archive and its installation procedure.

Step 2

unix

Configure the Vortex OpenSplice environment variables.

(This is only necessary on UNIX, as the Windows environment is configured by the Vortex OpenSplice installer.)

Go to the <install_dir>/<E>/<platform> directory, where <E> is HDE or RTS and <platform> is, for example, x86.linux2.6.

Source the release.com file from the shell command line.

This step performs all the required environment configuration.

Step 3

Usually not required, but install your desired ORB when the C++ language mapping is used with CORBA cohabitation. Ensure your chosen ORB and compiler is appropriate for the CCPP library being used (either Vortex OpenSplice’s default library or other custom-built library). Refer to the Release Notes for ORB and compiler information pertaining to Vortex OpenSplice’ default CCPP library.

5.3. Installation on Other Platforms

Please refer to Platform-specific Information for information about using Vortex OpenSplice on platforms other than Unix/Linux and Windows.

5.4. Configuration

Vortex OpenSplice is configured using an XML configuration file, as shown under Example XML Configuration Settings . It is advisable to use the osplconf tool (UNIX) or Vortex OpenSplice Configurator Tool (Windows Start Menu ) to edit your xml files. The configurator tool provides explanations of each attribute and also validates the input.

The default configuration file is ospl.xml located in $OSPL_HOME/etc/config (alternative configuration files may also be available in this directory, to assist in other scenarios). The default value of the environment variable OSPL_URI is set to this configuration file.

The configuration file defines and configures the following Vortex OpenSplice services:

spliced
The default service, also called the domain service; the domain service is responsible for starting and monitoring all other services.
durability
This service is responsible for storing non-volatile data and keeping it consistent within the domain (optional).
networking
This service realizes user-configured communication between the nodes in a domain.
tuner
This service provides a SOAP interface for the Vortex OpenSplice Tuner to connect to the node remotely from any other reachable node.

The default deployment specified by the XML configuration file is for a Single Process deployment. This means that the Vortex OpenSplice Domain Service, database administration and associated services are all started within the DDS application process. This is implicitly done when the user’s application invokes the DDS create_participant operation.

The deployment mode and other configurable properties can be changed by using a different OSPL_URI file. Several sample configuration files are provided at the same location.

info
If using a shared memory configuration, a <Database> attribute is specified in the XML configuration. The default Database Size that is mapped on a shared memory segment is 10 Megabytes.
caution
Note: The maximum user-creatable shared-memory segment is limited on certain machines, including Solaris, so it must either be adjusted or Vortex OpenSplice must be started as root.

A complete configuration file that enables durability as well as Real Time Native Networking is shown below. (The relevant lines are not enabled in the default configuration file, but editing them will allow you to enable support for PERSISTENT data (instead of just TRANSIENT or VOLATILE data) and to use multicast instead of broadcast.)

Adding support for PERSISTENT data requires you to add the <Persistent> element to the <DurabilityService> content (see the relevant lines in the XML example shown below). In this <Persistent> element you can then specify the actual path to the directory for persistent-data storage (if it does not exist, the directory will be created). In the example below this directory is /tmp/Pdata.

For the networking service, the network interface-address that is to be used is specified by the <NetworkInterfaceAddress> element. The default value is set to first available , meaning that Vortex OpenSplice will determine the first available interface that is broadcast or multicast enabled. However, an alternative address may be specified as well (specify as a.b.c.d).

The network service may use separate channels, each with their own name and their own parameters (for example the port-number, the queue size, and, if multicast enabled, the multicast address). Channels are either reliable (all data flowing through them is delivered reliably on the network level, regardless of QoS settings of the corresponding writers) or not reliable (all data flowing through them is delivered at most once, regardless of QoS settings of the corresponding writers). The idea its that the network service chooses the most appropriate channel for each DataWriter, i.e. the channel that fits its QoS settings the best.

Usually, networking shall be configured to support at least one reliable and one non-reliable channel. Otherwise, the service might not be capable of offering the requested reliability. If the service is not capable of selecting a correct channel, the message is sent through the default channel. The example configuration defines both a reliable and a non-reliable channel.

The current configuration uses broadcast as the networking distribution mechanism. This is achieved by setting the Address attribute in the GlobalPartition element to broadcast, which happens to be the default value anyway. This Address attribute can be set to any multicast address in the notation a.b.c.d in order to use multicast.

caution
If multicast is required to be used instead of broadcast, then the operating system’s multicast routing capabilities must be configured correctly.

See the Vortex OpenSplice Deployment Manual for more advanced configuration settings.

Example XML Configuration Settings

<OpenSpliceDDS>
    <Domain>
        <Name>OpenSpliceDDSV6.6</Name>
        <Database>
            <Size>10485670</Size>
        </Database>
        <Lease>
            <ExpiryTime update_factor=”0.05”>60.0</ExpiryTime>
        </Lease>
        <Service name="networking">
            <Command>networking</Command>
        </Service>
        <Service name="durability">
            <Command>durability</Command>
        </Service>
    </Domain>
    <NetworkService name="networking">
        <General>
            <NetworkInterfaceAddress>
                first available
            </NetworkInterfaceAddress>
        </General>
        <Partitioning>
          <GlobalPartition Address="broadcast"/>
        </Partitioning>
        <Channels>
           <Channel name="BestEffort" reliable="false"
              default="true">
                <PortNr>3340</PortNr>
            </Channel>
            <Channel name="Reliable" reliable="true">
                <PortNr>3350</PortNr>
            </Channel>
        </Channels>
    </NetworkService>
    <DurabilityService name="durability">
        <Network>
            <InitialDiscoveryPeriod>2.0</InitialDiscoveryPeriod>
            <Alignment>
                <RequestCombinePeriod>
                    <Initial>2.5</Initial>
                    <Operational>0.1</Operational>
                </RequestCombinePeriod>
            </Alignment>
            <WaitForAttachment maxWaitCount="10">
                <ServiceName>networking</ServiceName>
            </WaitForAttachment>
        </Network>
        <NameSpaces>
            <NameSpace durabilityKind="Durable"
                alignmentKind="Initial_and_Aligner">
                <Partition>*</Partition>
            </NameSpace>
        </NameSpaces>
        <Persistent>
            <StoreDirectory>/tmp/Pdata</StoreDirectory>
        </Persistent>
    </DurabilityService>
</OpenSplice>

5.4.1. Example configuration files

Vortex OpenSplice is delivered with a set of ready-made configuration files which provide a quick way of achieving different setups.

ospl_shmem_ddsi.xml
Federated deployment using shared-memory and standard DDSI networking.
ospl_shmem_ddsi2e.xml
Federated deployment using shared-memory and extended DDSI networking.
ospl_shmem_nativeRT.xml
Federated deployment using shared-memory and RTNetworking.
ospl_shmem_no_network.xml
Federated deployment using shared-memory only (i.e. without networking).
ospl_shmem_secure_nativeRT.xml
Federated deployment using shared-memory and secure RTNetworking.
ospl_sp_ddsi.xml
Stand-alone ‘single-process’ deployment and standard DDSI networking.
ospl_sp_ddsi_nativeRT_cohabitation.xml
Stand-alone ‘single-process’ deployment using DDSI and RTNetworking in cohabitation mode.
ospl_sp_nativeRT.xml
Stand-alone ‘single-process’ deployment using RTNetworking.
ospl_sp_ddsi_statistics.xml
Stand-alone ‘single-process’ deployment with DDSI networking and enabled statistics.
ospl_sp_no_network.xml
Stand-alone ‘single-process’ deployment without networking connectivity.

5.5. Examples

A great way to get started with Vortex OpenSplice is to try running the examples provided with the product. There are many examples in different languages and some with the CORBA cohabitation, showing different aspects of the DCPS API. To give you a feel for how powerful DDS is then we recommend trying PingPong and the Tutorial, as well as the RoundTrip and Throughput.

The way to build and run the examples is dependent on the Platform you are using. Each example has HTML documentation explaining how to build and run it on Unix/Linux and Windows systems.

For VxWorks and Integrity, please refer to VxWorks 5.5.1, VxWorks 6.x RTP, and Integrity in this Guide.

5.5.1. Using the Vortex OpenSplice Tools

caution
Note: The following instructions apply only to the shared memory deployment of Vortex OpenSplice. When deploying in single process configuration, there is no need to manually start the Vortex OpenSplice infrastructure prior to running a DDS application process, as the administration will be created within the application process. Please refer to the Vortex OpenSplice Deployment Guide for a discussion of these deployment architectures.

The Vortex OpenSplice infrastructure can be stopped and started from the Windows Start Menu , as well as the Tuner and Configurator.

Step 1

Manually start the Vortex OpenSplice infrastructure

  1. Enter ospl start on the command line [1]. This starts the Vortex OpenSplice services.

These log files may be created in the current directory when Vortex OpenSplice is started:

ospl-info.log - contains information and warning reports

ospl-error.log - contains error reports

info
If Vortex OpenSplice is used as a Windows Service then the log files are re-directed to the path specified by OSPL_LOGPATH. (Use the set command in the Vortex OpenSplice command prompt to see the OSPL_LOGPATH value.)

Step 2

Start the Vortex OpenSplice Tuner Tool

  1. Read the Vortex OpenSplice Tuner Guide (TunerGuide.pdf) before running the Tuner Tool.
  2. Start the tool by entering ospltun on the command line.
caution

The URI required to connect is set in the OSPL_URI environment variable (the default URI is: file://$OSPL_HOME/etc/config/ospl.xml).

The Vortex OpenSplice system can now be monitored.

Step 3

Experiment with the Vortex OpenSplice tools and applications

Use the Vortex OpenSplice Tuner to monitor all DDS entities and their (dynamic) relationships.

Step 4

Manually stop the Vortex OpenSplice infrastructure

  1. Choose File > Disconnect from the Vortex OpenSplice Tuner menu.
  2. Enter ospl stop on the command line; this stops all Vortex OpenSplice services.

Footnotes

[1]ospl is the command executable for Vortex OpenSplice.