.. _supif:

Introduction
############

Reference Documents
===================

[RD1]
    | Central Control System Development Standards;
    | `ESO-366378 v1 <https://pdm.eso.org/kronodoc/HQ/ESO-366378>`_


SysSup Interface
################

SysSup interface, ``supif``, is the interface to be used by the IFW
System Supervisor. This interface shall be used whenever you want to
interact with the supervisor.

This documentation provides an overview of the interface.  For data structures
only the data members are documented, not the accessors generated by MAL. Similarly
names are not fully qualified as it is different across the supported languages.

Constraints
###########

The SysSup interfaces have been defined under the following constraints imposed by CII MAL/RAD:

* CII MAL does not support optionals. This is huge limitation for a generic software
  like IFW. Some of the implications is that in some cases a complete structure has to
  be serialized even in one attribute is needed.

* RAD can only accepts one parameter for commands. So if a command needs more than
  one parameter, one should use structs and use the parameters as fields of the struct.

* CII MAL does not support defaults, this means you need to fill up properly all fields
  of your structs used as payload for your commands.




.. module:: supif

Interfaces
==========

.. class:: AppCmds

    SysSup Command interface.

    .. method:: Recover() -> String

        Command that tries to recover from error state produced by one or more subsystems. It will
        attempt to bring all subsystems to operational state. You can do the same
        going back to reset or ready state and coming back to operational.

        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubNames() -> String

        Command to get the list of subsystems managed by the server (SysSup).

        :return: A string with the list of subsystems.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubStatus(devices) -> String

        Command to get status of one or more subsystems. The status is a list of parameters
        with their current values.

        :param subsys: strings with the name of device.
        :return: A string with the list of device parameters.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: ReloadConfig() -> String

        Command to reload the server configuration.

        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SetConfig() -> String

        Command to update the server configuration.

        :param config: configuration in CII Config-Ng format.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: GetConfig() -> String

        Command to get actual server configuration. Reply is sent using the CII
        ConfigNg format (stream).

        :return: A CII Config-Ng stream with the server configuration.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.


    .. method:: SetObMode(mode) -> String

        Command to setup observation mode.

        :param mode: observation mode to be setup.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SetOpMode(mode) -> String

            Command to setup operation mode.

            :param mode: operation mode to be setup.
            :return: A string with information about the execution of the request.
            :rtype: String
            :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: Setup(payload) -> String

        Command to setup subsystem run-time parameters.

        :param payload: vector of run-time configurations to be applied to the subsystems.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubInit(devices) -> String

        Command for Subsystem direct control (maintenance/troubleshooting)
        It triggers the subsystem initialisation for one subsystem.

        :param subsys: subsystem name.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubEnable(devices) -> String

        Command for subsystem direct control (maintenance/troubleshooting)
        It moves one subsystem to operational state (from state ready).

        :param subsys: subsystem name.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubDisable(devices) -> String

        Command for subsystem direct control (maintenance/troubleshooting)
        It moves one subsystem to ready state (from state operational).

        :param subsys: subsystem name.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SubReset(devices) -> String

        Command for subsystem direct control (maintenance/troubleshooting)
        It triggers the subsystem reset.

        :param subsys: subsystem name.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.

    .. method:: SetAccess(params) -> String

        Command that changes the access configuration of a subsystem. The params is
        of type AccessParams.

        :param params: structure that contains the parameters for the command.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises supif::ExceptionErr: if a failure occurrs.



Data Structures
===============


.. class:: ExceptionErr

     Exception class thrown in case an error is encountered while handling a request.

     .. attribute:: code
          :type: int

          Exception (error) code allocated to the specific exception; 0 if no code is allocated.

     .. attribute:: desc
          :type: str

          Description of the exception (diagnostics).

.. class:: AccessParams

     Structure for the parameters of the SetAccess Command.

     .. attribute:: subsystem
          :type: string

          Subystem name

     .. attribute:: access
          :type: boolean

          Access true or false.




