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
Init	“”
Enable	“”
Disable	“”
Reset	“”
GetState	“”
GetStatus	“”
Exit	“”
SetLog	“<ERROR\|INFO\|DEBUG\|TRACE>”
Setup	“”
Recover	“”
GetConfig	“”
SubsysNames	“”
SubsysStatus	“”
SubsysInit	“<subsystem id>”
SubsysEnable	“<subsystem id>”
SubsysDisable	“<subsystem id>”
SubsysReset	“<subsystem id>”

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 (supclib).

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 uses the synchronous mal interface.

Error Handling¶

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

Classes¶

The supclib library provides one class that encapsulates the interface with the Supervisor. This class is the SysSupCommands class.

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
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
get_state	None	stdif
get_status		stdif
init	None	stdif
enable	None	stdif
disable	None	stdif
reset	None	stdif
stop	None	stdif

Examples¶

Retrieving the Status¶

import supclib.syssup_commands as sup

uri = "zpb.rr://134.171.3.48:30269"
supif = sup.SysSupCommands(uri)
print(supif.get_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

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.

Warning

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

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
-  help
-  init
-  subnames
-  reset
-  setup
-  get_config
-  state
-  status
-  subset
-  substatus

Command	Parameters	Description
disable	[<subsystem>]	sends the disable (stdif) event to the connected server. If the subsystem parameter is provided, the command will be forwarded to the specified subsystem by the server.
enable	[<subsystem>]	sends the enable (stdif) event to the connected server. If the subsystem parameter is provided, the command will be forwarded to the specified subsystem by the server.
help		print the list of supported commands
init	[<subsystem>]	sends the init (stdif) event to the connected server. If the subsystem parameter is provided, the command will be forwarded to the specified subsystem by the server.
subnames		Get the list of subsystems managed by the Supervisor
reset	[<subsystem>]	sends the reset (stdif) event to the connected server. If the subsystem parameter is provided, the command will be forwarded to the specified subsystem by the server.
setup	[–file <file>] <setup buffer>	The setup commands uses a JSON format to set SysSup run-time parameters. The JSON string shall match the defined schema. The command also accepts to use the contents of a file. The provided buffer will overwrite the information from the file.
state		sends the GetState (stdif) event to the connected server
status		sends the GetStatus (stdif) event to the connected server
subset		This command is equivalent to the setup but instead of JSON format, it uses a simple parameter format (SPF), e.g. subset <subsystem>:access=false
substatus		Get the detailed status of the subsystems managed by the server
get_config		Get the actual configuration used by the server
ctrl-d		Stop the shell

using subset command¶

supSh> subset subsim2:access=true
reply> = OK
supSh>

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"
                ]
            }
        }
}