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 ZPB subscription.

Even though the client application does not qualify as an RTC Component it heavily depends on the infrastructure and principles provided by the RTC Tk 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 -s file:/path/to/service/registry.yaml my_component Init

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

$ rtctkClient -s file:/path/to/service/registry.yaml my_component Listen

To terminate the listener simply use Ctrl-c.

Note

Note that arguments component name, command name and command argument are strings. The service discovery endpoint is a string in URI format currently pointing to the fake service registry yaml file.

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 to exit.
GetState: Query component for current state.
GetStatus: Query component for current status.
GetVersion: Sends the GetVersion command.

Function Control Interface fcif¶

Provides 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 Control Interface lsif¶

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

Suspend: Request to suspend loop.
Resume: Request to resume a suspended loop.

Update Command Interface ucif¶

Request dynamic configuration updates.

Update: This is equivalent to Update <arg> with empty argument.
Update <arg>: Sends the Update command with the provided argument.

Warning

Current version of RTCTK provided components do not make use the provided argument, instead they always update all their dynamic parameters. This may change in future versions.

Measure Command Interface mcif

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¶

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.

Customisation¶

Framework users can create a custom client lib that also 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 application only covers a basic set of command interfaces.

In subsequent releases the following functionality will be added:

Support for structured command payloads (i.e. JSON)

In the long term the tool may even be replaced by a generic commanding and messaging tool on the ELT level.