DESCRIPTION

spec supports the greateyes CCD Cameras via the spec server hardware facility, as described in spec server_hdw help file. A standalone server module from CSS must be linked with the API library provided by greateyes. The API library is only available on Linux. The server can connect to the camera via USB or ethernet interfaces.

This documentation describes the server code and macros supplied by CSS.

INSTALLATION

The spec distribution contains a subdirectory named servers that contains the greateyes-related files. All the source files that are needed to compile the server are included. The greateyes API library needs to be available to complete the build. The greateyes default installation places the library libgreateyes.so in /usr/local/lib. If the library is located elsewhere, make a symbolic link to that directory in the servers directory, and name it greateyes. The Makefile will look for the library there. The device-dependent server code is in the file greateyes_proto.c. The commands to compile and install the server are:

make greateyes_server
make install

By default, the server will be installed in SPECD/servers, where SPECD is the spec auxiliary file directory as set in the install_data file of the parent directory. The default value for SPECD is /usr/local/lib/spec.d.

The make install command will also place the greateyes.mac file in SPECD/macros. The command will install the greateyes help file as a standard spec help file, but requires the Python docutils package to succeed.

CONFIGURATION

Configure the server-hardware image device along these lines on the Acquisition screen of the configuration editor:

MCA (1D) and Image (2D) Acquisition Device Configuration

Image            DEVICE  ADDR  <>MODE              <>TYPE
 0  YES  localhost:5000               Server Image Device

The DEVICE field contains the resolvable hostname or IP address of where the server is running, followed by the port number. The ADDR field isn't used.

Additional parameters are set on the optional parameter screen reached by typing p. Enter both the parameter names and values along the following lines:

Custom Parameters for Image 0 "Server Image Device"     2/2 configured

NAME                      VALUE
command                   greateyes_server
args                      -v 2

The command parameter is required. The args parameter contains options to the server. In the example above, the verbosity level for the log file is set to the moderate level of 2.

In addition to the options recognized by the standard server module as described in the server_hdw help file, these additional command-line options are available:

-C

Turns off "safe FIFO mode". The server has it on by default. When in safe FIFO mode a ClearFifo() is done before each StartMeasurement() or TemperatureControl_GetTemperature() function. The calls add about 50 milliseconds of overhead to a measurement. If turned off, reading the data is faster, but in some cases can cause errors, according to the greateyes documentation.

-a IP

If using the ethernet interface rather than the USB interfaces, sets the IP address for the camera server with the specified MAC address. Syntax is as follows:

greateyes_server -a 192.168.1.3

-T cooling_hardware

Set the cooling hardware code as supplied in the Temperature-Hardware-Option.txt from the vendor. A default value of 42223 will be used if the argument is missing.

Note, as stated in the server_hdw help file, spec automatically includes the -d (daemonize) and -p port (port) arguments when it starts the server.

If the standard server -Q option is included, which causes the server to exit when spec exits, the camera temperature control will be disabled when spec quits.

A region-of-interest (ROI) pseudo counter can be configured on the Ddevices screen as follows:

Motor and Counter Device Configuration (Not CAMAC)
...
SCALERS        DEVICE   ADDR  <>MODE  NUM              <>TYPE U#
 1  YES        GE_roi      -            1       Macro Counter  0

Assign a counter on the Scaler screen with controller type MAC_CNT and matching unit number. This pseudo counter will contain a sum of the region-of-interest defined in the greateyes_setup or setroi macros.

USAGE

The greateyes server can run on the local host or on a remote host. If the server is properly configured, spec will start the server automatically. See the server_hdw help file for details on start-up options such as logging and lock files.

The supplied macros in greateyes.mac add a hook to the standard config_mac, which is called after reading the hardware configuration file to make sure the parameter values are in sync between spec and the server.

Note, though, it is not possible to completely synchronize the temperature control. It is possible to read the temperatures of the camera sensor and the thermoelectric cooler (TEC) backside, but it is not possible to read the current set point or whether the TEC is enabled. The server guesses at whether the TEC is enabled by comparing the readings from the sensor and the backside thermistors. If the values differ by more than 5 C, the server assumes it is enabled. The temperature setpoints are at 5 C intervals. The server guesses the current setpoint is the nearest value to the sensor reading.

