Console module

A command line console for DOS applications based on the Python cmd module.

Optional command line arguments

-app <name>
<name> specifies the default DOS application the console will attempt to connect to.
<name> is a string specifying a tag and/or interface separated by commas.
Remember the DOS convention that all tag and interface have to be uppercase.
If name == ‘None’ the console will not wait for and not connect to any default application.
Notation: -app tag, ‘role/interface name’
Examples:
-app ‘IB’,’IB3’
tag is required, the interface name is optional.
–noapp
Starts the console without waiting for any particular application.
This is equivalent to using -app None
–usecs
If given, the Console starts a Pyro command server so some functions can be exectuted by
other applications. The default is not to use a command server.
-command <name>
Execute single command <name>
-script <name>
Execute console script <name>
–nic <name>
IP address of network interface to be used for Advertise. Default is ‘’ to let the
system decide

User Documentation

The DOS Console is a simple command line interpreter. It allows for interfacing to devices and roles within an instance.

Console Commands

These are commands specific to the DOS Console itself.

  • alarm_display
    • Turn on/off display of alarm messages.
    • Commands:
      • alarm_display <on/off>
  • connect
    • Device Connection Management.
    • Commands:
      • connect device=<device name>, instance=<inst name>
      • connect device=<device name>, [logger=True/False], [reconnect=True/False]
  • disconnect
    • Device Connection Management.
    • Commands:
      • disconnect logger, device=<device name>
      • disconnect instance, device=<device name>
  • echo
    • Turns command echo on or off or adds a line to the log.
    • Useful only in script mode. Ignored in other modes.
    • Commands:
      • echo <on/off/log line>
  • execute
    • If the script name includes ‘.py’ the script is interpreted as python script. Otherwise it is considered as a console script and will be executed by the Console.
    • It is assumed that $DOS_CONSOLE (or $CONSOLE_DIR for eUPS) is defined.
    • The default command server (OCS) will be used to execute a console script
    • No other commands can be entered until the script is complete.
    • Commands:
      • execute <console script file/python script file>
  • exit
    • Exit the command loop
    • Commands:
      • exit
  • exposure
    • Retrieve information from the database for the exposure specified by <expid>.
    • If no expid is given the latest exposure number as returned by get_latest_expid() is used.
    • If no option is given a summary for this exposure is printed.
    • Commands:
      • exposure <expid> <(property)/all/add_header/add_comment>
    • The following options can be specified:
      • property - selects the attribute ‘property’ of the exposure object and prints its current value. A list of exposure properties can be found in the exposure table article of the DOS Wiki.
      • all - prints (almost) all attributes of the exposure object.
      • add_header - allows to add keyword/value pairs for the image FITS header. The syntax is exposure <expid> add_header KEYWORD=value.
      • add_comment - allows to add a comment about this exposure.
  • login
    • Login to start a new session.
    • Commands:
      • login <username>
  • logout
    • Logout current session user.
    • Commands:
      • logout
  • manage
    • Manage user sessions.
    • Commands:
      • manage list sessions
      • manage sid=<sid>, level=<level>, logout
  • monitor
    • When monitor is set to ‘on’ a status message is printed whenever an exposure is updated in the database.
    • If monitor is set to ‘all’ instead or ‘on’ the (almost) full exposure object is printed.
    • Set monitor to ‘off’ if no update messages should be displayed.
    • The monitor is off by default.
    • Commands:
      • monitor <off/on/all>
  • ns
    • Interact with the Pyro4 nameserver.
    • Commands:
      • ns list
      • ns lookup <Role>
      • ns ping
      • ns remove <Role>
  • read_sv
    • Subscribes to and reads a shared variable.
    • Commands:
      • readsv <GROUP_NAME>_<shared variable name>
  • seeker
    • Start/stop the seeker thread.
    • Add or remove a seeker from the seeker list. If device_instance is not given, the default (‘ ‘) is used which will find devices with any device_instance name (not necessarily hardware).
    • Reset device and instance lists (reset device=CCD1, reset instance=all).
    • Commands:
      • seeker <start/stop/reset/add/remove/list>, service=<service name>, device_instance = ‘’
  • select
    • Selects and connects to a new command server (PML) interface. Default switches to the default command server.
    • A single name given as an argument is first compared to the list of known tags. If a unique interface is found this command server is selected. If not, the argument is compared to the known roles.
    • Commands:
      • select <default/tag name/interface name>
  • shell
    • Execute a shell command.
    • Commands:
      • shell <command>
  • show
    • Prints information about DOS.
    • Commands:
      • show commands - Lists both the commands implemented by the command server functions. For the OCS the allowed transition command for the FSM are also listed.
      • show parameters - Lists the PML database elements of the selected command server and their current values.* Not currently supported?
      • show components - Lists all DOS components that have been discovered so far.
      • show default - Shows information about the default command server.
      • show selected - Shows information about the currently selected command server.
      • show version - Returns the Console version number, the product version and the DOS version used.
      • show pending - Shows commands executing in the background (submitted with & option)
      • show mode - Return the Console mode of operation.
      • show guiserver - Returns node and port information for the GUIServer.
      • show user - Returns the current user.
      • show privileges - Returns current user privileges.
      • show session - Returns information about current session.
      • show mc - Returns information about the master console.
      • show propid - Returns information about the session’s propid.
      • show observer - Returns information about the session’s observer(s).
      • show devices - Returns information about found devices.
      • show instances - Returns information about found instances.
  • shutdown
    • Call ARCHITECT to initiate shutdown.
    • Commands:
      • shutdown
  • sleep
    • Force Console to wait (sleep) - useful only in script mode. Ignored in other modes.
    • Commands:
      • sleep <time in seconds>
  • su
    • Change session privileges to the requested level.
    • The command will only succeed if the current user has sufficient privileges and if the DESI observer grants the request.
    • Commands: + su <user/observer/expert/root> + su mc - to start a master console session

