RTC Component¶

As already explained in the design document, RTC Components are software applications that adhere to specific communication, computation and composition principles defined in the RTC Tk Component Model.

The RTC Tk component infrastructure provides libraries that support the simple creation of such RTC Components.

Supported Functionality¶

Currently the following functionality is supported for RTC Components:

Functionality	Description
Component Identity	Component instance name and component version
Customisation Mechanism	Mechanism to create and select custom component life-cycles
Basic Life-Cycle	RtcComponent with interface towards business logic
Life-Cycle Extensions	Runnable, Measurable, Optimisable, Loopaware and Suspendable
Command Reception	CII MAL command interfaces STDIF, UCIF, FCIF, OCIF, MCIF, LCIF, LSIF
State Publication	State updates are automatically published to OLDB and CII MAL
Logging	Logging is initialised, configured and a default logger is created
Runtime Configuration Repository	Service Adapter to access the Runtime Configuration Repository
Online Database	Service Adapter to access the Online Database
Service Discovery	Service Adapter to access the Service Registry
Component Metrics	Service allowing components to add runtime metrics for monitoring
Alert Service	Facility that provides important event observability via alerts.

Each RTC component provides a standardised command interface, state machine model, as well as default extension points for activites and guards where users can add their own, custom behaviour.

Launching¶

The command line of each RTC Component application is the same:

$ rtctkRtcSupervisor -h
Options:
  -h [ --help ]         print help messages
  -i [ --cid ] arg      component identity
  -s [ --sde ] arg      service discovery endpoint (URI): use
                        file:/<path>/service_disc.yaml to select local file or
                        consul://127.0.0.1:8500 to select consul as backend
  -l [ --lpf ] arg      log4cplus properties file (URI)
  -d [ --debug ]        start in more verbose mode (with log-level DEBUG)
  -e [ --emf ] arg      export state machine model to file (URI)

To start an RTC Component process, the name of the component instance must be provided, as is shown in the following example command:

$ rtctkMyComponent my_component_1

An optional service discovery endpoint (-s or --sde) can be provided if a non-default Service Registry shall be used, e.g. --sde=file:///INTROOT/run/exampleTelRepub/service_disc.yaml.

Each component can be stopped either by sending an Exit command or by pressing Ctrl-C.

Baisc Component Life-cycle¶

Interface	Commands	States	Activities	Guards
STDIF	Init	Off	Starting
	Enable	Starting	Initialising
	Disable	NotReady	Enabling
	Reset	Initialising	Disabling
	Exit	Ready
	GetState	Enabling
	GetVersion	Disabling
	SetLogLevel	Operational
UCIF	Update	Update:Idle	Updating	UpdatingAllowed
UCIF		Update:Busy

Instropection Commands¶

These are part of the standard set of commands any ELT application must implement. In the case of the RTCTK these commands are included in the standard RTC Component implementation. There is no option to change its implementation.

Interface	Commands	States
INSTROSPECTIONIF	GetInterfaces	Any

The GetServices command allows client to get the list of services offered by a MAL server, and their XML definition. It is used to dynamically introspect commands offered by MAL servers and the creation of UIs, be them CLI or GUI.

Update Command with Custom Payload¶

The Update command was introduced to be able to perform dynamic configuration parameter updates while a component is in state On::NotOperational::Ready or higher.

To provide sufficient flexibility for user extension, the command takes a string argument in JSON format. Due to the nature of the RTC Toolkit, only a partial payload schema can be defined.

Partial Payload Schema of the Update command:

{
    "data_points" : ["<parameter_name>"],
    "apply_at_sample_id" : "<sample_id>",
    "apply_at_timestamp" : "<timestamp>"
}

Attribute data_points:

attribute is optional.
if the attribute is present, the component will update the specified list of dynamic parameters.
if the attribute is not present, the component will update all its dynamic parameters.
string field <parameter_name> is the last part of the data point path after component_id/dynamic/.

Attributes apply_at_sample_id and apply_at_timestamp:

these attributes are mainly foreseen to be used with HRTC Supervisor components.
both attributes are optional but mutally exclusive, they shall not be present at the same time!
if apply_at_sample_id is present, the component shall schedule an update for the given sample id.
if apply_at_timestamp is present, the component shall schedule an update for the given time.
if neither attribute is present, the component shall schedule an immediate update.
integer field <sample_id> shall be a 32 bit unsigned integer number.
string field <timestamp> shall have format: YYYY-MM-DDThh:mm:ss.sss (timezone consistent with what is set on the RTC cluster)

Examples for Update commands:

Update all dynamic parameters now: Update {}
Update control matrix now: Update {"data_points" : ["control_matrix"]"}
Update background and flat-field at sample id: Update {"data_points" : ["wfs/background", "wfs/flat_field"], "apply_at_sample_id" : 424242}
Update background at timestamp: Update {"data_points" : ["wfs/background"], "apply_at_timestamp" : "2024-01-01T09:42:30.987"}

Error Handling:

Instrument RTC developers are responsible to validate JSON input data in their custom components, the goal is to throw exceptions if invalid input data is detected. Invalid JSON input data shall never lead to an inconsistent system state where only part of an Update was applied.

Custom payload attributes:

In case the pre-defined attributes are not sufficient, instrument RTC developers may add their own custom payload attributes to their components. Do not hesitate to contact the RTC Tk team to discuss whether certain attributes are common enough to be added to the toolkit.

Custom Component Life-cycles¶

The RTC Tk provides a composition-based mechanism for component life-cycle customisation. Application developers select the desired component life-cycle by providing an expression that defines the abilities to be added to the basic RTC Component functionality. Depending on the selected life-cycle expression new functionality is added that supports new commands, changes the state machine, or adds new virtual methods to the business logic interface.

The life-cycle expression for a RTC component that uses the runnable state machine is Runnable<RtcComponent>.

The RTC Tk provides built-in life-cycle extensions that can be used on demand. Currently the following extensions are supported:

Runnable - For components that have the notion of Idle and Running.
Optimisable - Adds command Optimise.
Measurable - Adds command Measure.
Loopaware - For components that are aware of control loops.
Suspendable - For loopaware components that are also suspendable.

The various commands, states, activities and guards that are introduced by each extension is indicated in the following table:

Extension	Commands	States	Activities	Guards
Runnable	Run	Idle	GoingRunning
	Idle	Running	GoingIdle
	Recover	GoingRunning	Running
		GoingIdle	Recovering
		Error
		Recovering
Optimisable	Optimise	Optimise:Idle	Optimising	OptimisingAllowed
Optimisable		Optimise:Busy
Measurable	Measure	Measure:Idle	Measuring	MeasuringAllowed
Measurable		Measure:Busy
Loopaware	Run	Idle	GoingRunning
	Idle	GoingRunning	GoingIdle
	Recover	GoingIdle	Recovering
	Open	Error	Opening
	Close	Recovering	Closing
		Opened	Opened
		Closed	Closed
		Opening
		Closing
Suspendable	Suspend	Suspended	Suspended
	Resume	Suspending	Suspending
		Resuming	Resuming

The extensions can be used by including the specific header file and by adding the extension to the life-cycle expression. E.g. expression Optimisable<Runnable<RtcComponent>> adds optimise functionality to a component that is using the runnable state machine.

The component life-cycle can be customised in an open and stepwise manner by specifying a life-cycle expression that chains together as many life-cycle extensions as needed. In addition, application developers can also write their own life-cycle extensions.

API Usage¶

Tutorial Creating a Simple RTC Component explains how to make use of the provided libraries in order to create a simple RTC Component application that runs a user-provided business logic.

Tutorial Creating a Custom RTC Component explains how to combine both framework provided and instrument specific life-cycle extensions to create custom RTC Component applications.

Limitations and Known Issues¶

Event interfaces with subscription functionality are not supported yet, this feature will be added in a subsequent release.

Other functionality such as the support of user-defined command line arguments was omitted on purpose to discourage its use for now. This will be revisited later when the CII Config Service is available and some experience is gained regarding how it can be best integrated.