RTCBuilder-1.0.0_en

RTC Builder is a template generator tool for RT Components. It generates custom templates based on user-configured parameters. RTC Builder operates on top of Eclipse and interacts seamlessly and intuitively with other Eclipse plugins. Although RTC Builder can be used even if RT System Editor is not installed, if it is, RTC Builder's menus will be integrated with those of RT System Editor. This document is written assuming RT System Editor is installed.

Introduction

Requirements

The following software is required to use RT-Component Builder (RTCBuilder).

Java Development Kit 6 Note: Java 1.5 (5.0) is not suitable.
Eclipse 3.2. or higher
http://www.eclipse.org/downloads/index.php
http://archive.eclipse.org/eclipse/downloads/index.php
Eclipse IDE
Eclipse EMF 2.2 or higher (including SDO and XSD) Eclipse plugin required by RTC Builder
Note: be sure to use versions that match your Eclipse version.
Eclipse GEF 3.2 or higher(including Draw2D) Eclipse plugin required by RTC Builder
Note: be sure to use versions that match your Eclipse version.

If you will be generating components for C++ or Python, you will need the following as well:

Software Remarks
Eclipse CDT C++ development environment
Pydev for Eclipse Python development environment

Limitations

RTCBuilder is designed for OpenRTM-aist. It may not work with other RTC platforms.

Installing and Starting RTCBuilder

Installing and Starting RTC Builder

Installing RTC Builder

RTC Builder is an Eclipse plugin. As such, it requires that Eclipse and supporting Eclipse plugins are installed first. See the Requirements section for download links. The Eclipse install is simply extracting the archive. Plugins should be copied into the plugins directory in the Eclipse directory. To install RTC Builder, copy its jar file (jp.go.aist.rtm.rtcbuilder_X.X.X.jar) into the eclipse/plugins directory in the directory you extracted the Eclipse archive to.

Starting RTC Builder

The first time Eclipse is started, a Welcome page similar to that shown below will be displayed.

fig2InitialOfEclipseStart_1_en.png
Eclipse first start screen

Click the cross in the upper left of this page to close it.

fig3PerspectiveSwitch_en.png
Change perspective

Click the Open Perspective button in the top right and select Other...

fig2-3PerspectiveSelection_en.png
Select Perspective

Select RTC Builder and it will start.

fig2-4RTCBuilderInit_en.png
RTC Builder start screen

Creating a project for RTC Builder

Before generating a new RT Component, an Eclipse project for the component should be created. From the File menu, select New->Project.

fig2-5CreateProject_en.png
Creating a project for RTC Builder 1

In the displayed dialog, choose Other and then RTC Builder and click Next.

fig2-6CreateProject2_en.png
Creating a project for RTC Builder 2

Enter a project name and click Finish.

fig2-7CreateProject3_en.PNG
Creating a project for RTC Builder 3

A project with the chosen name will be created and added to the package explorer.

fig2-8CreateProject4_en.png
Creating a project for RTC Builder 4

A default RTC profile XML file (RTC.xml) is automatically added to the new project.

Starting the RTC Profile Editor

Click the Open New RtcBuilder Editor button in the toolbar or select Open New Builder Editor from the File menu to start the RTC Profile Editor.

fig2-9ToolsBarOpenNewRtcBuilder_en.png
fig2-10FileMenuOpenNewBuilder_en.png
Open New RtcBuilder Editor button in the toolbar Open New Builder Editor option in the File menu

Screen layout

RTC Builder screen layout

Outline

The RTC Builder screen is laid out as below.

fig3-1RTCBuilder_en.png
RTC Builder screenshot

RTC Builder components

Component Explanation
RTC Profile Editor Edit the RTC specification based profile, data port definitions, service port definitions, configuration parameter definitions, and other profile extensions.
Build view Graphically display the RT Component being edited, including its data ports, service ports, service interfaces.
Repository View Display information on a selected RT Repository.

Build View

The Build View displays the component being designed in a graphical viewer.

fig3-13BuildView_en.png
Build View


The Build View displays the component's name, data ports, service ports and service interfaces.

Displaying the Build View

If the Build View is not displayed when changing to the RTC Builder perspective, it can be enabled through the Window menu. Select Views, then Other. In the displayed dialog, select Other, then Build View.


