RTI Recorder GettingStarted...1-1 1. Welcome Chapter 1 Welcome to RTI Recorder RTI® Recorder is an RTI Data Distribution Service application that records both RTI Data Distribution

RTI Recorder

for RTI Data Distribution Service

Getting Started Guide

Version 1.5

© 2007-2010 Real-Time Innovations, Inc.All rights reserved.

Printed in U.S.A. First printing.June 2010.

TrademarksReal-Time Innovations and RTI are registered trademarks of Real-Time Innovations, Inc.All other trademarks used in this document are the property of their respective owners.

Copy and Use RestrictionsNo part of this publication may be reproduced, stored in a retrieval system, or transmitted in anyform (including electronic, mechanical, photocopy, and facsimile) without the prior writtenpermission of Real-Time Innovations, Inc. The software described in this document is furnishedunder and subject to the RTI software license agreement. The software may be used or copied onlyunder the terms of the license agreement.

Third-Party Copyright NoticesPortions of this product include software derived from Fnmatch, (c) 1989, 1993, 1994 The Regentsof the University of California. All rights reserved. The Regents and contributors provide thissoftware "as is" without warranty.

Technical Support Real-Time Innovations, Inc.385 Moffett Park DriveSunnyvale, CA 94089Phone: (408) 990-7444Email: [email protected]: http://www.rti.com/support

http://www.rti.com/support

Contents

1 Welcome to RTI Recorder

2 Installation

2.1 Downloading RTI Recorder..........................................................................................2-12.2 Installing RTI Recorder .................................................................................................2-22.3 Installing the License File .............................................................................................2-2

3 RTI Recorder Tutorial

3.1 Setting Up RTI Shapes Demo.......................................................................................3-23.2 Configuring RTI Recorder ............................................................................................3-43.3 Running RTI Recorder...................................................................................................3-63.4 Viewing the Recorded Data..........................................................................................3-73.5 Managing RTI Recorder Remotely ..............................................................................3-8

3.5.1 Connecting to RTI Recorder Using Shared Memory ..................................3-93.5.2 Connecting to RTI Recorder Using UDPv4................................................3-103.5.3 Connecting to RTI Recorder Using UDPv4 with a Partition Set.............3-113.5.4 Modifying RTI Recorder While it is Running............................................3-11

iii

iv

1. We

lco

me

Chapter 1 Welcome to RTI Recorder

RTI® Recorder is an RTI Data Distribution Service application that records both RTI DataDistribution Service discovery and topic data.

The recorded data is stored in one or more files that can be viewed later. One way toview the data is with the provided SQL command-line tool, sqlite3.

Features

❏ Records data from applications in multiple domains.

❏ Records entire Topics, or specific Topic fields, based on POSIX file-name match-ing expressions.

❏ Records all data types except bit-fields.

❏ Records to multiple files with configurable file-size limits. Optionally overwritesthe oldest file when the maximum number of files has been reached.

❏ Records the DDS SampleInfo structure and a timestamp for both discovery dataand user data.

❏ Records using either Best Effort or Reliable communications.

❏ Optionally records data from only specified partitions.

❏ Supports remote operation.

1-1

Chapter 1

1-2

2. Installa

tion

Chapter 2 Installation

This chapter describes how to download and install RTI Recorder:

❏ Downloading RTI Recorder (Section 2.1)❏ Installing RTI Recorder (Section 2.2)❏ Installing the License File (Section 2.3)

2.1 Downloading RTI RecorderBefore you can install RTI Recorder, you must download the distribution file from theRTI Customer Portal, accessible from http://www.rti.com/support. You will need yourusername and password to log in; these are included in the letter confirming your pur-chase or evaluation copy. If you do not have this letter, please contact [email protected].

Once you have logged into the portal, select the Downloads link, then select the distri-bution that matches the architecture on which you will be running RTI Recorder and theversion of your RTI Data Distribution Service application.

