GBS Elektronik MCA-166 User Manual
MCA-166, MCA-527
Multi-Channel Analyzers
GBS Elektronik GmbH
Bautzner Landstraße 22
01454 Großerkmannsdorf
Germany
Tel.: 0049 (0)351 21 70 07 - 0
Fax: 0049 (0)351 21 70 07 - 21
E-Mail: kontakt@gbs-elektronik.de
Website: www.gbs-elektronik.de
Description of the MCA
Description of the MCA
Communication DLL
Communication DLL
MCA527
Exclusion of liability
The information in this document has been carefully reviewed and is believed to be
accurate and reliable. However, the GBS Elektronik GmbH assumes no liabilities for
inaccuracies in this manual. This manual is subject to change without notice.
Last update: 2014-06-27
Address:
GBS-Elektronik GmbH
Bautzner Landstraße 22
01454 Großerkmannsdorf
Tel.: (0351) 217007-0
Fax: (0351) 217007-21
Internet: http://www.gbs-elektronik.de
Email to: kontakt@gbs-elektronik.de
2
Description of the MCA Communication DLL
Table of Contents
1 MS-Windows DLL for Communication with MCA166 and MCA527................................4
2 Initializing and Closing the Communication Port.............................................................4
3 Sending Firmware Commands to the MCA.....................................................................7
4 Functions to work with the MCA......................................................................................8
5 Managing the USB port..................................................................................................31
6 MS-Windows DLL for the Communication with Several MCAs.....................................32
3
MCA527
1 MS-Windows DLL for Communication with MCA166 and MCA527
The dynamic link library (mca32com.dll) is provided for Win32 applications. It must reside in the Windows system directory or in the
same directory as the calling application. In order to include the DLL in your program, you have to use the file MCA32COM.BAS for
Visual Basic or the files MCA_COMM.H and MCA32COM.LIB for C/C++. All functions and structures are declared in these files.
The description of the communication DLL refers to version 2.07.0008.
2 Initializing and Closing the Communication Port
Before you can use any other function, the communication port must be initialized. There are three functions for initializing the
communication port: COMM_INIT_EX2 initializes a RS232 or USB communication port. COMM_INIT_ETHERNET initializes an
Ethernet communication port. COMM_INIT_SELECT is the most recently added function and usable for all possible communication
ports. It also offers the most comfort for the developer. For this reason, it is the most commendable function.
Before the application will be exited, the communication port has to be closed with COMM_CLOSE. Only one communication port
can be used at the same time. If the communication port shall be changed, the current communication port has to be closed before
the new one can be initialized.
Name
COMM_INIT_EX2
Description The function initializes the RS232 or USB communication.
Declaration
short CALLBACK COMM_INIT_EX2(LPSTR lpszInterface,clock_t lTimeOut,
int nTryAgain,unsigned long ulBaudRate);
lpszInterface
Interface name (e. g. “COM1”)
lTimeOut
Time out [milliseconds] for the communication. It should be set to about 1000 milliseconds, because
there are commands that run a short measurement before they return. The parameter can be set to a
higher value if needed.
nTryAgain
Number of tries to send the command
ulBaudRate
Baud rate (38.400, 115.200, 307.200 or 3.000.000)
Return value If the function succeeds, the return value is nonzero.
Name
COMM_INIT_ETHERNET
Description The function initializes the Ethernet communication.
Declaration
short CALLBACK COMM_INIT_ETHERNET(unsigned short unNumberToFind,
clock_t lTimeOut,int nTryAgain,HWND hWnd);
unNumberToFind
Serial number of the MCA527 which shall be connected to the application.
If the parameter is unequal 0, the function exclusively tries to connect to the MCA527 with this serial
number.
If the parameter is equal 0, the function searches for all available MCA527. If MCA527's are available,
they are displayed in a list, from what the user can choose the desired one.
lTimeOut
Time out [milliseconds] for the communication. It should be set to about 1000 milliseconds, because
there are commands that run a short measurement before they return. The parameter can be set to a
higher value if needed.
nTryAgain
Number of tries to send the command
hWnd
Handle to the parent window
Return value If the function succeeds, the return value is nonzero.
4
Description of the MCA Communication DLL
Name COMM_INIT_SELECT
Description The function initializes the communication with any MCA. The function detects all available MCA's.
Declaration
short CALLBACK COMM_INIT_SELECT(MCA_COMM_INIT* init,clock_t lTimeOut,
int nTryAgain,HWND hWnd);
init
Pointer to a MCA_COMM_INIT structure.
lTimeOut
Time out [milliseconds] for the communication. It should be set to about 1000 milliseconds, because
there are commands that run a short measurement before they return. The parameter can be set to a
higher value if needed.
nTryAgain
Number of tries to send the command
hWnd
Handle to the parent window
Return value If the function succeeds, the return value is nonzero.
Name MCA_COMM_INIT
Description A pointer of the structure has to be passed to the COMM_INIT_SELECT function.
Declaration
struct MCA_COMM_INIT
{ unsigned short unSize;
unsigned short unNumberToFind;
VB_BOOL bMca166;
unsigned short unMca166FwVersion;
VB_BOOL bMca527;
unsigned short unMca527FwVersion;
VB_BOOL bShowLogo;
VB_BOOL bUserInterface;
unsigned short unInterfaceId;
unsigned long ulBaudrate;
};
unSize
Size of the structure.
unNumberToFind
[In] If this number is nonzero, the function tries to initializes the communication to the MCA with the
corresponding serial number. If the communication with this MCA is possible, the communication is
initialized and the function return. If the corresponding MCA is not detected or not usable, all detected
MCA are listed within a dialog window.
If this number is zero, all detected MCA are always listed within a dialog window.
bMca166
[In] If this parameter is nonzero, the MCA-166 is assumed to be applicable.
unMca166FwVersion
[In] This parameter sets the earliest MCA-166 firmware version that is assumed to be applicable.
bMca527
[In] If this parameter is nonzero, the MCA-166 is assumed to be applicable.
unMca527FwVersion
[In] This parameter sets the earliest MCA-527 firmware version that is assumed to be applicable.
bShowLogo
[In] If this parameter is nonzero, the function displays the MCA logo.
bUserInterface
[In] If this parameter is nonzero, the function displays message windows for signaling the work progress.
unInterfaceId
[In] If this parameter is unequal to 0xFFFF, it determines the communication port that shall be used.
[Out] This parameter returns the ID of the used communication port.
ulBaudrate
[Out] If the communication port is RS232 or USB, the parameter returns the current baud rate.
Name COMM_CLOSE
Description The function closes the communication.
Declaration
void CALLBACK COMM_CLOSE();
5
MCA527
Name GET_COMM_PARAM
Description The function returns the communication parameters.
Declaration
void CALLBACK GET_COMM_PARAM(MCA_COMM_PARAM* param);
param
Pointer to a MCA_COMM_PARAM structure.
Name
MCA_COMM_PARAM
Description The structure contains the MCA communication parameters. A pointer of the structure is passed to the
GET_COMM_PARAM function.
Declaration
struct MCA_COMM_PARAM
{ unsigned short unSize;
unsigned short unInterfaceId;
unsigned long ulBaudrate;
unsigned short unComPortNumber;
};
unSize
Size of the structure.
unInterfaceId
This parameter identifies the used communication interface.
0 = Ethernet
1 … 256 = RS232 (COM1 … COM256)
257 = USB, the MCA battery cannot be charged
1
258 = USB, the MCA battery can be charged
ulBaudrate
The baud rate is valid with RS232 and USB interface.
unComPortNumber
The virtual port number (COM1 … COM256) of the USB interface.
Name SET_TIMEOUT
Description The function sets the time out for the communication.
Declaration
void CALLBACK SET_TIMEOUT(clock_t lTimeOut);
lTimeOut
Time out [milliseconds] for the communication. It should be set to about 1000 milliseconds, because
there are commands that run a short measurement before they return. The parameter can be set to a
higher value if needed.
1 The MCA can only be charged over USB if the computer is connected directly with the USB connector
and not only via a USB adapter with the RS232 connector.
6
Description of the MCA Communication DLL
3 Sending Firmware Commands to the MCA
For information about MCA firmware commands (CMD_XXX) see document “Description of the
MCA527 Firmware Commands” or appendix “Description of the MCA166 firmware functions” within
the MCA-166 User's Manual.
Name MCA_COMM, MCA_COMM6
Description These functions allow to send single firmware commands to the MCA. These function are only intended
for testing. The function MCA_COMM6 has been added because new MCA527 commands need more
than 4 parameters. For the real work with the MCA you should use the other functions (MMCA_ ...)
described in chapter 4.
Regardless of its type, each parameter of the firmware command is passed to one unsigned long
parameter each. It will be cast within the function to the required type.
Declaration
ERROR_FLAG CALLBACK MCA_COMM(LPSTR command,LPSTR rec_data,
unsigned long param1=0,unsigned long param2=0,
unsigned long param3=0,unsigned long param4=0);
ERROR_FLAG CALLBACK MCA_COMM6(LPSTR command,LPSTR rec_data,
unsigned long param1=0,unsigned long param2=0,
unsigned long param3=0,unsigned long param4=0
unsigned long param5=0,unsigned long param6=0);
command
Command name (e. g. “CMD_START”)
rec_data
Pointer to RECDATA or command specific structure in which the received data is returned.
param1
1st parameter if required
param2
2nd parameter if required
param3
3rd parameter if required
param4
4th parameter if required
param5
5th parameter if required
param6
6th parameter if required
Return value ERROR_OK = 0 successful data transfer
ERROR_INTERFACE = 1 communication port is not initialized
ERROR_UNKNOWN_COMMAND = 2 unknown command
ERROR_COMMUNICATION = 3 faulty data transfer
ERROR_INVALID_PARAM = 4 invalid parameter
ERROR_RUNNING_MEAS = 5 measuring is running, but stopped
measurement is required for this command
ERROR_VIOLATED_RIGHT = 6 execution right violation
ERROR_STOPPED_MEAS = 7 measurement is stopped, but running
measurement is required for this command
ERROR_WRONG_MODE = 8 wrong mode for using this command
ERROR_UNHANDLED_COMMAND = 9 not handled by this firmware version
ERROR_FILE_WRITING_IN_PROCCESS = 10 file writing is in process; this command must
not be called before the process is finished
7
MCA527
4 Functions to work with the MCA
For the work with the MCA a lot of functions are available. The functions can be subdivided in five groups:
● Function for resetting the MCA (MMCA_RESET)
● Functions for starting and stopping the data acquisition (MMCA_..._AQUIRE)
● Functions for clearing (MMCA_CLEAR_...)
● Functions for setting (MMCA_SET_...)
● Functions for query (MMCA_QUERY_...)
The query functions are handed over a reference to a specific data structure. You can derive the name of the structure from the
name of the function, by leaving out ”MMCA_” from the function name. (e. g. function MMCA_QUERY_STATE requires the data
structur QUERY_STATE). You can also find important information in the files mca_comm.h (C/C++) and mca32com.bas (Visual
Basic).
For information about MCA firmware commands (CMD_XXX) see document “Description of the
MCA527 Firmware Commands” or appendix “Description of the MCA166 firmware functions” within
the MCA-166 User's Manual.
MCA Reset function:
Name
MMCA_RESET
Description All MCA parameters will be reset to their initial state and all spectra are cleared. The measurement is
aborted.
MCA-166: The states of the preamplifier power and the value of the high voltages are unchanged!
MCA-527: The preamplifier power and the high voltage are turned off!
Declaration
ERROR_FLAG CALLBACK MMCA_RESET();
Return value See MCA_COMM function
MCA Acquire functions:
Name MMCA_START_ACQUIRE
Description The acquisition is started or continued with the current parameters (see CMD_START).
Declaration
ERROR_FLAG CALLBACK MMCA_START_ACQUIRE(unsigned short unFlags,
unsigned long ulStartTime);
unFlags
Flags (see CMD_START)
ulStartTime
Start time (see CMD_START)
Return value See MCA_COMM function
Remarks Note, that the flags for MCA166 and MCA527 differ.
Name
MMCA_STOP_ACQUIRE
Description The acquisition is stopped.
Declaration
ERROR_FLAG CALLBACK MMCA_STOP_ACQUIRE();
Return value See MCA_COMM function
8
Description of the MCA Communication DLL
MCA Mode functions:
Name MMCA_SET_GENERAL_MODE
Description The function sets the general MCA527 mode.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_GENERAL_MODE(unsigned short unMode);
unMode
General MCA527 mode (see CMD_SET_GENERAL)
Return value See MCA_COMM function
Name MMCA_SET_MODE_MCA
Description The function sets the acquire mode to Multi-Channel Analyser.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_MODE_MCA();
Return value See MCA_COMM function
Name
MMCA_SET_MODE_MCS
Description The function sets the acquire mode to Multi-Channel Scaler. The MCS input remains unchanged.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_MODE_MCS();
Return value See MCA_COMM function
Name MMCA_SET_MODE_MCS_TTL
Description The function sets the acquire mode to Multi-Channel Scaler and the MCS input to “extern TTL”.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_MODE_MCS_TTL();
Return value See MCA_COMM function
Name
MMCA_SET_MODE_MCS_ICR
Description The function sets the acquire mode to Multi-Channel Scaler and the MCS input to “Input Rate”.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_MODE_MCS_ICR();
Return value See MCA_COMM function
Name MMCA_SET_MODE_MCS_DISCR
Description The function sets the acquire mode to Multi-Channel Scaler and the MCS input to “LLD/ULD”.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_MODE_MCS_DISCR();
Return value See MCA_COMM function
MCA Clear functions:
Name
MMCA_CLEAR_MEMORY
Description MCA166: The acquisition is stopped and the spectrum is cleared.
MCA527: The acquisition is stopped and the spectrum, the real time and the dead time are cleared.
Declaration
ERROR_FLAG CALLBACK MMCA_CLEAR_MEMORY();
Return value See MCA_COMM function
9
MCA527
Name MMCA_CLEAR_TIME
Description MCA166: The acquisition is stopped and the real time and the dead time are cleared.
MCA527: The acquisition is stopped and the spectrum, the real time and the dead time are cleared.
Declaration
ERROR_FLAG CALLBACK MMCA_CLEAR_TIME();
Return value See MCA_COMM function
Name MMCA_CLEAR_ROI
Description The acquisition is stopped and the ROI limits are set to LLD and ULD
Declaration
ERROR_FLAG CALLBACK MMCA_CLEAR_ROI();
Return value See MCA_COMM function
Name
MMCA_CLEAR_ALL
Description The function is a combination of MMCA_CLEAR_ROI, MMCA_CLEAR_MEMORY and
MMCA_CLEAR_TIME
Declaration
ERROR_FLAG CALLBACK MMCA_CLEAR_ALL();
Return value See MCA_COMM function
MCA Setup functions:
Name MMCA_SET_PRESET_NONE
Description None automatic stop condition.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_PRESET_NONE();
Return value See MCA_COMM function
Name
MMCA_SET_PRESET_LIVE_TIME
Description The function sets the time for the automatic stop condition (dead time corrected).
Declaration
ERROR_FLAG CALLBACK MMCA_SET_PRESET_LIVE_TIME(unsigned long ulLiveTime);
ulLiveTime
Live time: MCA166: 1 ... 65535 sec
MCA527: 1 ... 4294967295 sec
Return value See MCA_COMM function
Name MMCA_SET_PRESET_REAL_TIME
Description The function sets the time for the automatic stop condition.
Declaration
ERROR_FLAG CALLBACK MMCA_SET_PRESET_REAL_TIME(unsigned long ulRealTime);
ulRealTime
Real time: MCA166: 1 ... 65535 sec
MCA527: 1 ... 4294967295 sec
Return value See MCA_COMM function
Name
MMCA_SET_PRESET_INTEGRAL
Description The function sets the value for the ROI integral
Declaration
ERROR_FLAG CALLBACK MMCA_SET_PRESET_INTEGRAL(unsigned long ulIntegral);
ulIntegral
Integral: 1 ... 4294967295
Return value See MCA_COMM function
10
Loading...