fig3-14DispBuildView_en.png
fig3-14DispBuildView2_en.png
Displaying the Build View

Repository View

The Repository View can load and read files describing RT Components and display them in a repository. As well as displaying locally-stored files, it can also connect to remote repositories and display the information from them in a tree.

Displaying the Repository View

From the Window menu, select Views, then Other.


fig1-3SelectRepositoryView_en.png
Selecting the Repository View


By selecting Repository View, the Repository View will be started and displayed.

fig1-4RepositoryViewInit_en.png
Repository View start screen


Local operation

Locally-stored RT Component specifications are loaded and displayed in a tree view.

fig2-1RepositoryViewLocal_en.png
Repository View (local operation)


Loading files

Right-click within the Repository View area and select Load File from the context menu. Use the displayed file selector dialog to select an RT Component specification to load. The file selector dialog will only display XML files.

fig2-1LoadFile_en.png
Loading a file


When loading a locally-stored specification file, the absolute path will be displayed at the top level of the tree hierarchy. The second level will display the category specified by the component in the file. The third level will display the name of the component contained in the file.

Loading directories

All components in a directory can be loaded in a single action. Right-click in the Repository View and select Load Dir from the context menu. A directory selector dialog will be displayed. Select a directory to load. All components in that directory will be loaded into the Repository View and displayed as with loading individual files.

fig2-5LoadDir_en.png
After loading a directory


Deleting

Right-click on a component in the Repository View and select Delete from the context menu. Paths, categories and components can be deleted.

fig2-6Delete_en.png
Deletion


When deleting a top-level path, all categories and components below that path are deleted at the same time. If a component is deleted, and there are no more components in the same category, that category will be deleted. If there are no other categories, the top-level directory will also be deleted.

RT Profile Editor

fig3-2RTProfileEditor_en.png
RTC Profile Editor


The RTC Profile Editor is made up of several tabs.

RTC Profile Editor tabs

Tab Explanation
Basic profile Enter the RT Component's profile information, such as name and author.
Data ports Configure the data ports provided by the component.
Service ports Configure the service ports provided and interfaces used by the component.
Configuration parameters Configure the user-settable parameters of the component and configuration sets.
Language and environment Choose the programming language and operating systems that the component will be generated for.
RTC Profile XML editor View and edit the XML that is created based on the information entered in the other tabs.
Document settings Enter any extra documentation and information that should be included with the generated component.

Basic profile tab


fig3-3InputBaseProfile_en.png
Basic profile tab

Basic profile items

Item Default value Explanation
RT-Component Basic Profile
Module name ModuleName A name to differentiate this component. Required. This name will be used in source code.
Module description ModuleDescription Brief description of the component.
Module version 1.0.0 Version of the component. Ideally, an x.y.z format should be used.
Module vender VenderName Name of the component vendor.
Module category Category Category of the component. Required.
Component type DataFlowComponent Type of the component. Choose from DataFlowComponent, STATIC, UNIQUE or COMMUTATIVE.
Component’s activity type PERIODIC Choose from PERIODIC, SPORADIC or EVENT_DRIVEN.
Number of maximum instance 1 Number of simultaneous instances this component can have.
Execution type PeriodicExecutionContext Type of execution context this component will use. Choose from PeriodicExecutionContext or ExtTrigExecutionContext.
Execution Rate 1.0 The ExecutionContext's rate in Hertz. Entered as a floating-point number.
Output Project
None Project name for the generated code. If the project does not exist, it will be created. Required.

Activity profile tab

fig3-4ActivityProfile_en.png
Activity profile tab


Activity profile tab items

Item Explanation fundamental
Activity Profile
onInitialize Initialization processing. Only once called at the time of the start of a component life cycle. -
onFinalize End processing. Only once called at the time of the end of a component life cycle. -
onStartup When ExecutionContext starts execution, it is called only once. -
onShutdown When ExecutionContext stops execution, it is called only once. -
onActivated When becoming active from an inactive state, it is called only once. -
onDeactivated When becoming inactive from an active state, it is called only once. -
onAborting Before going into an ERROR state, it is called only once. -
onError It continues being called during ERROR state. -
onReset When it is reset from an ERROR state and shifts to an inactive state, it is called only once. -
onExecute It is periodically called in an active state. -
onStateUpdate It is called after on_execute each time. -
onRateChanged It is called when rate of ExecutionContext is changed. -
onAction It is called in order to perform operation according to the state of corresponding. -
onModeChanged It is called when the mode is changed. -