Distribution files follow the naming convention, RTI_Recorder-<RTI Recorder version>Setup<architecture>.exe. For example,RTI_Recorder-1.5.xSetupWin32.exe.

Save the file to a temporary directory on your computer, such as /tmp on UNIX-basedsystems or “My Documents” on Windows systems. If you need help with the downloadprocess, contact [email protected].

RTI Shapes Demo: If you want to work through the tutorial presented in Chapter 3,you will also need RTI Shapes Demo. This is available from RTI’s Downloads page(http://www.rti.com/downloads) in the section titled Interactive DDS Demonstration.

2-1

http://www.rti.com/downloads

http://www.rti.com/support

Chapter 2

RTI Shapes Demo runs on Windows and Linux systems. Follow the installation instruc-tions that accompany the distribution file.

2.2 Installing RTI RecorderYou do not need administrator privileges to install RTI Recorder, but you do need writepermission to the installation directory (non-administrator users do not have write per-mission to “Program Files” on Windows Vista/7 systems).

To install RTI Recorder, simply run the installation file that you downloaded and followthe on-screen instructions.

You will end up with the following directory structure under your chosen installationlocation:

❏ docs/ Documentation

❏ examples/ Example configuration files

❏ host/bin/<architecture>/ Executables to run on the host <architecture>;includes rtirecconv, rtirecsh, sqlite3

❏ target/bin/<architecture>/ Executables to run on the target <architecture>;includes rtirecorder

❏ resource/schema The RTI Recorder XSD and DTD for XMLvalidation and configuration help.

❏ resource/xml Folder for XML files, including the default RTIRecorder configuration. Please put your RTIRecorder XML files here.

2.3 Installing the License FileIf your RTI Recorder distribution requires a license file, you will receive one via emailafter you download the software.

Save the license file in any location of your choice. When RTI Recorder starts, it will lookin these locations until it finds a valid license:

1. The file specified with the -licenseFile option when you start RTI Recorder fromthe command-line.

2-2

2.3 Installing the License File2. Insta

llatio

n

2. The file specified in the environment variable RTI_LICENSE_FILE, which youmay set to point to the full path of the license file, including the filename (forexample, C:\RTI\my_rti_license.dat).

3. The file rti_license.dat in the current working directory.

4. The file rti_license.dat in the directory specified by the environment variableNDDSHOME.

If you have any questions about license installation, please contact [email protected].

2-3

Chapter 2

2-4

3. Tutoria

l

Chapter 3 RTI Recorder Tutorial

The best way to learn about RTI Recorder is to start using it. We will generate recordabledata via RTI Shapes Demo, an RTI Data Distribution Service application. We will use RTIRecorder to record data sent between two RTI Shapes Demo sessions, then view the data-base tables with the provided SQL tool, sqlite3.

Important:

❏ To understand the contents of each database record, you will need to consult theRTI Data Distribution Service C API Reference Manual.

❏ To use sqlite3 to view the recorded data, you will need a basic understanding ofSQL commands; for information, please visit www.sqlite.org.

The tutorial assumes you have the following software installed:

❏ RTI Recorder 1.5

❏ RTI Shapes Demo 2.0

The tutorial walks you through the following exercises:

❏ Setting Up RTI Shapes Demo (Section 3.1)

❏ Configuring RTI Recorder (Section 3.2)

❏ Running RTI Recorder (Section 3.3)

❏ Viewing the Recorded Data (Section 3.4)

❏ Managing RTI Recorder Remotely (Section 3.5)

3-1

http://www.sqlite.org

Chapter 3

3.1 Setting Up RTI Shapes DemoWe’ll use RTI Shapes Demo to publish and subscribe to Topics which will appear in theapplication window as colored moving shapes. Each shape is a Topic; the topic’s dataincludes the shape’s color and x, y coordinates.

Note: RTI Shapes Demo uses domain ID 0 by default. If you want to use a differentdomain ID, start RTI Shapes Demo with the -domainId <#> option (for example, to usedomain ID 5, enter: rtishapesdemo -domainId 5).

To Begin the Tutorial:

1. Start two copies of RTI Shapes Demo.

On Windows Vista systems: From the Start menu, select: All Programs, RTI, RTI Shapes Demo <version>, RTI Shapes Demo.

On other Windows systems: From the Start menu, select: Programs, RTI, RTI Shapes Demo <version>, RTI Shapes Demo.

On UNIX-based systems: Run RTI Shapes Demo from a command shell:

Depending on your secu-rity settings, you may seea Windows SecurityAlert dialog—simplyclick Unblock.

> <install directory>/rti/shapesdemo/rtishapesdemo

3-2

3.1 Setting Up RTI Shapes Demo3. Tuto

rial

The figure to the right showsthe demo program’s mainwindow. Start two of these.We’ll refer to the first Demowindow as the PublisherDemo and the second as theSubscriber Demo.

2. In the Publisher Demo, cre-ate 2 squares and a circle—allwith default QoS settings:

a. Under Publishers, selectSquare.

b. In the Create New Pub-lisher dialog, select REDand click OK. (We’ll usethe defaults for the othersettings).

You should see a redsquare moving in thedisplay area.

c. Use the same process to create a green square and a yellow circle.

You’ve just created 3 Writers (2 Squares, 1 Circle).

3. In the Subscriber Demo, subscribe to squares and circles:

a. Under Subscribers, select Square and click OK. (Leave the default settings.)

You’ve just created a single Reader that will receive data for all squares (allcolors).

b. Use the same process to create a Reader for circles.

3-3

Chapter 3

Your two RTI Shapes Demo windows should look like this:

By default, Subscribers show the most recent 6 samples—this is why you seeextra shapes behind the leading one. The most recent shape has a thick col-ored border. Older (historical) samples have a thinner border of the samecolor. Published shapes have a thin black border.

c. You may minimize these two windows.

3.2 Configuring RTI RecorderWhen starting RTI Recorder, you may specify a configuration file. The configuration fileis used to set properties that control what to record, how to record, and where to savethe recorded data.

The <install-dir>/examples directory contains these example files:

❏ simple_config.xml

❏ advanced_config.xml

❏ remote_shell.xml

Publisher Subscriber

3-4

3.2 Configuring RTI Recorder3. Tuto

rial

Let’s start learning about RTI Recorder with the simple configuration.

1. Copy simple_config.xml to a new filename, such as mysimple_config.xml.

2. Move the new file to your <install-dir>/target/bin/<architecture> directory, soit is in the same place as the rtirecorder executable.

3. If your computer has an active network interface and you are using the defaultdomain ID (0) for RTI Shapes Demo: proceed to Running RTI Recorder (Section3.3)—you can use the copied configuration file as is.

Otherwise, open mysimple_config.xml with an editor of your choice, make thefollowing changes, then save and close the file:

a. If you changed the domain ID used by RTI Shapes Demo, change the<domain_id> line to use the same value. For example, if you set the domainID to 3 in RTI Shapes Demo, then change it here too:

Change the bold faced line to use the same domain ID as RTI Shapes Demo

<domain name="domain0"> <domain_id> 3 </domain_id>

<deserialize_mode>RTIDDS_DESERIALIZEMODE_ALWAYS </deserialize_mode> </domain>

b. If your computer does not have an active network interface, use the followinglines in the domain properties section.

<domain name="domain0"> <participant_qos>

Turn off multicast—>

<discovery><multicast_receive_addresses/>

</discovery>Only use shared memory—>

<transport_builtin><mask>TRANSPORTBUILTIN_SHMEM </mask>

</transport_builtin></participant_qos>

</domain>

3-5

Chapter 3

3.3 Running RTI Recorder

1. On Linux systems: Open a command prompt, change to the <install-dir>/target/bin/<architec-ture> directory and start RTI Recorder with your new configuration file (fromSection 3.2) as the only argument. For example:

> rtirecorder -cfgFile mysimple_config.xml -cfgName example

On Windows systems: Navigate to the Start Menu, All Programs, RTI, RTI Recorder 1.5.x, RTIRecorder. At the command prompt, enter the following command:

> rtirecorder.exe -cfgFile mysimple_config.xml -cfgName example

On Windows systems, when running the evaluation version of RTI Recorder:If you are not logged in as Administrator, the license manager will display anerror message: “Error in saving configuration settings: You are not a licenseadministrator.” This message is benign and RTI Recorder should run normally.

On Windows systems, depending on your security settings, you may see a Win-dows Security Alert dialog—if so, simply click Unblock.

2. Wait about one minute, to give RTI Recorder time to record data from RTI ShapesDemo.

3. Stop RTI Recorder by pressing Control-C. Leave the command prompt windowopen—you will use it in the next steps in Section 3.4.

3-6

3.4 Viewing the Recorded Data3. Tuto

rial

3.4 Viewing the Recorded Data

1. After running and stopping RTI Recorder as described above, you can list thecontents of the directory. You will see that RTI Recorder created a file calledsimple_config.dat_0_0 in the current directory. (As you will learn from theUser’s Manual, the first 0 is a fileset number, the second 0 is a segment number.)

2. From the same command prompt used to run RTI Recorder, open the databasefile with <install-dir>/host/bin/<architecture>/sqlite3 to view the recordeddata. For example, assuming your command prompt is in <install-dir>/target/bin/<architecture> (where rtirecorder.exe and the data files are), enter:

> ..\..\..\host\bin\i86Win32VS2005\sqlite3 simple_config.dat_0_0

To use sqlite3, you will need some basic knowledge of SQL commands—forinformation, please visit www.sqlite.org.

3. Start by displaying a list of the tables in the database:

sqlite> .tables

RTI Recorder creates these tables for discovery data:

• DCPSPublication (data type DDS_PublicationBuiltinTopicData)

• DCPSSubscription (data type DDS_SubscriptionBuiltinTopicData)

• DCPSParticipant (data type DDS_ParticipantBuiltinTopicData)

These tables store the recorded topic data:• Circle$RecordAll$domain0

• Square$RecordAll$domain0

Topic table names follow this format: TopicName$RecordGroupName$Domain-Name. A “RecordGroup” is a way to specify what topics to record from whatdomains. This concept is explained in the RTI Recorder User’s Manual. In thisexample, the RecordGroup is called RecordAll.

RTI Recorder also creates two tables for internal use, RTILog and RTIVersion. 4. SQLite provides a number of builtin commands. Start with .help:

sqlite> .help

5. It is useful to turn column headings on:

sqlite> .headers on

3-7

http://www.sqlite.org

Chapter 3

6. Query the tables using standard SQL syntax. (Note that using “limit x” syntax atthe end of each select statement will limit the number of records displayed.Without a limit, you will likely see too many records scrolling off your display.)Here are some examples:

To list 3 records of data on Topic Circle:

sqlite> select * from Circle$RecordAll$domain0 limit 3;

To get the largest x-coordinate value for a Circle:

sqlite> select max(x) from Circle$RecordAll$domain0;

To get 10 samples from the table, in descending order by the column named“___timestamp” (note the 3 underscores):

sqlite> select * from Circle$RecordAll$domain0 order by ___timestamp desc limit 10;

To find the number of samples recorded:

sqlite> select count(*) from Circle$RecordAll$domain0;

To find all x values greater than 100:

sqlite> select x from Circle$RecordAll$domain0 where x > 100;

To find all x, y values, where x is greater than y:

sqlite> select x,y from Circle$RecordAll$domain0 where x > y;

Try other SQL commands to explore the recorded data.

When you are ready to exit sqlite3, enter:

sqlite> .exit

3.5 Managing RTI Recorder RemotelyRTI Recorder can be managed remotely using one of two ways:

❏ RTI Recorder Shell

❏ Another RTI Data Distribution Service application using special message types

See Chapter 7 in the RTI Recorder User's Manual for details.

This section contains examples of how to use the RTI Recorder Shell commands:

❏ Connecting to RTI Recorder Using Shared Memory (Section 3.5.1)

❏ Connecting to RTI Recorder Using UDPv4 (Section 3.5.2)

3-8

3.5 Managing RTI Recorder Remotely3. Tuto

rial

❏ Connecting to RTI Recorder Using UDPv4 with a Partition Set (Section 3.5.3)

❏ Modifying RTI Recorder While it is Running (Section 3.5.4)

The configuration files used in the examples are in the <RTI Recorder install directory>/examples directory.

Note: If you are using different Domain IDs for running RTI Recorder, you must edit theconfiguration files to use your Domain IDs. By default, the example configuration filesuse Domain IDs 0 and 1.

3.5.1 Connecting to RTI Recorder Using Shared Memory

1. Copy <installation directory>/examples/advanced_config.xml to <installation directory>/target/bin/<architecture>/advanced_config.xml.

2. Change to this directory:<installation directory>/target/bin/<architecture>.

3. Start RTI Recorder as follows:

./rtirecorder -cfgFile advanced_config.xml -cfgName remote_example

4. In another shell, change to this directory:<installation directory>/host/bin/<architecture>.

5. In the shell from step 4, start RTI Recorder Shell:

./rtirecsh -domainId 0 -shmem -noUdpv4

6. Enter the info command (in the shell that is running rtirecsh) to see which RTIRecorder session it is connected to.

7. Enter the status command to check the status of RTI Recorder. Note that State isRECORDING.

8. Enter the stop command to tell RTI Recorder to stop recording.

9. Enter the status command. The State value should be STOPPED, indicating thatrecording has been stopped.

10. Enter the start command again. The State value should now be RECORDINGagain. You may have to wait for a few seconds to get the status information.

11. Reconfigure RTI Recorder with a file that is local to RTI Recorder:

configure advanced_example -remotefile ../../../examples/advanced_config.xml

3-9

Chapter 3

12. Wait a few seconds and enter status in the shell. RTI Recorder should now beconfigured based on advanced_config.xml.

13. Reconfigure RTI Recorder with a file that is local to RTI Recorder Shell:

configure advanced_example -localfile ../../../examples/advanced_config.xml


15. Enter the stop command to stop recording.

16. Enter the shutdown command to shut down RTI Recorder.

17. Enter the exit command to exit the shell.

3.5.2 Connecting to RTI Recorder Using UDPv4


./rtirecorder -cfgFile advanced_config.xml -cfgName remote_example

2. On the different machine, start RTI Recorder Shell:

./rtirecsh -domain 0 -multicast

3. Enter the info command in the shell to see which RTI Recorder session it is con-nected to.

4. Enter the status command to check the status of RTI Recorder. Note that State isRECORDING.

5. Enter the stop command to tell RTI Recorder to stop recording.

6. Enter the status command. The State value should be STOPPED, indicating thatrecording has been stopped.

7. Enter the start command again. The State value should now be RECORDINGagain. You may have to wait for a few seconds to get the status information.

8. Reconfigure RTI Recorder using a file local to RTI Recorder as follows:

configure advanced_example -remotefile ../../../examples/advanced_config.xml


3-10


rial

10. Reconfigure RTI Recorder using a file local to RTI Recorder Shell as follows:

configure advanced_example -localfile ../../../examples/advanced_config.xml





3.5.3 Connecting to RTI Recorder Using UDPv4 with a Partition Set


./rtirecorder -cfgFile advanced_config.xml -cfgName advanced_example

2. On the different machine, start RTI Recorder Shell:

./rtirecsh -domainId 0 -multicast -partition Recorder

3. Enter the status command to check that the shell is connected to RTI Recorder.




3.5.4 Modifying RTI Recorder While it is Running

1. Copy <installation directory>/examples/remote_shell.xml to <installation directory>/target/bin/<architecture>/remote_shell.xml.

2. Start RTI Recorder with the configuration file, remote_shell.xml, in the examplesdirectory.

./rtirecorder -cfgFile remote_shell.xml -cfgName remote_shell

3. Start RTI Shapes Demo and create publishers for a Square, Circle and Triangle.

4. Start the remote shell.

./rtirecsh -domain 1

5. In the shell, enter:

model

3-11

Chapter 3

You will see the following results:

Current Recorder Model:=======================<recorder>

<model name="configuration"><domain name="domain0" state="RUNNING">

<domain_id>0</domain_id></domain><domain name="domain1" state="RUNNING">

<domain_id>1</domain_id></domain><topic_group name="Square" state="RUNNING" ref_count="1">

<topics><topic_expr>Square</topic_expr><exemption></exemption>

</topics><field_expr>*</field_expr>

</topic_group><topic_group name="Triangle" state="RUNNING" ref_count="1">

</topics><topic_expr>Triangle</topic_expr><exemption></exemption>


</topic_group><record_group name="SquareTriangle" state="RUNNING" ref_count="1">

<domain_ref><element>domain0</element>

</domain_ref><topic_ref>

<element>Square</element><element>Triangle</element>

</topic_ref></record_group>

</model></recorder>

6. In the shell, enter the following command (all on one line):

add <recorder><topic_group name="Circle"><topics><topic_expr>Circle</topic_expr></topics><field_expr>*</field_expr></topic_group></recorder>

The new model:

<recorder><model name="configuration">

3-12


rial

<domain name="domain0" state="RUNNING"><domain_id>0</domain_id>

</domain><domain name="domain1" state="RUNNING">

<domain_id>1</domain_id></domain><topic_group name="Circle" state="RUNNING" ref_count="0"> <topics>

<topic_expr>Circle</topic_expr><exemption></exemption>


</topic_group><topic_group name="Square" state="RUNNING" ref_count="1">

<topics> <topic_expr>Square</topic_expr>

<exemption></exemption></topics><field_expr>*</field_expr>


<topics><topic_expr>Triangle</topic_expr><exemption></exemption>


</topic_group><record_group name="SquareTriangle" state="RUNNING" ref_count="1">




</topic_ref></record_group>

</model></recorder>

Notice that the topic group we just added has a ref_count of 0. This means norecord groups are referencing it at the moment. Now let's fix that.

7. In the shell, enter the following command (all on one line):

add <recorder><record_group name="Circle"><domain_ref> <element>domain0</element></domain_ref><topic_ref> <element>Circle</element></topic_ref></record_group></recorder>

3-13

Chapter 3

New model:

<recorder><model name="configuration">

<domain name="domain0" state="RUNNING"><domain_id>0</domain_id>

</domain><domain name="domain1" state="RUNNING">

<domain_id>1</domain_id></domain><topic_group name="Circle" state="RUNNING" ref_count="1">

<topics> <topic_expr>Circle</topic_expr>


</topic_group><topic_group name="Square" state="RUNNING" ref_count="1">

<topics> <topic_expr>Square</topic_expr><exemption></exemption>



<topics> <topic_expr>Triangle</topic_expr>


</topic_group><record_group name="Circle" state="RUNNING" ref_count="1">



<element>Circle</element></topic_ref>

</record_group><record_group name="SquareTriangle" state="RUNNING"

ref_count="1"><domain_ref>

<element>domain0</element></domain_ref><topic_ref>


</topic_ref>

3-14


rial

</record_group></model>

</recorder>

Now we're recording the topic "Circle". You can open the database to verifythis.

8. Stop recording some topics. Enter the following command in the shell:

pause <recorder><record_group name="SquareTriangle"/></recorder>

Notice that the model now includes:

<record_group name="SquareTriangle" state="IDLE" ref_count="1">

The topics Square and Triangle are no longer recorded. By substituting "resume"for "pause" in the command above you can resume recording these topics.

3-15

Chapter 3

3-16