======================
SKA DS Manager Session
======================

Dish Structure Controller Session Management
--------------------------------------------
The Dish Structure Controller (DSC) has an arbitration mechanism to allow only one client to have authority and 
execute commands successfully. The `DscCmdAuthority` variable on the server indicates which client has authority to command the DSC. LMC has the lowest priority. 
The priority above LMC is the EGUI client, and above that is the Hand Held Panel (HHP) client. This means that either EGUI or HHP can take control of the DSC 
when LMC has authority. LMC can only take authority if there is no authority being held. If for some reason LMC loses connection without releasing authority, 
LMC will be able to retake authority and get a valid session id. This is done implicitly when executing a command. LMC uses a unique `immutable user id` specific to each dish
to identify itself to the DSC. The immutable user id has the format `LMC-<DISH_ID>-<UNIQUE HASH>`; the UNIQUE HASH is an obfuscated string generated from the tango device trl.

On Initialisation
-----------------
On initialisation, DSM (Dish Structure Manager) subscribes to the `DscCmdAuthority` variable, LMC will only attempt to take authority on command
execution or when the `TakeAuthority` command is executed. This sequence is shown below:

On Command Execution
--------------------

When executing commands a pre-check is done by inspecting `DscCmdAuthority` variable. If LMC has authority,
the command will be sent. If the server reports NO_AUTHORITY, LMC will attempt to issue a `ReTakeAuthority` command, 
to reclaim authority before re-attempting to send the command. 
If no client has authority, DSM will attempt to take authority and proceed with the command execution.
Commands will be rejected if a higher priority client has authority. This sequence is shown below:

.. uml:: session_id_cmd_exec.uml

Manually
--------------------

In addition to the automatic session handling implemented in the Dish Structure Manager, the `TakeAuthority`, `ReleaseAuth` and `ReTakeAuthority` commands have also been exposed
directly as Tango commands. The same sequence sequence of steps as described above in `On Command Execution` will take place when attempting to use
`TakeAuthority`. When releasing authority, if the session id being held by the DSM is valid then authority will be released and `DscCmdAuthority`
will report `NO_AUTHORITY`. In order to retake authority, the `ReTakeAuthority` command can be used if LMC has taken authority previously but lost the session id.