Data ports tab


fig3-4InputDataPort_en.png
Data ports tab


To add a port of the desired type (Inport/Output), click the Add button beside that type. The Delete button can be used to remove the selected port. The Documentation section allows you to enter documentation for the selected port.

Data port items

Item Default value Explanation
RT-Component Data InPort Profile
Port name dp_name Data InPort name. Required. Cannot conflict with any OutPort names.
Data Type dp_type Data InPort data type. Timed[ Short / Long / UShort / ULong / Float / Double / Char / Boolean / Octet / String ], as well as their Seq variants, are available. Required.
Var Name dp_vname Variable name for interaction with the port.
Disp. Position left Where this port will be displayed in the Build View.
RT-Component Data OutPort Profile
Port name dp_name Data OutPort name. Required. Cannot conflict with any InPort names.
Data Type dp_type Data OutPort data type. Timed[ Short / Long / UShort / ULong / Float / Double / Char / Boolean / Octet / String ], as well as their Seq variants, are available. Required.
Var Name dp_vname Variable name for interaction with the port.
Disp. Position right Where this port will be displayed in the Build View.
Documentation
Outline None Brief description of the port.
Data type None Description of the data type used.
Data count None For sequence types, the expected number of items.
Meaning None Meaning of the data.
Units None Any units used by the data.
Frequency None Frequency at which data will be produced.
Processing speed None Processing speed/period for the data.

Service ports tab


fig3-5InputServicePort_en.png
Service ports tab (service port entry)



fig3-6InputServicePort2_en.png
Service ports tab (service interface entry)


New service ports can be added by clicking the Add Port button in the left half of the screen. Select a port under RT-Component Service Ports and click Add Interface to add a new interface to that port. The Delete buuton can be used to remove selected interfaces and ports.

Service port items (service port)

Item Default value Explanation
RT-Component Service Port Profile
Name sv_name Service port name. Required. Must be unique.
Position left Position to display this port in the Build View.
Documentation
Outline None Brief description of the service port.
I/F Outline None Brief description of the interfaces attached to the service port.

Service port items (service interface)

Item Default value Explanation
RT-Component Service Port Interface Profile
Interface Name if_name Interface name. Required. Must be unique.
Direction Provided Type of service interface.
・Provided:Offered interface (Service Provider)
・Required:Used interface (Service Consumer)
Instance Name if_instance Instance name used by the service interface. Required.
Var Name if_varname Variable to use for the interface. If ommitted, the instance name will be used.
IDL file None File name of the IDL file that defines the interface. Use the Browse button to find it if necessary.
Interface Type None Type of interface used by the service interface. Required.
IDL Path None IDL search path. Use the Browse button to search for and select directories.
Documentation
Outline None Brief description of the service interface.
Arguments None Description of the interface arguments.
Return value None Description of the interface's return value.
Exceptions None Description of any exceptions used by the interface.
Preconditions None Preconditions that should be satisfied before using the interface.
Postconditions None Postconditions that should be satisfied after using the interface.

Configuration parameters tab


fig3-7InputConfigProfile_en.png
Configuration parameters tab


User-settable configuration parameters and other system configuration parameters can be added and removed using this tab. The documentation section allows documentation for the selected setting to be provided.

Configuration parameter items

Item Default value Explanation
RT-Component Configuration Parameter Definitions
Name conf_name Configuration parameter name. Required. Must be unique.
Type conf_type Data type of the parameter.
Var Name conf_vname Variable used to store the parameter's value.
Default Value conf_default Default value of the parameter.
RT-Component Configuration Parameter
Configuration manager.name Name of the configuration.
Default Value None Default value of the settings for this configuration. For settings with defaults already defined, the default will be set when the name is selected.
Documentation
Data name None Description of the data name.
Default value None Description of the default value.
Outline None Description of the parameter.
Units None Units used.
Data range None Range of allowable values.
Constraints None Description of constraints on the parameter.

Language and environment tab


fig3-8InputLangEnv_en.png
Language and environment tab


