Programming RT-Component.

Development Procedure of an RT-Component

OpenRTM-aist provides a framework that enables users (the component developers) to easily adapt existing software or develop new one that complies with the RT-Component specifications. The general development procedure of an RT-Component is described in figure below.


ComponentDevelFlow.png
RT-Component development procedure


The component developer can create new components by integrating existing software assets into the component framework. Therefore, the functionalities offered by legacy software will be modularized as RT-Components and will become reusable through different ranges of applications. The newly so developed RT-Component can then be deployed on any appropriate network node but will become, by supporting the distributed object technology, usable from any location on the network.

As described on that figure, there are basically two forms of executable binary files among RT-Components developed in conformance with the RT-Component framework. A standalone RT-Component is a binary file that can be directly executed as is. Loadable Module RT-Component is a binary file that can be dynamically loaded into an application. An RT-Component can support both these two patterns of development, distribution and execution.

Basis of RT-Component Programming

There are some huge differences between the ordinal programming and RT-Component programming.

Program without main function

RT-Component program differs from ordinal program, since it doesn't contain a main function. Instead, one RT-Component is implemented as a class which is inherited from a special base class.

The processing which we want to make the component is described in member functions (methods) which override those of its base class. For example, a processing like initialization is written in onInitialize function, and the processing which you want to perform when finalizing is written in onFinalize function.

 ReturnCode_t MyComponent::onInitialize()
 {
   // Initialization etc
 }
 ReturnCode_t MyComponent::onFinalize()
 {
   // Finalization etc
 }

When are those operations invoked respectively? To answer this question, you need to know the RT-Component lifecycle.

Component Lifecycle

The sequence of states from creation to destruction of an RT-Component is called the component's lifecycle.

A component generally has three states:

  • Created State(Created)
  • Alive State(Alive)
  • Final State

(The Alive state itself has multiple states inside, which is explained below.)

As described above, the component is one class. Therefore, the component creation is almost same as the object (the instance) one. Usually, RT-Component is created by Manager (RTC Manager) and the Manager manages the lifecycle of RT-Component.

Concretely, the manager calls onInitialize function shown above after creating an instance of RT-Component. It also calls onFinalize function when RT-Component finalizes. In this way, RT-Component is programmed by describing necessary details in each processing allocated in specific timing of the RT-Component in the life cycle (this is called Action).

Execution Contexts

A thread is usually attached when a program starts up, and executes processing described as a program. The program to control a robot, has loops, such as the control loop and the processing loop, which the thread executes, processes sensor data and keeps controlling its actuator. Such main processing to process and control something is called Core logic in RT-Component.

Once RT-Component is created and transits Alive state, one thread is attached and executes main processing (Core logic) of the component. This thread is called Execution Context (ExecutionContext) in RT-Component. Actually, execution context is not a thread itself but what expresses a thread abstractly, and has execution cycles and states.

In other words, when RT-Component is created, execution context is attached to RT-Component, and RT-Component executes any processing by driven Core Logic (for example, it controls a robot etc).

State transitions of RT-Component

As described above, RT-Component has states and you describe its processing as actions allocated in the states and the transitions. The state transitions of an RT-Component (State Machine Diagram in UML 2.0) are shown in the following figure.


RTCStateMachine040.png
State transitions of an RT-Component


Created and Alive are two RT-Component's states. Alive state itself has a few states.

Stopped and Running state of Thread

First, let's take a look at the Alive state's two states - Stopped and Running - which are shown in the uppermost area of the figure below.


RTCStateMachineStartStop.png
Stopped and Running State of a thread


When we consider the execution context as a thread, this represents that the thread is in the Stopped state or the Running state.

When the execution context in the Stopped state receives a start event, it executes onStartup of RT-Component and then transits to the Running state. Conversely, by a stop event, the execution context executes onShutdown of RT-Component and transits to the Stopped state.

The actions of the core logic are executed only in the Running state, and no actions are executed in the Stopped state at all.

Active and Inactive States

The lower area in the Alive state section shows the state transitions including Active, Inactive and Error of the core logic.

Immediately after RT-Component was created, it will be in the Inactive state. Once RT-Component is activated, onActivate action of RT-Component will be invoked, and RT-Component will transits to the Active state. While in the Active state, usually onExecute of RT-Component action is executed periodically. The main RT-Component's processing is usually executed within onExecute. For example, basic periodic processings of the robot, such as reading the data from a sensor and sending to other components, or controlling a motor based on the received data from other components, are written in onExecute.

The RT-Component stays in the active state until it is inactivated or an error occurs. Once the RT-Component is inactivated, onDeactivate is invoked, and the RT-Component will be inactivated. When any error occurs in the processing of the active state, onAborting is invoked, and the RT-Component will transit to the Error state.

When in the error state, until reset externally, the RT-Component stays in the error state and keeps invoking onError. onReset is invoked to reset. If onReset is successful, the RT-Component goes back to the inactive state and can be activated again, but if it fails, the component stays in the error state.


RTCStateMachineActiveInactive.png
Inactive, Active and Error State


Summary of Actions

The main job of RT-Component developers is to consider what processing should have been done in each RT-Component's state and to implement functions corresponding to those actions. In other words, they only have to override functions needed to create the components, and implement the contents of the function.

The functions of the component's action and roles are listed below.

onInitialize Initialization. It is invoked only once when the component starts its lifecycle.
onActivated It is invoked only once when the component in the Inactive state is activated.
onExecute It is invoked periodically while the component is in the Active state.
onDeactivated It is invoked only once when the component in the Active state is inactivated.
onAborting It is invoked only once before the component transits to the ERROR state.
onReset It is invoked when the component recovers from the Error state to the Inactive state by reset.
onError It is invoked periodically while the component is in the Error state.
onFinalize It is invoked only once when the component finalizes its lifecycle.
onStateUpdate It is invoked every time after onExecute.
onRateChanged It is invoked when a rate of ExecutionContext is updated
onStartup It is invoked only once when ExecutionContext starts
onShutdown It is invoked only once when ExecutionContext stops

Download

latest Releases : 2.0.0-RELESE

2.0.0-RELESE Download page

Number of Projects

Choreonoid

Motion editor/Dynamics simulator

OpenHRP3

Dynamics simulator

OpenRTP

Integrated Development Platform

AIST RTC collection

RT-Components collection by AIST

TORK

Tokyo Opensource Robotics Association

DAQ-Middleware

Middleware for DAQ (Data Aquisition) by KEK