Data can only be read once from the camera after an acquisition. However, the server keeps a copy of the most recent data, so that data can be retrieved again using image_get(). In addition, the image_par() "newData" option can be used to check if new data is available.

The server reverses the order of the rows in the data array to match spec convention where row zero is the top of the image.

MACROS

The following macros provide the basic user interface to the greateyes camera.

greateyes_setup

Presents an interactive menu for setting parameters for the camera.

greateyes_defaults

Called when the macro file is read when starting fresh or if the global variable GE_unit is unset. The macro uses cdef() to add the assignment GE_needs_sync to config_mac. Assigns reasonable values to the global variables.

If the server returns a nonzero value for the parameter lastMeasureTime, spec assumes the server has been configured with the wanted parameters and reads those values to synchronize spec with the server. If the global variables are unset, pec assigns default values to the parameters.

greateyes_config()

Added using cdef() to the built-in config_mac. The macro calls greateyes_defaults to synchronize parameters between spec and the server.

openGEshutter

Sets the shutter mode to manual and opens the shutter.

closeGEshutter

Sets the shutter mode to manual and closes the shutter.

autoGEshutter

Sets the shutter mode to automatic.

getGEdata

Reads the current image from the camera into the GE_image data array.

setroi

Sets the region of interest for the ROI pseudo counter. Can be invoked with four arguments that define the ROI, or will prompt for the values.

temp

Displays the current temperature and either takes arguments or prompts for a new temperature, or off to disable the temperature control.

video

Continually reads images. Optional arguments are the acquisition time and the sleep time between acquisitions. Type any key to quit. Useful if the GE_image shared data array is being displayed by another process.

GE_roi_cmd()

Implements the macro hardware ROI pseudo counter. The counter value is the sum of the array elements in the defined region of interest. If new data is available from the camera, reads that data into GE_image. Otherwise, uses the current contents of the GE_image data array.

SERVER MESSAGES

In addition to the standard messages described in the server_hdw help file, the greateyes_server recognizes the following message:

reconnect

Will close the existing connection to the camera and attempt to reconnect.

GET/SET SERVER PARAMETERS

The following parameters are accessible with the get messages. Those not marked read-only (ro) can also be set with set messages. For the most part, the parameters names are the same names as used in the greateyes API library calls. All strings are case insensitive. Any combination of lower/upper case letters is allowed.

modelString (ro)

Returns the camera model identifier as a string in the form "GE 1024 256 DD NIR".

tempLevels (ro)

Returns a string containing a space-separated list of the allowed temperature settings for the built-in temperature controller, similar to the following (abridged) string:

"-100 -95 -90 -85 [...] -10 -5 0 5 10 15 20"

Values are in degrees Celsius.

temp0 (ro)

Returns the measured temperature of the sensor in degrees Celsius or "?" if the reading failed.

temp1 (ro)

Returns the measured backside temperature in degrees Celsius or "?" if the reading failed.

temperature

Sets or returns the current temperature control set point. Units are degrees Celsius. Only values contained in the "tempLevels" string are allowed.

tempControl

Sets or returns a value indicating temperature control status. A nonzero argument enables temperature control. A zero turns it off.

shutterMode

Sets or returns a value indicating whether automatic or manual shutter mode is. A nonzero argument selects automatic mode. When enabled, the camera opens the shutter during an exposure, and closes it otherwise. The "openTime" and "closeTime" parameters affect the timing of the data acquisition sequence.

openTime

Sets or returns the shutter open-time parameter in milliseconds. The time is the delay between when the shutter is opened and the measurement starts.

closeTime

Sets or returns the shutter close-time parameter in milliseconds. The time is the delay between the end of measurement when the shutter is closed and the start of the readout.

shutterState

When in manual mode, sets or returns the state of the shutter. A nonzero argument indicates an open shutter.

shutterClose

Selects manual shutter mode and closes the shutter. No argument required.

shutterOpen

Selects manual shutter mode and opens the shutter. No argument required.

showSync

Selects or returns a value indicating whether the external sync output will be enabled during a measurement. A nonzero arguments enables the mode.

syncOutput

With a nonzero argument, sets the sync output high. A zero arguments sets the sync output low. With no arguments, returns the value last sent.

showShutter

Selects or returns a value indicating whether shutter control will be enabled during a measurement. An argument of zero disables the shutter.

triggerMode

Selects or returns a value indicating whether trigger mode is enabled. An argument of zero enables trigger mode. With trigger mode, an external signal is required to start a measurement.