The available languages that templates can be generated for are displayed, and one should be selected. The details for the selected language will be opened.

Language and environment items

Item Default value Explanation
C++
OS None Select the OS this component will be generated for.
Dependency None Enter any extra libraries this component will depend on.
Python
--- --- ---
Java
Jar File None Enter any extra jar files this component will depend on.

In the Java section, jar files can be added and removed using the Add and Delete buttons.

Ruby and C# are not currently supported.

RTC Profile XML Editor tab

The XML file (RTC.xml) based on the entered component information can be viewed and edited in this tab. Information that can't be entered using one of the other tabs can be directly entered here.

fig3-9InputLangEnv2_en.png
RTC Profile XML Editor tab


Anything entered in this tab will be saved only if the component is saved while this tab is visible. If, after editing the XML in this tab, another tab is opened and the component is saved, the values from that tab will take precedence. All changes made to the XML in this tab must follow the RTC.xml scheema. The contents will be validated when saved. If validation follows, an error similar to that shown below will appear. Fix the error and try saving again.

fig3-10ErrorXML_en.png
XML validation error dialog


Documentation settings tab

General documentation about the RT Component can be entered in this tab.

fig3-8Documentinfo_en.png
Document settings tab


The information entered in this tab is included in the generated code as doxygen comments.

Document settings items

Item Default value Explanation
Component outline
Outline None Description of the component.
Inputs and outputs None Description of the component's inputs and outputs.
Algorithms, etc None Description of algorithms used, etc.
Activity (on_initialize,on_finalize,on_startup,on_shutdown,on_activated,on_deactivated,on_execute,on_aborting,on_error,on_reset,on_state_update,on_rate_changed)
Execution outline None Description of the behaviour of each activity state.
Preconditions None Pre-conditions for each activity state.
Postconditions None Post-conditions for each activity state.
Other
Author/Contact address None Name of the component author and a contact address.
License None License for the component and usage conditions.
References None Cited works.

Build View

The Build View displays the component being designed in a graphical viewer.

fig3-13BuildView_en.png
Build View


The Build View displays the component's name, data ports, service ports and service interfaces.

Displaying the Build View

If the Build View is not displayed when changing to the RTC Builder perspective, it can be enabled through the Window menu. Select Views, then Other. In the displayed dialog, select Other, then Build View.


fig3-14DispBuildView_en.png
fig3-14DispBuildView2_en.png
Displaying the Build View

Repository View

The Repository View can load and read files describing RT Components and display them in a repository. As well as displaying locally-stored files, it can also connect to remote repositories and display the information from them in a tree.

Displaying the Repository View

From the Window menu, select Views, then Other.


fig1-3SelectRepositoryView_en.png
Selecting the Repository View


By selecting Repository View, the Repository View will be started and displayed.

fig1-4RepositoryViewInit_en.png
Repository View start screen


Local operation

Locally-stored RT Component specifications are loaded and displayed in a tree view.

fig2-1RepositoryViewLocal_en.png
Repository View (local operation)


Loading files

Right-click within the Repository View area and select Load File from the context menu. Use the displayed file selector dialog to select an RT Component specification to load. The file selector dialog will only display XML files.

fig2-1LoadFile_en.png
Loading a file


When loading a locally-stored specification file, the absolute path will be displayed at the top level of the tree hierarchy. The second level will display the category specified by the component in the file. The third level will display the name of the component contained in the file.

Loading directories

All components in a directory can be loaded in a single action. Right-click in the Repository View and select Load Dir from the context menu. A directory selector dialog will be displayed. Select a directory to load. All components in that directory will be loaded into the Repository View and displayed as with loading individual files.

fig2-5LoadDir_en.png
After loading a directory


Deleting

Right-click on a component in the Repository View and select Delete from the context menu. Paths, categories and components can be deleted.

fig2-6Delete_en.png
Deletion


When deleting a top-level path, all categories and components below that path are deleted at the same time. If a component is deleted, and there are no more components in the same category, that category will be deleted. If there are no other categories, the top-level directory will also be deleted.

Generating code, Saving and Loading

Generating code

Generating code

Once all the necessary information for the new RT Component has been specified, the template code can be generated. On the Basic Profile tab, click the Generate button to generate the template code.

