AzCamServer and Reference Manual

This document is now out of date… Also see this link for an out of date reference manual.

This document describes AzCam/AzCamServer installation, configuration, and programming. It is intended for advanced users only.

Programming

This is the general user manual and programming guide for AzCam. It is intended for advanced AzCam users. See the sphinx documentation links of the AzCam home page for programming information.

Versioning

Because AzCam consists of many different modules and plugins, there is no single version number or date which uniquely identifies all the code. The current AzCam “package version” is found in azcam.version. Clients can generally query the version with “get version”. The python source code modules may be examined for date/version information at the top of each file.

Conventions

Modules (files) have all lowercase filenames. Objects (such as controller) are always all lower case. Command names (methods) and attributes (parameters) are either all lowercase (new) or named with MixedCase convention (historical). A MixedCase example is focalplane.SetFormat(1,512,1,512,1,1). Commands must have parentheses following their names even if no attributes are required. Filenames should be given with forward slash ('/') separators, even on Windows machines. If back slashes are used for some reason, they must be doubled as in c:\\data. Strings must be enclosed in quotation marks (single preferred), as in Get('Version'). Quotation marks must match ('Version“ is not acceptable). A quotation mark may be included in a string by preceding it with a backslash (“I am Mike\'s dog.”)

Commands

Commands can be imported into modules in the standard pythonic manner, such as from azcam.support.commands import *.

Magic Commands

Magic commands are a special syntax available with IPython which do not use the standard Python syntax of Command(Par1, Par2, …). The equivalent magic syntax is “Command Par1 Pars …”. Magic commands are optionally defined for a system only for user convenience. They are usually imported into the command line with “load_magic_commands”.

There are three built-in magic commands for user convenience: 1. sav to save the current AzCam state 2. pcl to TOGGLE AzCamLog output to the command line window 3. cl to enter the command line interpreter which uses a custom command parser if defined.

AzCamLog and AzCamMonitor

AzCamLog is a console-like window which by default appears automatically along with the main AzCam window and is used to display messages. These messages do not appear in the main console window since there would then be a complex mixture of messages from command line commands, internal threading commands which run in the back ground, and remote client commands. AzCamLog is a special usage of AzCamMonitor.

AzCamMonitor is a python client which can be used to display messages from AzCam in a remote process. It is for monitoring only, no commands are sent to AzCam from AzCamMonitor. To start AzCamMonitor, execute the StartAzCamMonitor.bat batch file. Edit the command line parameters -s ServerName and -p PortNumber as needed. ServerName is the host name of the machine running AzCam and PortNumber is the AzCam monitor port on AzCam (usually one greater than the base port, so typically 2403 for the first AzCam process). Prompts will be displayed if no command line parameters are specified.

Scripting

Scripts are Python commands which are intended to be run at the AzCam command line. They may or may not also be defined as User Commands. Scripts are especially useful to invoke GUIs such as PyQt programs and to execute user written commands. Scripts are executed by the Run command and must be in the Python search path. Scripts must be written in pure Python. There are many modules which may define the various AzCam commands. These modules may need to be imported into a script before they can be used. All scripts should include the line: from AzCamCommands import * in order to include the base AzCam commands. Scripts should usually include the line: from UserCommands import * in order include user defined commands, if they exist. Objects need to be defined manually, usually with a command like exposure=GetObject('exposure'). It is possible to define ALL currently available objects with the commands:

# load all defined objects for name in Globals.Objects.keys():

  globals()[name] = Globals.Objects[name]

After these definitions, normal AzCam commands are available such as: exposure.Expose() or controller.Reset(). A script cannot be run outside of AzCam (e.g. from File Explorer) since scripts require global data structures which are only defined within the AzCam python environment. We do not recommend executing scripts from a remote client since there may be complex interactions between plotting windows, the command line console, and task running in the background. In some case running scripts which do not have user interaction can be safe when called from a remote client. Scripts are usually executed using the Run command, as Run GetTemps. This method has the advantage of loading the script each time the run command is called which is useful when debugging a script. In the first method above the script is only imported when AzCam starts and subsequent script edits are not registered. When arguments are supplied on the command line using Run they must be space delimited and not placed in parentheses. So

Run GetTemps 0.2 'logfile1.txt' is OK but Run GetTemps(0.2,'logfile1.txt') is not.

A script may have an initialization file (scriptname.ini) which is used to read and save defaults values. These files are located in a sub-folder named params of the SystemFolder and are usually created automatically as needed. Scripts may be included automatically in the AzCam at startup by adding them to the UserCommands module. They can then be executed without the Run command (e.g. SetDefauts() rather than Run SetDefaults).

Objects

Python is an object oriented programming language and objects are used extensively in AzCam. Object-based commands provide control of all aspects of AzCam. These commands (methods) interact with hardware such as controllers, instruments, temperature controllers, and telescopes as well as with more virtual objects such as the exposures, images, databases, time, communication interfaces, etc. The required command syntax is object.Command() where object is the object name (such as controller, instrument, telescope) and Command() is the command to be sent. If Command() uses attributes, they are specified as comma separated values of the appropriate type, such as object.Command('ITL',1.234,45). For example, to send the command CompsOn() to the instrument, use: instrument.CompsOn(). To send the GetFocus() command to the telescope, use: telescope.GetFocus(). A focalplane command might be: focalplane.SetRoi(1,100,1,200,2,3).

User Commands

There are built-in AzCam commands which are always available to the command line. All standard python commands are also always available to the command line. A high level “user command” syntax may optionally be provided in additional to the standard AzCam commands. User commands are defined on a system dependent basis and may include both object based and commands which do not require object names. AzCam attempts to load a module named AzCamCommands.py in the search path which would define all user commands.

Return Values and Errors

Nearly all AzCam commands return a python list in the format: [status,value1,value2,..] where status is the string OK, ERROR, WARNING, or ABORTED. OK means the command executed successfully. ERROR means the command encountered a problem. WARNING is a special error case which is considered non-fatal and should not produce a pop-up message in a client application. ABORTED means a command or process was aborted, which may or may not be interpreted as an error. Usually warnings appear only in the log window. When status is ERROR, then value1 is always an error message string describing the problem. The error message string is enclosed in quotes, as in: ERROR 'bad parameter specified for action'. When replying to a client, the python list is converted into a space delimited string, so that a return value of ['OK',value1,'value2',..] would become OK value1 'value2'. There are a (very) few commands which do not return a status for simplicity, such as Print() and some analysis commands which simply return calculated values.

Header Commands

AzCam uses object specific keyword indexed dictionary to maintain textual informational about some objects. These are typically called headers as they are used to provide information in image headers. The keywords and their corresponding values, data type, and comment field are stored in each of the controller, instrument, and telescope .header dictionary. These dictionaries are manipulated by commands both from clients and internally in AzCam. Most of the values are written to the image file header (such as a FITS header) when an exposure begins. The dictionaries are accessed through methods such as controller.Header.GetAllKeywords() and instrument.Header.GetKeyword('FILTER1'). The ReadHeader()method of each object will actively read hardware to obtain information (such as controller.ReadHeader() or instrument.ReadHeader()). This is very different from the object.Header.xxx methods which only manipulate the internal Header databases. The telescope and instrument dictionaries are considered temporary and re-read every time an exposure starts. This is so that rapidly changing data values do not become stale. Most dictionary information is written to the image file header if the selected image format supports headers. When an object such as an instrument or telescope is disabled, the corresponding object database information is deleted and no longer updated.

Attributes

Parameters or Attributes may be read with the Get()command and written with the Set()command. It is recommended that Get() and Set() be used when reading and writing attributes from remote clients. For example, Get('ImageType') returns the current image type. The return value might be ['OK', 'zero', 'str']. The first value being the status, the second ImageType, the third indicating the return values type (useful for clients which see all values as strings. A list of valid parameters which can be changed can be found by typing: Globals.AzCamParameters Python object attributes may also be read and changed directly with Set() and Get(), although clients should be very carefully when modifying objects directly. For example: Get('controller.TimingBoardInstalled') returns the value of the TimingBoardInstalled parameter from the controller object, as well as its data type specified as a string, ‘int’ in this case. Note that Set('instrument.SomeParameter') is not the same as Set('telescope.SomeParameter'), since SomeParameter in each case is an attribute of a different object. If no object is provided, then the Globals object is assumed (which contains global variables across all objects).

AzCam DSP Code

The DSP code which runs in the ARC and Magellan controllers is assembled and linked with Motorola software tools. The Motorola DSP tools installer can be found on the AzCam web site. This file installs to create to the folder structure /AzCam/MotorolaDSPtools/ which is required by the batch files which assemble and link the DSP source code. While the AzCam application code for the ARC timing board is typically downloaded during camera initialization, the boot code must be compatible for this to work properly. Therefore AzCam DSP code must be burned into the timing board EEPROMs before use. The AzCam timing DSP code is quite different from the ARC code and is required for AzCam operation. The PCI fiber optic interface board and the utility board use the original ARC code and does not need to be changed. Note this applies to gen3 systems only, the gen1 and gen2 situation is more complex. For the Magellan systems, there is only one DSP file which must be downloaded during initialization. Note that xxx.s files are loaded for the Magellan systems while xxx.lod files are loaded for ARC systems.   Installation

IPython

AzCam is intended to be executed within an IPyton window. Typically a desktop icon or batch file is used to start an IPython window with a specific “profile”, usually named azcam, azcamconsole, or azcamserver. The IPython configuration files for the profile selected define the look and feel of that window and may also define the available command line syntax.

Installation Configurations

Installation of AzCam is accomplished with several different installers so that systems may be configured and updated as needed. Download the installer files from http://azcam.itl.arizona.edu/Downloads and execute them to install the various components. · A controller server program runs on the machine where a camera hardware interface is installed. See ControllerServer for more information. · The main AzCam processes run on the machine where the user will work. These are typically processes for azczamserver, azcamconsole, and GUIs.

AzCam Apps

The following support applications may also be useful when operating AzCam. · AzCamTool is a graphical user interface (GUI) useful for operating AzCam in a point and click mode. It is not required, but is highly recommended. · EngineeringTool performs very low level (and dangerous!) controller functions. · AzamImageServer is a stand-alone python image server which can receive images on a remote machine. This is especially useful for receiving images on computer running Linux. · Ds9Tools is a set of tools useful when using SAO’s Ds9 display program.

Python

The current version of AzCam requires Python version 2.7.x. See http://www.python.org for all things python. AzCam uses IPython, see http://ipython.scipy.org/moin for it command line and command processor. The more you know about using IPython the better!

Graphics

We recommend using PyQT for AzCam graphics. We have seen problems with other packages and tried to integrate PyQt as the default graphics toolkit so that everything works well together. In particular, for matplotlib you should set backend: Qt4Agg in the matplotlibrc file (if not configured automatically by IPython).

Dependencies

Some AzCam commands require python packages which are not installed by default. These must be downloaded and installed according to their individual instructions. Not all commands require all these packages. The current non-default packages are currently: • FITS image file manipulation (astropy.io.fits) See http://docs.astropy.org/en/stable/io/fits/index.html. • Numeric python for data manipulation (numpy). See http://numpy.scipy.org. • Plotting (pylab/matplotlib). See http://matplotlib.sourceforge.net. • For code which use a Qt graphical interface, PyQt is required, see http://www.riverbankcomputing.co.uk/software/pyqt/download. You may need to add c:\python27 and/or c:\python27\Scripts to the Windows PATH environment variable. Do this in Control Panel→System→Advanced→Environment Variables. Select the System variable PATH, click Edit.

ControllerServer

Beginning with AzCam v3.8, ControllerServers are separate executable programs which manage all direct interaction with controller hardware. Communication with a ControllerServers takes place over sockets via communication protocols defined between AzCam and a specific ControllerServer program. The reason for this change is to support the future use of small, low power computers co-located with the controller hardware. One example of this architecture would be PC-104 form factor machines installed inside a camera controller. These small computers will run only the ControllerServer program (which is usually written in C/C++). Previously controller hardware functions were integrated into AzCamServer through the AzCamLibrary.dll. This DLL as well as AzCamServer have been eliminated. Download and install the appropriate installer for your hardware from the AzCam web site. Both the Astronomical Research Cameras, Inc. (ARC) fiber optic PCI interface boards (for gen1, gen2, and gen3 cameras) and the Magellan Controller PCI interface boards require drivers which provide communication from the boards to the OS and to AzCam.

To install the AzCam drivers , follow the steps below: • Install the drivers using the batch file InstallAzCamDrivers.bat found in the AzCamDrivers sub-folder of your ControllerServer. This may install driver files for multiple controller types. • If pop-up windows appear during installation which ask to install hardware, you should Cancel them. • While the driver files may be deleted after installation we recommend keeping them for updates and uninstalls. • To install the PCI boards in a computer, follow the steps below: • Power off and unplug the PC. • Install the interface card in an empty PCI slot. • Plug in the power and turn the PC on.

If the software has been installed, Windows should be happy and nothing more needs to be done. You may check that the installation was successful by looking in the Device Manager under System in Control Panel. The drivers are usually installed under the name Jungo and should not have associated errors. [XP] Uninstall in Control Panel→System→Hardware→Device Manager, the drivers are usually installed under the name Jungo. They may be uninstalled by right clicking the item in the Device Manager list and selecting Uninstall…. [XP] You can then scan again to reinstall by clicking Control Panel→System→Hardware→Device Manager→Action→Scan for hardware changes. Note this usually installs the same software as previously loaded. To make a clean install after a previous installation, search the /Windows/inf/ folder for all files containing the string jungo and delete them. Then reinstall and you will be prompted for new installation files. National Instruments LabVIEW The runtime LabVIEW installer must be downloaded to your computer and executed to install the LabVIEW Run-Time Engine which is required by all AzCam LabVIEW code such as AzCamTool. Administrator privileges may be required for installation.

LabVIEW installers should be obtained directly from National Instruments (http://www.ni.com).

AzCam currently uses LabVIEW 2011.

Configuration

AzCam must be configured to operate specific controller, instrument, telescope, and detector hardware. Because of the complex nature of the system, the configuration options can be confusing. Below is description of the necessary configuration steps. The startup sequence for AzCam is fairly complex due to the many different configurations which use it. We list here the general order of startup events as they may be useful for site customization.

1. AzCam is started by the StartAzCam.py file, typically found in /AzCam/systems/xxx. This file specifies an IPython profile, usually ipy_profile_AzCam.py. This file may also start multiple instances of AzCam as well as specific options such as site location. 2. In the SystemFolder is an optional SiteConfiguration.py file, which can be edited to define the SystemModule and any other customizations for your particular installation. If multiple instances of AzCam are used on one machine, it is best to specify the different SystemModules in the IPython profiles. Typically the same SiteConfiguration file is used for multiple camera systems. The SiteConfiguration file could be edited to indicate if the GUI should be started, where the ControllerServer is located, which user commands might be loaded, and any other customization. 3. After the (optional) SiteConfiguration file is loaded, then the SystemModule is loaded. This file defines the system hardware and most parameters. It must be configured for every system. It may be located in a different folder. It is found by using either an absolute pathname or is assumed to be in the current search path. 4. Next user commands are loaded. Which commands are loaded by is specified by the Globals.UserCommands list which can be defined in SiteConfiguration or a SystemModule. Most commands are loaded by default. 5. Next saved parameters are loaded which overwrite any default values. These are specified in the SavedParametersFile in SystemFolder, and are saved at the end of each AzCam session. The default filename is AzCamSavedParameters.ini. 6. One or more GUI’s may be started in the SystemModule or SiteConfiguration modules. As can be seen, when AzCam starts it loads (or imports) many files. The SystemFolder is the starting or parent folder from which AzCam searches for configuration information, such as SystemModules and configuration files. All subfolders of SystemFolder are added to the search path. Watch out for multiple file with the same name in the search folder structure. A special case is the prompt mode specified by SystemModule='prompt' in the SiteConfiguration file. In this mode AzCam will prompt for the SystemModule name. This is useful when the SystemModule is changed often. The specified SystemModule is saved as the prompt for the next time AzCam is started in prompt mode.

AzCam reserves ten socket ports for each process. The ports are used for the various server functions and may not actually be all used on a computer. The ports are referenced to the CommandServer port for each AzCam process. Only this port needs to be specified. The default is 2402 for the first AzCam process, 2412 for the second process, 2422 for the third, etc. The table below shows the port usage for a default system. All ports may be overridden in specific cases. Note that more complex systems often have additional associated ports, such as for the instrument server, telescope server, web server, etc.

Name Relative Port Process 1 Port CommandServerPort 0 2402 MonitorServerPort CommandServerPort + 1 2403 DataServerPort CommandServerPort + 2 2404 ControllerServerPort CommandServerPort + 3 2405 Reserved CommandServerPort + 4 2406 Reserved CommandServerPort + 5 2407 Reserved CommandServerPort + 6 2408 Reserved CommandServerPort + 7 2409 Reserved CommandServerPort + 8 2410 Reserved CommandServerPort + 9 2411

  Notes

  • Preparing a Windows PC for mountain guider operation
  • Install all updates
  • Make sure MS license is valid
  • Turn OFF automatic updates
  • Install all Python code from software/python
  • Add \python26 to environmental variable PATH
  • Install drivers
  • Install ControllerServer
  • Install AzCam
  • Set to auto login as azcam (pw XXX)
  • administrator account should have pw YYY
  • install UltrvNC (pw YYY)

Manual

See the Azcam Reference Manual in Files for AzCamServer information. It is intended for advanced AzCam users.

AzCamSupport Programs

There are installers for most AzCam support programs. Which programs should be installed depends on the specific system installation requirements. We recommend first removing versions which are to be updated by removing their folder. The run the appropriate installer.

See the LabView topic for information relating to the LabVIEW infrastructure required by AzCamTool and other graphical programs.

The following support programs may also be useful when operating AzCam.

  • EngineeringTool performs very low level (and dangerous!) controller functions.
  • AzamImageWriter is a stand-alone python image server which can receive images on a remote machine. This is especially useful for receiving images on computer running Linux (Python required).
  • Ds9Tools is a set of tools useful when using SAO’s Ds9 display program

Architecture

This sketch shows the overall architecture of AzCam in its most common configuration.