Mark Koennecke from The SICS Master User manual. userrefman. converted to tex using html2tex (from Mark Koennecke) converted to docbook4using htlatex converted to docbook5 using the transform available in Oxygen hand edited to remove lint and put into In the previous chapter, you learnt how to start and stop SICS, and how to login. Now you'll learn how to control the instrument. The first part of this chapter deals with some of the most used commands in SICS. This includes system commands and control commands. This provides you with a soft start. The second part of the chapter deals with logging activity and configuring your connection to SICS. The next chapter will go more deeply into the how SICS executes those commands, through a sequence of states. You may want to skip the next chapter if you don't require a deeper understanding of SICS. This chapter and the next are from the master user manual for SICS. It gives an overview over all commands implemented, independent of a specific instrument. This is to be used as the source for more instrument specific user manuals and gives an overview of the commands available within SICS. Please note, that many instruments have special commands realized as scripts in the SICS built in scripting language. Only the most common of such commands are listed here. A client server system is potentially open to unauthorised hackers who might mess up the instrument and your valuable measurements. A known problem in instrument control is that less knowledgeable user accidentally change instrument parameters which ought to be left fixed. In order to solve these two problems SICS supports authorisation on a very fine level. As a user you have to specify a username and password in order to able to access SICS. Some clients already do this for you automatically. SICS support four levels of access to an instrument: Spy may look at everything, request any value, but may not actually change anything. No damage potential here. User is privileged to perform a certain amount of operations necessary to run the instrument. Manager has the permission to mess with almost everything. A very dangerous person. Internal is not accessible to the outside world and is used to circumvent protection for internal uses. However some parameters are considered to be so critical that they cannot be changed during the runtime of the SICS-server, not even by Managers. All this is stated here in order to explain the common error message: You are not authorised to do that and that or something along these lines. SICS is a client server system. The application the user sees is usually some form of client. A client has two tasks: the first is to collect user input and send it to the SICS server which then executes the command. The clients second task is to listen to the server messages and display them in a readable format. This approach has two advantages: clients can reside on machines across the whole network thus enabling remote control from everywhere in the world. The second advantage is that new clients (such as graphical user interface clients) can be written in any feasible language without changes to the server. SICS is an object oriented system. This is reflected in the command syntax. SICS objects can be devices such as motors, single counters, histogram memories or other hardware variables such as wavelength or Title and measurement procedures. Communication with these objects happens by sending messages to the target object. This is very simply done by typing something like: object message par1 par2 .. parn. For example, if we have a motor called A1: A1 list will print a parameter listing for the motor A1. In this example no parameters were needed. There exist a number of one-word commands as well. For compatibility reasons some commands have a form which resembles a function call such as: drive a1 26.54 This will drive motor a1 to 26.54. All commands are ASCII-strings and usually in english. SICS is in general CASE INSENSITIVE. However, this does not hold for parameters you have to specify. On a unix system for instance file names are case sensitive and that had to be preserved. Commands defined in the scripting language are lower case by convention. Most SICS objects also hold the parameters required for their proper operation. The general syntax for handling such parameters is: objectname parametername prints the current value of the parameter objectname parametername newvalue sets the parameter value to newvalue if you are properly authorized. Most of the parameters SICS uses are hidden in the objects to which they belong. But some are separate objects of their own right and are accessible at top level. For instance things like Title or wavelength. They share a common syntax for changing and requesting their values. This is very simple: The command objectname will return the value, the command objectname newvalue will change the variable. But only if the authorisation codes match. The most used commands in SICS are: status Prints SICS state. Useful for troubleshooting. Possible return values can be: Eager to execute commands Scanning Counting Running Halted Note that if a command is executing which takes some time to complete the server will return an ERROR: Busy message when further commands are issued. This does not take into account the state of the PLC. See plc_ready plc_ready Prints the state of the PLC. Useful for troubleshooting. If FALSE, you won't be able to open a shutter or move a motor. It means that you should look at the PLC panel in the instrument cabin and see what exactly is need to be attended to and fix it e.g. Enable Motion. You can't access operations on this panel remotely. Possible return values can be: FALSEInstrument not ready TRUEInstrument ready sicslist interface drivable prints a list of all drivable objects. This is more than motors and includes virtual motors, sample environment devices and wavelength run device value run a device to a value runs any object listed using sicslist interface drivable in non-blocking/asynchronous mode drive device value drive a device to a value drives any object listed using sicslist interface drivable in blocking/synchronous mode stopexe device interrupts a drive or run command. In the case of motors, the motor will decelerate. It won't stop immediately, as this can cause damage to the instrument This will not interrupt a scan e.g. runscan. SICS will continue to accept commands from a client stopexe all interrupts all devices. In the case of motors, the motor will decelerate. It won't stop immediately, as this can cause damage to the instrument This will not interrupt a scan e.g. runscan. SICS will continue to accept commands from a client runscan scanvar start stop numpoints mode preset [force datatype savetype] Arguments must be in the order described. See more detail in the "Simple Scans" chapter. scanvar a drivable device, ie a motor or temperature controller etc start the start position for the scan variable stop the stop position for the scan variable numpoints the number of scan points (the start and stop positions will be included in the scan) mode Allowed mode one of: time unlimited period count frame MONITOR_n (where n=1,2,3 ...) If you set the mode to MONITOR_1 then the histogram server will stop when MONITOR_1 reaches the preset number of counts which has been set with the following preset parameter preset the acquisition duration at each scan point, this is in second if the mode is time, or counts if the mode is count or MONITOR_n INT1712 3 interrupts a runscan command. In the case of motors, the motor will decelerate. It won't stop immediately, as this can cause damage to the instrument sics_exitus A single word commands which shuts the server down. Only managers may use this command. wait time waits time seconds before the next command is executed. This does not stop other clients from issuing commands. resetserver resets the server after an interrupt. sicslist Prints a list of all SICS objects. sicslist server Prints a list of all server options. sicslist sicsobject Prints all the metadata associated with the SICS object sicsobject. sicslist sicsobject key Prints the value of the key associated with the SICS object sicsobject. sicslist setatt sicsobject key value Sets a user defined attribute with the name key and the value value for the SICS object sicsobject. sicslist metadatakey List all unique entries for the specified metadata key. System supplied metadata keys are: type The object class interface The object interfaces implemented by SICS e.g. sicslist type will print all the objects classes available in the SICS server This list may be augmented with user generated keys as defined through using the sicslist setatt obj key value command sicslist metadatakey value List all the SICS objects which match the value for the metadatakey given as parameters. e.g. sicslist interface drivable will print all objects implementing the drivable interface in the SICS server. sicslist objstatus obj Will query the current state of the SICS object obj. This makes sense for things like motors, counter etc. which can be run asynchronously. The result can be: idle, fault, busy etc. sicslist match mask Will print the names of all SICS objects where the name matches the wildcard given as mask status A single word command which makes SICS print its current status. Possible return values can be: Eager to execute commands Scanning Counting Running Halted Note that if a command is executing which takes some time to complete the server will return an ERROR: Busy message when further commands are issued. status interest initiates automatic printing of any status change in the server. This command is primarily of interest for status display client implementors. backup saves the current values of SICS variables and selected motor and device parameters to the disk file specified as parameter. If no file parameter is given the data is written to the system default status backup file. The format of the file is a list of SICS commands to set all these parameters again. The file is written on the instrument computer relative to the path of the SICS server. This is usually /home/INSTRUMENT/bin. backup motsave toggles a flag which controls saving of motor positions. If this flag is set, commands for driving motors to the current positions are included in the backup file. This is useful for instruments with slipping motors. restore reads a file produced by the backup command described above and restores SICS to the state it was in when the status was saved with backup. If no file argument is given the system default file gets read. restore listerr prints the list of lines which caused errors during the last restore. killfile decrements the data number used for SICS file writing and thus consequently overwrites the last datafile. This is useful when useless data files have been created during tests. As this is critical command in normal user operations, this command requires managers privilege. sicsidle prints the number of seconds since the last invocation of a counting or driving operation. Used in scripts. dir DEPRECATED: use sicslist a command which lists objects available in the SICS system. Without any options prints a list of all objects. The list can be restricted with: dir var DEPRECATED: use sicslistprints all SICS primitive variables dir mot DEPRECATED: use sicslistprints a list of all motors dir inter driv DEPRECATED: use sicslistprints a list of all drivable objects. This is more than motors and includes virtual motors such as environment devices and wavelength as well. dir inter count DEPRECATED: use sicslistShows everything which can be counted upon. dir inter env DEPRECATED: use sicslistShows all currently configured environment devices. dir match wildcard DEPRECATED: use sicslistlists all objects which match the wildcard string given in wildcard - doesn't work SICS offers not less then three different ways of logging your commands and the SICS server’s responses You may create a similar per client log file on the computer running the SICS server through the logbook command. Then there is a way to log all activity registered from users with either user or manager privilege into a file. This means all commands which affect the experiment regardless from which client they have been issued. This is accomplished with the commandlog command. the GetLog command receives messages from all active clients. This allows you to view all events on your connection, and is intended for debugging. Some users like to have all the input typed to SICS and responses collected in a file for further review. This is implemented via the LogBook command. LogBook is actually a wrapper around the config file command. LogBook understands the following syntax: LogBook alone prints the name of the current logfile and the status of event logging. LogBook file filename sets the filename to which output will be printed. Please note that this new filename will only be in effect after restarting logging. LogBook on This command turns logging on. All commands and all answers will be written to the file defined with the command described above. Please note, that this command will overwrite an existing file with the same name. LogBook off This command closes the logfile and ends logging. The Commandlog is a file where all communication with clients having user or manager privilege is logged. This log allows to retrace each step of an experiment. This log is normally configured in the startup file or can be configured by the instrument manager. There exists a special command, Commandlog, which allows to control this log file. Commandlog new filename starts a new commandlog writing to filename. Any prior files will be closed. The log file can be found in the directory specified by the ServerOption LogFileDir. Usually this is the log directory. Commandlog displays the status of the commandlog. Commandlog close closes the commandlog file. Commandlog auto Switches automatic log file creation on. This is normally switched on. Log files are written to the log directory of the instrument account. There are time stamps any hour in that file and there is a new file any 24 hours. Commandlog tail n prints the last n entries made into the command log. n is optional and defaults to 20. Up to 1000 lines are held in an internal buffer for this command. Commandlog intervall minutes Queries and configures the intervall in minutes at which time stamps are written to the commandlog. It is now possible to have a script executed whenever a new log file is started. In order to make this work a ServerOption with the name logstartfile must exist in the instrument configuration file. The value of this option must be the full path name of the file to execute. Note: with the command config listen 1 you can have the output to the command log printed into your client, too. With config listen 0 you can switch this off again. This is useful for listening into a running instrument. The SICS server logs all its activities to a logfile, regardless of what the user requested. This logfile is mainly intended to help in server debugging. However, clients may register an interest in certain server events and can have them displayed. This facility is accessed via the GetLog command. It needs to be stressed that this log receives messages from all active clients. GetLog understands the following messages: GetLog All achieves that all output to the server logfile is also written to the client which issued this command. GetLog Kill stops all logging output to the client. GetLog OutCode request that only certain events will be logged to the client issuing this command. Enables only the level specified. Multiple calls are possible. Possible values for OutCode are: Internal internal errors such as memory errors etc. Command all commands issued from any client to the server. HWError all errors generated by instrument hardware. The SICS server tries hard to fix HW errors in order to achieve stable operations and may not generate an error message if it was able to fix the problem. This option may be very helpful when tracking dodgy devices. InError All input errors found on any clients input. Error All error messages generated by all clients. Status some commands send status messages to the client invoking the command in order to monitor the state of a scan. Value Some commands return requested values to a user. These messages have an output code of Value. SICS has a command for changing the user rights of the current client server connection, control the amount of output a client receives and to specify additional logfiles where output will be placed. All this is accessed through the following commands: The config command configures various aspects of the current client server connection. Basically three things can be manipulated: The connections output class, the user rights associated with it, and output files. config OutCode val sets the output code for the connection. By default all output is sent to the client. But a graphical user interface client might want to restrict message to only those delivering requested values and error messages and suppressing anything else. In order to achieve this, this command is provided. Possible values: Values for val are Internal Command HWError InError Status Error Value This list is hierarchical. For example specifying InError for val lets the client receive all messages tagged InError, Status, Error and Value, but not HWError, Command and Internal messages. config Rights Username Password Each connection between a client and the SICS server has user rights assocociated with it. These user rights can be configured at runtime with the command config Rights Username Password. If a matching entry can be found in the servers password database new rights will be set. config File name Scientists are not content with having output on the screen. In order to check results a log of all output may be required. The command config File name makes all output to the client to be written to the file specified by name as well. The file must be a file accessible to the server, i.e. reside on the same machine as the server. Up to 10 logfiles can be specified. Note, that a directly connected line printer is only a special filename in unix. config close num closes the log file denoted by num again. config list lists the currently active values for outcode and user rights. config myname returns the name of the connection. config myrights prints the rights associated with your connection. config listen val switches listening to the commandlog on or off for this conenction. If this on, all output to the commandlog, i.e. all interesting things happening in SICS, is printed to your connection as well. val = 0 is off val = 1 is on