Role Commands (PML)

Roles’s exposed PML commands can be called from the console. This can be done one of two ways.

  • The role can be selected with the select command, and then the PML command entered in directly.
    • select <role>
    • <command> <args>
    • <command> <args>
  • Call the command preceded by the role.
    • <role> <command> <args>
    • <role> <command> <args>

Background Commands

Commands are executed in a separate thread when the command line ends with an ampersand ‘&’. Use the ‘show pending’ command to see a list of all pending commands. It is not possible to stop a pending command. However, if a command like ‘configure’ fails, using the background option will avoid a possible dead lock. The Console prompt returns and it is now possible to submit additional commands, for example to restart a failed component with the Architect, which might lead to a successful completion of the original command (configure in this case).

Developer Documentation

This file defines the DosConsole class.

Author: KH
Date: Jan 10, 2010

Version Histories
0.1.0 1/1/2010 KH Initial version
0.5.0 4/1/2010 KH Stable version, pre-exposure table
1.0.0 5/12/2010 KH Stable version, pre server mode
1.1.0 5/13/2010 KH server mode added
1.2.0 11/11/2010 KH alarm handling added
1.2.1 12/22/2010 KH product name and version added
1.3.0 12/27/2010 KH background execution mode added, instance and dos version added
1.4.0 1/7/2011 KH Fixed script execution, exit handling
1.5.0 1/21/2011 KH Interlock and Monitor status displayed in window title
2.0.0 8/30/2011 KH Session Management
3.0.0 12/1/2014 AEE DOS Port
3.0.1 12/26/2014 KH Remove obsolete SISPI parts
3.1.0 1/24/2014 KH readsv, callbacks added, logging stuff removed
3.2.0 1/11/2016 KH Device support added
class Console.DosConsole(app, input=None, mode='interactive', auth=True, role='CONSOLE', log_level='ERROR', devicesupport=False, instance=None, alarmhandler=False, consoleserver=False, network_interface='')

Bases: cmd.Cmd

The DosConsole class

get_published_value(sv)
Parameters:sv (str) – The name of the Shared Variable to get the value for
Returns tuple:The current published value and update time for the requested SV, or (None, None) if the sv or the SVE are not available or not connected or the variable hasn’t yet been written to
log_message(*args, **kwargs)

Print a message to the console. Will print either args[0][3] or the kwargs if not.

do(*args, **kwargs)

Make an action NEEDS MORE

configure(*args, **kwargs)

Configure does nothing

get(*args, **kwargs)

Basic getter function. Accepted values are role, interface, status, instance, instances, or devices.

Parameters:key – The value to retreive
Returns:The value requested, or FAILED if it isn’t available.
cleanup_pyro()
cleanup_svs()

Cleanup all of the collected variables.

precmd(line)

Processes the entered text before calling the command with onecmd. Responsible for processing HELP calls.

Parameters:line (str) – The line of text entered in the console
Returns str:The formatted line sent to the onecmd method
postcmd(stop, line)

Runs after onecmd finishes. Print out the result of the command, and update the list of running background commands.

Parameters:
  • stop (boolean) – The return value of the onecmd call
  • line (str) – The string that was returned by precmd before the onecmd call
Returns boolean:
 

Whether or not to stop the command loop
preloop()

Runs before the command loop starts. Can print a message for script mode, and checks authentication for interactive mode.

postloop()

Runs after the command loop completes. Can print a message for scripts completing.

emptyline()

Make it so entering an empty line does nothing (instead of the default repeat prior command)

do_connect(line)

Device Connection Management.

Commands: connect device=<device name>, instance=<inst name>
connect device=<device name>, [logger=True/False], [reconnect=True/False]
do_disconnect(line)

Device Connection Management.

Commands: disconnect logger, device=<device name>
disconnect instance, device=<device name>
do_show(line)

Prints information about DOS.

