Client Application¶

The client application (supClient) is a simple utility allowing to send commands to the System Supervisor from the command line. In this context we use the words commands and events as synonyms. The supClient uses two interface module (stdif and supif) to compose the payload of the messages. For simplicity purposes, the associated interface for each command is hidden to the user. The supClient sends the messages using CII MAL request/reply.

Note

This client uses the synchronous version of the stdif and supif interfaces.

$ supClient <serviceURI> <command> ["<parameters>"]

Where
      <serviceURI> destination of the command (e.g. zpb.rr://127.0.0.1:12081)
      <command>    command to be sent to the server (e.g. Init)
      <parameters> optional parameters of the command.

Warning

The URI shall not contain the ‘/’ at the end otherwise the client will hang trying to connect to a non existing server.

List of Commands¶

The commands (events) currently supported by the supClient utility are:

Client commands¶
Command	Parameters	Description
Init	“”	Moves the server from NotReady to Ready state.
Enable	“”	Moves the server from Ready to Operational state.
Disable	“”	Moves the server from Operational to Ready state.
Reset	“”	Moves the server to NotReady state.
GetState	“”	Get the state of the server.
GetStatus	“”	Get the status of the server.
Exit	“”	Stop the server.
SetLogLevel	“<ERROR\|INFO\|DEBUG\|TRACE>”	Change the logging level of the server.
Recover	“”	Recover the server in case it entered in error state.
GetConfig	“”	Get the actual configuration of the server.
SubsysNames	“”	Get the list of subsystems coordinated by the Supervisor.
SubsysStatus	“[<subsystem id>]”	Get the status of a subsystem.
SubsysInit	“<subsystem id>”	Move a given subsystem to Ready state.
SubsysEnable	“<subsystem id>”	Move a given subsystem to Operational state.
SubsysDisable	“<subsystem id>”	Move a given subsystem from Operational back to Ready state.
SubsysReset	“<subsystem id>”	Move a given subsystem to NotReady state.

Note

The subsystem commands like SubsysInit or SubsysEnable control the individual state of a subsystem.

Examples¶

Note

The following examples assume the server is listening for incoming events under the URI zpb.rr://127.0.0.1:12081 in the local host.

Initialising the server¶

$ supClient zpb.rr://127.0.0.1:12081  Init ""

Moving the server to Operational state¶

$ supClient zpb.rr://127.0.0.1:12081  Enable ""

Python Client Library¶

It is possible to communicate with the System Supervisor through clients developed in Python. The SysSup provides a library that simplifies the interaction with the System Supervisor (clib).

Users might want to interact directly with Supervisor ICD binding methods. This is, of course possible, but it is outside the scope of this library.

Note

The Supervisor python library provides both versions of the MAL communication: synchronous and asynchronous.

Error Handling¶

The clib reports as a RuntimeError exceptions that may be delivered by the System Supervisor.

Classes¶

The clib library provides two classes that encapsulates the interface with the Supervisor. The class SysSupCommands (synchronous) and the class SysSupAsyncCommands (asynchronous). Both classes provide the same functionality.

SysSupCommands¶

The constructor of the SysSupCommands class support two parameters: uri and timeout. The timeout is optional and has a default of one minute, expressed in milliseconds.

The class handles two MAL client interfaces to deal with standard commands and Supervisor specific commands. The correct interface will be selected according to the method used so this is hidden to the user.

Methods for Command Interface¶

Method	parameters	interface
setup	<setup buffer>	supif
get_config		supif
set_config		supif
subsystem_status		supif
subsystem_init	<subsystem name>	supif
subsystem_enable	<subsystem name>	supif
subsystem_disable	<subsystem name>	supif
subsystem_reset	<subsystem name>	supif
subsystem_names	None	supif
state	None	stdif
status		stdif
init	None	stdif
enable	None	stdif
disable	None	stdif
reset	None	stdif
stop	None	stdif

Examples¶

Retrieving the Status¶

import ifw.sup.syssup.clib.syssup_commands as sup

uri = "zpb.rr://134.171.3.48:30269"
supif = sup.SysSupCommands(uri)
print(supif.status())
NotOperational;Ready

Supervisor CLI¶

The SysSup python library provides already an easy way to interact with the Supervisor. However it might not be the best choice when more interactivity is needed. The SysSup CLI provides a experimental command shell with simple commands aiming to simplify the interaction with the Supervisor. The SysSup shell can be invoked issuing the command supcli.

Command Line Parameters¶

The supcli offers some few command line parameters. If no parameters are specified, the supcli will use the default name service and use nomad/consul to obtain the correct IP and port numbers of the Supervisor. The syssup shell commands are not necessary using the same names as the MAL interfaces with the purpose to shorten the commands names. Commands that could take long time, are executed in a dedicated thread to allow the shell to continue being responsive while waiting for the answer from the previous command. Asynchronous CII cannot be used here because unlike in C++, it is not yet available in python (see ECII-365).

Parameter	Description
–uri	if the URI is specified, the supcli will use it to connect to the server
–name	When using nomad, one could specify the name of the service instead of the URI
–module	Custom interface library
–class_name	Custom command class name
–timeout	Timeout for CII MAL requests in ms
–log_level	log level (ERROR, INFO, DEBUG)
–help	Show the usage message

Warning

The supcli shell assumes NOMAD/CONSUL services are up and running. If this is not the case then only –uri parameter can be used.

Note

The supcli shell was created for the Supervisor but since it uses the standard interface, it can be used for any server implementing this interface, although only for the standard events like init, enable, disable, etc.

supcli --uri zpb.rr://134.171.3.48:30269
supSh>?
Available command list:
-  disable
-  enable
-  get_config
-  help
-  init
-  is_operational
-  reset
-  set_config
-  set_obmode
-  setaccess
-  setloglevel
-  state
-  status
-  stop
-  subsystem_disable
-  subsystem_enable
-  subsystem_init
-  subsystem_names
-  subsystem_reset
-  subsystem_status

Command	Parameters	Description
disable		sends the disable (stdif) event to the connected server.
enable		sends the enable (stdif) event to the connected server.
help		print the list of supported commands
init		sends the init (stdif) event to the connected server.
reset		sends the reset (stdif) event to the connected server.
state		sends the GetState (stdif) event to the connected server
status		sends the GetStatus (stdif) event to the connected server
set_obmode	<mode>	Set observation mode.
setaccess	<subsystem>, <access level>	Set the access level for a particular subsystem. existing configuration. Example: setaccess fcs1,true
get_config		Get the actual configuration used by the server
set_config	<yaml string>	Update the actual configuration. The parameter shall be a valid yaml string. The configuration will be merged to the existing configuration. Example: set_config {server: {req_timeout: 15000}}
setloglevel	<level>,<logger>	Update logging level of the server.
subsystem_disable	<subsystem>	Forwarded the disable command to the subsystem.
subsystem_enable	<subsystem>	Forwarded the enable command to the subsystem.
subsystem_init	<subsystem>	Forwarded the init command to the subsystem.
subsystem_names		Get the list of the subsystems managed by the server.
subsystem_reset	<subsystem>	Forwarded the reset command to the subsystem.
subsystem_status	[<subsystem>]	Get the detailed status of the subsystems managed by the server
ctrl-d		Stop the shell

JSON Schema¶

The schema used by the supervisor to validate the syntax of the setup buffer is described below.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "title": "Supervisor schema",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {
                "type": "string",
                "description": "Subsystem identifier."
            },
        "param": {
            "$ref": "#/definitions/param"
            }
        }
    },
    "definitions": {
        "param": {
            "type": "object",
            "properties": {
                "subsystem": {
                    "$ref": "#/definitions/subsystem"
                    }
                },
            "required": [
                "subsystem"
                ]
        },
        "subsystem": {
            "type": "object",
                "properties": {
                    "access": {
                        "type": "boolean",
                        "description": "Subsystem access flag."
                    }
                },
                "required": [
                    "access"
                ]
            }
        }
}