azcam.h File Reference

AzCam Client API Header. More...

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#include <sys/time.h>
#include <sys/times.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/file.h>
#include <netdb.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <time.h>
#include <termios.h>
#include <fcntl.h>
#include <signal.h>
#include <math.h>

Go to the source code of this file.

Defines
#define	SH_OPEN   1
	Shutter is open.
#define	SH_CLOSED   0
	Shutter is closed.
#define	IDLE   0
	Server is idle and awaiting commands.
#define	READOUT   1
	Server is busy reading out the detector.
#define	EXPOSING   2
	Server is busy exposing (integrating) the detector.
#define	PAUSE   3
	Server is busy with a paused exposure.
#define	DT670   0
	Temperature sensor is a DT670 diode.
#define	AD590   1
	Temperature sensor is an AD590 IC temperature transducer.
#define	N914   3
	Temperature sensor is a 1N914 diode (weirdness of C, doesn't allow a #def to begin with a number).
#define	DARK_IMAGE   0
	Dark image, keep shutter closed during integration.
#define	LIGHT_IMAGE   1
	Light image, open shutter during integration.
#define	TDI   2
	TDI mode, shutter open during readout (unsupported, for future expansion).
#define	EXP_NOWAIT   0
	Do not wait for exposure to complete, return immediately from StartExposure.
#define	EXP_WAIT   1
	Wait for exposure to complete before returning status from StartExposure.
#define	IMMEDIATE   0
	Readout occurs immediately after integration.
#define	DEFERRED   1
	Readout is deferred until explicit readout request.
#define	STDFITS   1
	Write image as Standard FITS format.
#define	BINARY   2
	Write image as raw Binary format.
#define	EXTFITS   3
	Write image as Extended FITS (MEF) format.
#define	GUIDER_CLIENT   1
	[Open] a persistent guider client socket
#define	GUIDER_CLOSE   2
	Close a guider client socket.
#define	MESSAGE_CLIENT   3
	[Open] a persistent message client socket
#define	MESSAGE_CLOSE   4
	Close a message client socket.
#define	DISPLAY_CLIENT   5
	Set hostname/port of a display client socket.
#define	FILE_CLIENT   6
	Set hostname/port of a file client socket.
#define	SINGLE_AMP   0
	Single-amplifier readout mode.
#define	TWO_AMP_PARALLEL   1
	2-amplifier, split parallels, diagonally opposed corners readout
#define	TWO_AMP_SERIAL   2
	2-amplifier, split serials
#define	FOUR_AMP_QUAD   3
	4-amplifier, quad radout
#define	MOSAIC   6
	Multi-detector mosaic.
#define	NO_SPLIT   0
	Detector has no split registers.
#define	SPLIT_SERIAL   1
	Detector has split serial registers (2-amp readout).
#define	SPLIT_PARALLEL   2
	Detector has split parallel registers (2-amp readout).
#define	SPLIT_QUAD   3
	Detector has split parallel and serial registers (4-amp readout).
Typedefs
typedef azcam	azcam_t
	AzCam Server Parameter Table.
Functions
int	OpenAzCam (azcam_t *, char *)
	Open a TCP socket connection to an AzCamServer.
void	CloseAzCam (azcam_t *)
	Terminate an AzCam client session and close the server socket.
int	WriteAzCam (azcam_t *, char *)
	Write data to an AzCam server TCP socket.
int	ReadAzCam (azcam_t *, char *)
	Read data from an AzCam server TCP socket.
int	AzCamCommand (azcam_t *, char *, char *)
	Send a command to the AzCam server and await a reply.
int	CloseConnection (azcam_t *, char *)
	Close the AzCam Server Connection.
int	RunScript (azcam_t *, char *, char *)
	Execute an AzCam command script on the server.
int	SetParameter (azcam_t *, char *, char *, char *, char *)
	Set a FITS card in the AzCam server's header database.
int	GetParameter (azcam_t *, char *, char *, char *)
	Get the value of a FITS card in the AzCam server's header database.
int	ClearParameter (azcam_t *, char *)
	Clear the AzCam server's FITS header database.
int	SetSocket (azcam_t *, int, char *, int, char *)
	Open/Close socket connections to various AzCam server clients.
int	WriteImage (azcam_t *, char *, char *)
	Write an image from memory to disk.
int	SendImage (azcam_t *, int, char *, int, char *)
	Send the image in memory to the named client.
int	ClearArray (azcam_t *, char *)
	Clear (erase) the detector array.
int	StartExposure (azcam_t *, int, char *)
	Start an exposure (integration).
int	SetExposure (azcam_t *, float, char *)
	Set the exposure (integration) time.
int	ReadExposure (azcam_t *, char *)
	Query the AzCam server for the current elapsed exposure time.
int	AbortExposure (azcam_t *, char *)
	Abort an exposure in progress.
int	PauseExposure (azcam_t *, char *)
	Pause an exposure in progress.
int	ResumeExposure (azcam_t *, char *)
	Resume a paused exposure.
int	SetFormat (azcam_t *, char *)
	Define the detector format in unbinned pixels.
int	SetConfiguration (azcam_t *, char *)
	Define the detector readout configuration.
int	SetROI (azcam_t *, char *)
	Define the detector region of interest for the next readout.
int	OpenShutter (azcam_t *, char *)
	Open the Shutter.
int	CloseShutter (azcam_t *, char *)
	Close the Shutter.
int	RowShift (azcam_t *, int, char *)
	Shift the image on the array by a given number of rows.
int	GetDetPars (azcam_t *, char *)
	Query the AzCam server for the current image size.
int	GetPixelCount (azcam_t *, char *)
	Query the AzCam server for the number of pixels readout.
int	SetShutterMode (azcam_t *, int, char *)
	Set the shutter mode.
int	SetReadoutMode (azcam_t *, int, char *)
	Set the detector readout mode.
int	GetTemp (azcam_t *, char *)
	Get the Detector and Dewar temperatures.
int	SetTemp (azcam_t *, float, char *)
	Set the CCD temperature set point.
int	SetTempCal (azcam_t *, int, int, int, char *)
	Set the calibration curves used for each temperature sensor.
void	InitAzCam (azcam_t *)
	Initialize an azcam data structure.
void	AzCamInfo (azcam_t *)
	Print the contents of the struct on stdout.
int	ARCCommand (azcam_t *, char *, char *)
	Send a raw command to the ARC Controller.

---

Detailed Description

AzCam Client API Header.

Author:

R. Pogge, OSU Astronomy Dept. (pogge@astronomy.ohio-state.edu)

Date:

2005 May 5

Modification History:

  2005 May 17 - updated and cleaned up Doxygen hooks [rwp/osu]

---

Define Documentation

#define SH_OPEN   1

Shutter is open.

#define SH_CLOSED   0

Shutter is closed.

#define IDLE   0

Server is idle and awaiting commands.

#define READOUT   1

Server is busy reading out the detector.

#define EXPOSING   2

Server is busy exposing (integrating) the detector.

#define PAUSE   3

Server is busy with a paused exposure.

#define DT670   0

Temperature sensor is a DT670 diode.

#define AD590   1

Temperature sensor is an AD590 IC temperature transducer.

#define N914   3

Temperature sensor is a 1N914 diode (weirdness of C, doesn't allow a #def to begin with a number).

#define DARK_IMAGE   0

Dark image, keep shutter closed during integration.

#define LIGHT_IMAGE   1

Light image, open shutter during integration.

#define TDI   2

TDI mode, shutter open during readout (unsupported, for future expansion).

#define EXP_NOWAIT   0

Do not wait for exposure to complete, return immediately from StartExposure.

#define EXP_WAIT   1

Wait for exposure to complete before returning status from StartExposure.

#define IMMEDIATE   0

Readout occurs immediately after integration.

#define DEFERRED   1

Readout is deferred until explicit readout request.

#define STDFITS   1

Write image as Standard FITS format.

#define BINARY   2

Write image as raw Binary format.

#define EXTFITS   3

Write image as Extended FITS (MEF) format.

#define GUIDER_CLIENT   1

[Open] a persistent guider client socket

#define GUIDER_CLOSE   2

Close a guider client socket.

#define MESSAGE_CLIENT   3

[Open] a persistent message client socket

#define MESSAGE_CLOSE   4

Close a message client socket.

#define DISPLAY_CLIENT   5

Set hostname/port of a display client socket.

#define FILE_CLIENT   6

Set hostname/port of a file client socket.

#define SINGLE_AMP   0

Single-amplifier readout mode.

#define TWO_AMP_PARALLEL   1

2-amplifier, split parallels, diagonally opposed corners readout

#define TWO_AMP_SERIAL   2

2-amplifier, split serials

#define FOUR_AMP_QUAD   3

4-amplifier, quad radout

#define MOSAIC   6

Multi-detector mosaic.

#define NO_SPLIT   0

Detector has no split registers.

#define SPLIT_SERIAL   1

Detector has split serial registers (2-amp readout).

#define SPLIT_PARALLEL   2

Detector has split parallel registers (2-amp readout).

#define SPLIT_QUAD   3

Detector has split parallel and serial registers (4-amp readout).

---

Typedef Documentation

typedef struct azcam azcam_t

AzCam Server Parameter Table. Contains basic information about the AzCam server configuration we're using. It starts simple and will become more complex as required.

---

Function Documentation

int OpenAzCam (  azcam_t *  cam, char *  reply )

Open a TCP socket connection to an AzCamServer. Parameters: cam  pointer to an azcam struct with the AzCam server parameters reply  string to carry any messages from the open process Returns: File descriptor of the open comm port connection, or -1 if an error, with any error message text in reply. Performs the necessary initialization functions to open a TCP socket connection to an AzCam server. To use, you must fill in the relevant data members of the azcam struct. The cam->Host and cam->Port members are used to define the server TCP address. For socket communications we use INET streams (SOCK_STREAM) with a persistent client connection. See also: CloseAzCam()

void CloseAzCam (  azcam_t *  cam  )

Terminate an AzCam client session and close the server socket. Parameters: cam  pointer to an azcam struct with the AzCam server parameters (see OpenAzCam()) Sends the "CloseConnection" command to the AzCam server and closes the client TCP socket. See also: OpenAzCam().

int WriteAzCam (  azcam_t *  cam, char *  cmdstr )

Write data to an AzCam server TCP socket. Parameters: cam  pointer to an azcam struct with the AzCam server parameters cmdstr  message string to write Returns: Number of bytes written if successful, 0 or -1 if unsuccessful. Writes the message string provided to the AzCam server described by the cam struct. An AzCam client session must have been previously initiated using the OpenAzCam() function. On errors, it returns an error message in cmdstr. See also: ReadAzCam()

int ReadAzCam (  azcam_t *  cam, char *  msgstr )

Read data from an AzCam server TCP socket. Parameters: cam  Pointer to an azcam struct with the AzCam server parameters msgstr  Message string to carry the input string Returns: The number of characters read, or <0 if an error. -1 on error or timeout, with msgstr containing the error message text. Uses select() to read data from the specified comm port with the timeout interval specified. Note that because TCP sockets are streams rather than line-buffered, the data can arive in bursts depending on the system state and the degree of stream synchronization. As such we read in chunks of data w/o blocking until we have read everything from the port, which means looking for the \r (ASCII 13 = Ctrl+M) or \n terminator. This makes the logic tricky, but robust against most comm glitches. Use of a timeout allows us to break out of cases where the message is unterminated because of a comm fault, not because of the usual stream buffering/sync issues. Note: If select() is interrupted by Ctrl+C, it returns an error message in the reply string.

int AzCamCommand (  azcam_t *  cam, char *  cmdstr, char *  reply )

Send a command to the AzCam server and await a reply. Parameters: cam  pointer to an azcam struct with the AzCam server parameters cmdstr  command to send reply  string returned by the AzCam server Returns: Number of bytes written if successful, 0 or -1 if unsuccessful. Sends a command to the AzCam server and waits for a reply up to a specified timeout interval (defined by #azcam::timeout). On reply, the message is parsed into components. A successful command receives a reply prefixed by "OK" followed (most times) by a message string with information (e.g., the parameters requested). Errors are prefixed by "ERROR", followed by error message text. This routine does no processing of the return reply, but instead packages it as a string (with the OK/ERROR tag removed) for further handling by the calling routine. See also: WriteAzCam(), ReadAzCam()

int CloseConnection (  azcam_t *  cam, char *  reply )

Close the AzCam Server Connection. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 on success, -1 on failure. reply contains an error messages. Transmits a CloseConnection command to an open AzCam server and closes the client-side socket, resetting the file descriptor to the "no connection" state (azcam::FD=-1).

int RunScript (  azcam_t *  cam, char *  script, char *  reply )

Execute an AzCam command script on the server. Parameters: cam  pointer to an azcam struct with the server parameters script  string with the full filename of the command script reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to run a script on the server proper. Note that the script file must be on a valid path as seen by the server, not the client. This is most often used to execute large blocks of AzCam server commands from files resident on the server proper (e.g., the standard startup commands to configure a particular camera).

int SetParameter (  azcam_t *  cam, char *  keyword, char *  value, char *  comment, char *  reply )

Set a FITS card in the AzCam server's header database. Parameters: cam  pointer to an azcam struct with the server parameters keyword  string with the FITS keyword to set value  string with the data value associated with the keyword comment  string describing the keyword reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Uploads a new FITS header parameter into the AzCam server's FITS header database using the SetParameter command. This feature of AzCam is somewhat inflexible in that all parameters are treated as string type FITS header keywords. A sensible AzCam client application will employ a postprocessing routine to launder the non-standard FITS headers coming from the AzCam server into more conventional form. See also: ClearParameter(), GetParameter()

int GetParameter (  azcam_t *  cam, char *  keyword, char *  value, char *  reply )

Get the value of a FITS card in the AzCam server's header database. Parameters: cam  pointer to an azcam struct with the server parameters. keyword  string with the keyword to retrieve value  string with the keyword value reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Gets the value of a FITS header keyword from the AzCam server's FITS header database, putting the result into the value string. This function only returns the current keyword value, not the text of the comment associated with the keyword. Unknown keywords generate an error. Note that the AzCam server stores all user-defined header parameters as strings. The calling application will need to translate that string into the appropriate data type (int, float, boolean, or string) as required. See also: SetParameter(), ClearParameter()

int ClearParameter (  azcam_t *  cam, char *  reply )

Clear the AzCam server's FITS header database. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text. Returns: 0 if successful, -1 on errors, with error text in reply Clears all parameters from the AzCam server's FITS header keyword database. Sends the "SetParameter CLEARALL" command to the server. See also: SetHeader(), GetParameter()

int SetSocket (  azcam_t *  cam, int  client, char *  host, int  port, char *  reply )

Open/Close socket connections to various AzCam server clients. Parameters: cam  pointer to an azcam struct with the server parameters client  client code, one of (GUIDER_CLIENT, GUIDER_CLOSE, MESSAGE_CLIENT, MESSAGE_CLOSE, DISPLAY_CLIENT, FILE_CLIENT). host  string with the hostname of the target client port  port number of the target client reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to open a client connection socket to one of a set of possible remote clients. For Guider and Message clients, there are also options to close that client socket. Those clients designed to handle image data are sent image data using the SendImage() function. Supported client codes are: GUIDER_CLIENT - opens a connection to an autoguider client GUIDER_CLOSE - closes a connection to an autoguider client MESSAGE_CLIENT - opens a connection to a message client (sees all status messages) MESSAGE_CLOSE - closes a connection to a messge client DISPLAY_CLIENT - defines a display client (SendImage() will open/close socket) FILE_CLIENT - defines a file handler client (SendImage() will open/close socket) There are two classes of clients at work: persistent clients whose socket connections are opened or closed by this function (Guider and Message clients), and non-persistent clients that are opened/closed by the SendImage() function. See also: SendImage()

int WriteImage (  azcam_t *  cam, char *  filename, char *  reply )

Write an image from memory to disk. Parameters: cam  pointer to an azcam struct with the server parameters filename  full path and name of the file to create. reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Writes the contents of the AzCam server's internal image buffer to a disk file. This function is issued after readout has finished. If the image is a multi-detector mosaic, the format code is ignored and the image is written as a multi-extension FITS (MEF) format image (same as format=EXTFITS) as indicated by the azcam::FileFormat value. The filename provided must be the full name of the file including all counters, paths, etc. The calling application is responsible for building a full valid filename; this function cannot do validation. The path must be a valid file path on the AzCam server proper. On successful completion, this function sets the azcam::LastFile datum to tell the calling application the name of the file just written. It does not, however advance file counters. That is the responsibility of the calling application (since counters are optional).

int SendImage (  azcam_t *  cam, int  client, char *  host, int  port, char *  reply )

Send the image in memory to the named client. Parameters: cam  pointer to an azcam struct with the server parameters client  client type, one of DISPLAY_CLIENT, FILE_CLIENT, or GUIDER_CLIENT. host  hostname of the target client port  port number of the target client reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sends the current image in memory to the specified client. If client is DISPLAY_CLIENT, the AzCam server opens the client socket, sends the data, then closes the client socket. If client is FILE_CLIENT, the AzCam server opens the client socket, sends the complete image (header+data), then closes the client socket. If client is GUIDER_CLIENT, the AzCam server sends the image data to the client. The AzCam server does not first open the guider client, this must be done with a previous call to SetSocket().

int ClearArray (  azcam_t *  cam, char *  reply )

Clear (erase) the detector array. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Erases the detector array preparatory to starting an integration.

int StartExposure (  azcam_t *  cam, int  wait, char *  reply )

Start an exposure (integration). Parameters: cam  pointer to an azcam struct with the server parameters wait  sets whether the AzCam server waits until the exposure, is complete before replying. One of EXP_NOWAIT or EXP_WAIT. reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Starts an exposure on the detector of the current exposure time (see SetExposure()). The array is not erased first, this must be done explicitly using ClearArray(). If wait=EXP_WAIT, the AzCam server will not return status until the integration is completed. This is usually only done for zero-length (ZERO or BIAS) images, or very short integrations where the application decides not to poll the exposure progress using ReadExposure() calls. If wait=EXP_NOWAIT, the AzCam server will return status immediately after starting the integration. Integration progress can be monitored using the ReadExposure() function. IMPORTANT: if wait=EXP_WAIT, the timeout interval for the AzCam server communications (azcam::Timeout) must be set long enough as as to not timeout before the integration is complete. To ensure that this does not happen, we store the current default timeout, compute a new timeout of the exposure time + 10 seconds, and then make the call, resetting the default timeout after completion (or error). The exposure time used is the value in the azcam::ExpTime data member. See also: SetExposure()

int SetExposure (  azcam_t *  cam, float  exptime, char *  reply )

Set the exposure (integration) time. Parameters: cam  pointer to an azcam struct with the server parameters exptime  exposure time in decimal seconds reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the exposure time for subsequent integrations. The user provides the exposure time in seconds and this function converts it to milliseconds for the AzCamServer. This function also sets the value of the azcam::ExpTime data member.

int ReadExposure (  azcam_t *  cam, char *  reply )

Query the AzCam server for the current elapsed exposure time. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: elapsed exposure time in milliseconds, or -1 if errors, with error text in reply Query the AzCam server and return the elapsed exposure (integration) time in milliseconds. Note In some AzCam server implementions (i.e., every one we've encountered or heard about so far), if you send a ReadExposure command to the AzCam server while a readout is in progress, the server will crash after readout is done, rebooting the machine (meaning total system crash). We avoid this by not allowing the user to send this directive during readout by checking the value of the azcam::State data member.

int AbortExposure (  azcam_t *  cam, char *  reply )

Abort an exposure in progress. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues an AbortExposure command to the AzCam server and sets the API's ABORT flag (kept in the azcam::Abort data member). It also sets the server state flag to IDLE (azcam::State data member). Because of some odd hardware interactions that we have observed, an AbortExposure() command must be preceeded by PauseExposure(). We do not know if this is generic to all ARC controllers or just the ones we're working with at OSU. Applications calling this API should call AbortExposure() with some circumspection.

int PauseExposure (  azcam_t *  cam, char *  reply )

Pause an exposure in progress. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues a PauseExposure command to the AzCam server. Sets the azcam::State flag to PAUSE on success. If it fails, the azcam::State flag is left unchanged. A PauseExposure should be followed by either AbortExposure() or ResumeExposure(). We test the value of the azcam::State flag and only send a PauseExposure command if EXPOSING. Sending a PauseExposure directive otherwise may be unpredictable. See also: AbortExposure(), ResumeExposure()

int ResumeExposure (  azcam_t *  cam, char *  reply )

Resume a paused exposure. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Issues a ResumeExposure command to the AzCam server. Sets the azcam::State flag to EXPOSING on success. If it fails, the azcam::State flag is left unchanged. Does not send ResumeExposure if the controller is not in a PAUSE state. If you send a ResumeExposure() command when the AzCam server is not actually in a paused state, very bad things can happen (e.g., it crashes and reboots its host computer). See also: PauseExposure()

int SetFormat (  azcam_t *  cam, char *  reply )

Define the detector format in unbinned pixels. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Defines the detector format in unbinned pixels. Since this function is very complicated and important, involving 9 parameters, we do this by using the relevant data members of the azcam struct to define the parameters, rather than having a lot of function arguments. The relevant data members are: azcam::NCtotal - Total number of columns (serial pixels) azcam::NCpredark - Number of physical dark prescan columns azcam::NCunderscan - Number of underscan columns to read azcam::NCoverscan - Number of overscan columns to read azcam::NRtotal - Total number of rows (lines) azcam::NRpredark - Number of physical dark prescan rows azcam::NRunderscan - Number of underscan rows to read azcam::NRoverscan - Number of overscan rows to read azcam::NRframexfer - Number of rows to shift for frame transfer mode A calling application would first set the various parameters in the azcam struct and then call this function to send them to the AzCam server. See also: SetROI(), SetConfiguration()

int SetConfiguration (  azcam_t *  cam, char *  reply )

Define the detector readout configuration. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Defines the readout configuration of the camera. Since this function is complicated and important, involving 5+ parameters, we do this by using the relevant data members of the azcam struct to define the parameters, rather than having a lot of function arguments. The relevant data members are: azcam::ReadMode - Readout Mode, one of SINGLE_AMP, TWO_AMP_PARALLEL, TWO_AMP_SERIAL, FOUR_AMP_QUAD, or MOSAIC azcam::Splits - Split register flag, one of NO_SPLIT, SPLIT_SERIAL, SPLIT_PARALLEL, or SPLIT_QUAD azcam::NumDetX - Number of X (columns) direction detectors in a multi-detector mosaic azcam::NumDetY - Number of Y (rows) direction detectors in a multi-detector mosaic azcam::AmpConfig - Amplifier configuration string, one parameter per amp, 0=no flip, 1=flip cols, 2=flip rows, 3=flip both A calling application would first set the various parameters in the azcam struct and then call this function to send them to the AzCam server. Note, if the ReadMode is changed, you must call SetROI immediately after, or bad things will happen. See also: SetROI(), SetFormat()

int SetROI (  azcam_t *  cam, char *  reply )

Define the detector region of interest for the next readout. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the region of interest for the next detector readout in units of unbinned pixels. Since this is complicated and would involve a lot of arguments, we set this by using the relevant data members of the azcam struct to define the parameters: azcam::FirstCol - first column to read in unbinned pixels azcam::LastCol - last column to read in unbinned pixels azcam::ColBin - column-axis binning factor azcam::FirstRow - first row to read in unbinned pixels azcam::LastRow - last row to read in unbinned pixels azcam::RowBin - row-axis binning factor Note that regions of interest that are smaller than the physical size of the device in unbinned pixels are only supported for single-amplifier readout modes.

int OpenShutter (  azcam_t *  cam, char *  reply )

Open the Shutter. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to open the shutter. See also: CloseShutter()

int CloseShutter (  azcam_t *  cam, char *  reply )

Close the Shutter. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Instructs the AzCam server to close the shutter. See also: OpenShutter()

int RowShift (  azcam_t *  cam, int  nrows, char *  reply )

Shift the image on the array by a given number of rows. Parameters: cam  pointer to an azcam struct with the server parameters nrows  number of rows to shift reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Shift charges on the CCD vertically by nrows, moving the image "up" towards the readout register if positive, "down" away from the readout register if negative. We allow nrows=0 as a way to take repeated images without row shifts (commonly done for shutter shading correction images). If nrows=0, it returns success rather than sending "ParShift 0" to the server. This function implements the ParShift server command. We elected to call it RowShift since that syntax is closer to what we do in other OSU instruments (ParShift stands for "PARallel SHIFT": the ITL folks use "Parallel" and "Serial" the same way OSU folks use "Vertical" and "Horizontal").

int GetDetPars (  azcam_t *  cam, char *  reply )

Query the AzCam server for the current image size. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: the total number of pixels in the image if successful, -1 if errors. Queries the AzCam server for the current total image size in pixels (including effects of binning, overscan regions, etc). It also sets the azcam::Ncols, azcam::Nrows, and azcam::Npixels data members in the cam struct for the convenience of the calling application.

int GetPixelCount (  azcam_t *  cam, char *  reply )

Query the AzCam server for the number of pixels readout. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: Count of the number of pixels readout if successful, -1 on errors, with error text in reply Queries the AzCam server and returns the number of pixels readout from the detector array. Repeated calls to GetPixelCount() are often used by applications to monitor readout progress. When the array is finished reading out, the pixel count returned should equal the total pixel size returned by GetDetPars(). After each call to GetPixelCount(), it stores the current number of pixels read in azcam::Nread. Note that unlike ReadExposure(), experiments have so far shown that calling GetPixelCount() is benign in all circumstances. See also: GetDetPars()

int SetShutterMode (  azcam_t *  cam, int  mode, char *  reply )

Set the shutter mode. Parameters: cam  pointer to an azcam struct with the server parameters mode  shutter mode, one of DARK_IMAGE, LIGHT_IMAGE, TDI reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the shutter mode to be used during subsequent exposures. The options are: DARK_IMAGE: shutter kept closed during integration LIGHT_IMAGE: shutter is opened during integration TDI: shutter open during readout (currently unsupported) Shutter mode settings stay in force for the rest of the AzCam session unless changed. This function implements the "SetMode 1 X" server command. See also: SetReadoutMode()

int SetReadoutMode (  azcam_t *  cam, int  mode, char *  reply )

Set the detector readout mode. Parameters: cam  pointer to an azcam struct with the server parameters mode  detector readout mode, one of IMMEDIATE or DEFERRED reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the readout behavior for exposures. There are two options: IMMEDIATE: readout is initiated immediately after integration DEFERRED: readout is deferred until an explicit readout is requested IMMEDIATE mode should be used for all normal exposures, whereas DEFERRED is used for custom multiple exposures like focus plates, nod-and-shuffle, shutter shading calibrations, etc. This function implements the "SetMode 2 X" server command, where we have introduced the "immediate" and "deferred" mode names. See also: SetShutterMode()

int GetTemp (  azcam_t *  cam, char *  reply )

Get the Detector and Dewar temperatures. Parameters: cam  pointer to an azcam struct with the server parameters reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply. Temperature values are in azcam::CCDTemp and azcam::DewarTemp. Queries the AzCam server and readout out the detector and dewar temperatures in degrees C, storing the results in the azcam::CCDTemp and azcam::DewarTemp data members. See also: SetTemp(), SetTempCal()

int SetTemp (  azcam_t *  cam, float  temp, char *  reply )

Set the CCD temperature set point. Parameters: cam  pointer to an azcam struct with the server parameters temp  CCD detector set point in degrees Celsius reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the target detector temperature setpoint in degrees C. Temperatures may be given to the nearest 0.1C. The new setpoint temperature is stored in azcam::SetPoint data member for use by the application. SetTemp implements the SetTemperature server command. The name was shortened to match the syntax of the related GetTemp and SetTempCal server commands. See also: GetTemp(), SetTempCal()

int SetTempCal (  azcam_t *  cam, int  diode, int  detector, int  dewar, char *  reply )

Set the calibration curves used for each temperature sensor. Parameters: cam  pointer to an azcam struct with the server parameters diode  sensor type of the diode detector  sensor type of the detector temperature sensor dewar  sensor type of the dewar temperature reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sets the calibration curves to be used by each of the temperature sensors monitored by the AzCam server. There are three types of temperature calibration curves available, depending on the type of sensor used: DT670 - DT670 diode AD590 - AD590 sensor N914 - 1N914 diode Note that there is an oddity about C in that parameters defined as "macros" with #define statements apparently cannot begin with numbers, which is why for the 1N914 diode we use N914 not 1N914 as the value passed to the subroutine. Go figure. See also: GetTemp(), SetTemp()

void InitAzCam (  azcam_t *  cam  )

Initialize an azcam data structure. Parameters: cam  pointer to an azcam struct with the server parameters Initialize the azcam data structure to default values. Many detector values take 0, which means "I don't know" to other routines in this API. This function should be called to clear out the azcam struct before filling it with valid data (e.g., from a setup file loaded by the application).

void AzCamInfo (  azcam_t *  cam  )

Print the contents of the struct on stdout. Parameters: cam  pointer to an azcam struct with the server parameters Prints the contents of the azcam struct on stdout in human-readable form.

int ARCCommand (  azcam_t *  cam, char *  cmdstr, char *  reply )

Send a raw command to the ARC Controller. Parameters: cam  pointer to an azcam struct with the server parameters cmdstr  command string to send reply  string to contain any reply text Returns: 0 if successful, -1 on errors, with error text in reply Sends a raw ARC Controller command to the AzCam server. Command strings are sent as-is with no validation, so if there is a syntax error on the server side, this function will report an error back to the calling application. A complete list of valid ARC Controller commands can be found in section 11 of the AzCam Programmers Reference Manual.

---