DESCRIPTION

spec supports the Multix ME100 detector module via a standalone server and the spec server hardware facility, as described in spec server_hdw help file. The standalone server module from CSS must be linked with API libraries provided by Multix.

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

CONFIGURATION

Configure the macro-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 hostname and port number for the medet server. The ADDR field isn't used.

Use the p command to enter custom parameters, if needed. See the server_hdw help file for details.

A macro-hardware scaler can also be configured to display the line-count from the detector, as follows. On the Devices screen of the configuration editor, add a macro counter:

Motor and Counter Device Configuration (Not CAMAC)

SCALERS       DEVICE  ADDR <>MODE NUM            <>TYPE
    ...
    YES  medet_lines     -          1     Macro Counter

The DEVICE field contains the prefix to the supplied macro.

Configure a specific counter along these lines:

Scaler (Counter) Configuration

Number   Name  Mnemonic  <>Device  Unit Chan  <>Use As  Scale Factor
   ...
     1  Lines     lines   MAC_CNT     0    0   counter             1

INSTALLATION

The spec distribution contains a subdirectory named servers/multix that contains the Multix-related files. To build and install the Multix server, from the servers directory, type:

make multix_server
make install

Building the server requires header files and libraries provided by the vendor. For the header files, create a symbolic link named multix that points to the location of the vendor distribution that contains an include directory. That directory contains many files, including one named ME100.h. In addition, the file servers/multix/multix.mk includes built-in path names pointing to the standard locations for the library files. If the files reside elsewhere, assign values to PUREGEV_LIB_DIR and ME100_LIB_DIR appropriately.

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.

To create and install the help file, type:

make multix_help

Note, building the help file from the multix.rst source requires that the Python docutils package is installed on the system.

The macros for using the server with spec are in the file multix.mac. This file could be copied to /usr/local/lib/spec.d or any other location where local macros are kept. A command can be added to a /usr/local/lib/spec.d/site.mac file to read in the Multix macros.

USAGE

The Multix 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.

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

-a MAC IP subnet

Set the IP address and subnet for the detector with the specified MAC address. Syntax is as follows:

multix_server -a 00-11-1c-f5-d0-2e 192.168.1.3 255.255.255.0

-q

Quit immediately. Intended to be used after setting the network parameters when using the -a option.

When starting, unless the -q option is specified, the server immediately initiates a connection with the detector. The process of connecting takes a number of seconds. However, the server will respond to client commands immediately, as the connection is started from a separate thread. Commands that require access to the detector will return a "Detector not connected" error if issued before the connection process is completed.

SERVER MESSAGES

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

connect

Will attempt to connect to the detector. Normally not needed, as the server connects automatically. However, if a disconnect is sent, a connect is required to re-establish the ability to use the detector.

The command will return a "Waiting for connection" string if a connection is in progress. If a connection already exists, the command will do nothing. It will not be an error.

disconnect

Disconnects the detector from the server. A connect command is required to re-establish contact with the detector.

detector_state

Returns the detector state as one of the following strings: "starting", "stopping", "stopped", "preheating", "ready", "checking", "preparing", "prepared", "fail", "acquiring" or "unknown".

reset arg

Call the API reset function. If arg is zero does a soft reset. If arg is nonzero does a hard reset.

setnow arg value

Sets a parameter immediately. (Currently only supported for the parameters detector_flags and test_pattern.) Otherwise, parameters that have been changed are programmed at the start of the next acquisition.

run count_time mode

The run message to start an acquisition is documented in the server_hdw help file. The following documents how the message is treated in the multix_server.

mode is 1 or 3 means counting to a monitor preset or during a move_cnt. The server starts acquisition for a very long time. The client needs to send a halt command to terminate acquisition.

mode is 2 or 4 and count_time is nonzero means counting to time or counting via image_par(MEDE_unit, "run"). Acquisition is set to the count time specified in seconds.

If neither of the above conditions is met but a value for lines has been set, acquisition is started for the preset number of lines.

If none of the above conditions is met, acquisition is set to a default 100 lines.

board_temperature arg

Returns the temperature of the board numbered arg.

sensor_temperature arg

Returns the temperature of the sensor numbered arg.

preheating arg

Sets the preheating state according to arg, which can be "run" or "stop". If arg is "time", returns the time remaining for the current preheating.

filename path

Sets the path name for the file in which to save the data. The path argument can contain conversion specifications (strings starting with a %) that will be replaced according to the conventions of the C library strftime() function. If the directory portion of path contains a %, the server will not attempt to create the directory path until it starts acquisition. Otherwise, the directory path will be created when the command is received.

filename

Returns the filename associated with the most recent acquisition.

lines

Sets the number of lines which will be used for the next acquisition according to the rules specified for the run command.

lines?

Returns the number of lines so far acquired if acquisition is active or the number of lines acquired in the most recent acquisition.

The messages hello, connect, filename, lines and exit are the only ones accepted before the connection is made to the detector.

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.

detector_flags

Sets or returns a set of flags associated with the detector. The API uses a nonstandard format to represent a binary string. The hexadecimal value 0xB000000 can have up to four bits set with meanings as follows:

0xB000001 - Include temperature in file header.

0xB000010 - Reverse pixel output direction.

0xB000100 - Enable power-down mode.

0xB001000 - Enable automatic preheating.

acquisition_mode

Sets or returns the acquisition mode. A value of 1 indicates HER mode. A value of 2 indicates BIN mode.

channels_count

Sets or returns the number of channels to use in HER mode.

bin_count

