AzCamServer and Reference Manual

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

See the sphinx documentation links of the AzCam home page for programming information.


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”. Most source code modules have a “last update” date near at the top the file.


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). 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 can be imported into modules in the standard pythonic manner, such as from azcam.api import *.

Alias Commands

Alias commands are a special syntax available with IPython (using the auto-parenthesis mode) which do not use the standard Python syntax of command(par1, par2, …). The equivalent magic syntax is command par1 pars …. Alias commands are optionally defined for a system for user convenience.

Command “alias” commands available are:

  • sav to save the current AzCam state
  • p to TOGGLE AzCamLog output to the command line window


Scripts are Python files (modules) which are intended to be run at the command line. Scripts should be written in pure Python. There are many modules which may define the various AzCam commands and the appropriate modules may need to be imported into a script before they can be used. Most scripts typically include the lines: from azcam.commands import * and from azcam.api import * in order to include the base AzCam commands. Objects need to be defined manually, usually with a command like exposure=get_object('exposure').

After these definitions, normal AzCam commands are available such as: exposure.expose() or controller.reset(). 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. Scripts must be in the Python search path and are usually executed using the Run command, as Run get_temps. This method has the advantage of reloading the script each time the run command is called which is useful when debugging a script. When arguments are supplied on the command line using Run they must be space delimited and not placed in parentheses. So
Run get_temps 0.2 'logfile1.txt'
is OK but
Run get_temps(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 though the plugin system. They can then be executed without the Run command (e.g. get_temps() rather than Run get_temps).


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(args) where object is the object name (such as controller, instrument, telescope) and command() is the command to be sent. If command() uses arguments, 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 initialize to the instrument, use instrument.initialize(). To send the get_focus command to the telescope, use telescope.get_focus().

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.get_all_keywords() and instrument.header.get_keyword('FILTER1'). The read_header() method of each object will actively read hardware to obtain information (such as controller.read_header() or instrument.read_header()). 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.


Parameters may be read with the get() command and written with the set() command. For example, get('imagetype') returns the current image type.

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.


The current version of AzCam requires Python version 3.6.x. See for all things python.


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:

You may need to add c:\python36 and/or c:\python36\Scripts to the Windows PATH environment variable,


ControllerServers are separate executable programs which manage all direct interaction with controller hardware. Communication with a ControllerServer 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. 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.

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 AzCam LabVIEW code (such as AzCamTool). Administrator privileges may be required for installation. LabVIEW installers should be obtained directly from National Instruments ( AzCam currently uses LabVIEW 2014.


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
  • WebServerPort CommandServerPort + 1 2403
  • InstrumentServerPort 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

AzCam Support Programs

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

  • AzCamTool - the main user GUI for takign data with 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


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