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.
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 |
RTCBuilder is designed for OpenRTM-aist. It may not work with other RTC platforms.
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.
The first time Eclipse is started, a Welcome page similar to that shown below will be displayed.
Click the cross in the upper left of this page to close it.
Click the Open Perspective button in the top right and select Other...
Select RTC Builder and it will start.
Before generating a new RT Component, an Eclipse project for the component should be created. From the File menu, select New->Project.
In the displayed dialog, choose Other and then RTC Builder and click Next.
Enter a project name and click Finish.
A project with the chosen name will be created and added to the package explorer.
A default RTC profile XML file (RTC.xml) is automatically added to the new project.
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.
Open New RtcBuilder Editor button in the toolbar | Open New Builder Editor option in the File menu |
The RTC Builder screen is laid out as below.
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. |
The Build View displays the component being designed in a graphical viewer.
The Build View displays the component's name, data ports, service ports and service interfaces.
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.
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.
From the Window menu, select Views, then Other.
By selecting Repository View, the Repository View will be started and displayed.
Locally-stored RT Component specifications are loaded and displayed in a tree view.
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.
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.
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.
Right-click on a component in the Repository View and select Delete from the context menu. Paths, categories and components can be deleted.
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.
The RTC Profile Editor is made up of several 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. |
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. |
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. | - |
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.
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. |
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.
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. |
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. |
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.
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. |
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.
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.
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.
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.
General documentation about the RT Component can be entered in this tab.
The information entered in this tab is included in the generated code as doxygen comments.
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. |
The Build View displays the component being designed in a graphical viewer.
The Build View displays the component's name, data ports, service ports and service interfaces.
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.
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.
From the Window menu, select Views, then Other.
By selecting Repository View, the Repository View will be started and displayed.
Locally-stored RT Component specifications are loaded and displayed in a tree view.
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.
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.
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.
Right-click on a component in the Repository View and select Delete from the context menu. Paths, categories and components can be deleted.
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.
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.
The generated template files are as follows, dependent on the language selected:
Filename | Explanation |
README_<RTC name> | README file. Contains the information entered before generation. |
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. |
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*. |
Filename | Explanation |
<RTC name>.py | RT component implementation. |
<Service type name>_idl.py | |
<Service type name>_idl_example.py | Service provider implementation class*. |
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.
~* 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.
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.
~* When the correct development plugins are installed, and a new project is generated, the correct properties will be set for the language in use.
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).
Use one of the following methods to save the editor contents to an RTC Profile XML file.
~* Save As... allows the profile to be saved to any project.
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.
#BR
* The format to export in is determined by the file type option in the file selector dialog.
The RTC Builder settings screen can be accessed from the Window menu's Settings... option. Select RTC Builder from the displayed settings dialog.
These settings allow the default values in the Basic Profile tab and the Configuration Parameters tab to be set.
Clicking the Reset to Default button will set these to the following values.
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 |
These settings allow the default values in the Data Port tab and the Service Port tab to be set.
Clicking the Reset to Default button will set these to the following values.
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 |
These settings allow what information is displayed in the configuration profile and the system profile to be configured.
Clicking the Reset to Default button will set these to the following values.
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 |
These settings allow what is included in the different archive types to be set.
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.
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.
* 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. |
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.
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 |
These settings allow the colours of different icons displayed in the Build View to be congfigured.
Clicking the various colour buttons allows the colors of the Component, DataInPort, DataOutPort, ServicePort and ServiceInterface to be changed.
A. This error is displayed when the destination to save to is incorrect. Select a directory within the project.