fig4-1GenerateTemplate_en.png
Generating template code


The generated template files are as follows, dependent on the language selected:

Generated files

  • All
Filename Explanation
README_<RTC name> README file. Contains the information entered before generation.
  • C++
Filename Explanation
<RTC name> Comp.cpp RT Component launch code.
<RTC name>.h RT Component main header.
<RTC name>.cpp RT Component main code.
<Service type name>SVC_impl.h Service provider header*.
Only the specified ServiceProvider Type will be output.
<Service type name>SVC_impl. cpp Service provider implementation*.
Only the specified ServiceProvider Type will be output.
Makefile.<RTC name> Makefile for compiling the component.
<RTC name>.vcproj Project file for Visual Studio.
Only generated when the supported OS is set to Windows.
OpenRTM-aist.vsprops Visual Studio property file for OpenRTM-aist.
  • Java
Filename Explanation
<RTC name>Comp.java RT Component launch class.
<RTC name>.java RT Component's Component Profile. Class specified during initialisation.
<RTC name>Impl.java RT Component implementation.
build_<RTC name>.xml Build file for the RT Component.
<Service type name> SVC_impl.java Service provider implementation class*.
  • Python
Filename Explanation
<RTC name>.py RT component implementation.
<Service type name>_idl.py
<Service type name>_idl_example.py Service provider implementation class*.
~* RTC Builder will parse the IDL file(s) when generating the template code in order to generate the operation templates for the service providers. However, the following limitations apply to this:
  • Only #include can be used by the preprocessor. #ifdef, etc. are ignored.
  • The generated operations are only those directly specified by the interface. Inherited operations are not generated.

Output selection

If an output file of the code to be generated already exists, and there are differences between the existing file and the generated file, it will request confirmation of how to merge the two files.

fig4-2SelectOutPut_en.png
Output selection screen


In this screen there are three options to select from.
  • Original: Use the existing file.
  • Merge: Merge using a merge block*.
  • Generate: Overwrite using the generated code.

~* When merging, only blocks of code surrounged by <rtc-template block="block"> tags will be overwritten by newly generated code. Unchanged code in a generated file will already be surrouned by these tags. The contents of these tags will be replaced when merging, so take care not to change code within these tagged blocks.

Changing perspective

If the correct development environment plugins are installed for the language the template was generated in, after generation is complete the perspective will ask to change to the correct perspective for that language.

fig4-3MessagePerspectiveSwitch_en.png
Change perspective confirmation dialog


The necessary development plugins are:
  • Java: JDT (Java Development Tools) - already included in Eclipse
  • C++: CDT (C/C++ Development Tooling)
  • Pytho: PyDev

~* When the correct development plugins are installed, and a new project is generated, the correct properties will be set for the language in use.

Loading and Saving Settings

RTC Builder can save and load the contents of the RTC Profile Editor entered by the user to and from an RTC Profile XML file (RTC.xml).

Saving

Use one of the following methods to save the editor contents to an RTC Profile XML file.

  • Press Ctrl-S
  • Right-click in the editor and select Save or Save As... from the context menu
  • Select Save or Save As... from the File menu.

~* Save As... allows the profile to be saved to any project.

fig5-1Save_en.png
Saving


Loading

Use one of the following methods to load an RTC Profile into the editor from an RTC Profile XML file.
  • Right-click on the editor and select Open from the context menu.
  • Select Open File... from the File menu.
    fig5-2Load_en.png
    Loading

Export and Import of Profile

The contents of the RTC Profile Editor can be exported to an external file in XML format and YAML format, and later imported again. Click the Profile Export or Profile Import buttons on the Basic Profile tab to display a file selector dialog.

fig8-1FunctionExportImport_en.png
Profile Export/Import function


#BR

fig8-2DialogProfileExport_en.png
Destination file selection


* The format to export in is determined by the file type option in the file selector dialog.

Settings

The RTC Builder settings screen can be accessed from the Window menu's Settings... option. Select RTC Builder from the displayed settings dialog.

fig7-1SettingRTCBuilder_en.png
The RTC Builder settings


Code Generation

These settings allow the default values in the Basic Profile tab and the Configuration Parameters tab to be set.

fig7-2SettingGenerateCode_en.png
Code Generation settings


