Client Application

Overview

The rtctkClient application is used to send commands to RTC components using the CII MAL ZPB middleware. The client can also listen to state change events via CII MAL subscription.

Even though the client application does not qualify as an RTC Component, it heavily depends on the infrastructure and principles provided by the RTCTK Component Framework.

The list of supported commands are enumerated below in section Commands.

Configuration

The client application uses the service discovery mechanism to retrieve MAL endpoints of the targeted RTC Components from the central service registry, therefore the service discovery endpoint must be provided as an additional command argument.

Note

In the provided examples, the rtctkClient application is usually indirectly called from the respective shell script. This was done to save users from always having to provide the long service discovery endpoint information.

Usage

Synopsis:

rtctkClient [options] <component id> <command> [<command-arg>]

To send commands to RTC Components, invoke the rtctkClient application like this:

$ rtctkClient my_component Init

To listen to state-change events, use this command:

$ rtctkClient my_component Listen

To terminate the listener, simply use Ctrl-c.

Note

Note that the arguments component name, command name and command argument are strings. The service discovery endpoint is an optional string in URI format pointing to the service registry; when using Consul the argument is not necessary.

Commands

The following lists the standard commands (<command> in the synopsis) supported by rtctkClient grouped by command interface.

Synopsis:

rtctkClient [options] <component id> <command> [<command-arg>]

Special Commands

Special commands unrelated to a MAL command interface are documented here.

Listen

Subscribes to component state-change events. Stop with a keyboard interrupt Ctrl-c.

Standard Interface stdif

Provides standard component life-cycle control and query capabilities. A more detailed description of the standard interface can be found here.

Init

Request to bring component to state Initialising and load static and dynamic configuration parameters.

Stop

Request to stop the ongoing initialisation and transition to NotOperational:NotReady.

Enable

Request to bring component to state Operational:Ready from NotOperational:Idle.

Disable

Request to bring component to state NotOperational:Ready from Operational:Idle.

Reset

Sends the Reset command, which brings component back to initial state in NotOperational.

Exit

Request component application to terminate.

GetState

Query component for current state.

GetStatus

Query component for current status.

GetVersion

Query component software version.

SetLogLevel

Sets the log level of the component’s main logger.

Update Command Interface ucif

Request dynamic configuration updates.

Update {}

Sends the Update command with an empty JSON argument.

Update {"data_points" : ["control_matrix"]}

Sends the Update command with the provided JSON argument (see RTC Component).

Warning

At the current version, many RTCTK-provided components do not make use of the provided argument; instead, they always update all their dynamic parameters. This will change in future versions.

Function Control Interface fcif

For runnable and loop-aware components, these commands provide state control for transitioning between the Operational states Running and Idle, as well as error recovery.

Run

Request to bring component to state Running.

Idle

Request to bring component to state Idle.

Recover

Request to recover from asynchronous error when in state Error.

Loop Control Interface lcif

For loop-aware components, the commands provide state control to open/close.

Open

Request loop to open.

Close

Request loop to close.

Loop Suspension Interface lsif

For loop-aware and suspendable components, the commands provide state control to suspend/resume loops.

Suspend

Request to suspend loop.

Resume

Request to resume a suspended loop.

Measure Command Interface mcif

For measurable components, the command can be used to trigger a measurement cycle.

Measure <arg>

Sends the Measure command with the provided argument in serialized JSON form.

Note

The schema for the JSON argument is component specific. Please refer to the details of the component being commanded.

Optimise Command Interface ocif

For optimisable components, the command can be used to trigger an optimisation cycle.

Optimise <arg>

Sends the Optimise command with the provided argument in serialized JSON form.

Note

The schema for the JSON argument is component specific. Please refer to the details of the component being commanded.

Set Modes Interface smif

For the RTC Supervisor, these commands can be used to set and query modes.

GetAvailableModes

Query available modes.

GetActiveModes

Query active modes.

SetModes

Apply specified modes.

DeferredModes

Set modes to be applied during next initialisation.

GetDeferredModes

Query deferred modes.

Writeback Interface wbif

For the RTC Supervisor, this command can be used to trigger a configuration writeback.

WriteBack

Write back selected parameters.

Customisation

Framework users can create a custom client lib that also supports user-specific command interfaces. Customisation is done by extending the toolkit provided CommandRequestor class and then registering it as a template parameter to the toolkit-provided client runner function.

A concrete example how to create a custom client application can be found in the advanced tutorial Creating a Custom RTC Component.

Limitations and Known Issues

Currently, the tool only covers a limited set of command interfaces.

In the long term, the tool will be integrated into the Control and Monitoring Tool.