Sets or returns the number of windows to use in BIN mode.

bin_window_all

Sets or returns twelve values containing the starting and ending energy for each of the possible six windows when acquiring in BIN mode.

bin_window_0 bin_window_1 bin_window_2 bin_window_3 bin_window_4 bin_window_5

Sets or returns two values for the starting and ending energy for the numbered BIN-mode window.

int_time

Sets or returns the integration time. An acquisition consists of a set number of integrations, where each integration is called a "line".

binning_mode

Sets or returns the binning mode value. A value of 1 indicates no binning. A value of 2 indicates every two consecutive channels are combined to return a single value.

roi_enable

Sets or returns a value indication the state of the ROI feature. A zero indicates disabled. Nonzero indicates enabled.

roi_start

Sets or returns the starting pixel number of the region of interest.

roi_end

Sets or returns the ending pixel number of the region of interest.

test_pattern

Sets or returns the current test pattern value. Acceptable values are 0, 1, 2, 3, 10, 11 and 12. A value of zero means test-pattern generation is off. See Multix documentation for details.

pixel_count (ro)

Returns the pixel count of the detector.

detector_state (ro)

Returns the value associated with ME100_PROP__DETECTOR_STATE. The values is the API numerical value corresponding to the string the server returns for the detector_state command.

post (ro)

Returns the value which encodes the result of the power-on self test.

api_version (ro)

Returns ME100_ENTITY_API.

ebus_version (ro)

Returns ME100_ENTITY_EBUS_RUNTIME.

gige_version (ro)

Returns ME100_ENTITY_GIGE_PROTOCOL.

hard_ib_version (ro)

Returns ME100_PROP__VERSION_HARD_IB.

hard_all_version (ro)

Returns ME100_PROP__VERSION_HARD_ALL.

firm_mb_version (ro)

Returns ME100_PROP__VERSION_FIRM_MB.

firm_ib_version (ro)

Returns ME100_PROP__VERSION_FIRM_IB.

soft_nios_version (ro)

Returns ME100_PROP__VERSION_SOFT_NIOS.

soft_all_version (ro)

Returns ME100_PROP__VERSION_SOFT_ALL.

hard_mb_version (ro)

Returns ME100_PROP__VERSION_HARD_MB.

hard_pb_version (ro)

Returns ME100_PROP__VERSION_HARD_PB.

GLOBAL VARIABLES

MEDET_unit

The unit number for image_par() calls.

MEDET_acquisition_mode

Set to 1 for HER mode and 2 for BIN mode.

MEDET_bin_count

The number of windows (energy bands) in BIN mode. Allowed values are 2, 3, 4, 5 and 6.

MEDET_bin_window[]

An associative array containing the minimum and maximum energy values for each window in BIN mode. Even indices (starting from 0) contain the minimum values and odd indices contain the maximum values for the consecutive windows.

MEDET_channels_count

The number of values for each pixel in HER mode. Allowed values are 16, 32, 64 and 128.

MEDET_int_time

Integration time, i.e. time per line of acquisition. Valid range is from 2 to 10000 milliseconds.

MEDET_binning_mode

Can be set to 1 or 2. If set to 2, the detector will combine two consecutive pixels along the detector line.

MEDET_detector_flags

Contains a value with bits representing the API detector flags as follows:

0xB000001 - Include temperature in file header.

0xB000010 - Reverse pixel output direction.

0xB000100 - Enable power-down mode.

0xB001000 - Enable automatic preheating.

MEDET_roi_enable

Nonzero if region-of-interest mode is enabled.

MEDET_roi_start

The pixel number of the start of the region of interest.

MEDET_roi_end

The pixel number for the end of the region of interest.

MEDET_test_pattern

The value for the test pattern parameter. Acceptable values are 0, 1, 2, 3, 10, 11 and 12. A value of zero means test-pattern generation is off. See Multix documentation for details.

MEDET_pixel_count

Contains the number of pixels per line as set by the detector. This value should be treated as read only.

MEDET_preset

Default preset time for image_par(MEDET_unit, "run").

MEDET_directory

The directory for data files. The server will attempt to create the directory path if it doesn't exist. The directory can contain conversion specifications (strings starting with a %) that will be replaced according to the conventions of the C library strftime() function.

MEDET_filename

The filename for data saved by the server. The filename can contain conversion specifications (strings starting with a %) that will be replaced according to the conventions of the C library strftime() function.

MEDET_needs_sync

Set on start up and reconfig. If set, parameters will be synchronized between spec and the detector before starting the detector and before editing the parameters with medet_setup.

MEDET_auto_run

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

MEDET_soft_preset

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

MACROS

The following macros provide the basic user interface to the Multix detector.

medet cmd

Sends the command to the server. Displays the return value, if there is one. Defined as:

def medet 'p image_par(MEDET_UNIT, "$*")'

medet_defaults

Sets the detector parameters to a default set of values.

medet_setup

Presents an interactive menu for setting parameters for the detector and for operation.

medet_diagnostic

Displays a number of diagnostic parameters, such as firmware versions.

medet_precount()

Assigned to user_precount to insure that the ME100 parameters are current.

medet_sync_one_par(par)

Makes sure the server and spec agree on the value for the given parameter. If the parameter hasn't been set in spec the current value is read from the server. Otherwise, the current value in spec is sent to the server.

medet_sync_pars(how)

Makes sure the server and spec agree on the values for all the parameters. If how is nonzero, the macro will wait up to 10 seconds for the server to connect before synchronizing the parameters.

medet_get

Reads image data from the detector and places the data into an array named image.