Clicking the Reset to Default button will set these to the following values.

Code Generation settings defaults

Item Default value
Basic
Component name ModuleName
Description ModuleDescription
Version 1.0.0
Vendor VendorName
Category Category
Component Type DataFlowComponent
Component’s activity type PERIODIC
Max. Instances 1
Execution type PeriodicExecutionContext
Execution rate 1.0
Configuration
Name conf_name
Type conf_type
Variable Name conf_varname
Default Value conf_default

Port

These settings allow the default values in the Data Port tab and the Service Port tab to be set.

fig7-3SettingPort_en.png
Port settings


Clicking the Reset to Default button will set these to the following values.

Port settings defaults

Item Default value
Data Port
DataPort Name dp_name
DataPort Type dp_type
DataPort Variable Name dp_vname
Service Port
ServicePort Name sv_name
Service Interface
Interface Name if_name
Instance Name if_instance
Variable Name if_varname

Configuration

These settings allow what information is displayed in the configuration profile and the system profile to be configured.

fig7-4SettingConfig_en.png
Configuration settings


Clicking the Reset to Default button will set these to the following values.

Configuration Setting Window Default value

Item Default value Item Default value
manager .name Manager naming.enable YES
os.name None naming.type corba
os.release None naming.format %h.host/%n.rtc
os.version None naming.update.enable YES
os.arch None naming.update.interval 10.0
os.hostname None timer.enable YES
logger.enable YES timer.tick 0.1
logger.file_name ./rtc%p.log corba.args None
logger.data_format %b %d %H:%M:%S corba.endpoint None
logger.log_level NORMAL corba.name_servers None
logger.stream_lock NO exec_cxt.periodic.type PeriodicExecutionContext
logger.master_logger None exec_cxt.periodic.rate 1000
module.conf_path None exec_cxt.evdriven.type EventDrivenExecutionContext
module.load_path None

Export

These settings allow what is included in the different archive types to be set.

fig7-4SettingExport_en.png
Export settings


The settings are divided by archive type (Source export, Binary export and Source plus binary export). Each section is divided in file extension and file name sections.

fig7-5SettingExport_en.png
Export settings (sections)


The file extension section allows file types to be included in the archive to be specified by extension. Click the Select type button to display the file type selection dialog. Select which file types to include in the archive using this dialog.

fig7-6Select_en.png
* The list only displays registered file types. To enter types not in the list, enter them in the text field at the bottom of the dialog. Separate multiple entries with a comma.


File type selection dialog


The file name section allows files to be included in the archive to be specified by file name. Click the Add button to add a new name to the list. Use the Delete button to remove names from the list. In the above Export settings (sections) figure, the "Source plus binary" archive type will include all files with the extensions .cpp and .h, as well as any files named "Makefile" and "README." Clicking the Reset to Default button will set these to the following values.

Export settings defaults

Item Default value
Source Export
Extension conf,cpp,h,vcproj,java,xml,py
Name Makefile,README
Binary Export
Extension conf,exe,class,py
Name README
Source+Binary Export
Extension conf,cpp,h,vcproj,java,xml,py,exe,class
Name Makefile,README

Build View

These settings allow the colours of different icons displayed in the Build View to be congfigured.

fig7-7SettingBuildView_en.png
Build View settings


Clicking the various colour buttons allows the colors of the Component, DataInPort, DataOutPort, ServicePort and ServiceInterface to be changed.

FAQ and Acknowledgements

FAQ

When saving the contents of the RTC Profile Editor to an RTC Profile, an "Error writing file." error appears.

A. This error is displayed when the destination to save to is incorrect. Select a directory within the project.

Acknowledgements

RTC Builder is developed using the following libraries and products. We thank these projects.
  • Apache Velocity 1.5 ~Copyright (C) 2000-2007 The Apache Software Foundation This product includes software developed by The Apache Software Foundation ( http://www.apache.org/ ).
  • Apache Jakarta Commons CLI 1.1 ~Copyright 2001-2007 The Apache Software Foundation This product includes software developed by The Apache Software Foundation ( http://www.apache.org/ ).
  • JYaml 1.3 ~Copyright (c) 2005, Yu Cheung Ho All rights reserved.
  • Java CC (Uses generated source code) https://javacc.dev.java.net/