triggerTimeOut

Selects or returns the trigger-timeout value. Units are milliseconds. When trigger mode is enabled, if no trigger arrives with in the timeout period, the measurement is ended with an error generated.

readoutSpeed

Selects or returns the settings of the pixel clock for readout. Possible values are 50e3, 500e3, 1e6 and 3e6 Hz. These values can be selected as given, or with the integers 1, 2, 3 and 4, respectively. A lower frequency reduces the readout noise and increases the image quality.

correctBias

Selects or returns a value indicating whether bias correction is enabled. greateyes says the camera sensor contains several dark pixels on either side outside of the active image area. Those pixels are not part of the image but will be used to compensate for small differences in the dark noise between the lines if this mode is enabled. greateyes recommends enabling.

gainSetting

Selects or returns the current gain setting. greateyes says, "Two settings are available in order to adjust the pre-amplification. Please select the setting Low (maximum dynamic range) in order to exploit the full pixel capacity which is fully mapped onto the dynamic range of the AD converter. Here, the sensor signal is not amplified prior to digital conversion, which is recommended when detecting strong signals. In contrast, you can select the setting Std (highest sensitivity) when detecting weak signals well below the full pixel capacity. In this mode, the signal is amplified using a gain value of about 1e-/count, which is particularly useful to map weak signals onto the full dynamic range of the AD converter. Please keep in mind that the noise is also amplified."

capacityMode

Selects or returns the capacity mode setting, only available on camera types GE 2048 512 and GE 2048 2048. A zero value indicates standard (low noise) mode. Nonzero is extended (high signal) mode.

lastMeasureTime (ro)

Returns the total elapsed time of the last measurement in seconds.

maxExposureTime (ro)

Returns the maximum length of time allowed for an exposure in seconds. A value of 420 is typical.

numPixelInX (ro)

Returns the number of pixels in X (columns) taking into account the current binning and crop mode settings.

numPixelInY (ro)

Returns the number of pixels in Y (rows) taking into account the current binning and crop mode settings.

cropMode

Sets or returns the current crop mode setting. When enabled, the sensor is read from the pixel (0, 0) up to the specified cropX and cropY values.

cropX

Sets or returns the current value for the crop region in X. Only available with some model cameras.

cropY

Sets or returns the current value for the crop region in Y.

binningX

Sets or returns the current binning value in X. Binning in X is disabled if the value is zero or 1. Only available with some model cameras.

binningY

Sets or returns the current binning value in X. Binning in Y is disabled if the value is zero or 1.

newData

Returns 1 if there is new data that hasn't been read.

GLOBAL VARIABLES

GE_unit

The unit number for image_par() calls.

GE_auto_run

spec parameter. If enabled, the camera will be started when counting. If not enabled, use image_par(GE_unit, "run") to start.

GE_preset

spec parameter. Default preset time for image_par(GE_unit, "run").

GE_soft_preset

spec parameter. If enabled, the camera will be programmed with the number of lines to match the count time. If not enabled, the camera will be halted when the master timer finishes.

GE_auto_clear

spec parameter. If enabled, the clear command will be sent to the server which calls the ClearFifo() function.

GE_image

A shared ushort spec data array dimensioned to fit the image data returned by the configured camera.

GE_has_binningX

Set if the camera model supports binning in X.

GE_has_cropX

Set if the camera model supports cropping in X.

GE_has_capacityMode

Set if the camera model supports the capacityMode command.

GE_xbeg

The first column of the region-of-interest for the ROI macro hardware counter.

GE_xend

The last column of the region-of-interest for the ROI macro hardware counter.

GE_ybeg

The first row of the region-of-interest for the ROI macro hardware counter.

GE_yend

The last row of the region-of-interest for the ROI macro hardware counter.

The following global variables mirror the values with the same name (after the GE_) accessed via image_par() described above:

GE_modelString
GE_tempLevels
GE_temperature
GE_tempControl
GE_shutterMode
GE_openTime
GE_closeTime
GE_shutterState
GE_showShutter
GE_showSync
GE_triggerMode
GE_triggerTimeOut
GE_readoutSpeed
GE_correctBias
GE_gainSetting
GE_capacityMode
GE_maxExposureTime
GE_cropMode
GE_cropX
GE_cropY
GE_binningX
GE_binningY