Commands: show <argument>

  • show commands - Lists both the commands implemented by the command server functions. For the OCS the allowed transition commands for the FSM are also listed.
  • show parameters - Lists the PML database elements of the selected command server and their current values.*
  • show components - Lists all DOS components that have been discovered so far.
  • show default - Shows information about the default command server.
  • show selected - Shows information about the currently selected command server.
  • show version - Returns the Console version number, the product version and the DOS version used.
  • show pending - Shows commands executing in the background (submitted with & option)
  • show mode - Return the Console mode of operation.
  • show guiserver - Returns node and port information for the GUIServer
  • show user - Returns the current user
  • show privileges - Returns current user privileges
  • show session - Returns information about current session
  • show mc - Returns information about the master console
  • show propid - Returns information about the session’s propid
  • show observer - Returns information about the session’s observer(s)
  • show devices - Returns information about found devices
  • show instances - Returns information about found instances
  • show blacklist - Returns information about blocked Name Servers

*Not currently supported?

do_clear_blacklist(line)
do_ns(line)

Interact with the Pyro4 nameserver

Commands: ns list
ns lookup <Role>
ns ping
ns remove <Role>
do_manage(line)

Manage user sessions.

Commands: manage list sessions
manage sid=<sid>, level=<level>, logout
do_login(line)

Login to start a new session

Commands: login <username>
do_log_level(line)

Set the log level for this Console session

Commands: log_level [ERROR, WARN, INFO, DEBUG]
do_logout(line)

Logout current session user

Commands: logout
do_shutdown(line)

Call ARCHITECT to initiate shutdown

Commands: Shutdown
do_alarm_display(line)

Turn on/off display of alarm messages.

Commands: alarm_display <on/off>
do_exit(line)

Exit the command loop

Commands: exit
do_EOF(line)

EOF (Ctrl D) received. Exit the command loop

do_shell(line)

Execute a shell command.

Commands: shell <command>
do_sleep(line)

Force Console to wait (sleep) - useful only in script mode. Ignored in other modes.

Commands: sleep <time in seconds>
do_echo(line)

Turns command echo on or off or adds a line to the log. Useful only in script mode. Ignored in other modes.

Commands: echo <on/off/log line>
do_execute(line)

If the script name includes ‘.py’ the script is interpreted as python script. Otherwise it is considered as a console script and will be executed by the Console. It is assumed that $DOS_CONSOLE (or $CONSOLE_DIR for eUPS) is defined. The default command server (OCS) will be used to execute a console script No other commands can be entered until the script is complete.

Commands: execute <console script file/python script file>
do_monitor(line)

When monitor is set to ‘on’ a status message is printed whenever an exposure is updated in the database. If monitor is set to ‘all’ instead or ‘on’ the (almost) full exposure object is printed. Set monitor to ‘off’ if no update messages should be displayed.

The monitor is off by default.

Commands: monitor off/on/all
do_exposure(line)

Retrieve information from the database for the exposure specified by <expid>. If no expid is given the latest exposure number as returned by get_latest_expid() is used. If no option is given a summary for this exposure is printed.

Commands: exposure <expid> <(property)/all/add_header/add_comment>

The following options can be specified:
property: selects the attribute ‘property’ of the exposure object and prints its current value.
For example the command
exposure 175 exptime
prints the exposure time used for image 175. A list of exposure properties
can be found in the exposure table article of the DOS Wiki.
all: prints (almost) all attributes of the exposure object
add_header: allows to add keyword/value pairs for the image FITS header. The syntax is
exposure <expid> add_header KEYWORD=value
add_comment: allows to add a comment about this exposure.
do_su(line)

Change session privileges to the requested level. The command will only succeed if the current user has sufficient privileges and if the DESI observer grants the request.

Commands: su <user/observer/expert/root>
su mc to start a master console session
do_readsv(line)

Subscribes and reads a shared variable

Commands: readsv <GROUP_NAME>_<shared variable name>
do_seeker(line)

Start/stop the seeker thread. Add or remove a seeker from the seeker list. If device_instance is not given, the default (‘ ‘) is used which will find devices with any device_instance name (not necessarily hardware).

Reset device and instance lists (reset device=CCD1, reset instance=all).

Commands: seeker <start/stop/reset/add/remove/list>, service=<service name>, device_instance = ‘’
do_select(line)

Selects and connects to a new command server (PML) interface. Default switches to the default command server. A single name given as an argument is first compared to the list of known tags. If a unique interface is found this command server is selected. If not the argument is compared to the known roles. Again, if a unique interface is found this command server is selected.

Commands: select <default/tag name/interface name>
default(line)

The default command is called for everything else (all unrecognized commands). Anything starting with ‘#’ is a comment and is ignored. If the first word of line is a PML tag followed by “::” a connection to this interface is attempted. Without a “::” the next word of <line> is checked. If it is uppercase it is used as the interface name. If no PML tag is given, the current command server is used. The next word of <line> [or the first if line doesn’t start with a PML tag as described above] becomes the cmd and the rest becomes the params argument for a PML execute call using the selected command server.

class Console.Background(target, cmd, *args, **kwargs)

Bases: threading.Thread

Class used to excecute a background command

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

Console.dos_file(string)